refactor: rewrite all MCP tool documentation for AI agent optimization

- Redesigned documentation to be utilitarian and AI-agent focused - Removed all pleasantries, emojis, and conversational language - Added concrete numbers throughout (528 nodes, 108 triggers, 264 AI tools) - Updated all tool descriptions with practical, actionable information - Enhanced examples with actual return structures and usage patterns - Made Code node guides prominently featured in overview - Verified documentation accuracy through extensive testing - Standardized format across all 30+ tool documentation files Documentation now optimized for token efficiency while maintaining clarity and completeness for AI agent consumption. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-10 07:13:07 +00:00 · 2025-07-17 19:49:07 +02:00
parent c1a6347d4f
commit 24d775960b
16 changed files with 1031 additions and 289 deletions
--- a/src/mcp/tools-documentation.ts
+++ b/src/mcp/tools-documentation.ts
@@ -1,6 +1,14 @@
-import { toolsDocumentation, ToolDocumentation } from './tool-docs';
+import { toolsDocumentation } from './tool-docs';

 export function getToolDocumentation(toolName: string, depth: 'essentials' | 'full' = 'essentials'): string {
+  // Check for special documentation topics
+  if (toolName === 'javascript_code_node_guide') {
+    return getJavaScriptCodeNodeGuide(depth);
+  }
+  if (toolName === 'python_code_node_guide') {
+    return getPythonCodeNodeGuide(depth);
+  }
+  
  const tool = toolsDocumentation[toolName];
  if (!tool) {
    return `Tool '${toolName}' not found. Use tools_documentation() to see available tools.`;
@@ -59,86 +67,98 @@ ${full.relatedTools.map(t => `- ${t}`).join('\n')}`;

 export function getToolsOverview(depth: 'essentials' | 'full' = 'essentials'): string {
  if (depth === 'essentials') {
-    return `# n8n MCP Tools Quick Reference
+    return `# n8n MCP Tools Reference

-Welcome to n8n-mcp! This tool provides comprehensive access to n8n node documentation.
+## Code Node Configuration
+When working with Code nodes, always start by calling the relevant guide:
+- tools_documentation({topic: "javascript_code_node_guide"}) for JavaScript Code nodes
+- tools_documentation({topic: "python_code_node_guide"}) for Python Code nodes

-## Most Used Tools
+## Standard Workflow Pattern

-### 🔍 Discovery
- **search_nodes**: Search nodes by keyword
- **list_nodes**: List all nodes with filters
- **list_ai_tools**: See all AI-capable nodes
+1. **Find** the node you need:
+   - search_nodes({query: "slack"}) - Search by keyword
+   - list_nodes({category: "communication"}) - List by category
+   - list_ai_tools() - List AI-capable nodes

-### ⚙️ Configuration  
- **get_node_essentials**: Get key properties only (<5KB vs 100KB+)
- **get_node_info**: Get complete node schema
- **search_node_properties**: Find specific properties
+2. **Configure** the node:
+   - get_node_essentials("nodes-base.slack") - Get essential properties only (5KB)
+   - get_node_info("nodes-base.slack") - Get complete schema (100KB+)
+   - search_node_properties("nodes-base.slack", "auth") - Find specific properties

-### ✅ Validation
- **validate_node_minimal**: Quick required field check
- **validate_node_operation**: Full validation with fixes
- **validate_workflow**: Complete workflow validation
+3. **Validate** before deployment:
+   - validate_node_minimal("nodes-base.slack", config) - Check required fields
+   - validate_node_operation("nodes-base.slack", config) - Full validation with fixes
+   - validate_workflow(workflow) - Validate entire workflow

-### 📋 Templates
- **list_tasks**: See common task templates
- **get_node_for_task**: Get pre-configured nodes
- **search_templates**: Find workflow templates
+## Tool Categories

-### 🔧 n8n Management (requires API config)
- **n8n_create_workflow**: Create workflows
- **n8n_update_partial_workflow**: Update with diffs
- **n8n_health_check**: Test API connectivity
+**Discovery Tools**
+- search_nodes - Full-text search across all nodes
+- list_nodes - List nodes with filtering by category, package, or type
+- list_ai_tools - List all AI-capable nodes with usage guidance

-## Quick Start Examples
+**Configuration Tools**
+- get_node_essentials - Returns 10-20 key properties with examples
+- get_node_info - Returns complete node schema with all properties
+- search_node_properties - Search for specific properties within a node
+- get_property_dependencies - Analyze property visibility dependencies

-\`\`\`javascript
-// Find a node
-search_nodes({query: "slack"})
+**Validation Tools**
+- validate_node_minimal - Quick validation of required fields only
+- validate_node_operation - Full validation with operation awareness
+- validate_workflow - Complete workflow validation including connections

-// Get essential config
-get_node_essentials("nodes-base.slack")
+**Template Tools**
+- list_tasks - List common task templates
+- get_node_for_task - Get pre-configured node for specific tasks
+- search_templates - Search workflow templates by keyword
+- get_template - Get complete workflow JSON by ID

-// Validate configuration
-validate_node_minimal("nodes-base.slack", {resource: "message", operation: "post"})
-\`\`\`
+**n8n API Tools** (requires N8N_API_URL configuration)
+- n8n_create_workflow - Create new workflows
+- n8n_update_partial_workflow - Update workflows using diff operations
+- n8n_validate_workflow - Validate workflow from n8n instance
+- n8n_trigger_webhook_workflow - Trigger workflow execution

-## Performance Guide
- **Instant**: <10ms (static/cached)
- **Fast**: <100ms (queries/generation)
- **Moderate**: 100-500ms (validation/analysis)
- **Network-dependent**: Varies with API
+## Performance Characteristics
+- Instant (<10ms): search_nodes, list_nodes, get_node_essentials
+- Fast (<100ms): validate_node_minimal, get_node_for_task
+- Moderate (100-500ms): validate_workflow, get_node_info
+- Network-dependent: All n8n_* tools

-For detailed tool documentation, use:
-\`tools_documentation({topic: "tool_name", depth: "full"})\``;
+For comprehensive documentation on any tool:
+tools_documentation({topic: "tool_name", depth: "full"})`;
  }

-  // Full overview
  const categories = getAllCategories();
-  return `# n8n MCP Tools Complete Reference
+  return `# n8n MCP Tools - Complete Reference

-## Available Tools by Category
+## Code Node Guides
+For Code node configuration, use these comprehensive guides:
+- tools_documentation({topic: "javascript_code_node_guide", depth: "full"}) - JavaScript patterns, n8n variables, error handling
+- tools_documentation({topic: "python_code_node_guide", depth: "full"}) - Python patterns, data access, debugging
+
+## All Available Tools by Category

 ${categories.map(cat => {
  const tools = getToolsByCategory(cat);
-  return `### ${cat.charAt(0).toUpperCase() + cat.slice(1)}
+  const categoryName = cat.charAt(0).toUpperCase() + cat.slice(1).replace('_', ' ');
+  return `### ${categoryName}
 ${tools.map(toolName => {
  const tool = toolsDocumentation[toolName];
  return `- **${toolName}**: ${tool.essentials.description}`;
 }).join('\n')}`;
 }).join('\n\n')}

