@ericrisco/rsc 0.1.36 → 0.1.38

package/skills/make/references/make-mcp-and-auth.md

@@ -0,0 +1,101 @@
+# Make MCP server & auth setup
+
+The Make MCP server exposes your Make account to an MCP client (Claude, Cursor,
+ChatGPT, or any MCP-capable agent) so it can run — and, on paid plans, manage —
+scenarios as tools. It is **GA and free on every plan**; you pay only the normal
+scenario **credits** each run consumes. Verify specifics at
+[developers.make.com/mcp-server](https://developers.make.com/mcp-server) at
+author time — tool names and transports move.
+
+## Transports
+
+Two ways to authenticate the connection:
+
+### OAuth (remote, recommended for end users)
+
+Point the client at the hosted endpoint:
+
+```
+https://mcp.make.com            # stateless (default)
+https://mcp.make.com/stream     # streamable HTTP
+https://mcp.make.com/sse        # server-sent events
+```
+
+The client runs an OAuth consent flow; the **scopes you grant at consent decide
+which tools appear**. No token to manage by hand.
+
+### MCP token (per-zone URL)
+
+Generate an **MCP token** in Make (Profile → API/SDK) and embed it in a zoned URL:
+
+```
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stateless
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/stream
+https://{zone}.make.com/mcp/u/{MCP_TOKEN}/sse
+```
+
+- `{zone}` is your org's zone (`eu1|eu2|us1|us2`, + `celonis`) — same **zone
+  trap** as the REST API: wrong zone = auth failure.
+- The MCP token is **separate** from the REST API token.
+
+### Timeout — pick the transport by run length
+
+| Transport | Timeout | Use for |
+|---|---|---|
+| `/stateless` | ~60 s | quick scenarios, simple clients |
+| `/stream` | ~5 min 20 s | long-running scenarios |
+| `/sse` | ~5 min 20 s | streaming clients |
+
+A scenario that takes longer than 60 s on `/stateless` will time out — use
+`/stream` or `/sse`.
+
+## Tool tiers
+
+Exact tool names change; confirm in the client's tool list. The **tiers** are
+stable:
+
+- **Run tools — all plans.** List the account's on-demand scenarios and execute
+  a chosen one with inputs, returning its output bundle. This is what lets an
+  agent *use* an automation you built.
+- **Management tools — paid plans only.** View and modify scenarios,
+  connections, hooks, data stores, teams, and organizations — effectively the
+  REST CRUD surfaced as MCP tools. On a free plan these do not appear.
+
+On the OAuth transport, missing scopes (not just plan tier) can also hide tools.
+
+## Client config sketches
+
+Token transport (generic `mcpServers` block; adapt to your client):
+
+```json
+{
+  "mcpServers": {
+    "make": {
+      "url": "https://eu2.make.com/mcp/u/${MAKE_MCP_TOKEN}/stream"
+    }
+  }
+}
+```
+
+For stdio-only clients, bridge a streamable-HTTP URL to stdio with a proxy such
+as `mcp-proxy`.
+
+## Legacy local server
+
+`integromat/make-mcp-server` is the **older local stdio** server. It runs as a
+local process and exposes your on-demand scenarios as tools over stdio. It
+predates the cloud server; prefer the cloud MCP unless you specifically need a
+local, offline-ish process (e.g. an air-gapped client that cannot reach
+`mcp.make.com`).
+
+## Credits, not a free lunch
+
+The MCP *server* is free, but every scenario an MCP call runs burns the same
+**credits** as any other run. An agent that loops over a run tool can quietly
+drain credits — cap it the way you would any autonomous consumer.
+
+## When NOT to use MCP
+
+If the operator is your own deterministic script/CI, the REST API v2 is simpler
+and fully controllable — MCP earns its keep only when an **agent** is the one
+driving Make.

package/skills/n8n/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: n8n
+description: "Use when operating a live n8n instance programmatically — driving its public REST API (`{host}/api/v1`, `X-N8N-API-KEY`) or the n8n-mcp server to create, validate, test, activate/deactivate, list, update, or delete workflows and read executions, on self-host or `*.app.n8n.cloud`. Triggers: 'deploy this workflow to my n8n over the API', 'push my workflow JSON to n8n with curl', 'I set active:true in the create call but it stays inactive', 'connect n8n-mcp / n8n_create_workflow to Claude', 'validate and autofix my n8n workflow', 'run an n8n workflow by id from a script', 'delete a workflow via the API', 'automatiza n8n por API', 'desplega el workflow a n8n.cloud'. NOT designing the flow's trigger-step-error logic or hand-building the importable workflow JSON (that is automation-flows), NOT operating Make / Zapier / Power Automate (their own skills), NOT a typed API client with auth+pagination+retry (api-connector-builder), NOT the inbound webhook receiver in your own app (webhooks)."
+tags: [n8n, automation, workflows, mcp, rest-api, no-code, integrations]
+recommends: [automation-flows, automation-strategy, api-connector-builder, webhooks]
+profiles: [full]
+origin: risco
+---
+
+# n8n — operate a live instance over its REST API and MCP
+
+You already have a workflow *design* (the trigger→steps→error shape and the importable JSON).
+This skill is the **operate** half: push that JSON into a running n8n, validate it, test it, flip it
+live, watch its executions, and tear it down safely — all without touching the UI. n8n has the
+richest programmatic story of the no-code platforms: a first-party REST API **plus** a mature MCP
+server, both hitting the same instance.
+
+Designing the flow itself (what fires it, how errors are handled, dedup) is **automation-flows** —
+this skill *consumes* that skill's `references/n8n-workflow-json.md` payload; it does not re-teach
+design.
+
+## Connect first — REST API vs MCP
+
+Two ways to drive the same instance. Pick by who is at the wheel.
+
+| | **Public REST API** | **n8n-mcp** (czlonkowski, de-facto standard) |
+|---|---|---|
+| What it is | n8n's own HTTP API at `{host}/api/v1` | MCP server wrapping that API **+** offline node/expression knowledge |
+| Best for | scripts, CI/CD, deterministic deploys, no extra dependency | an agent (Claude) building/fixing workflows in the loop — it can look up node schemas, then validate/autofix before it writes |
+| Auth | API key in header `X-N8N-API-KEY` | management tools need `N8N_API_URL` + `N8N_API_KEY`; **node-knowledge tools need no auth** |
+| Surface | identical on self-host **and** `*.app.n8n.cloud` | same underlying API; hosted trial at `dashboard.n8n-mcp.com` |
+
+**Version reality (verify at author time — n8n moves fast):**
+- API base is `{host}/api/v1`. Self-host ships interactive Swagger at `/api/v1/docs`; **cloud does not**.
+- `POST /workflows/{id}/execute` (run-by-id) is **recent** (n8n PR #20234). Older instances lack it —
+  there, the only programmatic run is POSTing to a Webhook node's URL. It also takes **no custom input**.
+- The API surface is the SAME whether you self-host or run on `*.app.n8n.cloud`; only the host differs.
+
+### `.env`
+
+```bash
+# host root only — you append /api/v1 for REST; n8n-mcp reads it whole
+N8N_API_URL=https://your-instance.app.n8n.cloud   # or N8N_HOST for self-host, e.g. http://localhost:5678
+N8N_API_KEY=n8n_api_...                            # Settings → n8n API → Create an API key
+```
+
+Never inline the key in a command that gets logged, and never put a *node* credential (Slack token,
+etc.) in the workflow payload — reference it by the n8n **credential store** id/name (see
+automation-flows' JSON schema). Full key-creation + self-host vs cloud + MCP install:
+`references/auth-and-selfhost.md`.
+
+## The payload you POST
+
+The create/update body is exactly the automation-flows workflow JSON. Required top-level keys on
+**create**: `name`, `nodes`, `connections`, `settings`. Build it per
+`../automation-flows/references/n8n-workflow-json.md` — non-empty `nodes` with one trigger, a wired
+`connections` map, `settings.errorWorkflow`, credentials referenced by store (never inlined).
+
+**Node/expression essentials** (pointer, not a tutorial): node `type` is namespaced
+(`n8n-nodes-base.webhook`), `typeVersion` must match a node version installed on the target instance
+or activation/execution fails; field values use expressions like `={{ $json.email }}` or
+`={{ $node["Webhook"].json.body.id }}`. If you are hand-authoring nodes, let n8n-mcp's node-knowledge
+tools (`search_nodes`, `get_node_essentials`, `validate_node_operation`) fill in the exact property
+shapes rather than guessing — that is the single biggest reason to drive via MCP.
+
+## Dynamic lifecycle
+
+create → **validate** → test → **activate** → manage → delete. A concrete sketch per step, curl and
+n8n-mcp side by side.
+
+### 1. Validate (do this BEFORE create)
+
+REST has no validation endpoint — n8n only tells you at create/activate time. MCP does, so validate
+first when it is available:
+
+```
+n8n_validate_workflow   { "workflow": { …the full JSON… } }
+n8n_autofix_workflow    { "workflow": { … } }   # repairs common structural errors, returns fixed JSON
+```
+
+### 2. Create
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows" \
+  -H "X-N8N-API-KEY: $N8N_API_KEY" -H "Content-Type: application/json" \
+  -d @workflow.json          # body = { name, nodes, connections, settings }
+# → returns the created workflow WITH its "id" — capture it for every step below
+```
+```
+n8n_create_workflow     { "name": "...", "nodes": [ … ], "connections": { … }, "settings": { … } }
+```
+
+### 3. Test / dry-run
+
+- **No input needed** → run by id (recent instances only): `POST /workflows/{id}/execute`.
+- **Needs input** → the execute endpoint accepts none. Make the trigger a **Webhook node** and POST to
+  its URL (test URL `/webhook-test/<path>` while "Listen for test event" is armed; production
+  `/webhook/<path>` once active).
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/execute" -H "X-N8N-API-KEY: $N8N_API_KEY"
+curl -sS -X POST "$N8N_HOST/webhook-test/my-path" -H "Content-Type: application/json" -d '{"foo":"bar"}'
+```
+```
+n8n_test_workflow       { "id": "$ID" }
+```
+
+### 4. Activate — the step people miss
+
+`active` in the create/update body is **read-only and silently ignored**. Setting `"active": true`
+does nothing. You MUST call the separate endpoint:
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate"   -H "X-N8N-API-KEY: $N8N_API_KEY"
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/deactivate" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+n8n-mcp deliberately does not expose activate/deactivate as tools (activation has live side effects).
+Check the current tool list; if absent, call the REST `/activate` endpoint as above.
+
+### 5. Manage
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/workflows?limit=50"      -H "X-N8N-API-KEY: $N8N_API_KEY"  # list (paginate via nextCursor)
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID"           -H "X-N8N-API-KEY: $N8N_API_KEY"  # get
+curl -sS -X PUT "$N8N_API_URL/api/v1/workflows/$ID"    -H "X-N8N-API-KEY: $N8N_API_KEY" \
+  -H "Content-Type: application/json" -d @workflow.json                                  # FULL replace
+curl -sS "$N8N_API_URL/api/v1/executions?workflowId=$ID&limit=20" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+```
+n8n_list_workflows {}        n8n_get_workflow { "id": "$ID" }        n8n_executions { "workflowId": "$ID" }
+n8n_update_full_workflow    { "id": "$ID", "nodes": [ … ], "connections": { … } }   # replace everything
+n8n_update_partial_workflow { "id": "$ID", "operations": [ … ] }                    # atomic diff — preferred
+n8n_health_check {}          # confirm API reachable + which features the instance supports
+```
+`PUT` is a **full replace** — GET, mutate the whole object, PUT it back, or you drop the nodes you
+omitted. n8n-mcp's `n8n_update_partial_workflow` applies a targeted, atomic batch instead (safer).
+
+### 6. Delete — irreversible
+
+`DELETE` is a **hard delete: no trash, no undo.** Export the current JSON first, every time.
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY" > backup-$ID.json  # export FIRST
+curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" -H "X-N8N-API-KEY: $N8N_API_KEY"
+```
+```
+n8n_get_workflow { "id": "$ID" }   →  save output  →  n8n_delete_workflow { "id": "$ID" }
+```
+
+**Irreversibility rule:** never DELETE (or full-replace) a live workflow without exporting it first.
+
+## Governance
+
+If you expose n8n-mcp to an agent, lock down destructive tools with the `DISABLED_TOOLS` env var
+(comma-separated), e.g. `DISABLED_TOOLS=n8n_delete_workflow,n8n_update_full_workflow`. Scope the API
+key itself too — n8n supports scoped keys (e.g. grant `workflow:read` without `workflow:execute`).
+Details in `references/n8n-mcp-tools.md`.
+
+## Honesty / gotchas
+
+- **`active` and `tags` are read-only on create/update** — ignored in the body; activate/tag via the
+  dedicated endpoints. This is the #1 "why is my workflow inactive" bug.
+- **`/workflows/{id}/execute` takes no custom input** — for runtime params, trigger a Webhook workflow
+  by POSTing to its URL. Also, it is a newer endpoint; older instances 404 it.
+- **`DELETE` and `PUT` are destructive** — hard delete (no trash) and full replace. Export first; prefer
+  `n8n_update_partial_workflow` for edits.
+- **`typeVersion` must exist on the target** — a node version the instance doesn't have fails only at
+  activate/execute time, not at create. Validate (MCP) or test before activating.
+- **Credential secrets are not fully manageable over the public API** — you can reference existing
+  credentials by id/name and create some, but you cannot read secrets back; provision credentials in
+  the UI / n8n-mcp `n8n_manage_credentials` and reference them.
+- **Cloud has no Swagger** — `/api/v1/docs` is self-host only; on cloud, work from the docs.
+- **Activation can succeed via API where the UI would block it** — the public API historically skips a
+  few UI-side activation validations, so a workflow can be "active" yet non-functional. Test it live.
+
+## Related skills
+
+- **automation-flows** — *design* the flow and produce the importable JSON this skill deploys. Design
+  vs operate boundary: they decide the trigger/steps/error path; you push it live. Start there if the
+  flow's logic isn't settled yet.
+- **automation-strategy** — whether n8n is even the right platform (cost model, self-host vs cloud) vs
+  Make/Zapier/Power Automate.
+- **make / zapier / power-automate** — the other platforms' operate stories (Zapier and Power Automate
+  can't create flows via API — n8n's edge).
+- **api-connector-builder** — a generic typed HTTP client with auth/pagination/backoff, when the answer
+  is real code, not a workflow.
+- **webhooks** — building the inbound receiver *in your own app*; here webhooks are just n8n triggers.
+
+## Checklist
+
+- [ ] `.env` has `N8N_API_URL`/`N8N_HOST` + `N8N_API_KEY` (key from Settings → n8n API); key not logged.
+- [ ] Payload has `name`, `nodes` (one trigger), `connections`, `settings` per automation-flows' schema;
+      node credentials referenced by store, never inlined.
+- [ ] Validated (`n8n_validate_workflow` / `n8n_autofix_workflow`) before create when MCP is available.
+- [ ] Created via `POST /workflows` or `n8n_create_workflow`; captured the returned `id`.
+- [ ] Tested — `execute`-by-id (no input) or POST to the webhook URL (with input) — and the run succeeded.
+- [ ] Activated via `POST /workflows/{id}/activate` (NOT `active:true` in the body).
+- [ ] Before any DELETE or full-replace: exported the current JSON (hard delete, no trash).
+- [ ] If MCP is exposed to an agent: `DISABLED_TOOLS` set and/or the API key scoped.
+
+## References
+
+- `references/rest-api-cheatsheet.md` — every workflow/execution endpoint with curl, pagination, scopes.
+- `references/n8n-mcp-tools.md` — the management + node-knowledge tool list, the auth split, `DISABLED_TOOLS`.
+- `references/auth-and-selfhost.md` — API-key creation, self-host vs cloud, Swagger, installing/pointing n8n-mcp.

package/skills/n8n/evals/README.md

@@ -0,0 +1,14 @@
+# Evals — n8n
+
+`cases.yaml` has three groups. `should_trigger` covers the operate tasks this skill owns: deploying a
+workflow JSON over the REST API, the read-only-`active` gotcha, wiring n8n-mcp management tools,
+running a workflow by id, hard-delete safety, and validate/autofix — with a Spanish phrasing. Each
+`should_not_trigger` names a real sibling: flow design + importable JSON → automation-flows,
+platform/cost choice → automation-strategy, another platform → make, a typed code client →
+api-connector-builder, an in-app inbound receiver → webhooks. `capability` is one end-to-end deploy
+scenario whose `must_include` rubric pins the current API/MCP calls, the honesty limits (read-only
+`active`, no-input `execute`), and the irreversibility rule (export before hard delete).
+
+No automated runner. Score by judgement: feed each `should_trigger`/`should_not_trigger` prompt to the
+routing layer and confirm it activates or routes to the listed sibling; for `capability`, have the
+skill produce the deploy plan/commands and check every `must_include` bullet by hand.

package/skills/n8n/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: n8n
+
+should_trigger:
+  - prompt: "Push my workflow JSON to n8n over the API with curl and turn it on."
+    why: Canonical operate task — POST /workflows then the separate /activate endpoint. Core deliverable.
+  - prompt: "I set active:true in my POST to /api/v1/workflows but the workflow stays inactive. Why?"
+    why: The read-only-active gotcha — active/tags are ignored on create; must call /workflows/{id}/activate.
+  - prompt: "Wire n8n-mcp into Claude Code so it can call n8n_create_workflow and n8n_update_partial_workflow against my instance."
+    why: MCP operate path — configuring the management tier with N8N_API_URL + N8N_API_KEY.
+  - prompt: "How do I run an n8n workflow by its id from a shell script, and can I pass it input data?"
+    why: POST /workflows/{id}/execute (recent) plus the no-custom-input limit → webhook trigger for params.
+  - prompt: "Delete this workflow from my n8n via the API — is there an undo?"
+    why: Hard-delete irreversibility; must export (GET) first, no trash.
+  - prompt: "desplega este workflow a mi n8n.cloud por la API y valídalo antes de activarlo"
+    why: Spanish; programmatic deploy + validate + activate against cloud — same REST surface.
+  - prompt: "Validate and autofix my n8n workflow before I create it, then list its executions."
+    why: n8n_validate_workflow / n8n_autofix_workflow then n8n_executions — MCP management lifecycle.
+
+should_not_trigger:
+  - prompt: "Design an n8n flow: Stripe payment → Notion row → Slack, with an error path and dedup. Give me the importable JSON."
+    route_to: automation-flows
+    why: Designing the trigger/steps/error shape and producing the JSON is automation-flows; this skill only deploys/operates that JSON.
+  - prompt: "Should I use n8n, Make, or Zapier for 50k runs a month, and self-host or cloud?"
+    route_to: automation-strategy
+    why: Platform/cost-model selection, not operating a specific live n8n instance.
+  - prompt: "Create this scenario in my Make account programmatically."
+    route_to: make
+    why: Operating a different platform (Make) — its own skill; Make also has no create-via-API story like n8n's.
+  - prompt: "Write a TypeScript client for the Acme REST API with API-key auth, cursor pagination, and exponential backoff."
+    route_to: api-connector-builder
+    why: A typed HTTP client in code, not driving n8n's API or MCP.
+  - prompt: "Build the endpoint in my Express app that receives and verifies inbound webhook signatures."
+    route_to: webhooks
+    why: An inbound receiver in the user's own app; here webhooks are only n8n triggers, not something this skill builds.
+
+capability:
+  - scenario: "User has an importable n8n workflow JSON (webhook trigger → HTTP node → Slack) and wants it deployed to their n8n.cloud instance: created, tested, activated, and later safely removed — via the REST API and/or n8n-mcp."
+    must_include:
+      - "Reads N8N_API_URL/N8N_HOST + N8N_API_KEY from env; key from Settings → n8n API; sends it as the X-N8N-API-KEY header (not a bearer token)."
+      - "Builds the create body per automation-flows' n8n-workflow-json schema (name, nodes, connections, settings); node credentials referenced by the credential store, never inlined."
+      - "Creates with POST /workflows (or n8n_create_workflow) and captures the returned id for subsequent calls."
+      - "States that active (and tags) are read-only on create/update and activates with a separate POST /workflows/{id}/activate."
+      - "Notes POST /workflows/{id}/execute takes no custom input (and is a recent endpoint), so runtime params require POSTing to a Webhook node URL."
+      - "Exports the workflow (GET /workflows/{id}) before any DELETE, and states DELETE is a hard delete with no trash."
+      - "When driving via MCP, validates/autofixes (n8n_validate_workflow / n8n_autofix_workflow) before create; notes management tools need the two env vars while node-knowledge tools do not."

package/skills/n8n/references/auth-and-selfhost.md

@@ -0,0 +1,62 @@
+# n8n auth, self-host vs cloud, and pointing n8n-mcp
+
+## Get an API key
+
+1. In n8n, open **Settings → n8n API**.
+2. **Create an API key.** Prefer a **scoped** key — pick only the resource scopes the automation needs
+   (e.g. `workflow:read`, `workflow:create`, `workflow:execute`, `execution:read`). An unscoped key can
+   do everything the user can, including delete.
+3. Copy it once (it is shown once) and store it as `N8N_API_KEY`. Rotate by deleting + recreating.
+
+Every REST call carries it as a header: `X-N8N-API-KEY: <key>`. It is NOT a bearer token and NOT in
+the query string.
+
+```bash
+export N8N_API_KEY="n8n_api_..."
+export N8N_API_URL="https://your-instance.app.n8n.cloud"   # host root; append /api/v1 for REST
+```
+
+## Self-host vs cloud — what actually differs
+
+| | Self-host | Cloud (`*.app.n8n.cloud`) |
+|---|---|---|
+| API base | `{host}/api/v1` (e.g. `http://localhost:5678/api/v1`) | `https://<tenant>.app.n8n.cloud/api/v1` |
+| API surface | **identical** | **identical** |
+| Interactive Swagger | **Yes** at `/api/v1/docs` | **No** — work from docs.n8n.io |
+| Where data lives | your infra | n8n's | 
+| Enabling the API | on by default; can be toggled via `N8N_PUBLIC_API_DISABLED=true` | always on |
+| Base URL override | `WEBHOOK_URL` / `N8N_HOST`/`N8N_PROTOCOL`/`N8N_PORT` shape the host + webhook URLs | fixed |
+
+The only thing that changes between environments is the host and (self-host) the Swagger page.
+Scripts written against one work against the other by swapping `N8N_API_URL`.
+
+Webhook URLs on self-host derive from `WEBHOOK_URL` (or host/protocol/port). If your production webhook
+URLs look wrong (localhost behind a proxy), that env var is usually why.
+
+## Pointing n8n-mcp at your instance
+
+`n8n-mcp` reads the **same two env vars** for its management tier:
+
+```bash
+N8N_API_URL=https://your-instance.app.n8n.cloud
+N8N_API_KEY=n8n_api_...
+```
+
+Ways to run it:
+
+- **Hosted** — `dashboard.n8n-mcp.com`: add an instance (URL + key), get an MCP endpoint. Fastest trial;
+  free tier caps daily tool calls.
+- **Local (npx)** — run the `n8n-mcp` package and register it in your MCP client's config
+  (Claude Code / Claude Desktop / Cursor / Windsurf), passing the two env vars.
+- **Docker** — the repo ships an image; inject the env vars.
+
+Node-knowledge tools work with **no** auth; only the management tools need the two vars. Confirm the
+link with `n8n_health_check` — it reports reachability and which features (e.g. the `/execute`
+endpoint) the target instance supports.
+
+## Governance quick-set
+
+- **Scope the key** at creation (least privilege) — see above.
+- **`DISABLED_TOOLS`** on n8n-mcp to gate destructive tools — see `n8n-mcp-tools.md`.
+- **Never** commit `N8N_API_KEY` or inline node-credential secrets in a workflow payload; reference
+  credentials from the n8n credential store by id/name.

package/skills/n8n/references/n8n-mcp-tools.md

@@ -0,0 +1,84 @@
+# n8n-mcp — tool reference & governance
+
+`n8n-mcp` (github.com/czlonkowski/n8n-mcp, ~22k★, the de-facto community standard) is an MCP server
+that gives an agent two things: **offline knowledge** of n8n's node/expression catalogue, and
+**management** of a live instance via its REST API. Distinct from n8n's own first-party built-in MCP
+node, which lets a *workflow* act as an MCP server/client — that is not this.
+
+Tool names and counts move; **verify against the running server's tool list** (or
+`dashboard.n8n-mcp.com` / the repo docs) before relying on any one name.
+
+## Two tiers, two auth requirements
+
+| Tier | Needs auth? | Purpose |
+|---|---|---|
+| **Node-knowledge tools** | **No** | Search/describe nodes, get property essentials, validate a node's config, browse templates — all offline. Safe to expose broadly. |
+| **Management tools** | **Yes** — `N8N_API_URL` + `N8N_API_KEY` | CRUD/validate/test/run/inspect a real instance. These are the ones governance applies to. |
+
+Set the same two env vars the REST API uses:
+
+```bash
+N8N_API_URL=https://your-instance.app.n8n.cloud   # host root, whole value
+N8N_API_KEY=n8n_api_...
+```
+
+Without them the server still runs — you just get the node-knowledge tier only.
+
+## Node-knowledge tools (no auth)
+
+- `search_nodes`, `list_nodes`, `list_ai_tools` — find the right node.
+- `get_node_essentials`, `get_node_info`, `get_node_documentation` — properties & docs for a node type.
+- `validate_node_operation`, `validate_node_minimal` — check a single node's config before you wire it.
+- `search_templates`, `get_template` — reuse community workflow templates.
+
+Use these to author node JSON correctly instead of guessing `typeVersion`/property shapes.
+
+## Management tools (need `N8N_API_URL` + `N8N_API_KEY`)
+
+| Tool | Does |
+|---|---|
+| `n8n_create_workflow` | Create from a full workflow object. |
+| `n8n_get_workflow` | Fetch one workflow (export before delete/replace). |
+| `n8n_list_workflows` | List/filter workflows. |
+| `n8n_update_full_workflow` | Replace the whole workflow (like REST `PUT`). |
+| `n8n_update_partial_workflow` | **Atomic ordered batch of targeted edits** — if any op fails, nothing is saved. Prefer this for edits. |
+| `n8n_delete_workflow` | **Hard delete.** Export first. |
+| `n8n_validate_workflow` | Structural/connection/expression validation of a workflow object. |
+| `n8n_autofix_workflow` | Repair common errors and return fixed JSON. |
+| `n8n_test_workflow` | Trigger a run for testing. |
+| `n8n_executions` | List/inspect execution runs. |
+| `n8n_workflow_versions` | Version history of a workflow. |
+| `n8n_deploy_template` | Deploy a catalogue template to the instance. |
+| `n8n_manage_credentials` | Create/manage credentials (secrets not readable back). |
+| `n8n_manage_datatable` | Manage n8n data tables. |
+| `n8n_health_check` | Confirm API reachability + which features the instance supports. |
+| `n8n_audit_instance` | Security audit (built-in audit API + deep workflow scan). |
+
+**Note on activate/deactivate:** n8n-mcp intentionally does not surface these as tools (activation has
+live side effects). Flip a workflow live with the REST `POST /workflows/{id}/activate` endpoint (see
+`rest-api-cheatsheet.md`) or the UI. Verify the current tool list in case this changes.
+
+## Governance — `DISABLED_TOOLS`
+
+For agent-facing deployments, disable destructive/write tools with a comma-separated env var:
+
+```bash
+# read-only agent: no create/replace/delete/autofix/test/template/credential/datatable writes
+DISABLED_TOOLS=n8n_create_workflow,n8n_update_full_workflow,n8n_update_partial_workflow,n8n_delete_workflow,n8n_autofix_workflow,n8n_deploy_template,n8n_test_workflow,n8n_manage_credentials,n8n_manage_datatable
+```
+
+Layer it with a **scoped API key** (grant only `workflow:read`/`execution:read` for a monitoring
+agent) so a disabled tool can't be worked around and the key itself can't mutate. Two independent
+locks: the tool gate and the key scope.
+
+## Sketch: agent-driven deploy
+
+```
+search_nodes / get_node_essentials     → get the exact node property shapes
+n8n_validate_workflow { workflow }      → catch structural errors offline
+n8n_autofix_workflow  { workflow }      → auto-repair, re-validate
+n8n_create_workflow   { name, nodes, connections, settings }  → capture returned id
+n8n_test_workflow     { id }            → confirm it runs
+# then activate via REST /workflows/{id}/activate (no MCP tool for it)
+n8n_executions        { workflowId: id } → confirm the live run
+```

package/skills/n8n/references/rest-api-cheatsheet.md

@@ -0,0 +1,94 @@
+# n8n public REST API — cheat sheet
+
+Base URL: `{host}/api/v1`. Auth header on every call: `X-N8N-API-KEY: $N8N_API_KEY`.
+Same surface on self-host and `*.app.n8n.cloud`. Self-host has interactive Swagger at
+`{host}/api/v1/docs`; cloud does not. Verify shapes at author time — n8n ships often.
+
+Set once:
+
+```bash
+export N8N_API_URL="https://your-instance.app.n8n.cloud"   # or http://localhost:5678
+export N8N_API_KEY="n8n_api_..."
+auth=(-H "X-N8N-API-KEY: $N8N_API_KEY")
+```
+
+## Workflows
+
+| Verb & path | What it does | Notes |
+|---|---|---|
+| `POST /workflows` | Create | Body needs `name, nodes, connections, settings`. `active` + `tags` in the body are **ignored** (read-only). Returns the new object incl. `id`. |
+| `GET /workflows/{id}` | Get one | The full exportable JSON. Use to back up before delete/replace. |
+| `GET /workflows` | List | Query: `limit` (default ~100), `cursor`, `active=true|false`, `tags`, `name`, `projectId`. Paginate with the returned `nextCursor`. |
+| `PUT /workflows/{id}` | **Full replace** | Send the WHOLE object; omitted fields are dropped. GET → mutate → PUT. |
+| `DELETE /workflows/{id}` | **Hard delete** | No trash, no undo. Export first. |
+| `POST /workflows/{id}/activate` | Activate | The ONLY way to go live — the body `active` flag never does it. |
+| `POST /workflows/{id}/deactivate` | Deactivate | Same, in reverse. |
+| `POST /workflows/{id}/execute` | Run by id | **Recent (PR #20234); older instances 404.** Runs `executeManually`; **accepts no custom input** — needs `workflow:execute` scope. |
+| `PUT /workflows/{id}/tags` | Set tags | Tags are managed here, not in the create/update body. |
+| `PUT /workflows/{id}/transfer` | Move to a project | Enterprise/projects. |
+
+```bash
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows" "${auth[@]}" \
+  -H "Content-Type: application/json" -d @workflow.json
+curl -sS "$N8N_API_URL/api/v1/workflows?limit=50&active=true" "${auth[@]}"
+curl -sS "$N8N_API_URL/api/v1/workflows/$ID" "${auth[@]}" > backup-$ID.json
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/activate" "${auth[@]}"
+curl -sS -X POST "$N8N_API_URL/api/v1/workflows/$ID/execute"  "${auth[@]}"
+curl -sS -X DELETE "$N8N_API_URL/api/v1/workflows/$ID" "${auth[@]}"
+```
+
+Paginate:
+
+```bash
+cursor=""
+while :; do
+  page=$(curl -sS "$N8N_API_URL/api/v1/workflows?limit=100&cursor=$cursor" "${auth[@]}")
+  echo "$page" | jq -r '.data[].id'
+  cursor=$(echo "$page" | jq -r '.nextCursor // empty')
+  [ -z "$cursor" ] && break
+done
+```
+
+## Executions
+
+| Verb & path | What it does |
+|---|---|
+| `GET /executions` | List runs. Query: `workflowId`, `status` (`success|error|waiting`), `limit`, `cursor`, `includeData=true`. |
+| `GET /executions/{id}` | One run; `?includeData=true` for the full item data. |
+| `DELETE /executions/{id}` | Delete a run's stored data. |
+
+```bash
+curl -sS "$N8N_API_URL/api/v1/executions?workflowId=$ID&status=error&limit=20" "${auth[@]}"
+```
+
+## Triggering a run WITH input
+
+`/execute` takes no body data. To pass runtime params, the workflow's trigger must be a **Webhook**
+node; POST to its URL:
+
+- Test URL (only while the editor's "Listen for test event" is armed): `{host}/webhook-test/<path>`
+- Production URL (only once the workflow is active): `{host}/webhook/<path>`
+
+```bash
+curl -sS -X POST "$N8N_HOST/webhook/my-path" -H "Content-Type: application/json" -d '{"orderId":123}'
+```
+
+## Other resources
+
+- `GET/POST/DELETE /credentials` — create/delete credentials and `GET /credentials/schema/{type}` for
+  the field shape. **You cannot read secrets back.** Reference existing creds from a workflow by id/name.
+- `GET/POST/PUT/DELETE /tags`, `/projects`, `/variables`, `/users` (admin), `/source-control/pull`,
+  `/audit` (instance security audit).
+
+## API-key scopes (least privilege)
+
+Create a **scoped** key in Settings → n8n API. Scopes are grouped by resource, e.g. `workflow:read`,
+`workflow:create`, `workflow:update`, `workflow:delete`, `workflow:execute`, `execution:read`,
+`credential:create`, `tag:*`. Grant only what a given automation needs — e.g. a read-only dashboard
+key gets `workflow:read` + `execution:read` and nothing that can mutate or run.
+
+## Error responses
+
+`401` bad/missing key · `403` key lacks the scope · `404` no such id (or `/execute` on an instance
+too old to have it) · `400` malformed body (e.g. missing `connections`) · `500` server-side (often a
+node the instance doesn't have installed).