📦 deps(thirdparty): update snapshots

2026-07-22 10:09:47 +00:00
parent 316c012df0
commit 60364c6660
353 changed files with 24740 additions and 1264 deletions
@@ -0,0 +1,130 @@
+# Naming and discovery
+
+A sub-workflow nobody can find gets rebuilt. The community MCP can't read, write, or filter by tags — tags are a UI-only concept — so the **only searchable surface is the workflow's name and description**, via `n8n_list_workflows` (scan the library) and `n8n_get_workflow` (read a candidate's inputs/outputs and body). That makes naming the discovery mechanism, not a cosmetic nicety. Put your discovery hooks in the name and description deliberately.
+
+---
+
+## Tags don't help here
+
+n8n has tags in the UI, but the MCP can't see them. Don't rely on tags for AI-side discovery — anything you want re-found later has to be findable by name or description.
+
+---
+
+## The naming convention is the discovery mechanism
+
+Use verb-first prefix names. The prefix groups the library; the verb + object says what it does:
+
+```
+Subworkflow: <verb> <object>      # stateless, generic, reusable anywhere
+<Domain>: <verb> <object>         # domain-specific (Customer, Billing, Notification, …)
+Tool: <description>               # exposed as an AI-agent tool
+```
+
+Examples:
+
+- `Subworkflow: Parse RFC2822 date`
+- `Subworkflow: Compute MRR from subscription`
+- `Subworkflow: Format invoice as HTML`
+- `Customer: hydrate from Stripe`
+- `Customer: write to billing table`
+- `Billing: compute MRR`
+- `Notification: send + log`
+- `Tool: list available credentials`
+
+Why this works when the only search is name/description matching:
+
+- Scanning the list for `Subworkflow:` surfaces every reusable sub-workflow.
+- Scanning for `Customer:` surfaces every customer-domain sub-workflow.
+- Scanning for `Tool:` surfaces every agent-callable tool.
+- Scanning for `date` surfaces anything with "date" in its name or description, regardless of prefix.
+
+Put a prefix on **every** sub-workflow, at create time. It's far easier than retrofitting once callers exist.
+
+---
+
+## Search-before-build, in practice
+
+Before writing logic for a generic problem, scan the library:
+
+```
+n8n_list_workflows()                          # then filter the results by name
+n8n_get_workflow({ id: "<candidate>" })       # read description + inputs/outputs + body
+```
+
+When to look: any time you're about to build something that fits a domain or an operation keyword. About to parse a date? Look for `date`. Format an invoice? `invoice`. Send a Slack notification? `Slack` and `Notification`. Two scans is cheap; a duplicate is not.
+
+If a candidate matches, fetch it with `n8n_get_workflow` and read the `description` first — that's the contract. If the inputs/outputs fit, use it. If it's close-but-not-quite, decide whether to extend the existing one or build a deliberate variant (and name the variant so *it* is findable too).
+
+If you expected to find a workflow and it isn't showing up, the most common cause isn't naming — it's that the workflow isn't exposed to the MCP at all. Confirm it exists and is reachable before assuming it's missing.
+
+---
+
+## The description as a discoverability tool
+
+After a name match, the reader reads the `description`. Make it scan well — what it does, the output shape, the typical caller:
+
+```
+Parses an RFC2822-formatted date string into ISO format.
+Returns { ok: true, iso: "..." } or { ok: false, error: "invalid_format" }.
+Used by webhook handlers that receive email-style timestamps.
+```
+
+The description also feeds name/description matching, so seed it with representative keywords ("RFC2822", "date", "ISO", "webhook") so varied scans surface it. A sub-workflow with no description forces the reader to open and inspect every node to figure out what it is — which usually ends in them rebuilding it.
+
+---
+
+## Naming at create time
+
+Set the name and description when you create the workflow, not later:
+
+```
+n8n_update_partial_workflow({
+  id: "<new workflow id>",
+  operations: [
+    { type: "updateSettings", /* name + description carried on the workflow object */ }
+  ]
+})
+```
+
+In practice you'll set `name` and `description` on the workflow when you create it, then add the trigger and body nodes via `addNode` / `addConnection`. The point is: don't let a new sub-workflow ship without the prefix and a real description.
+
+---
+
+## What a healthy library looks like
+
+Roughly:
+
+- 5–20 `Subworkflow:` entries for common shapes (date parsing, ID generation, formatting…).
+- A handful of domain sub-workflows per main domain (`Customer:`, `Billing:`, `Notification:`).
+- Fewer per-domain "operations" sub-workflows (write to billing table, send email + log).
+
+Counter-signals:
+
+- **100 sub-workflows** → likely lots of near-duplicates to merge.
+- **0 sub-workflows** → no extraction; logic is being duplicated inline.
+- **50 entries named `Helper`, `Util1`, `Helper2`** → discoverability is broken. Rename to the prefix convention.
+
+When the user asks "what sub-workflows do we have?", scan with `n8n_list_workflows`, filter by prefix, and return a list with each name plus a one-line summary pulled from its description. That's also a good moment to spot duplicates and propose consolidating.
+
+---
+
+## Cross-project sub-workflows
+
+On Cloud or project-enabled instances, sub-workflows live inside a project, and by default a workflow can only call sub-workflows in its own project. Sharing across projects is opt-in.
+
+Only share cross-project when **both** hold:
+
+- **Stateless** — no project-scoped credentials, Data Tables, or other state that wouldn't make sense outside the owning project.
+- **Generic problem** — date parsing, ID generation, signature validation, formatting. Clearly not coupled to one project's domain.
+
+A stateful sub-workflow (`Customer: get by id`) shared across projects would pull one project's data into another's workflows, which is almost never intended. Keep those in-project and let each project own its repository layer. For ones that meet the bar, tell the user — they share via the n8n UI — and note the cross-project intent in the description.
+
+---
+
+## Renaming and reorganizing
+
+For duplicates or poorly-named sub-workflows:
+
+- **Renaming preserves the workflow ID**, so existing Execute Workflow callers (which reference the ID, not the name) keep working. The new name shows up in scans immediately.
+- n8n has no alias mechanism — just rename, update any sticky-note references inside callers, and move on.
+- For a mass rename, audit callers first: `n8n_list_workflows` to find candidates, then `n8n_get_workflow` on each to check its Execute Workflow node for the old workflow ID before you touch anything.