-## Tool Categories Explained
+## Usage Notes
+- All node types require the "nodes-base." or "nodes-langchain." prefix
+- Use get_node_essentials() first for most tasks (95% smaller than get_node_info)
+- Validation profiles: minimal (editing), runtime (default), strict (deployment)
+- n8n API tools only available when N8N_API_URL and N8N_API_KEY are configured

- **discovery**: Find and explore n8n nodes
- **configuration**: Configure and understand nodes
- **validation**: Validate node and workflow configurations
- **templates**: Pre-built configurations and examples
- **workflow_management**: Create and manage n8n workflows (requires API)
- **system**: MCP system tools and diagnostics
-
-For specific tool documentation, use:
-\`tools_documentation({topic: "tool_name", depth: "full"})\``;
+For detailed documentation on any tool:
+tools_documentation({topic: "tool_name", depth: "full"})`;
 }

 export function searchToolDocumentation(keyword: string): string[] {
@@ -166,4 +186,489 @@ export function getAllCategories(): string[] {
    categories.add(tool.category);
  });
  return Array.from(categories);
+}
+
+// Special documentation topics
+function getJavaScriptCodeNodeGuide(depth: 'essentials' | 'full' = 'essentials'): string {
+  if (depth === 'essentials') {
+    return `# JavaScript Code Node Guide
+
+Essential patterns for JavaScript in n8n Code nodes.
+
+**Key Concepts**:
+- Access all items: \`$input.all()\` (not items[0])
+- Current item data: \`$json\`
+- Return format: \`[{json: {...}}]\` (array of objects)
+
+**Available Helpers**:
+- \`$helpers.httpRequest()\` - Make HTTP requests
+- \`$jmespath()\` - Query JSON data
+- \`DateTime\` - Luxon for date handling
+
+**Common Patterns**:
+\`\`\`javascript
+// Process all items
+const allItems = $input.all();
+return allItems.map(item => ({
+  json: {
+    processed: true,
+    original: item.json,
+    timestamp: DateTime.now().toISO()
+  }
+}));
+\`\`\`
+
+**Tips**:
+- Webhook data is under \`.body\` property
+- Use async/await for HTTP requests
+- Always return array format
+
+For full guide: tools_documentation({topic: "javascript_code_node_guide", depth: "full"})`;
+  }
+
+  // Full documentation
+  return `# JavaScript Code Node Complete Guide
+
+Comprehensive guide for using JavaScript in n8n Code nodes.
+
+## Data Access Patterns
+
+### Accessing Input Data
+\`\`\`javascript
+// Get all items from previous node
+const allItems = $input.all();
+
+// Get specific node's output
+const webhookData = $node["Webhook"].json;
+
+// Current item in loop
+const currentItem = $json;
+
+// First item only
+const firstItem = $input.first().json;
+\`\`\`
+
+### Webhook Data Structure
+**CRITICAL**: Webhook data is nested under \`.body\`:
+\`\`\`javascript
+// WRONG - Won't work
+const data = $json.name;
+
+// CORRECT - Webhook data is under body
+const data = $json.body.name;
+\`\`\`
+
+## Available Built-in Functions
+
+### HTTP Requests
+\`\`\`javascript
+// Make HTTP request
+const response = await $helpers.httpRequest({
+  method: 'GET',
+  url: 'https://api.example.com/data',
+  headers: {
+    'Authorization': 'Bearer token'
+  }
+});
+\`\`\`
+
+### Date/Time Handling
+\`\`\`javascript
+// Using Luxon DateTime
+const now = DateTime.now();
+const formatted = now.toFormat('yyyy-MM-dd');
+const iso = now.toISO();
+const plus5Days = now.plus({ days: 5 });
+\`\`\`
+
+### JSON Querying
+\`\`\`javascript
+// JMESPath queries
+const result = $jmespath($json, "users[?age > 30].name");
+\`\`\`
+
+## Return Format Requirements
+
+### Correct Format
+\`\`\`javascript
+// MUST return array of objects with json property
+return [{
+  json: {
+    result: "success",
+    data: processedData
+  }
+}];
+
+// Multiple items
+return items.map(item => ({
+  json: {
+    id: item.id,
+    processed: true
+  }
+}));
+\`\`\`
+
+### Binary Data
+\`\`\`javascript
+// Return with binary data
+return [{
+  json: { filename: "report.pdf" },
+  binary: {
+    data: Buffer.from(pdfContent).toString('base64')
+  }
+}];
+\`\`\`
+
+## Common Patterns
+
+### Processing Webhook Data
+\`\`\`javascript
+// Extract webhook payload
+const webhookBody = $json.body;
+const { username, email, items } = webhookBody;
+
+// Process and return
+return [{
+  json: {
+    username,
+    email,
+    itemCount: items.length,
+    processedAt: DateTime.now().toISO()
+  }
+}];
+\`\`\`
+
+### Aggregating Data
+\`\`\`javascript
+// Sum values across all items
+const allItems = $input.all();
+const total = allItems.reduce((sum, item) => {
+  return sum + (item.json.amount || 0);
+}, 0);
+
+return [{
+  json: { 
+    total,
+    itemCount: allItems.length,
+    average: total / allItems.length
+  }
+}];
+\`\`\`
+
+### Error Handling
+\`\`\`javascript
+try {
+  const response = await $helpers.httpRequest({
+    url: 'https://api.example.com/data'
+  });
+  
+  return [{
+    json: {
+      success: true,
+      data: response
+    }
+  }];
+} catch (error) {
+  return [{
+    json: {
+      success: false,
+      error: error.message
+    }
+  }];
+}
+\`\`\`
+
+## Available Node.js Modules
+- crypto (built-in)
+- Buffer
+- URL/URLSearchParams
+- Basic Node.js globals
+
+## Common Pitfalls
+1. Using \`items[0]\` instead of \`$input.all()\`
+2. Forgetting webhook data is under \`.body\`
+3. Returning plain objects instead of \`[{json: {...}}]\`
+4. Using \`require()\` for external modules (not allowed)
+5. Trying to use expression syntax \`{{}}\` inside code
+
+## Best Practices
+1. Always validate input data exists before accessing
+2. Use try-catch for HTTP requests
+3. Return early on validation failures
+4. Keep code simple and readable
+5. Use descriptive variable names
+
+## Related Tools
+- get_node_essentials("nodes-base.code")
+- validate_node_operation()
+- python_code_node_guide (for Python syntax)`;
+}
+
+function getPythonCodeNodeGuide(depth: 'essentials' | 'full' = 'essentials'): string {
+  if (depth === 'essentials') {
+    return `# Python Code Node Guide
+
+Essential patterns for Python in n8n Code nodes.
+
+**Key Concepts**:
+- Access all items: \`_input.all()\` (not items[0])
+- Current item data: \`_json\`
+- Return format: \`[{"json": {...}}]\` (list of dicts)
+
+**Limitations**:
+- No external libraries (no requests, pandas, numpy)
+- Use built-in functions only
+- No pip install available
+
+**Common Patterns**:
+\`\`\`python
+# Process all items
+all_items = _input.all()
+return [{
+    "json": {
+        "processed": True,
+        "count": len(all_items),
+        "first_item": all_items[0]["json"] if all_items else None
+    }
+}]
+\`\`\`
+
+**Tips**:
+- Webhook data is under ["body"] key
+- Use json module for parsing
+- datetime for date handling
+
+For full guide: tools_documentation({topic: "python_code_node_guide", depth: "full"})`;
+  }
+
+  // Full documentation
+  return `# Python Code Node Complete Guide
+
+Comprehensive guide for using Python in n8n Code nodes.
+
+## Data Access Patterns
+
+### Accessing Input Data
+\`\`\`python
+# Get all items from previous node
+all_items = _input.all()
+
+# Get specific node's output (use _node)
+webhook_data = _node["Webhook"]["json"]
+
+# Current item in loop
+current_item = _json
+
+# First item only
+first_item = _input.first()["json"]
+\`\`\`
+
+### Webhook Data Structure
+**CRITICAL**: Webhook data is nested under ["body"]:
+\`\`\`python
+# WRONG - Won't work
+data = _json["name"]
+
+# CORRECT - Webhook data is under body
+data = _json["body"]["name"]
+\`\`\`
+
+## Available Built-in Modules
+
+### Standard Library Only
+\`\`\`python
+import json
+import datetime
+import base64
+import hashlib
+import urllib.parse
+import re
+import math
+import random
+\`\`\`
+
+### Date/Time Handling
+\`\`\`python
+from datetime import datetime, timedelta
+
+# Current time
+now = datetime.now()
+iso_format = now.isoformat()
+
+# Date arithmetic
+future = now + timedelta(days=5)
+formatted = now.strftime("%Y-%m-%d")
+\`\`\`
+
+### JSON Operations
+\`\`\`python
+# Parse JSON string
+data = json.loads(json_string)
+
+# Convert to JSON
+json_output = json.dumps({"key": "value"})
+\`\`\`
+
+## Return Format Requirements
+
+### Correct Format
+\`\`\`python
+# MUST return list of dictionaries with "json" key
+return [{
+    "json": {
+        "result": "success",
+        "data": processed_data
+    }
+}]
+
+# Multiple items
+return [
+    {"json": {"id": item["json"]["id"], "processed": True}}
+    for item in all_items
+]
+\`\`\`
+
+### Binary Data
+\`\`\`python
+# Return with binary data
+import base64
+
+return [{
+    "json": {"filename": "report.pdf"},
+    "binary": {
+        "data": base64.b64encode(pdf_content).decode()
+    }
+}]
+\`\`\`
+
+## Common Patterns
+
+### Processing Webhook Data
+\`\`\`python
+# Extract webhook payload
+webhook_body = _json["body"]
+username = webhook_body.get("username")
+email = webhook_body.get("email")
+items = webhook_body.get("items", [])
+
+# Process and return
+return [{
+    "json": {
+        "username": username,
+        "email": email,
+        "item_count": len(items),
+        "processed_at": datetime.now().isoformat()
+    }
+}]
+\`\`\`
+
+### Aggregating Data
+\`\`\`python
+# Sum values across all items
+all_items = _input.all()
+total = sum(item["json"].get("amount", 0) for item in all_items)
+
+return [{
+    "json": {
+        "total": total,
+        "item_count": len(all_items),
+        "average": total / len(all_items) if all_items else 0
+    }
+}]
+\`\`\`
+
+### Error Handling
+\`\`\`python
+try:
+    # Process data
+    webhook_data = _json["body"]
+    result = process_data(webhook_data)
+    
+    return [{
+        "json": {
+            "success": True,
+            "data": result
+        }
+    }]
+except Exception as e:
+    return [{
+        "json": {
+            "success": False,
+            "error": str(e)
+        }
+    }]
+\`\`\`
+
+### Data Transformation
+\`\`\`python
+# Transform all items
+all_items = _input.all()
+transformed = []
+
+for item in all_items:
+    data = item["json"]
+    transformed.append({
+        "json": {
+            "id": data.get("id"),
+            "name": data.get("name", "").upper(),
+            "timestamp": datetime.now().isoformat(),
+            "valid": bool(data.get("email"))
+        }
+    })
+
+return transformed
+\`\`\`
+
+## Limitations & Workarounds
+
+### No External Libraries
+\`\`\`python
+# CANNOT USE:
+# import requests  # Not available
+# import pandas   # Not available
+# import numpy    # Not available
+
+# WORKAROUND: Use JavaScript Code node for HTTP requests
+# Or use HTTP Request node before Code node
+\`\`\`
+
+### HTTP Requests Alternative
+Since Python requests library is not available, use:
+1. JavaScript Code node with $helpers.httpRequest()
+2. HTTP Request node before your Python Code node
+3. Webhook node to receive data
+
+## Common Pitfalls
+1. Trying to import external libraries (requests, pandas)
+2. Using items[0] instead of _input.all()
+3. Forgetting webhook data is under ["body"]
+4. Returning dictionaries instead of [{"json": {...}}]
+5. Not handling missing keys with .get()
+
+## Best Practices
+1. Always use .get() for dictionary access
+2. Validate data before processing
+3. Handle empty input arrays
+4. Use list comprehensions for transformations
+5. Return meaningful error messages
+
+## Type Conversions
+\`\`\`python
+# String to number
+value = float(_json.get("amount", "0"))
+
+# Boolean conversion
+is_active = str(_json.get("active", "")).lower() == "true"
+
+# Safe JSON parsing
+try:
+    data = json.loads(_json.get("json_string", "{}"))
+except json.JSONDecodeError:
+    data = {}
+\`\`\`
+
+## Related Tools
+- get_node_essentials("nodes-base.code")
+- validate_node_operation()
+- javascript_code_node_guide (for JavaScript syntax)`;
 }