# n8n Flow — Cursor Skills + n8n-mcp 使用指南

本專案讓你在 **Cursor IDE** 裡，透過 **n8n-mcp**（MCP 伺服器）連線到你的 n8n 實例，並搭配 **12 個專家 Skills**，由 AI 協助設計、建立、驗證與除錯 n8n 工作流程。

---

## 這是什麼？

| 元件 | 作用 |
|------|------|
| **n8n-mcp** | MCP 協定伺服器，讓 AI 能搜尋節點、讀寫 workflow、驗證設定、管理憑證等 |
| **Skills**（`.cursor/skills/`） | 教 AI 正確使用 n8n 的專家知識庫（expression 語法、節點設定、錯誤處理等） |
| **Cursor** | 讀取專案內 Skills，並透過 MCP 呼叫 n8n API |

簡單說：**你開這個專案資料夾跟 AI 對話，AI 會自動套用 Skills 知識，並透過 MCP 直接操作你的 n8n。**

---

## 前置需求

1. **[Cursor](https://cursor.com/)**（建議最新版）
2. **[Node.js](https://nodejs.org/)**（需能執行 `npx`）
3. 可連線的 **n8n 實例**（自架或雲端）
4. n8n **API Key**（在 n8n → Settings → API 產生）

---

## 快速開始

### 步驟 1：複製 MCP 設定檔

`.cursor/mcp.json` 含 API 金鑰，**不會**提交到 Git（見 `.gitignore`）。首次使用請自行建立：

在專案根目錄建立 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["-y", "n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://你的-n8n-網址",
        "N8N_API_KEY": "你的-api-key"
      }
    }
  }
}
```

| 環境變數 | 說明 |
|----------|------|
| `N8N_API_URL` | n8n 實例網址，例如 `https://n8n.example.com`（**不要**加尾端斜線） |
| `N8N_API_KEY` | 在 n8n 後台產生的 API Key |

> 也可參考範例：`_vendor/n8n-skills-main/.mcp.json.example`

### 步驟 2：在 Cursor 啟用 MCP

1. 用 Cursor **開啟本專案資料夾**（`n8n_flow`）
2. 開啟 **Cursor Settings** → **MCP**（或 **Features → MCP**）
3. 確認 `n8n-mcp` 伺服器顯示為 **已連線 / Enabled**
4. 若狀態異常：重啟 Cursor，或執行 `npx -y n8n-mcp` 確認 Node.js 正常

### 步驟 3：確認 n8n 端權限

若 AI 找不到你在 UI 建立的 workflow，請在 n8n 中：

1. 開啟該 workflow
2. 進入 **Settings**
3. 啟用 **MCP access**（允許 MCP 存取此 workflow）

### 步驟 4：開始對話

在 Cursor **Agent** 模式開啟聊天，直接描述需求，例如：

```
幫我建立一個 Webhook 接收表單，驗證後送到 Slack
```

```
列出我 n8n 上所有 workflow
```

```
這個 HTTP Request 節點驗證失敗，幫我修
```

Skills 會依關鍵字自動啟用，AI 會透過 MCP 工具操作 n8n。

---

## Skills 是什麼？怎麼運作？

Skills 是放在 `.cursor/skills/` 的 Markdown 指引檔。Cursor Agent 在處理 n8n 相關任務時會**自動讀取**對應 Skill，避免常見錯誤（錯誤的 expression、節點格式、憑證寫法等）。

你**不需要手動載入** Skill；在對話中提到 workflow、節點、expression、AI Agent 等關鍵字即可觸發。

### 路由 Skill（必讀入口）

| Skill | 路徑 | 用途 |
|-------|------|------|
| `using-n8n-mcp-skills` | `.cursor/skills/using-n8n-mcp-skills/` | 總路由器：決定該用哪個 Skill、MCP 工具清單、三條鐵律 |

### 12 個專家 Skills

