@path58/p58-n8n 0.2.20-demo.2 → 0.2.20-demo.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENT_INSTALL.md +262 -172
- package/CHANGELOG.md +19 -0
- package/p58-n8n.mcpb +0 -0
- package/package.json +2 -1
package/AGENT_INSTALL.md
CHANGED
|
@@ -1,10 +1,28 @@
|
|
|
1
1
|
# p58-n8n — LLM Agent Installation Guide
|
|
2
2
|
|
|
3
|
-
> **AX-Native install (the canonical demo path):** Tell your LLM client *"install p58-n8n using this guide"* and paste
|
|
3
|
+
> **AX-Native install (the canonical demo path):** Tell your LLM client *"install p58-n8n using this guide"* and paste this file's URL. Your agent detects what it can do, picks the lowest-friction install path for your environment, walks you through configuration conversationally, and **proactively offers a working demo** using only the credentials you already have. Per Pillar 3 of `STRATEGIC_ANCHORS.md` v1.2.0 — *every customer-facing operation happens through the agent the user already uses*.
|
|
4
4
|
|
|
5
|
-
> **🤖 ACTION REQUIRED:** You are reading this because a user wants you to install the **p58-n8n** MCP server. Follow the steps in order. Everything you need is in this file — do NOT search the web. Minimize questions to the user: auto-discover what you can
|
|
5
|
+
> **🤖 ACTION REQUIRED:** You are reading this because a user wants you to install the **p58-n8n** MCP server. Follow the steps in order. Everything you need is in this file — do NOT search the web. Minimize questions to the user: auto-discover what you can; only ask when you must.
|
|
6
6
|
|
|
7
|
-
> **Your job:** detect
|
|
7
|
+
> **Your job:** detect your own capabilities → pick the right install path → guide configuration → verify with `setup_check` → propose a tailored opportunistic demo → build + test + report.
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Step 0 — Self-check: what can you actually do? (DO THIS FIRST)
|
|
12
|
+
|
|
13
|
+
Different agent environments have different capabilities. Pick the path that matches your environment **before** giving the user any instructions, so you don't promise actions you can't deliver.
|
|
14
|
+
|
|
15
|
+
| Your environment | Can you read/write the user's filesystem? | Can you run shell commands? | Use this install path |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| **claude.ai web** (sandboxed Linux container, no host access) | ❌ No | ❌ Only inside sandbox | **STOP — hand off.** Tell the user: *"I'm running in claude.ai's sandbox and can't reach your machine. Please open Claude Desktop OR run `claude` in a terminal, then paste this same guide URL there. I'll be able to install properly from either of those."* |
|
|
18
|
+
| **Claude Desktop with Cowork / workspace folder** (filesystem access scoped to a connected folder; can't reach `~/Library/Application Support/Claude/`) | ⚠️ Scoped | ✅ Inside workspace | **Path A: `.mcpb` extension** (mandatory — Cowork can't write the config dir) |
|
|
19
|
+
| **Claude Desktop with a filesystem MCP granted write access** to `~/Library/Application Support/` | ✅ Yes | Maybe | Either Path A or Path B works. **Recommend Path A** (no PATH issues, faster). |
|
|
20
|
+
| **Claude Code CLI** (`claude` in terminal — full filesystem + bash) | ✅ Yes | ✅ Yes | Either path. **Recommend Path A** for non-developer users; **Path B** is fine for developers who prefer JSON. |
|
|
21
|
+
| **Anything else** (Cursor, Windsurf, VS Code Copilot, Codex, Antigravity) | Varies | Varies | Path B — these clients use JSON config files; see § Path B below. |
|
|
22
|
+
|
|
23
|
+
> **Tier indicators in chat.** If your tools include any with names containing `screenshot`, `bash`, `desktop_commander`, or `apple_script`, you likely have full or near-full local access (Cowork or local-agent Desktop). If your only tools are `web_search`, `web_fetch`, `repl`, or `analysis`, you are in claude.ai sandbox — STOP and hand off.
|
|
24
|
+
|
|
25
|
+
Once you've identified your path, proceed.
|
|
8
26
|
|
|
9
27
|
---
|
|
10
28
|
|
|
@@ -25,76 +43,108 @@ These are orthogonal: premium catalog works with or without n8n connected, and n
|
|
|
25
43
|
|
|
26
44
|
---
|
|
27
45
|
|
|
28
|
-
|
|
46
|
+
# Path A — `.mcpb` extension (recommended)
|
|
29
47
|
|
|
30
|
-
|
|
48
|
+
The `.mcpb` is a Claude Desktop Extension. It bundles its own Node runtime so it has **no PATH issues, no `npx` problems**, and configuration happens through a clean form UI guided by you (the agent) in chat. This is the path **most users should take.**
|
|
31
49
|
|
|
32
|
-
1
|
|
33
|
-
2. Click **Configure**
|
|
34
|
-
3. Leave **all 7 fields blank**
|
|
35
|
-
4. Click **Save**
|
|
36
|
-
5. Restart Claude Desktop
|
|
50
|
+
## A.1 — Where to get the file
|
|
37
51
|
|
|
38
|
-
The
|
|
39
|
-
- 1,603 node-name catalog (offline)
|
|
40
|
-
- 14,805 operation-name index
|
|
41
|
-
- 679 credential type lookups
|
|
42
|
-
- L1-L3 validation (offline)
|
|
43
|
-
- Discovery + `get_node_info` (names + metadata)
|
|
52
|
+
The .mcpb is published to npm and downloadable directly via unpkg (no GitHub credentials required):
|
|
44
53
|
|
|
45
|
-
|
|
54
|
+
```
|
|
55
|
+
https://unpkg.com/@path58/p58-n8n@latest/p58-n8n.mcpb
|
|
56
|
+
```
|
|
46
57
|
|
|
47
|
-
|
|
58
|
+
Tell the user:
|
|
59
|
+
> *"Download the extension file from `https://unpkg.com/@path58/p58-n8n@latest/p58-n8n.mcpb`. Then drag the file onto your Claude Desktop window (or use Settings → Extensions → Install from File)."*
|
|
48
60
|
|
|
49
|
-
|
|
61
|
+
## A.2 — Install
|
|
50
62
|
|
|
51
|
-
|
|
63
|
+
After the user drags the file in, Claude Desktop shows:
|
|
64
|
+
1. An **Install** button — they click it.
|
|
65
|
+
2. A **Configure** form with 7 user-config fields (all marked optional).
|
|
52
66
|
|
|
53
|
-
|
|
67
|
+
**They can click Save with all fields blank** and get instant **free-tier access** (the 1,603-node offline catalog, L1-L3 validation, discovery). This is enough to browse and plan workflows without any credentials. Tell them this is fine — they can add credentials any time later.
|
|
54
68
|
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
jq '.mcpServers["p58-n8n"].env' ~/Library/Application\ Support/Claude/claude_desktop_config.json
|
|
58
|
-
```
|
|
69
|
+
To unlock n8n build/deploy/test or the premium enriched catalog, the user needs to fill some fields. **DO NOT have them figure that out alone** — guide them conversationally (next step).
|
|
59
70
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
71
|
+
## A.3 — Configure conversationally (the AX-Native part)
|
|
72
|
+
|
|
73
|
+
After the .mcpb is installed (with or without blank fields), the user opens Claude chat and says something like *"configure p58-n8n"* or *"finish setting up p58-n8n"*.
|
|
74
|
+
|
|
75
|
+
**Your loop:**
|
|
76
|
+
|
|
77
|
+
1. Call `setup_check`. The response tells you exactly what's missing — `n8n_configured: false` if no n8n URL+key, `access_mode: "free"` if no premium token, etc.
|
|
78
|
+
2. For each missing field, ask the user **one question at a time**. Don't dump all 7 fields on them.
|
|
79
|
+
3. After the user gives you a value, tell them exactly where to paste it:
|
|
80
|
+
> *"Paste that into the **n8n_api_url** field of the p58-n8n extension settings. Open Claude Desktop → Settings → Extensions → p58-n8n → Configure. Click Save when you've pasted it. Let me know when done."*
|
|
81
|
+
4. When they say "done," call `setup_check` again. Confirm it shows the new value registered. Move to the next field.
|
|
82
|
+
5. **Search before asking** when possible — try common locations for credentials so you don't ask for things the user already has stored. See § Credential search (below).
|
|
83
|
+
6. Stop when `setup_check` returns `n8n_configured: true` AND the user's intended `access_mode` is achieved (`premium` if they have a P58 token, `free` if not).
|
|
84
|
+
|
|
85
|
+
**Order of fields to ask about (in priority):**
|
|
86
|
+
|
|
87
|
+
| Field | Why ask | Skip if |
|
|
88
|
+
|---|---|---|
|
|
89
|
+
| `n8n_api_url` | Required for build/deploy/test | User has no n8n / doesn't want to connect one |
|
|
90
|
+
| `n8n_api_key` | Pairs with the URL | (same as above) |
|
|
91
|
+
| `p58_access_token` | Unlocks premium enriched catalog | User has no token |
|
|
92
|
+
| `cf_access_client_id` + `cf_access_client_secret` | Only if their n8n is behind Cloudflare Access | Pair-test shows no 302 to cloudflareaccess.com |
|
|
93
|
+
| `n8n_user_email` + `n8n_user_password` | Optional — enables clean `test_credential` + run-and-verify | User doesn't need credential testing |
|
|
94
|
+
|
|
95
|
+
After every Save → restart, the `.mcpb` extension reloads with the new env vars and `setup_check` reflects them. Don't proceed until verified.
|
|
96
|
+
|
|
97
|
+
## A.4 — Credential search (search before asking)
|
|
98
|
+
|
|
99
|
+
Before asking the user for `N8N_API_KEY` or `P58_ACCESS_TOKEN`, search common locations:
|
|
64
100
|
|
|
65
|
-
**Codex (TOML config):**
|
|
66
101
|
```bash
|
|
67
|
-
#
|
|
68
|
-
|
|
102
|
+
# .env files in the user's current directory or common project paths
|
|
103
|
+
grep -rl "N8N_API_KEY" . --include=".env*" 2>/dev/null
|
|
104
|
+
grep -rl "P58_ACCESS_TOKEN" . --include=".env*" 2>/dev/null
|
|
105
|
+
|
|
106
|
+
# Sibling MCP configs (they may have it set there from a prior install)
|
|
107
|
+
~/Library/Application\ Support/Claude/claude_desktop_config.json
|
|
108
|
+
~/.cursor/mcp.json
|
|
109
|
+
.vscode/mcp.json
|
|
110
|
+
|
|
111
|
+
# Secret managers
|
|
112
|
+
op item list 2>/dev/null | grep -i n8n # 1Password
|
|
113
|
+
security find-generic-password -s n8n 2>/dev/null # macOS Keychain
|
|
69
114
|
```
|
|
70
115
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
"CF_ACCESS_CLIENT_ID": "...",
|
|
80
|
-
"CF_ACCESS_CLIENT_SECRET": "..."
|
|
81
|
-
}
|
|
116
|
+
If you find values, **confirm with the user** before using them ("I found an N8N_API_KEY in your `.env` — want me to use it?"). Don't autofill secrets without consent.
|
|
117
|
+
|
|
118
|
+
## A.5 — Validate the pairing — **before** declaring config done
|
|
119
|
+
|
|
120
|
+
A valid-looking key against the wrong instance fails silently. After the user fills `n8n_api_url` + `n8n_api_key`, before announcing success, pair-test:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
curl -s -o /dev/null -w "%{http_code}" "$N8N_API_URL/workflows?limit=1" -H "X-N8N-API-KEY: $KEY" -L
|
|
82
124
|
```
|
|
83
125
|
|
|
84
|
-
|
|
126
|
+
| Result | Meaning | Action |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| `200` | Correct pair | ✅ Tell user, move on |
|
|
129
|
+
| `401 {"message":"invalid signature"}` | Valid JWT, **wrong instance** (e.g. prod key vs local n8n) | Re-pair: "the key is real but points at a different n8n than the URL you gave me. Which is right?" |
|
|
130
|
+
| `401 {"message":"unauthorized"}` | Wrong/expired key | Ask user to mint a fresh one: n8n → Settings → API → Create API Key |
|
|
131
|
+
| `302` → `*.cloudflareaccess.com` | n8n is **behind Cloudflare Access** | Trigger the CF-Access branch (ask for `CF_ACCESS_CLIENT_ID` + `CF_ACCESS_CLIENT_SECRET`) |
|
|
85
132
|
|
|
86
|
-
>
|
|
133
|
+
> If `setup_check` says `n8n_configured: true` but the curl pair-test fails, trust the curl. The server may be caching the previous successful test. Re-test after any field change.
|
|
87
134
|
|
|
88
135
|
---
|
|
89
136
|
|
|
90
|
-
|
|
137
|
+
# Path B — JSON config (advanced / power users)
|
|
91
138
|
|
|
92
|
-
|
|
139
|
+
Use this path when:
|
|
140
|
+
- The user is on Claude Code CLI (`claude` in terminal)
|
|
141
|
+
- The user is on Cursor / Windsurf / VS Code Copilot / Codex / Antigravity
|
|
142
|
+
- The user explicitly wants to manage `claude_desktop_config.json` themselves
|
|
93
143
|
|
|
94
|
-
|
|
144
|
+
## B.1 — Detect the MCP client
|
|
95
145
|
|
|
96
146
|
| Client | Config file | OS |
|
|
97
|
-
|
|
147
|
+
|---|---|---|
|
|
98
148
|
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` | macOS |
|
|
99
149
|
| **Claude Desktop** | `%APPDATA%\Claude\claude_desktop_config.json` | Windows |
|
|
100
150
|
| **Claude Desktop** | `~/.config/Claude/claude_desktop_config.json` | Linux |
|
|
@@ -105,106 +155,56 @@ Check for these config files (if several exist, ask which client to configure):
|
|
|
105
155
|
| **Codex (OpenAI)** | `~/.codex/config.toml` (**TOML**, not JSON) | All |
|
|
106
156
|
| **Antigravity (Google)** | `~/.gemini/antigravity/mcp_config.json` (needs global install + full paths) | All |
|
|
107
157
|
|
|
108
|
-
|
|
158
|
+
## B.2 — Resolve absolute path to `npx` (CRITICAL on macOS)
|
|
109
159
|
|
|
110
|
-
|
|
160
|
+
Desktop apps on macOS don't inherit your shell's PATH. Bare `npx` in MCP config **silently fails** with `Failed to spawn process: No such file or directory` because the app searches only `/usr/local/bin:/usr/bin:/bin:/sbin` — but Homebrew Node lives in `/opt/homebrew/bin/npx` and nvm Node lives in `~/.nvm/versions/node/vX.Y.Z/bin/npx`.
|
|
111
161
|
|
|
112
|
-
|
|
162
|
+
**ALWAYS resolve to the absolute path before writing the config:**
|
|
113
163
|
|
|
114
164
|
```bash
|
|
115
|
-
|
|
116
|
-
echo "
|
|
117
|
-
#
|
|
118
|
-
curl -s -o /dev/null -w "%{http_code}" http://localhost:5678/api/v1/workflows
|
|
119
|
-
# C. Docker
|
|
120
|
-
docker ps --filter "name=n8n" --format "{{.Ports}}"
|
|
121
|
-
# D. Running processes
|
|
122
|
-
ps aux | grep -i n8n | grep -v grep
|
|
165
|
+
NPX_PATH="$(command -v npx)"
|
|
166
|
+
echo "Using: $NPX_PATH"
|
|
167
|
+
# Use $NPX_PATH below — NEVER write the bare word "npx" in the command field.
|
|
123
168
|
```
|
|
124
169
|
|
|
125
|
-
If
|
|
126
|
-
|
|
127
|
-
> The API URL must include the `/api/v1` suffix, e.g. `http://localhost:5678/api/v1`. `N8N_API_BASE_URL` is accepted as a fallback for `N8N_API_URL`.<sup>[[4]](#sources)</sup>
|
|
128
|
-
|
|
129
|
-
---
|
|
130
|
-
|
|
131
|
-
## Step 3: Get the credentials
|
|
170
|
+
If `command -v npx` returns nothing, Node isn't installed. Tell the user:
|
|
171
|
+
> *"Node isn't installed. Install it first: `brew install node` on macOS (or download from nodejs.org), then run this guide again."*
|
|
132
172
|
|
|
133
|
-
|
|
173
|
+
## B.3 — Find the user's n8n instance
|
|
134
174
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
### 3b — n8n API key — **search before asking** (G1)
|
|
138
|
-
|
|
139
|
-
The key can't be auto-*extracted* from n8n (n8n stores it as a hash; the plaintext JWT exists only where the user saved it), but it can often be **found**. Search local artifacts BEFORE asking the user:<sup>[[5]](#sources)</sup>
|
|
175
|
+
Same as A.4 + try environment variables and standard ports:
|
|
140
176
|
|
|
141
177
|
```bash
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
# ~/.cursor/mcp.json · .vscode/mcp.json · ~/.codex/config.toml
|
|
147
|
-
# 3. Secret managers
|
|
148
|
-
op item list 2>/dev/null | grep -i n8n # 1Password
|
|
149
|
-
security find-generic-password -s n8n 2>/dev/null # macOS Keychain
|
|
150
|
-
# 4. Docker
|
|
151
|
-
docker inspect <n8n-container> --format '{{json .Config.Env}}'
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
Only if all are dry, ask the user to mint one: **n8n → Settings → API → Create API Key** (it starts with `eyJ…`, JWT format).
|
|
155
|
-
|
|
156
|
-
### 3c — Optional: session auth for `test_credential` and run-and-verify
|
|
157
|
-
|
|
158
|
-
Some n8n versions gate two things behind a logged-in session (not just the API key): reading credential **secrets** (`test_credential`), and **executing** a workflow via REST — which `test_workflow`'s verification step uses. **Optional** — build/deploy/activate and the workflow's own execution all work on URL + API key alone. To enable clean run-and-verify + `test_credential`, set `N8N_USER_EMAIL` + `N8N_USER_PASSWORD` (the user's n8n web-UI login).<sup>[[4]](#sources)</sup>
|
|
159
|
-
|
|
160
|
-
> ⚠️ **Known false-negative when absent.** On a session-auth-gated n8n without these set, `test_workflow` can report **"❌ TEST FAILED … N8N_USER_EMAIL/PASSWORD required"** even though the workflow **actually ran and delivered** (the deployed workflow executes server-side on API-key alone). If you see this, check the channel — the result likely arrived. Setting the optional login removes the false-negative. (Tracked: `INC-2026-06-02-test-workflow-clone-verify-false-negative-session-auth`.)
|
|
161
|
-
|
|
162
|
-
---
|
|
163
|
-
|
|
164
|
-
## Step 4: Validate the (URL, key) pairing — **before writing any config** (G3/G4)
|
|
165
|
-
|
|
166
|
-
A valid-looking key against the wrong instance fails *silently* after install. Pair-test first:<sup>[[5]](#sources)</sup>
|
|
167
|
-
|
|
168
|
-
```bash
|
|
169
|
-
curl -s -o /dev/null -w "%{http_code}" "$N8N_API_URL/workflows?limit=1" -H "X-N8N-API-KEY: $KEY" -L
|
|
178
|
+
echo "$N8N_API_URL"; echo "$N8N_API_BASE_URL"; echo "$N8N_HOST"
|
|
179
|
+
curl -s -o /dev/null -w "%{http_code}" http://localhost:5678/api/v1/workflows
|
|
180
|
+
docker ps --filter "name=n8n" --format "{{.Ports}}"
|
|
181
|
+
ps aux | grep -i n8n | grep -v grep
|
|
170
182
|
```
|
|
171
183
|
|
|
172
|
-
|
|
173
|
-
|---|---|---|
|
|
174
|
-
| `200` | Correct pair | ✅ Write the config |
|
|
175
|
-
| `401 {"message":"invalid signature"}` | Valid JWT, **wrong instance** (e.g. prod key vs local n8n) | Re-pair — try another URL/key combination |
|
|
176
|
-
| `401 {"message":"unauthorized"}` | Wrong/expired key | Mint a fresh key (Step 3b) |
|
|
177
|
-
| `302` → `*.cloudflareaccess.com` | n8n is **behind Cloudflare Access** | Optional CF branch ↓ — **most users skip this** |
|
|
178
|
-
|
|
179
|
-
> **Never assume one key ↔ one URL.** If a user has both a local dev n8n and a remote one, the wrong pairing returns `invalid signature`. Pair-test to confirm.<sup>[[5]](#sources)</sup>
|
|
184
|
+
If none work, ask: *"What's the URL of your n8n instance? (e.g. `http://localhost:5678` or `https://n8n.example.com`)"*
|
|
180
185
|
|
|
181
|
-
|
|
186
|
+
> The API URL must include the `/api/v1` suffix.
|
|
182
187
|
|
|
183
|
-
|
|
188
|
+
## B.4 — Get credentials
|
|
184
189
|
|
|
185
|
-
|
|
186
|
-
curl -s -o /dev/null -w "%{http_code}" "$N8N_API_URL/workflows?limit=1" \
|
|
187
|
-
-H "X-N8N-API-KEY: $KEY" \
|
|
188
|
-
-H "CF-Access-Client-Id: $CF_ID" -H "CF-Access-Client-Secret: $CF_SECRET"
|
|
189
|
-
# 200 → add CF_ACCESS_CLIENT_ID / CF_ACCESS_CLIENT_SECRET to the MCP env in Step 5
|
|
190
|
-
```
|
|
190
|
+
Same as A.4 (search-first, then ask).
|
|
191
191
|
|
|
192
|
-
|
|
192
|
+
## B.5 — Pair-test (before writing config)
|
|
193
193
|
|
|
194
|
-
|
|
194
|
+
Same as A.5.
|
|
195
195
|
|
|
196
|
-
##
|
|
196
|
+
## B.6 — Write the configuration
|
|
197
197
|
|
|
198
|
-
Add p58-n8n inside the existing `mcpServers` object — **do not overwrite other servers.**
|
|
198
|
+
Add p58-n8n inside the existing `mcpServers` object — **do not overwrite other servers.** Use the **absolute** npx path you resolved in B.2.
|
|
199
199
|
|
|
200
|
-
### Claude Desktop / Cursor / Windsurf
|
|
200
|
+
### Claude Desktop / Cursor / Windsurf (JSON)
|
|
201
201
|
|
|
202
202
|
```json
|
|
203
203
|
{
|
|
204
204
|
"mcpServers": {
|
|
205
205
|
"p58-n8n": {
|
|
206
|
-
"command": "npx",
|
|
207
|
-
"args": ["-y", "@path58/p58-n8n@
|
|
206
|
+
"command": "/opt/homebrew/bin/npx",
|
|
207
|
+
"args": ["-y", "@path58/p58-n8n@latest"],
|
|
208
208
|
"env": {
|
|
209
209
|
"N8N_API_URL": "https://YOUR-n8n-host/api/v1",
|
|
210
210
|
"N8N_API_KEY": "<n8n-api-key>",
|
|
@@ -215,22 +215,37 @@ Add p58-n8n inside the existing `mcpServers` object — **do not overwrite other
|
|
|
215
215
|
}
|
|
216
216
|
```
|
|
217
217
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
218
|
+
> Replace `/opt/homebrew/bin/npx` with whatever `command -v npx` returned in B.2. Never write the bare `"npx"` string here.
|
|
219
|
+
|
|
220
|
+
### VS Code
|
|
221
|
+
|
|
222
|
+
Top-level key is `"servers"` (not `"mcpServers"`), and add `"type": "stdio"`.
|
|
222
223
|
|
|
223
224
|
### Claude Code (CLI)
|
|
224
225
|
|
|
225
226
|
```bash
|
|
227
|
+
NPX_PATH="$(command -v npx)"
|
|
226
228
|
claude mcp add p58-n8n \
|
|
227
229
|
-e N8N_API_URL=https://YOUR-n8n-host/api/v1 \
|
|
228
230
|
-e N8N_API_KEY=<n8n-api-key> \
|
|
229
231
|
-e P58_ACCESS_TOKEN=<premium-token-if-you-have-one> \
|
|
230
|
-
--
|
|
232
|
+
-- "$NPX_PATH" -y @path58/p58-n8n@latest
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### Codex (TOML)
|
|
236
|
+
|
|
237
|
+
```toml
|
|
238
|
+
[mcpServers.p58-n8n]
|
|
239
|
+
command = "/opt/homebrew/bin/npx"
|
|
240
|
+
args = ["-y", "@path58/p58-n8n@latest"]
|
|
241
|
+
|
|
242
|
+
[mcpServers.p58-n8n.env]
|
|
243
|
+
N8N_API_URL = "https://YOUR-n8n-host/api/v1"
|
|
244
|
+
N8N_API_KEY = "<n8n-api-key>"
|
|
245
|
+
P58_ACCESS_TOKEN = "<premium-token-if-you-have-one>"
|
|
231
246
|
```
|
|
232
247
|
|
|
233
|
-
### Avoid plaintext secrets (optional
|
|
248
|
+
### Avoid plaintext secrets (optional)
|
|
234
249
|
|
|
235
250
|
To keep secrets out of `~/.claude.json` / config files, wrap them with a secret manager at launch:
|
|
236
251
|
|
|
@@ -238,55 +253,128 @@ To keep secrets out of `~/.claude.json` / config files, wrap them with a secret
|
|
|
238
253
|
{
|
|
239
254
|
"mcpServers": {
|
|
240
255
|
"p58-n8n": {
|
|
241
|
-
"command": "sh",
|
|
242
|
-
"args": ["-c", "N8N_API_KEY=$(op read 'op://Vault/n8n/api-key') P58_ACCESS_TOKEN=$(op read 'op://Vault/p58/access-token') N8N_API_URL=https://YOUR-n8n-host/api/v1 npx -y @path58/p58-n8n@
|
|
256
|
+
"command": "/bin/sh",
|
|
257
|
+
"args": ["-c", "N8N_API_KEY=$(op read 'op://Vault/n8n/api-key') P58_ACCESS_TOKEN=$(op read 'op://Vault/p58/access-token') N8N_API_URL=https://YOUR-n8n-host/api/v1 /opt/homebrew/bin/npx -y @path58/p58-n8n@latest"]
|
|
243
258
|
}
|
|
244
259
|
}
|
|
245
260
|
}
|
|
246
261
|
```
|
|
247
262
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
---
|
|
251
|
-
|
|
252
|
-
## Step 6: Restart the client (G6)
|
|
253
|
-
|
|
254
|
-
The MCP server reads its env **only at startup** — a running process keeps showing the old state until the session restarts.
|
|
263
|
+
## B.7 — Restart the client
|
|
255
264
|
|
|
256
265
|
| Client | Restart |
|
|
257
|
-
|
|
266
|
+
|---|---|
|
|
258
267
|
| **Claude Desktop** | Fully quit (Cmd+Q on macOS — closing the window is not enough), reopen |
|
|
259
268
|
| **Claude Code** | Exit and restart the CLI session |
|
|
260
269
|
| **Cursor / Windsurf / VS Code** | Reload window / restart |
|
|
261
270
|
| **Codex / Antigravity** | Restart the app |
|
|
262
271
|
|
|
272
|
+
## B.8 — Verify with `setup_check`
|
|
273
|
+
|
|
274
|
+
After restart, call `setup_check`. A healthy connected result shows:
|
|
275
|
+
- `access_mode: "premium"` (if a token is set) or `"free"`
|
|
276
|
+
- `n8n_configured: true` + `workflow_engine_connected: true`
|
|
277
|
+
- a `credential_count`, and `issues: []`
|
|
278
|
+
|
|
279
|
+
If `n8n_configured: false`, the URL/key pairing is wrong — re-run § A.5.
|
|
280
|
+
|
|
263
281
|
---
|
|
264
282
|
|
|
265
|
-
|
|
283
|
+
# Step ∞ — Proactively offer an opportunistic demo (BOTH paths)
|
|
266
284
|
|
|
267
|
-
|
|
285
|
+
The moment `setup_check` returns GREEN for the first time after install, **don't wait for the user to ask** what to do next. Discover what they have, propose a tailored workflow that pulls live data and delivers a visible result, and build it.
|
|
268
286
|
|
|
269
|
-
|
|
270
|
-
- `access_mode: "premium"` (if a token is set) or `"free"`,
|
|
271
|
-
- `n8n_configured: true` + `workflow_engine_connected: true`,
|
|
272
|
-
- a `credential_count`, and `issues: []`.
|
|
287
|
+
This is the "wow" moment of the install. Done well, the user goes from "ok it's connected" to "holy crap that worked" in 30 seconds.
|
|
273
288
|
|
|
274
|
-
|
|
289
|
+
## ∞.1 — Discover what the user has
|
|
275
290
|
|
|
276
|
-
|
|
291
|
+
Call `list_credentials`. Bucket each credential by capability:
|
|
292
|
+
|
|
293
|
+
```
|
|
294
|
+
DATASOURCE (preferred: PUBLIC APIs to avoid touching user data)
|
|
295
|
+
ZERO-CRED: HTTP request to public endpoints (no n8n credential needed):
|
|
296
|
+
- HackerNews top stories (hacker-news.firebaseio.com)
|
|
297
|
+
- Wikipedia daily featured (en.wikipedia.org/api)
|
|
298
|
+
- GitHub trending (api.github.com/search)
|
|
299
|
+
- Public RSS feeds
|
|
300
|
+
- boredapi.com, jsonplaceholder.typicode.com (test APIs)
|
|
301
|
+
- cat-facts API (catfact.ninja)
|
|
302
|
+
KEY-BASED public: openWeatherMap, serpApi, newsApi, perplexityApi,
|
|
303
|
+
coinMarketCap, exchangeRateApi
|
|
304
|
+
USER-DATA SaaS: notionApi, airtableApi, googleSheets, githubApi,
|
|
305
|
+
hubspotApi, salesforceApi, monday, supabase
|
|
306
|
+
USER DB: postgres, mysql, mongodb, microsoftSql, redis
|
|
307
|
+
|
|
308
|
+
AI
|
|
309
|
+
openAi, anthropic, googlePalmApi, mistralCloud, cohereApi,
|
|
310
|
+
openRouterApi, perplexityApi, huggingFaceApi
|
|
311
|
+
|
|
312
|
+
CHANNEL
|
|
313
|
+
slackApi, telegramApi, gmailOAuth2, discordApi, twilioApi,
|
|
314
|
+
microsoftOutlookOAuth2, microsoftTeams, sendGrid, mailgun
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
## ∞.2 — Pick datasource using PUBLIC-FIRST priority ladder
|
|
318
|
+
|
|
319
|
+
```
|
|
320
|
+
1. ZERO-CRED public APIs → works for everyone, never touches user data
|
|
321
|
+
2. KEY-BASED public APIs → if user has e.g. openWeatherMap credential
|
|
322
|
+
3. USER-DATA SaaS → ONLY with explicit consent ("want me to use your Notion?")
|
|
323
|
+
4. USER DB → ONLY when user explicitly invites it
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
The default is always tier 1 or 2 (public data). Only escalate to user-data tiers if the user asks for richer demo with their own data.
|
|
327
|
+
|
|
328
|
+
## ∞.3 — Pick AI + Channel from their list
|
|
329
|
+
|
|
330
|
+
- AI: prefer Anthropic > OpenAI > others (any AI cred works)
|
|
331
|
+
- Channel: prefer Slack > Telegram > Gmail > Discord > whatever they have
|
|
332
|
+
|
|
333
|
+
## ∞.4 — Propose ONE workflow before building
|
|
334
|
+
|
|
335
|
+
Tell the user concretely what you'd build, using THEIR actual tools by name:
|
|
277
336
|
|
|
278
|
-
|
|
337
|
+
> *"You've got OpenAI + Slack connected. I'd build a quick demo: pull the current top 5 HackerNews stories, have GPT-4 summarize them into a 3-sentence digest, and post to your Slack #general. ~15 seconds. Want me to go ahead?"*
|
|
279
338
|
|
|
280
|
-
|
|
339
|
+
| User has | Proposed demo (public-data default) |
|
|
340
|
+
|---|---|
|
|
341
|
+
| OpenAI + Slack | HackerNews top 5 → GPT summarizes → post to Slack |
|
|
342
|
+
| Anthropic + Telegram | Wikipedia daily featured → Claude shortens to a tweet → Telegram DM |
|
|
343
|
+
| OpenAI + Gmail | GitHub trending repos → GPT picks 3 most relevant → email summary |
|
|
344
|
+
| openWeatherMap + Anthropic + Slack | Tel Aviv weather → Claude writes 2-line forecast with personality → Slack |
|
|
345
|
+
| Just OpenAI (no channel) | Wikipedia featured → GPT summary → respond inline in chat |
|
|
346
|
+
| Just Slack (no AI) | OpenWeatherMap (free key) → simple 2-node weather post |
|
|
281
347
|
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
5
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
348
|
+
If the user has user-data credentials (Notion, Airtable, Postgres) but ALSO has a public-data path available, **propose the public-data demo by default** and OFFER the richer one as an alternative:
|
|
349
|
+
|
|
350
|
+
> *"Quick proof-of-life demo: HackerNews → GPT → Slack. If you want a more personalized one, I could pull from your Notion or query your Postgres instead — just say the word."*
|
|
351
|
+
|
|
352
|
+
## ∞.5 — Build defensively
|
|
353
|
+
|
|
354
|
+
Once the user says yes:
|
|
355
|
+
|
|
356
|
+
1. **Use a webhook trigger** — runs via public URL, no n8n session login needed for execution.
|
|
357
|
+
2. **Bind credentials by ID, not name** — use the cred IDs from `list_credentials`.
|
|
358
|
+
3. **Hardcode explicit values** — channel name, city, message text. Don't depend on payload defaults.
|
|
359
|
+
4. **Prefer version-stable nodes** — Webhook, HTTP Request, Slack, OpenAI/Anthropic, Code over volatile LangChain nodes for the FIRST run.
|
|
360
|
+
5. **Cap at 3-5 nodes.** Don't get fancy — the goal is "it runs and posts."
|
|
361
|
+
|
|
362
|
+
```
|
|
363
|
+
build_workflow → returns workflow ID + canvas link
|
|
364
|
+
test_workflow → returns sync execution result
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
On a config gap, read `failed_node` + `recovery_hint` and `partial_update_workflow` the fix, then re-test. Don't tell the user it failed if the side-effect actually landed.
|
|
368
|
+
|
|
369
|
+
## ∞.6 — Report honestly with evidence
|
|
370
|
+
|
|
371
|
+
✅ if the workflow actually delivered (Slack message landed, email arrived, etc.). Include the concrete proof:
|
|
372
|
+
|
|
373
|
+
> *"✅ Built workflow `YQcQOAy8IcG7zG6w`, test_workflow GREEN. Top story 'X' summarized and posted to #general at 09:42:13. Open the canvas: <link>."*
|
|
374
|
+
|
|
375
|
+
If `test_workflow` returned a session-auth false negative (see Step A.5 ⚠️ note) but the result actually landed in the channel, **say so plainly** — don't claim failure when there's a real Slack message:
|
|
376
|
+
|
|
377
|
+
> *"It ran and the message should have arrived in #general. I couldn't run my verification pass without your n8n login, but check the channel — it almost certainly landed."*
|
|
290
378
|
|
|
291
379
|
---
|
|
292
380
|
|
|
@@ -309,25 +397,27 @@ Don't hand the user a bare "hello world." Immediately after a healthy `setup_che
|
|
|
309
397
|
## Troubleshooting
|
|
310
398
|
|
|
311
399
|
| Symptom | Cause | Fix |
|
|
312
|
-
|
|
313
|
-
| Tools not appearing |
|
|
314
|
-
| `"
|
|
315
|
-
| `
|
|
316
|
-
| `
|
|
317
|
-
| `
|
|
318
|
-
|
|
|
400
|
+
|---|---|---|
|
|
401
|
+
| Tools not appearing after install | `.mcpb` not installed OR JSON config broken | A: re-install .mcpb. B: validate JSON and absolute npx path (B.2) |
|
|
402
|
+
| `"Failed to spawn process: No such file or directory"` | Path B with bare `npx` — Claude Desktop can't find it | Re-run B.2 to get absolute path; replace `"npx"` with that path in config |
|
|
403
|
+
| `"npx: command not found"` in logs | Node.js not installed at all | `brew install node` (or nodejs.org) |
|
|
404
|
+
| `setup_check` → `n8n_configured: false` after Save | Wrong URL/key pairing | Re-run A.5 pair-test; check pair returns 200 |
|
|
405
|
+
| `401 invalid signature` from n8n | Valid key, wrong instance | Confirm URL matches the n8n that issued the key |
|
|
406
|
+
| `302` to cloudflareaccess.com | n8n behind Cloudflare Access | Add `CF_ACCESS_CLIENT_ID` + `CF_ACCESS_CLIENT_SECRET` |
|
|
407
|
+
| New env vars not taking effect | Process not restarted | Cmd+Q + reopen (Desktop) / exit + re-run (CLI) |
|
|
408
|
+
| `test_workflow` says fail but Slack/email got the message | Session-auth false negative (Step A.5 ⚠️) | Set `N8N_USER_EMAIL` + `N8N_USER_PASSWORD`; or trust the side-effect |
|
|
319
409
|
|
|
320
410
|
---
|
|
321
411
|
|
|
322
412
|
## Sources
|
|
323
413
|
|
|
324
|
-
1. **18 tools** — `src/mcp/tools/index.ts` `TOOL_ENTRIES` (14 core + 4 credential-management;
|
|
325
|
-
2. **Bundled catalog counts** — `src/data/public-catalog/manifest.json` (`bundle_type: public-basic
|
|
326
|
-
3. **Tier model** — `src/mcp/runtime/access-mode.ts`: `P58_ACCESS_TOKEN` → `premium
|
|
327
|
-
4. **n8n engine env vars** — `src/config/env.schema.ts` (`N8N_API_BASE_URL`/`N8N_API_KEY`/`N8N_USER_EMAIL`/`N8N_USER_PASSWORD`)
|
|
328
|
-
5. **Search-first discovery + validation loop** — field report `MCP_INSTALL_FIELD_REPORT_2026-06-01` §6 (key discovery)
|
|
329
|
-
6. **Cloudflare Access headers** — `src/shared/n8n-api-adapter.ts` injects `CF-Access-Client-Id
|
|
414
|
+
1. **18 tools** — `src/mcp/tools/index.ts` `TOOL_ENTRIES` (14 core + 4 credential-management; RAG-4.97.2 locked set).
|
|
415
|
+
2. **Bundled catalog counts** — `src/data/public-catalog/manifest.json` (`bundle_type: public-basic`): 1,603 nodes / 14,805 operations / 679 credential types.
|
|
416
|
+
3. **Tier model** — `src/mcp/runtime/access-mode.ts`: `P58_ACCESS_TOKEN` → `premium`; `P58_DATABASE_URL` → `dev` (internal); neither → `free`.
|
|
417
|
+
4. **n8n engine env vars** — `src/config/env.schema.ts` (`N8N_API_BASE_URL`/`N8N_API_KEY`/`N8N_USER_EMAIL`/`N8N_USER_PASSWORD`).
|
|
418
|
+
5. **Search-first discovery + validation loop** — field report `MCP_INSTALL_FIELD_REPORT_2026-06-01` §6 (key discovery), §7 (pair-test matrix).
|
|
419
|
+
6. **Cloudflare Access headers** — `src/shared/n8n-api-adapter.ts` injects `CF-Access-Client-Id`/`CF-Access-Client-Secret`.
|
|
330
420
|
|
|
331
421
|
---
|
|
332
422
|
|
|
333
|
-
**Package:** `@path58/p58-n8n` · **npm:** https://www.npmjs.com/package/@path58/p58-n8n · **Version:** 0.2.20-demo.
|
|
423
|
+
**Package:** `@path58/p58-n8n` · **npm:** https://www.npmjs.com/package/@path58/p58-n8n · **Version:** 0.2.20-demo.3 (candidate)
|
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [0.2.20-demo.3] - 2026-06-03
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **`p58-n8n.mcpb` shipped in npm tarball** — `package.json` `files[]` now includes the Claude Desktop Extension file. Cohort recipients can download directly via `https://unpkg.com/@path58/p58-n8n@latest/p58-n8n.mcpb` (one-click) or via `npm install`. Fills the gap where demo.1/demo.2 had the .mcpb on disk and on private GitHub Release only.
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
|
|
16
|
+
- **`AGENT_INSTALL.md` v3** — restructured for clean-Mac success on first try:
|
|
17
|
+
- **Step 0 (NEW)**: client-capability self-check (sandbox / Cowork / local-agent / Claude Code CLI) — agent picks correct install path based on what it can actually do, instead of failing mid-install.
|
|
18
|
+
- **Path A — `.mcpb` (recommended)** with conversational config flow: agent calls `setup_check`, asks user one field at a time, tells them exactly which Configure form field to paste into, re-verifies between steps. No JSON editing.
|
|
19
|
+
- **Path B — JSON config (advanced)** with **mandatory absolute-`npx`-path resolution** (closes the `Failed to spawn process` bug on macOS — bare `npx` in `claude_desktop_config.json` silently fails because Claude Desktop's app PATH doesn't include `/opt/homebrew/bin/` or `~/.nvm/`).
|
|
20
|
+
- **Opportunistic demo with public-data-first priority ladder** — after `setup_check` green, agent proposes a 3-node workflow using public APIs (HackerNews / Wikipedia / OpenWeatherMap / GitHub trending) before touching user-data sources. Notion / Postgres / Airtable only with explicit user consent.
|
|
21
|
+
- **Footer version** updated to 0.2.20-demo.3.
|
|
22
|
+
|
|
23
|
+
### Fixed
|
|
24
|
+
|
|
25
|
+
- **Clean-Mac install via JSON path** no longer fails with `Failed to spawn process: No such file or directory` — agent now resolves `command -v npx` to an absolute path before writing the config field (Path B § B.2). The bare `"npx"` value in MCP config worked only when the host shell PATH bled through into Claude Desktop, which it doesn't on stock macOS.
|
|
26
|
+
|
|
8
27
|
## [0.2.20-demo.2] - 2026-06-02
|
|
9
28
|
|
|
10
29
|
### Changed
|
package/p58-n8n.mcpb
ADDED
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@path58/p58-n8n",
|
|
3
|
-
"version": "0.2.20-demo.
|
|
3
|
+
"version": "0.2.20-demo.3",
|
|
4
4
|
"description": "The smartest and fastest n8n MCP server — validate, fix, and discover workflows inside your LLM",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mcp",
|
|
@@ -27,6 +27,7 @@
|
|
|
27
27
|
"files": [
|
|
28
28
|
"dist/mcp/server.bundle.cjs",
|
|
29
29
|
"src/data/public-catalog/**/*",
|
|
30
|
+
"p58-n8n.mcpb",
|
|
30
31
|
"README.md",
|
|
31
32
|
"AGENT_INSTALL.md",
|
|
32
33
|
"CHANGELOG.md",
|