From 808088f25eccf3cf73a90017af9f5abdd1893886 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Romuald=20Cz=C5=82onkowski?= <56956555+czlonkowski@users.noreply.github.com> Date: Fri, 26 Dec 2025 14:50:58 +0100 Subject: [PATCH] docs: fix connection keys documentation to say "node names" not "node IDs" (#510) (#511) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The documentation incorrectly stated connection keys should be "node IDs" when n8n actually requires "node names". This caused workflow creation failures for AI-generated workflows. Changes: - tools-n8n-manager.ts: "Keys are source node names (the name field, not id)" - n8n-create-workflow.ts: "Keys are source node names (not IDs)" - Fixed example: "Webhook"/"Slack" instead of "webhook_1"/"slack_1" - get-template.ts: clarified "source node names" Closes #510 Conceived by Romuald Członkowski - https://www.aiadvisors.pl/en 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Romuald Członkowski Co-authored-by: Claude Opus 4.5 --- CHANGELOG.md | 36 +++++++++++++++++++ package.json | 2 +- src/mcp/tool-docs/templates/get-template.ts | 2 +- .../n8n-create-workflow.ts | 6 ++-- src/mcp/tools-n8n-manager.ts | 6 ++-- 5 files changed, 44 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 215b10c..1505e82 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.31.3] - 2025-12-26 + +### Fixed + +**Documentation Bug: Connection Keys Say "Node IDs" but Require "Node Names" (Issue #510)** + +Fixed documentation that incorrectly stated connection keys should be "node IDs" when n8n actually requires "node names". + +**Problem:** +The `n8n_create_workflow` documentation and examples showed using node IDs (e.g., `"webhook_1"`) as connection keys, but the validator requires node names (e.g., `"Webhook"`). This caused workflow creation failures and contributed to low success rates for AI-generated workflows. + +**Changes:** +- Updated `tools-n8n-manager.ts` parameter description: "Keys are source node names (the name field, not id)" +- Updated `n8n-create-workflow.ts` documentation: "Keys are source node names (not IDs)" +- Fixed example to use `"Webhook"` and `"Slack"` instead of `"webhook_1"` and `"slack_1"` +- Clarified `get-template.ts` return description + +**Before (incorrect):** +```javascript +connections: { + "webhook_1": { "main": [[{node: "slack_1", ...}]] } // WRONG +} +``` + +**After (correct):** +```javascript +connections: { + "Webhook": { "main": [[{node: "Slack", ...}]] } // CORRECT +} +``` + +**Impact:** +- AI models following documentation will now generate valid workflows +- Clear distinction between node `id` (internal identifier) and `name` (connection key) +- No breaking changes - validator behavior unchanged + ## [2.31.2] - 2025-12-24 ### Changed diff --git a/package.json b/package.json index 5089006..307d930 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "n8n-mcp", - "version": "2.31.2", + "version": "2.31.3", "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/src/mcp/tool-docs/templates/get-template.ts b/src/mcp/tool-docs/templates/get-template.ts index 9322531..5890645 100644 --- a/src/mcp/tool-docs/templates/get-template.ts +++ b/src/mcp/tool-docs/templates/get-template.ts @@ -42,7 +42,7 @@ export const getTemplateDoc: ToolDocumentation = { - url: Link to template on n8n.io - workflow: Complete workflow JSON with structure: - nodes: Array of node objects (id, name, type, typeVersion, position, parameters) - - connections: Object mapping source nodes to targets + - connections: Object mapping source node names to targets - settings: Workflow configuration (timezone, error handling, etc.) - usage: Instructions for using the workflow`, examples: [ diff --git a/src/mcp/tool-docs/workflow_management/n8n-create-workflow.ts b/src/mcp/tool-docs/workflow_management/n8n-create-workflow.ts index 2b6558a..0ab299e 100644 --- a/src/mcp/tool-docs/workflow_management/n8n-create-workflow.ts +++ b/src/mcp/tool-docs/workflow_management/n8n-create-workflow.ts @@ -20,7 +20,7 @@ export const n8nCreateWorkflowDoc: ToolDocumentation = { parameters: { name: { type: 'string', required: true, description: 'Workflow name' }, nodes: { type: 'array', required: true, description: 'Array of nodes with id, name, type, typeVersion, position, parameters' }, - connections: { type: 'object', required: true, description: 'Node connections. Keys are source node IDs' }, + connections: { type: 'object', required: true, description: 'Node connections. Keys are source node names (not IDs)' }, settings: { type: 'object', description: 'Optional workflow settings (timezone, error handling, etc.)' } }, returns: 'Minimal summary (id, name, active, nodeCount) for token efficiency. Use n8n_get_workflow with mode "structure" to verify current state if needed.', @@ -55,8 +55,8 @@ n8n_create_workflow({ } ], connections: { - "webhook_1": { - "main": [[{node: "slack_1", type: "main", index: 0}]] + "Webhook": { + "main": [[{node: "Slack", type: "main", index: 0}]] } } })`, diff --git a/src/mcp/tools-n8n-manager.ts b/src/mcp/tools-n8n-manager.ts index 0a69aea..55ac582 100644 --- a/src/mcp/tools-n8n-manager.ts +++ b/src/mcp/tools-n8n-manager.ts @@ -46,9 +46,9 @@ export const n8nManagementTools: ToolDefinition[] = [ } } }, - connections: { - type: 'object', - description: 'Workflow connections object. Keys are source node IDs, values define output connections' + connections: { + type: 'object', + description: 'Workflow connections object. Keys are source node names (the name field, not id), values define output connections' }, settings: { type: 'object',