ros/n8n-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(tools): rename start_here to tools_documentation with depth control (v2.7.4)

Browse Source 
- Renamed start_here_workflow_guide to tools_documentation for clarity
- Added depth parameter to control documentation detail (essentials/full)
- Converted output from JSON to LLM-friendly plain text format
- Added per-tool documentation capability
- Created two-tier documentation system:
  - Essentials: brief info with key parameters and tips
  - Full: comprehensive docs with examples and best practices
- Documented 8 commonly used MCP tools
- Removed 380+ lines of unused getWorkflowGuide method
- Fixed duplicate tool definitions
- Updated all documentation references
- Added test script for tools documentation

BREAKING CHANGE: start_here_workflow_guide renamed to tools_documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-07-03 23:22:26 +02:00
parent e9ea15ef09
commit b73cffc27f
12 changed files with 1662 additions and 392 deletions
Download Patch File Download Diff File Expand all files Collapse all files

388
src/mcp/server.ts
View File

@@ -24,6 +24,7 @@ import { WorkflowValidator } from '../services/workflow-validator';
import { isN8nApiConfigured } from '../config/n8n-api';
import * as n8nHandlers from './handlers-n8n-manager';
import { handleUpdatePartialWorkflow } from './handlers-workflow-diff';
import { getToolDocumentation, getToolsOverview } from './tools-documentation';
import { PROJECT_VERSION } from '../utils/version';
interface NodeRow {
@@ -191,8 +192,8 @@ export class N8NDocumentationMCPServer {
async executeTool(name: string, args: any): Promise<any> {
switch (name) {
case 'start_here_workflow_guide':
return this.getWorkflowGuide(args.topic);
case 'tools_documentation':
return this.getToolsDocumentation(args.topic, args.depth);
case 'list_nodes':
return this.listNodes(args);
case 'get_node_info':
@@ -1180,385 +1181,14 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
};
}
private async getWorkflowGuide(topic?: string): Promise<any> {
const guides: Record<string, any> = {
overview: {
title: "n8n MCP Tools Quick Start Guide",
sections: {
recommended_workflow: {
title: "Recommended Workflow",
steps: [
"1. search_nodes({query:'slack'}) - Find nodes by keyword",
"2. get_node_essentials('nodes-base.slack') - Get only essential properties (<5KB)",
"3. get_node_for_task('send_slack_message') - Get pre-configured settings",
"4. validate_node_minimal() - Quick check for required fields only",
"5. validate_node_operation() - Full validation with suggestions"
],
tip: "Avoid get_node_info unless you need ALL properties (100KB+ response)"
},
essential_tools: {
discovery: "list_nodes({category:'trigger'}) - Browse by category",
quick_config: "get_node_essentials() - 95% smaller than get_node_info",
tasks: "list_tasks() then get_node_for_task() - Pre-configured common tasks",
validation: "validate_node_minimal() for quick checks, validate_node_operation() for full validation",
ai_tools: "get_node_as_tool_info() - Learn how to use ANY node as an AI tool",
management: "n8n_create_workflow, n8n_list_workflows - Manage workflows (if API configured)"
},
ai_workflow_pattern: {
title: "AI Agent Workflows",
key_insight: "ANY node can be used as an AI tool - not just those marked with usableAsTool!",
steps: [
"1. Create an AI Agent node (e.g., @n8n/n8n-nodes-langchain.agent)",
"2. Connect ANY node to the AI Agent's 'ai_tool' port",
"3. Use get_node_as_tool_info() to understand tool configuration",
"4. Configure tool with $fromAI() expressions for dynamic values",
"5. validate_workflow() to check AI tool connections"
],
examples: [
"Slack node → AI Agent's tool port = AI can send Slack messages",
"Google Sheets → AI Agent's tool port = AI can read/write spreadsheets",
"HTTP Request → AI Agent's tool port = AI can call any API"
],
validation: "Use validate_workflow() to verify ai_tool connections are valid"
},
complete_workflow_lifecycle: {
title: "Complete Workflow Lifecycle (NEW!)",
overview: "With n8n management tools, you can now manage the entire workflow lifecycle:",
phases: {
"1. Discover": {
tools: ["search_nodes", "list_nodes", "get_node_documentation"],
purpose: "Find the right nodes for your automation"
},
"2. Build": {
tools: ["get_node_essentials", "get_node_for_task", "search_node_properties"],
purpose: "Configure nodes with the right settings"
},
"3. Validate": {
tools: ["validate_node_minimal", "validate_node_operation", "validate_workflow", "n8n_validate_workflow"],
purpose: "Ensure your workflow is correct before deployment",
new: "n8n_validate_workflow - Validate workflows already in n8n by ID"
},
"4. Deploy": {
tools: ["n8n_create_workflow", "n8n_update_workflow", "n8n_list_workflows"],
purpose: "Create or update workflows in your n8n instance",
requirement: "Requires N8N_API_URL and N8N_API_KEY configuration"
},
"5. Execute": {
tools: ["n8n_trigger_webhook_workflow", "n8n_list_executions", "n8n_get_execution"],
purpose: "Run workflows and monitor their execution",
note: "Workflows must be activated manually in n8n UI"
}
},
example_flow: [
"1. search_nodes({query: 'slack'}) - Find Slack node",
"2. get_node_essentials('nodes-base.slack') - Get configuration",
"3. validate_node_operation() - Validate settings",
"4. n8n_create_workflow() - Deploy to n8n",
"5. n8n_validate_workflow({id: 'workflow-id'}) - Validate deployed workflow",
"6. n8n_trigger_webhook_workflow() - Execute via webhook"
]
}
}
},
workflow: {
title: "Efficient Workflow Patterns",
patterns: [
{
name: "Building from scratch",
steps: [
"search_nodes or list_nodes to find nodes",
"get_node_essentials for configuration",
"validate_node_minimal for quick required field check",
"validate_node_operation for full validation"
]
},
{
name: "Common tasks",
steps: [
"list_tasks() to see available templates",
"get_node_for_task() for instant configuration",
"Fill in userMustProvide fields",
"validate_node_minimal() to ensure all required fields present"
]
},
{
name: "AI Agent with Tools",
steps: [
"Create AI Agent node",
"search_nodes() to find tool nodes",
"get_node_as_tool_info() for each tool node",
"Connect nodes to ai_tool port",
"Configure with $fromAI() expressions",
"validate_workflow() to check everything"
]
}
]
},
search_tips: {
title: "Search Best Practices",
tips: [
"search_nodes returns ANY word match (OR logic)",
"'send slack message' finds nodes with 'send' OR 'slack' OR 'message'",
"Single words are more precise: 'slack' vs 'slack message'",
"Use list_nodes({category:'trigger'}) if search fails",
"Node types need prefix: 'nodes-base.slack' not just 'slack'"
]
},
common_nodes: {
title: "Most Used Nodes",
categories: {
triggers: ["webhook", "schedule", "emailReadImap", "slackTrigger"],
core: ["httpRequest", "code", "set", "if", "merge", "splitInBatches"],
integrations: ["slack", "gmail", "googleSheets", "postgres", "mongodb"],
ai: ["agent", "openAi", "chainLlm", "documentLoader"]
},
ai_tool_usage: {
note: "ANY node from above can be used as an AI tool!",
popular_ai_tools: [
"slack - Send messages, create channels",
"googleSheets - Read/write data",
"httpRequest - Call any API",
"gmail - Send emails",
"postgres - Query databases"
]
}
},
known_issues: {
title: "Known Issues & Workarounds",
issues: [
"Package names: Use 'n8n-nodes-base' NOT '@n8n/n8n-nodes-base'",
"Duplicate properties: Check showWhen/hideWhen conditions",
"Large responses: Use get_node_essentials instead of get_node_info",
"Property search: Some nodes have 200+ properties, use search_node_properties",
"Node not found: Try without prefix or lowercase"
]
},
performance: {
title: "Performance Guide",
tools: {
fast: [
"get_node_essentials - <5KB responses",
"search_nodes - Indexed search",
"list_nodes - Direct queries",
"validate_node_minimal - Only required fields",
"start_here_workflow_guide - Static content"
],
slow: [
"get_node_info - 100KB+ responses",
"get_node_documentation - Can be large",
"validate_workflow - Full workflow analysis"
]
},
tips: [
"Use get_node_essentials for 95% of use cases",
"Only use get_node_info when essentials lack needed property",
"Results are cached for repeated queries",
"Use validate_node_minimal before validate_node_operation"
]
},
ai_tools: {
title: "AI Tools & Agent Workflows",
key_concept: "In n8n, ANY node can be used as an AI tool - not just those marked with usableAsTool!",
how_it_works: {
"1. Connection": "Connect any node to an AI Agent's 'ai_tool' port",
"2. Configuration": "Use $fromAI() expressions to let AI provide dynamic values",
"3. Description": "Give tools clear names and descriptions in AI Agent settings",
"4. Validation": "Use validate_workflow() to verify ai_tool connections"
},
common_patterns: {
"Data Collection": {
nodes: ["googleSheets", "postgres", "mongodb"],
usage: "AI reads data to answer questions or make decisions"
},
"Actions & Notifications": {
nodes: ["slack", "gmail", "httpRequest"],
usage: "AI performs actions based on analysis"
},
"API Integration": {
nodes: ["httpRequest", "webhook"],
usage: "AI calls external services and APIs"
}
},
example_expressions: {
"Dynamic values": '{{ $fromAI("channel", "Slack channel to post to") }}',
"Complex data": '{{ $fromAI("query", "SQL query to execute") }}',
"Conditional": '{{ $fromAI("shouldNotify", "true/false to send notification") }}'
},
best_practices: [
"Test nodes individually before connecting as tools",
"Write detailed tool descriptions for better AI understanding",
"Use validate_workflow() to catch connection issues",
"Start simple - one or two tools, then expand",
"Monitor AI tool usage in workflow executions"
],
tools_to_use: [
"get_node_as_tool_info() - Understand any node's AI capabilities",
"list_ai_tools() - See nodes optimized for AI (263 available)",
"validate_workflow() - Verify ai_tool connections",
"get_node_essentials() - Configure tool nodes efficiently"
]
},
n8n_management: {
title: "n8n Workflow Management Tools (NEW!)",
overview: "Manage n8n workflows directly through MCP. Create, update, execute, and monitor workflows programmatically.",
requirements: {
configuration: "Set N8N_API_URL and N8N_API_KEY environment variables",
access: "n8n instance with API access enabled",
version: "n8n v1.0.0 or higher"
},
available_tools: {
workflow_management: [
"n8n_create_workflow - Create new workflows with nodes and connections",
"n8n_get_workflow - Get complete workflow by ID",
"n8n_get_workflow_details - Get workflow with execution statistics",
"n8n_update_workflow - Update existing workflows (requires full node array)",
"n8n_delete_workflow - Delete workflows permanently",
"n8n_list_workflows - List workflows with filtering"
],
execution_management: [
"n8n_trigger_webhook_workflow - Execute workflows via webhook",
"n8n_get_execution - Get execution details",
"n8n_list_executions - List executions with status filtering",
"n8n_delete_execution - Delete execution records"
],
system_tools: [
"n8n_health_check - Check API connectivity",
"n8n_list_available_tools - List all management tools"
]
},
limitations: {
"Workflow Activation": "Cannot activate/deactivate workflows via API - use n8n UI",
"Direct Execution": "No direct execution - must use webhook triggers",
"Update Requirements": "Updates require complete nodes array, not just changes",
"Tags": "Read-only during creation/update"
},
workflow_examples: {
"⚠️ CRITICAL: Connection Rules": {
warning: "ALWAYS use node NAMES in connections, NEVER use node IDs!",
explanation: "Using IDs will make nodes appear disconnected in n8n UI",
wrong: {
connections: {"1": {main: [[{node: "2", type: "main", index: 0}]]}} // ❌ WRONG - uses IDs
},
correct: {
connections: {"Start": {main: [[{node: "Set", type: "main", index: 0}]]}} // ✅ CORRECT - uses names
}
},
"Create Simple Workflow": {
tools: ["n8n_create_workflow"],
example: {
name: "My Test Workflow",
nodes: [
{id: "1", name: "Start", type: "n8n-nodes-base.start", position: [250, 300]},
{id: "2", name: "Set", type: "n8n-nodes-base.set", position: [450, 300]}
],
connections: {"Start": {main: [[{node: "Set", type: "main", index: 0}]]}} // ✅ Uses node names!
}
},
"Execute via Webhook": {
tools: ["n8n_trigger_webhook_workflow"],
steps: [
"1. Workflow must have webhook trigger node",
"2. Workflow must be manually activated in UI",
"3. Use webhook URL from workflow"
]
}
},
best_practices: [
"⚠️ ALWAYS use node NAMES in connections, NEVER node IDs",
"Always use n8n_health_check first to verify connectivity",
"Fetch full workflow before updating (n8n_get_workflow)",
"Validate workflows before creating (validate_workflow)",
"Monitor executions after triggering webhooks",
"Use descriptive workflow names for easy management"
],
integration_pattern: {
title: "Complete Automation Pipeline",
steps: [
"1. Design: Use documentation tools to understand nodes",
"2. Build: Configure nodes with get_node_essentials",
"3. Validate: Use validate_workflow before deployment",
"4. Deploy: Create with n8n_create_workflow",
"5. Activate: Manually activate in n8n UI",
"6. Execute: Trigger with n8n_trigger_webhook_workflow",
"7. Monitor: Check status with n8n_list_executions"
]
}
}
};
// Method removed - replaced by getToolsDocumentation
if (topic && guides[topic]) {
return guides[topic];
private async getToolsDocumentation(topic?: string, depth: 'essentials' | 'full' = 'essentials'): Promise<string> {
if (!topic || topic === 'overview') {
return getToolsOverview(depth);
}
// Return complete overview
return {
title: "n8n MCP Tools Complete Guide",
quickStart: guides.overview,
sections: {
workflow: guides.workflow,
searchTips: guides.search_tips,
commonNodes: guides.common_nodes,
knownIssues: guides.known_issues,
performance: guides.performance,
aiTools: guides.ai_tools,
n8nManagement: guides.n8n_management
},
examples: {
"Find and configure Slack": [
"search_nodes({query:'slack'})",
"get_node_essentials('nodes-base.slack')",
"validate_node_minimal('nodes-base.slack', {resource:'message',operation:'post'})",
"get_node_for_task('send_slack_message')"
],
"Set up webhook trigger": [
"get_node_for_task('receive_webhook')",
"validate_node_minimal('nodes-base.webhook', config)",
"// Returns pre-configured webhook with instructions"
],
"HTTP API call": [
"get_node_essentials('nodes-base.httpRequest')",
"search_node_properties('nodes-base.httpRequest', 'auth')",
"validate_node_operation('nodes-base.httpRequest', config)"
],
"AI Agent with Slack tool": [
"search_nodes({query:'agent'})",
"get_node_as_tool_info('nodes-base.slack')",
"// Connect Slack to AI Agent's ai_tool port",
"// Configure with $fromAI() expressions",
"validate_workflow(workflow)"
],
"Complete Workflow Lifecycle": [
"// 1. Discover & Design",
"search_nodes({query: 'webhook'})",
"get_node_essentials('nodes-base.webhook')",
"// 2. Build & Validate",
"const workflow = { nodes: [...], connections: {...} }",
"validate_workflow(workflow)",
"// 3. Deploy (requires API config)",
"n8n_create_workflow(workflow)",
"// 4. Execute",
"n8n_trigger_webhook_workflow({webhookUrl: '...'})",
"// 5. Monitor",
"n8n_list_executions({workflowId: '...'})"
]
},
validation_guide: {
title: "Validation Tools Guide",
tools: {
"validate_node_minimal": "Fastest - only checks required fields",
"validate_node_operation": "Smart - checks based on selected operation",
"validate_workflow": "Complete - validates entire workflow including AI connections",
"validate_workflow_connections": "Structure - just checks node connections",
"validate_workflow_expressions": "Expressions - validates $json, $node, $fromAI"
},
when_to_use: {
"Building nodes": "Use validate_node_minimal first, then validate_node_operation",
"AI workflows": "Always use validate_workflow to check ai_tool connections",
"Quick checks": "validate_node_minimal when you just need required fields",
"Before deployment": "validate_workflow with all options enabled"
}
}
};
return getToolDocumentation(topic, depth);
}
// Add connect method to accept any transport