| Skill | 何時會用到 |
|-------|-----------|
| `n8n-mcp-tools-expert` | 呼叫任何 MCP 工具前；搜尋節點、管理 workflow、憑證、範本 |
| `n8n-workflow-patterns` | 設計新 workflow 架構（Webhook / API / 資料庫 / AI / 排程 / 批次） |
| `n8n-node-configuration` | 設定節點參數、欄位相依、Merge / IF 等多輸出節點 |
| `n8n-expression-syntax` | 撰寫 `{{ }}` expression、`$json` / `$('節點名')` 資料對應 |
| `n8n-validation-expert` | 解讀驗證錯誤與警告、區分假陽性 |
| `n8n-code-javascript` | n8n **Code 節點**（JavaScript） |
| `n8n-code-python` | n8n **Code 節點**（Python，僅在明確需要時） |
| `n8n-code-tool` | AI Agent 的 **Custom Code Tool**（與 Code 節點不同合約） |
| `n8n-error-handling` | Webhook/API、錯誤分支、重試、4xx/5xx 回應 |
| `n8n-binary-and-data` | 檔案、圖片、PDF、`$binary` 與 Agent 工具邊界 |
| `n8n-subworkflows` | 子 workflow、Execute Workflow、模組化重用 |
| `n8n-agents` | AI Agent、工具設計、記憶體、結構化輸出、RAG、聊天機器人 |

每個 Skill 資料夾內有 `SKILL.md`（主指引）與 `README.md`（摘要），可手動閱讀加深了解。

---

## MCP 工具一覽

AI 透過 **n8n-mcp** 可使用以下主要工具（完整清單以連線後 MCP 面板為準）：

### 探索與文件

| 工具 | 用途 |
|------|------|
| `tools_documentation` | MCP 工具說明文件 |
| `search_nodes` | 依關鍵字搜尋節點 |
| `get_node` | 取得節點 schema、操作、文件 |
| `validate_node` | 驗證單一節點設定 |
| `search_templates` / `get_template` | 搜尋與讀取 workflow 範本 |

### 建立與編輯 Workflow

| 工具 | 用途 |
|------|------|
| `n8n_create_workflow` | 建立新 workflow |
| `n8n_update_partial_workflow` | **增量修改**（新增節點、連線、改欄位；最常用） |
| `n8n_update_full_workflow` | 整份 workflow JSON 覆寫 |
| `n8n_get_workflow` | 讀取 workflow（含 connections） |
| `n8n_list_workflows` | 列出 workflow |
| `n8n_delete_workflow` | 刪除 workflow |
| `validate_workflow` | 驗證 workflow JSON |
| `n8n_validate_workflow` | 依 workflow ID 驗證已部署的 workflow |
| `n8n_autofix_workflow` | 自動修正常見驗證問題 |

### 測試與執行

| 工具 | 用途 |
|------|------|
| `n8n_test_workflow` | 測試執行（會觸發真實副作用，需謹慎） |
| `n8n_executions` | 查詢執行紀錄 |

### 憑證、資料表、安全

| 工具 | 用途 |
|------|------|
| `n8n_manage_credentials` | 憑證 CRUD 與 schema |
| `n8n_manage_datatable` | n8n Data Table 管理 |
| `n8n_audit_instance` | 實例安全稽核 |
| `n8n_health_check` | 連線健康檢查 |

> **注意**：`get_node` 使用**短格式** `nodes-base.httpRequest`；workflow JSON 內使用**長格式** `n8n-nodes-base.httpRequest`，兩者不可混用。

---

## 建議操作順序（AI 與人都適用）

建立或修改 workflow 時，Skills 建議遵循此流程：

```
1. 辨識任務 → 對應 Skill（路由：using-n8n-mcp-skills）
2. search_nodes / get_node → 查 live schema，不要憑記憶設參數
3. 建立或 n8n_update_partial_workflow 修改
4. validate_workflow → 驗證 JSON 格式
5. n8n_get_workflow → 檢查 connections 是否正確連線
6. 確認無誤後再啟用（activate）
```

### 三條鐵律

1. **動手前先 invoke 對應 Skill** — 寫 expression、設節點、連線前都要對照 Skill
2. **驗證 + 目視 connections** — `validate_workflow` 通過不代表連線正確
3. **密鑰只走憑證系統** — API Key、Token 不可寫在 Set 節點或 workflow 文字欄位

---

## 對話範例

| 你想做的事 | 可以這樣說 |
|-----------|-----------|
| 建新 workflow | 「用 Webhook 模式建一個接收 LINE 訊息的 workflow」 |
| 找節點 | 「搜尋可以發 Email 的 n8n 節點」 |
| 寫 expression | 「怎麼從上一個節點取 `user.email`？」 |
| 除錯 | 「validate 報錯 `missing required field`，幫我看 HTTP Request 節點」 |
| AI Agent | 「幫 AI Agent 加一個查資料庫的 tool」 |
| 安全檢查 | 「稽核我的 n8n 實例有沒有硬編碼密鑰」 |

多個 Skill 會協同運作。例如「建立並驗證 Webhook → Slack workflow」可能依序用到：`n8n-workflow-patterns` → `n8n-mcp-tools-expert` → `n8n-node-configuration` → `n8n-expression-syntax` → `n8n-validation-expert`。

---

## 專案目錄結構

```
n8n_flow/
├── README.md                 ← 本文件
├── .gitignore
├── .cursor/
│   ├── mcp.json              ← MCP 設定（本地建立，不提交 Git）
│   └── skills/               ← 12+1 個 n8n 專家 Skills
│       ├── using-n8n-mcp-skills/   # 路由器
│       ├── n8n-mcp-tools-expert/
│       ├── n8n-workflow-patterns/
│       ├── n8n-node-configuration/
│       ├── n8n-expression-syntax/
│       ├── n8n-validation-expert/
│       ├── n8n-code-javascript/
│       ├── n8n-code-python/
│       ├── n8n-code-tool/
│       ├── n8n-error-handling/
│       ├── n8n-binary-and-data/
│       ├── n8n-subworkflows/
│       └── n8n-agents/
└── _vendor/
    └── n8n-skills-main/      ← 上游 n8n-skills 參考來源（不提交 Git）
```

---

## 常見問題

### MCP 顯示離線或連線失敗

- 確認已安裝 Node.js，終端機可執行 `npx -y n8n-mcp`
- 檢查 `N8N_API_URL`、`N8N_API_KEY` 是否正確
- 確認 n8n 實例可從本機網路存取
- 重啟 Cursor

### AI 找不到我的 workflow

- 在 n8n workflow **Settings** 啟用 **MCP access**
- 請 AI 執行 `n8n_list_workflows` 確認列表

### 驗證通過但執行還是錯

- 用 `n8n_get_workflow` 檢查 `connections` 物件
- 檢查 Merge 輸入數、錯誤輸出是否有接線
- 查 `n8n_executions` 看實際執行錯誤

### Webhook 資料讀不到

- Webhook 的 body 通常在 `$json.body`，不是根層 `$json`
- 詳見 Skill：`n8n-expression-syntax`、`n8n-code-javascript`

### 想更新 Skills

Skills 源自 [czlonkowski/n8n-skills](https://github.com/czlonkowski/n8n-skills)。可從上游同步到 `.cursor/skills/`，或參考 `_vendor/n8n-skills-main/`。

---

## 安全注意事項

- **切勿**將含真實 `N8N_API_KEY` 的 `mcp.json` 提交到 Git
- **切勿**在 workflow 的 Set / 文字欄位硬編碼 Token；使用 n8n **Credentials**
- 執行 `n8n_test_workflow` 前確認副作用（會真的發信、寫 DB、呼叫 API）
- 定期用 `n8n_audit_instance` 檢查實例安全設定

---

## 相關連結

- [n8n](https://n8n.io/) — 工作流程自動化平台
- [n8n-mcp](https://github.com/czlonkowski/n8n-mcp) — MCP 伺服器
- [n8n-skills](https://github.com/czlonkowski/n8n-skills) — 上游 Skills 專案
- [Cursor MCP 文件](https://docs.cursor.com/context/mcp)

---

## 白話總結

1. 在本機建立 `.cursor/mcp.json`，填入你的 n8n 網址與 API Key。
2. 用 Cursor 開啟這個 `n8n_flow` 資料夾，確認 MCP 已連上。
3. 在聊天裡用自然語言描述你要的自動化，AI 會讀 Skills、呼叫 MCP 幫你建 workflow。
4. 啟用前記得驗證，並檢查節點連線；密鑰一律用 n8n 憑證，不要寫死在流程裡。

這樣你就能在 Cursor 裡用對話方式開發、維護 n8n 自動化流程。
