n8n-mcp 2.7.9 → 2.7.11

package/dist/mcp/tools-documentation.js

@@ -11,43 +11,48 @@ exports.toolsDocumentation = {
         name: 'search_nodes',
         category: 'discovery',
         essentials: {
-            description: 'Search for n8n nodes by keyword across names, descriptions, and categories',
-            keyParameters: ['query', 'limit'],
-            example: 'search_nodes({query: "slack", limit: 10})',
-            performance: 'Fast - uses indexed full-text search',
+            description: 'Search nodes. Primary nodes ranked first.',
+            keyParameters: ['query', 'limit', 'mode'],
+            example: 'search_nodes({query: "webhook"})',
+            performance: 'Fast - FTS5 when available',
             tips: [
-                'Uses OR logic - "send slack" finds nodes with ANY of these words',
-                'Single words are more precise than phrases'
+                'Primary nodes first: webhook→Webhook, http→HTTP Request',
+                'Modes: OR (any word), AND (all words), FUZZY (typos OK)'
             ]
         },
         full: {
-            description: 'Performs full-text search across all n8n nodes using indexed search. Returns nodes matching ANY word in the query (OR logic). Searches through node names, display names, descriptions, and categories.',
+            description: 'Search n8n nodes using FTS5 full-text search (when available) with relevance ranking. Supports OR (default), AND, and FUZZY search modes. Results are sorted by relevance, ensuring primary nodes like Webhook and HTTP Request appear first.',
             parameters: {
-                query: { type: 'string', description: 'Search terms (words are ORed together)', required: true },
-                limit: { type: 'number', description: 'Maximum results to return (default: 20)', required: false }
+                query: { type: 'string', description: 'Search terms. Wrap in quotes for exact phrase matching', required: true },
+                limit: { type: 'number', description: 'Maximum results to return (default: 20)', required: false },
+                mode: { type: 'string', description: 'Search mode: OR (any word), AND (all words in ANY field), FUZZY (typo-tolerant using edit distance)', required: false }
             },
-            returns: 'Array of nodes with nodeType, displayName, description, category, and relevance score',
+            returns: 'Array of nodes sorted by relevance with nodeType, displayName, description, category. AND mode includes searchInfo explaining the search scope.',
             examples: [
-                'search_nodes({query: "slack"}) - Find all Slack-related nodes',
-                'search_nodes({query: "webhook trigger", limit: 5}) - Find nodes with "webhook" OR "trigger"',
-                'search_nodes({query: "ai"}) - Find AI-related nodes'
+                'search_nodes({query: "webhook"}) - Webhook node appears first',
+                'search_nodes({query: "http call"}) - HTTP Request node appears first',
+                'search_nodes({query: "send message", mode: "AND"}) - Nodes with both words anywhere in their data',
+                'search_nodes({query: "slak", mode: "FUZZY"}) - Finds Slack using typo tolerance'
             ],
             useCases: [
-                'Finding nodes for specific integrations',
-                'Discovering available functionality',
-                'Exploring nodes by keyword when exact name unknown'
+                'Finding primary nodes quickly (webhook, http, email)',
+                'Discovering nodes with typo tolerance',
+                'Precise searches with AND mode',
+                'Exploratory searches with OR mode'
             ],
-            performance: 'Very fast - uses SQLite FTS5 full-text index. Typically <50ms even for complex queries.',
+            performance: 'FTS5: <20ms for most queries. Falls back to optimized LIKE queries if FTS5 unavailable.',
             bestPractices: [
-                'Use single words for precise matches',
-                'Try different variations if first search fails',
-                'Use list_nodes for browsing by category',
-                'Remember it\'s OR logic, not AND'
+                'Default OR mode is best for exploration',
+                'Use AND mode when you need all terms present',
+                'Use FUZZY mode if unsure of spelling',
+                'Quotes force exact phrase matching',
+                'Primary nodes are boosted in relevance'
             ],
             pitfalls: [
-                'Multi-word queries may return too many results',
-                'Doesn\'t search in node properties or operations',
-                'Case-insensitive but doesn\'t handle typos'
+                'AND mode searches ALL fields (description, documentation, operations) not just names',
+                'FUZZY mode uses edit distance - may return unexpected matches for very short queries',
+                'Special characters are ignored in search',
+                'FTS5 syntax errors fallback to basic LIKE search'
             ],
             relatedTools: ['list_nodes', 'get_node_essentials', 'get_node_info']
         }
@@ -56,13 +61,12 @@ exports.toolsDocumentation = {
         name: 'get_node_essentials',
         category: 'configuration',
         essentials: {
-            description: 'Get only the most important 10-20 properties for a node with examples',
+            description: 'Get 10-20 key properties with examples',
             keyParameters: ['nodeType'],
-            example: 'get_node_essentials("n8n-nodes-base.slack")',
-            performance: 'Very fast - returns <5KB instead of 100KB+',
+            example: 'get_node_essentials("nodes-base.slack")',
+            performance: '<5KB vs 100KB+',
             tips: [
-                'Use this instead of get_node_info for 95% of cases',
-                'Includes working examples for common operations'
+                'Use this first! Has examples.'
             ]
         },
         full: {
@@ -294,11 +298,12 @@ exports.toolsDocumentation = {
             performance: 'API call - depends on n8n instance',
             tips: [
                 'ALWAYS use node names in connections, never IDs',
+                'Error handling properties go at NODE level, not inside parameters!',
                 'Requires N8N_API_URL and N8N_API_KEY configuration'
             ]
         },
         full: {
-            description: 'Creates a new workflow in your n8n instance via API. Requires proper API configuration. Returns the created workflow with assigned ID.',
+            description: 'Creates a new workflow in your n8n instance via API. Requires proper API configuration. Returns the created workflow with assigned ID.\n\n⚠️ CRITICAL: Error handling properties (onError, retryOnFail, etc.) are NODE-LEVEL properties, not inside parameters!',
             parameters: {
                 name: { type: 'string', description: 'Workflow name', required: true },
                 nodes: { type: 'array', description: 'Array of node configurations', required: true },
@@ -308,14 +313,61 @@ exports.toolsDocumentation = {
             },
             returns: 'Created workflow object with id, name, nodes, connections, and metadata',
             examples: [
-                `n8n_create_workflow({
-  name: "Slack Notification",
+                `// Basic workflow with proper error handling
+n8n_create_workflow({
+  name: "Slack Notification with Error Handling",
   nodes: [
-    {id: "1", name: "Webhook", type: "n8n-nodes-base.webhook", position: [250, 300]},
-    {id: "2", name: "Slack", type: "n8n-nodes-base.slack", position: [450, 300], parameters: {...}}
+    {
+      id: "1",
+      name: "Webhook",
+      type: "n8n-nodes-base.webhook",
+      typeVersion: 2,
+      position: [250, 300],
+      parameters: {
+        path: "/webhook",
+        method: "POST"
+      },
+      // ✅ CORRECT - Error handling at node level
+      onError: "continueRegularOutput"
+    },
+    {
+      id: "2",
+      name: "Database Query",
+      type: "n8n-nodes-base.postgres",
+      typeVersion: 2.4,
+      position: [450, 300],
+      parameters: {
+        operation: "executeQuery",
+        query: "SELECT * FROM users"
+      },
+      // ✅ CORRECT - Error handling at node level
+      onError: "continueErrorOutput",
+      retryOnFail: true,
+      maxTries: 3,
+      waitBetweenTries: 2000
+    },
+    {
+      id: "3",
+      name: "Error Handler",
+      type: "n8n-nodes-base.slack",
+      typeVersion: 2.2,
+      position: [650, 450],
+      parameters: {
+        resource: "message",
+        operation: "post",
+        channel: "#errors",
+        text: "Database query failed!"
+      }
+    }
   ],
   connections: {
-    "Webhook": {main: [[{node: "Slack", type: "main", index: 0}]]}
+    "Webhook": {
+      main: [[{node: "Database Query", type: "main", index: 0}]]
+    },
+    "Database Query": {
+      main: [[{node: "Success Handler", type: "main", index: 0}]],
+      error: [[{node: "Error Handler", type: "main", index: 0}]]  // Error output
+    }
   }
 })`
             ],
@@ -323,17 +375,20 @@ exports.toolsDocumentation = {
                 'Deploying workflows programmatically',
                 'Automating workflow creation',
                 'Migrating workflows between instances',
-                'Creating workflows from templates'
+                'Creating workflows from templates',
+                'Building error-resilient workflows'
             ],
             performance: 'Depends on n8n instance and network. Typically 100-500ms.',
             bestPractices: [
                 'CRITICAL: Use node NAMES in connections, not IDs',
+                'CRITICAL: Place error handling at NODE level, not in parameters',
                 'Validate workflow before creating',
                 'Use meaningful workflow names',
-                'Check n8n_health_check before creating',
-                'Handle API errors gracefully'
+                'Add error handling to external service nodes',
+                'Check n8n_health_check before creating'
             ],
             pitfalls: [
+                'Placing error handling properties inside parameters object',
                 'Using node IDs in connections breaks UI display',
                 'Workflow not automatically activated',
                 'Tags must exist (use tag IDs not names)',
@@ -348,15 +403,16 @@ exports.toolsDocumentation = {
         essentials: {
             description: 'Update workflows using diff operations - only send changes, not entire workflow',
             keyParameters: ['id', 'operations'],
-            example: 'n8n_update_partial_workflow({id: "123", operations: [{type: "updateNode", nodeId: "Slack", updates: {...}}]})',
+            example: 'n8n_update_partial_workflow({id: "123", operations: [{type: "updateNode", nodeName: "Slack", changes: {onError: "continueRegularOutput"}}]})',
             performance: '80-90% more efficient than full updates',
             tips: [
                 'Maximum 5 operations per request',
-                'Can reference nodes by name or ID'
+                'Can reference nodes by name or ID',
+                'Error handling properties go at NODE level, not inside parameters!'
             ]
         },
         full: {
-            description: 'Update existing workflows using diff operations. Much more efficient than full updates as it only sends the changes. Supports 13 different operation types.',
+            description: 'Update existing workflows using diff operations. Much more efficient than full updates as it only sends the changes. Supports 13 different operation types.\n\n⚠️ CRITICAL: Error handling properties (onError, retryOnFail, maxTries, etc.) are NODE-LEVEL properties, not parameters!',
             parameters: {
                 id: { type: 'string', description: 'Workflow ID to update', required: true },
                 operations: { type: 'array', description: 'Array of diff operations (max 5)', required: true },
@@ -364,29 +420,50 @@ exports.toolsDocumentation = {
             },
             returns: 'Updated workflow with applied changes and operation results',
             examples: [
-                `// Update node parameters
+                `// Update node parameters (properties inside parameters object)
+n8n_update_partial_workflow({
+  id: "123",
+  operations: [{
+    type: "updateNode",
+    nodeName: "Slack",
+    changes: {
+      "parameters.channel": "#general",  // Nested property
+      "parameters.text": "Hello world"    // Nested property
+    }
+  }]
+})`,
+                `// Update error handling (NODE-LEVEL properties, NOT inside parameters!)
 n8n_update_partial_workflow({
   id: "123",
   operations: [{
     type: "updateNode",
-    nodeId: "Slack",
-    updates: {parameters: {channel: "general"}}
+    nodeName: "HTTP Request",
+    changes: {
+      onError: "continueErrorOutput",    // ✅ Correct - node level
+      retryOnFail: true,                 // ✅ Correct - node level
+      maxTries: 3,                       // ✅ Correct - node level
+      waitBetweenTries: 2000             // ✅ Correct - node level
+    }
   }]
 })`,
-                `// Add connection between nodes
+                `// WRONG - Don't put error handling inside parameters!
+// ❌ BAD: changes: {"parameters.onError": "continueErrorOutput"}
+// ✅ GOOD: changes: {onError: "continueErrorOutput"}`,
+                `// Add error connection between nodes
 n8n_update_partial_workflow({
   id: "123",
   operations: [{
     type: "addConnection",
-    from: "HTTP Request",
-    to: "Slack",
-    fromOutput: "main",
-    toInput: "main"
+    source: "Database Query",
+    target: "Error Handler",
+    sourceOutput: "error",  // Error output
+    targetInput: "main"
   }]
 })`
             ],
             useCases: [
                 'Updating node configurations',
+                'Adding error handling to nodes',
                 'Adding/removing connections',
                 'Enabling/disabling nodes',
                 'Moving nodes in canvas',
@@ -394,13 +471,14 @@ n8n_update_partial_workflow({
             ],
             performance: 'Very efficient - only sends changes. 80-90% less data than full updates.',
             bestPractices: [
+                'Error handling properties (onError, retryOnFail, etc.) go at NODE level, not in parameters',
+                'Use dot notation for nested properties: "parameters.url"',
                 'Batch related operations together',
                 'Use validateOnly:true to test first',
-                'Reference nodes by name for clarity',
-                'Keep under 5 operations per request',
-                'Check operation results for success'
+                'Reference nodes by name for clarity'
             ],
             pitfalls: [
+                'Placing error handling properties inside parameters (common mistake!)',
                 'Maximum 5 operations per request',
                 'Some operations have dependencies',
                 'Node must exist for update operations',
@@ -408,6 +486,641 @@ n8n_update_partial_workflow({
             ],
             relatedTools: ['n8n_get_workflow', 'n8n_update_full_workflow', 'validate_workflow']
         }
+    },
+    code_node_guide: {
+        name: 'code_node_guide',
+        category: 'code_node',
+        essentials: {
+            description: 'Comprehensive guide for writing Code node JavaScript and Python',
+            keyParameters: ['topic'],
+            example: 'tools_documentation({topic: "code_node_guide"})',
+            performance: 'Instant - returns documentation',
+            tips: [
+                'Essential reading before writing Code node scripts',
+                'Covers all built-in variables and helpers',
+                'Includes common patterns and error handling'
+            ]
+        },
+        full: {
+            description: `Complete reference for the n8n Code node, covering JavaScript and Python execution environments, built-in variables, helper functions, and best practices.
+
+## Code Node Basics
+
+The Code node allows custom JavaScript or Python code execution within workflows. It runs in a sandboxed environment with access to n8n-specific variables and helpers.
+
+### JavaScript Environment
+- **ES2022 support** with async/await
+- **Built-in libraries**: 
+  - **luxon** (DateTime) - Date/time manipulation
+  - **jmespath** - JSON queries via $jmespath()
+  - **crypto** - Available via require('crypto') despite editor warnings!
+- **Node.js globals**: Buffer, process.env (limited)
+- **require() IS available** for built-in modules only (crypto, util, etc.)
+- **No npm packages** - only Node.js built-ins and n8n-provided libraries
+
+### Python Environment  
+- **Python 3.10+** with standard library (Pyodide runtime)
+- **No pip install** - standard library only
+- **Variables use underscore prefix**: \`_input\`, \`_json\`, \`_jmespath\` (not \`$\`)
+- **item.json is JsProxy**: Use \`.to_py()\` to convert to Python dict
+- **Shared state** between Code nodes in same execution
+
+## Essential Variables
+
+### $input
+Access to all incoming data:
+\`\`\`javascript
+// Get all items from all inputs
+const allItems = $input.all();  // Returns: Item[][]
+
+// Get items from specific input (0-indexed)
+const firstInput = $input.all(0);  // Returns: Item[]
+
+// Get first item from first input
+const firstItem = $input.first();  // Returns: Item
+
+// Get last item from first input  
+const lastItem = $input.last();  // Returns: Item
+
+// Get specific item by index
+const item = $input.item(2);  // Returns: Item at index 2
+\`\`\`
+
+### items
+Direct access to incoming items (legacy, prefer $input):
+\`\`\`javascript
+// items is equivalent to $input.all()[0]
+for (const item of items) {
+  console.log(item.json);  // Access JSON data
+  console.log(item.binary);  // Access binary data
+}
+\`\`\`
+
+### $json
+Shortcut to current item's JSON data (only in "Run Once for Each Item" mode):
+\`\`\`javascript
+// These are equivalent in single-item mode:
+const value1 = $json.fieldName;
+const value2 = items[0].json.fieldName;
+\`\`\`
+
+### Accessing Other Nodes
+Access data from other nodes using $('Node Name') syntax:
+\`\`\`javascript
+// Access another node's output - use $('Node Name') NOT $node
+const prevData = $('Previous Node').all();
+const firstItem = $('Previous Node').first();
+const specificItem = $('Previous Node').item(0);
+
+// Get node parameter
+const webhookUrl = $('Webhook').params.path;
+
+// Python uses underscore prefix
+const pythonData = _('Previous Node').all();
+\`\`\`
+
+⚠️ **Expression vs Code Node Syntax**:
+- **Expressions**: \`{{$node['Previous Node'].json.field}}\`
+- **Code Node**: \`$('Previous Node').first().json.field\`
+- These are NOT interchangeable!
+
+### $workflow
+Workflow metadata:
+\`\`\`javascript
+const workflowId = $workflow.id;
+const workflowName = $workflow.name;
+const isActive = $workflow.active;
+\`\`\`
+
+### $execution
+Execution context:
+\`\`\`javascript
+const executionId = $execution.id;
+const executionMode = $execution.mode;  // 'manual', 'trigger', etc.
+const resumeUrl = $execution.resumeUrl;  // For wait nodes
+\`\`\`
+
+### $prevNode
+Access to the immediate previous node:
+\`\`\`javascript
+const prevOutput = $prevNode.outputIndex;  // Which output triggered this
+const prevData = $prevNode.data;  // Previous node's data
+const prevName = $prevNode.name;  // Previous node's name
+\`\`\`
+
+## Helper Functions
+
+### Date/Time (Luxon)
+\`\`\`javascript
+// Current time
+const now = DateTime.now();
+const iso = now.toISO();
+
+// Parse dates
+const date = DateTime.fromISO('2024-01-01');
+const formatted = date.toFormat('yyyy-MM-dd');
+
+// Time math
+const tomorrow = now.plus({ days: 1 });
+const hourAgo = now.minus({ hours: 1 });
+\`\`\`
+
+### JSON Queries (JMESPath)
+\`\`\`javascript
+// n8n uses $jmespath() - NOTE: parameter order is reversed from standard JMESPath!
+const data = { users: [{ name: 'John', age: 30 }, { name: 'Jane', age: 25 }] };
+const names = $jmespath(data, 'users[*].name');  // ['John', 'Jane']
+
+// ⚠️ IMPORTANT: Numeric literals in filters need BACKTICKS in n8n!
+const adults = $jmespath(data, 'users[?age >= \`18\`]');  // ✅ CORRECT - backticks around 18
+const seniors = $jmespath(data, 'users[?age >= \`65\`]');  // ✅ CORRECT
+
+// ❌ WRONG - This will cause a syntax error!
+// const adults = $jmespath(data, 'users[?age >= 18]');  // Missing backticks
+
+// More filter examples with proper backticks:
+const expensive = $jmespath(items, '[?price > \`100\`]');
+const inStock = $jmespath(products, '[?quantity >= \`1\`]');
+const highPriority = $jmespath(tasks, '[?priority == \`1\`]');
+
+// String comparisons don't need backticks
+const activeUsers = $jmespath(data, 'users[?status == "active"]');
+
+// Python uses underscore prefix
+const pythonAdults = _jmespath(data, 'users[?age >= \`18\`]');
+\`\`\`
+
+⚠️ **CRITICAL DIFFERENCES** from standard JMESPath:
+1. **Parameter order is REVERSED**:
+   - **Expression**: \`{{$jmespath("query", data)}}\`
+   - **Code Node**: \`$jmespath(data, "query")\`
+2. **Numeric literals in filters MUST use backticks**: \`[?age >= \`18\`]\`
+   - This is n8n-specific and differs from standard JMESPath documentation!
+
+### Available Functions and Libraries
+
+#### Built-in Node.js Modules (via require)
+\`\`\`javascript
+// ✅ These modules ARE available via require():
+const crypto = require('crypto');        // Cryptographic functions
+const util = require('util');            // Utility functions
+const querystring = require('querystring'); // URL query string utilities
+
+// Example: Generate secure random token
+const crypto = require('crypto');
+const token = crypto.randomBytes(32).toString('hex');
+const uuid = crypto.randomUUID();
+\`\`\`
+
+**Note**: The editor may show errors for require() but it WORKS at runtime!
+
+#### Standalone Functions (Global Scope)
+\`\`\`javascript
+// ✅ Workflow static data - persists between executions
+// IMPORTANT: These are standalone functions, NOT methods on $helpers!
+const staticData = $getWorkflowStaticData('global'); // Global static data
+const nodeData = $getWorkflowStaticData('node');    // Node-specific data
+
+// Example: Counter that persists
+const staticData = $getWorkflowStaticData('global');
+staticData.counter = (staticData.counter || 0) + 1;
+
+// ❌ WRONG - This will cause "$helpers is not defined" error:
+// const data = $helpers.getWorkflowStaticData('global');
+
+// JMESPath queries - note the parameter order!
+const result = $jmespath(data, 'users[*].name');
+\`\`\`
+
+#### $helpers Object (When Available)
+\`\`\`javascript
+// Some n8n versions provide $helpers with these methods:
+// (Always test availability in your n8n instance)
+
+// HTTP requests
+const response = await $helpers.httpRequest({
+  method: 'GET',
+  url: 'https://api.example.com/data',
+  headers: { 'Authorization': 'Bearer token' }
+});
+
+// Binary data preparation  
+const binaryData = await $helpers.prepareBinaryData(
+  Buffer.from('content'), 
+  'file.txt',
+  'text/plain'
+);
+
+// Check if $helpers exists before using:
+if (typeof $helpers !== 'undefined' && $helpers.httpRequest) {
+  // Use $helpers.httpRequest
+} else {
+  throw new Error('HTTP requests not available in this n8n version');
+}
+\`\`\`
+
+#### Important Notes:
+- **$getWorkflowStaticData()** is ALWAYS a standalone function
+- **require()** works for built-in Node.js modules despite editor warnings
+- **$helpers** availability varies by n8n version - always check first
+- Python uses underscore prefix: \`_getWorkflowStaticData()\`, \`_jmespath()\`
+- Editor red underlines are often false positives - test at runtime!
+
+## Return Format
+
+Code nodes MUST return an array of objects with 'json' property:
+
+\`\`\`javascript
+// ✅ CORRECT - Array of objects with json property
+return [
+  { json: { id: 1, name: 'Item 1' } },
+  { json: { id: 2, name: 'Item 2' } }
+];
+
+// ✅ CORRECT - Single item (still wrapped in array)
+return [{ json: { result: 'success' } }];
+
+// ✅ CORRECT - With binary data
+return [{
+  json: { filename: 'report.pdf' },
+  binary: {
+    data: {
+      data: base64String,
+      mimeType: 'application/pdf',
+      fileName: 'report.pdf'
+    }
+  }
+}];
+
+// ❌ WRONG - Not an array
+return { json: { result: 'success' } };
+
+// ❌ WRONG - No json property
+return [{ result: 'success' }];
+
+// ❌ WRONG - Not wrapped in object
+return ['item1', 'item2'];
+\`\`\`
+
+## Common Patterns
+
+### Data Transformation
+\`\`\`javascript
+// Transform all items
+const transformedItems = [];
+for (const item of items) {
+  transformedItems.push({
+    json: {
+      ...item.json,
+      processed: true,
+      timestamp: DateTime.now().toISO(),
+      uppercaseName: item.json.name?.toUpperCase()
+    }
+  });
+}
+return transformedItems;
+\`\`\`
+
+### Filtering Items
+\`\`\`javascript
+// Filter items based on condition
+return items
+  .filter(item => item.json.status === 'active')
+  .map(item => ({ json: item.json }));
+\`\`\`
+
+### Aggregation
+\`\`\`javascript
+// Aggregate data from all items
+const total = items.reduce((sum, item) => sum + (item.json.amount || 0), 0);
+const average = total / items.length;
+
+return [{
+  json: {
+    total,
+    average,
+    count: items.length,
+    items: items.map(i => i.json)
+  }
+}];
+\`\`\`
+
+### Error Handling
+\`\`\`javascript
+// Safe data access with defaults
+const results = [];
+for (const item of items) {
+  try {
+    const value = item.json?.nested?.field || 'default';
+    results.push({
+      json: {
+        processed: value,
+        status: 'success'
+      }
+    });
+  } catch (error) {
+    results.push({
+      json: {
+        error: error.message,
+        status: 'failed',
+        originalItem: item.json
+      }
+    });
+  }
+}
+return results;
+\`\`\`
+
+### Working with APIs
+\`\`\`javascript
+// Make HTTP request and process response
+try {
+  const response = await $helpers.httpRequest({
+    method: 'POST',
+    url: 'https://api.example.com/process',
+    body: {
+      data: items.map(item => item.json)
+    },
+    headers: {
+      'Content-Type': 'application/json'
+    }
+  });
+  
+  return [{ json: response }];
+} catch (error) {
+  throw new Error(\`API request failed: \${error.message}\`);
+}
+\`\`\`
+
+### Async Operations
+\`\`\`javascript
+// Process items with async operations
+const results = [];
+for (const item of items) {
+  // Simulate async operation
+  await new Promise(resolve => setTimeout(resolve, 100));
+  
+  results.push({
+    json: {
+      ...item.json,
+      processedAt: new Date().toISOString()
+    }
+  });
+}
+return results;
+\`\`\`
+
+### Webhook Data Access (CRITICAL!)
+\`\`\`javascript
+// ⚠️ WEBHOOK DATA IS NESTED UNDER 'body' PROPERTY!
+// This is a common source of errors in webhook-triggered workflows
+
+// ❌ WRONG - This will be undefined for webhook data:
+const command = items[0].json.testCommand;
+
+// ✅ CORRECT - Webhook data is wrapped in 'body':
+const command = items[0].json.body.testCommand;
+
+// Complete webhook data processing example:
+const webhookData = items[0].json.body; // Get the actual webhook payload
+const headers = items[0].json.headers;   // HTTP headers are separate
+const query = items[0].json.query;       // Query parameters are separate
+
+// Process webhook payload
+return [{
+  json: {
+    command: webhookData.testCommand,
+    user: webhookData.user,
+    timestamp: DateTime.now().toISO(),
+    requestId: headers['x-request-id'],
+    source: query.source || 'unknown'
+  }
+}];
+
+// For other trigger nodes (non-webhook), data is directly under json:
+// - Schedule Trigger: items[0].json contains timestamp
+// - Database Trigger: items[0].json contains row data
+// - File Trigger: items[0].json contains file info
+\`\`\`
+
+## Python Code Examples
+
+### Basic Python Structure
+\`\`\`python
+import json
+from datetime import datetime
+
+# Access items - Python uses underscore prefix for built-in variables
+results = []
+for item in _input.all():
+    # IMPORTANT: item.json is NOT a standard Python dict!
+    # Use to_py() to convert to a proper Python dict
+    processed_item = item.json.to_py()  # Converts JsProxy to Python dict
+    processed_item['timestamp'] = datetime.now().isoformat()
+    results.append({'json': processed_item})
+
+return results
+\`\`\`
+
+### Python Data Processing
+\`\`\`python
+# Aggregate data - use _input.all() to get items
+items = _input.all()
+total = sum(item.json.get('amount', 0) for item in items)
+average = total / len(items) if items else 0
+
+# For safe dict operations, convert JsProxy to Python dict
+safe_items = []
+for item in items:
+    # Convert JsProxy to dict to avoid KeyError with null values
+    safe_dict = item.json.to_py()
+    safe_items.append(safe_dict)
+
+# Return aggregated result
+return [{
+    'json': {
+        'total': total,
+        'average': average,
+        'count': len(items),
+        'processed_at': datetime.now().isoformat(),
+        'items': safe_items  # Now these are proper Python dicts
+    }
+}]
+\`\`\`
+
+## Code Node as AI Tool
+
+Code nodes can be used as custom tools for AI agents:
+
+\`\`\`javascript
+// Code node configured as AI tool
+// Name: "Calculate Discount"
+// Description: "Calculates discount based on quantity"
+
+const quantity = $json.quantity || 1;
+const basePrice = $json.price || 0;
+
+let discount = 0;
+if (quantity >= 100) discount = 0.20;
+else if (quantity >= 50) discount = 0.15;
+else if (quantity >= 20) discount = 0.10;
+else if (quantity >= 10) discount = 0.05;
+
+const discountAmount = basePrice * quantity * discount;
+const finalPrice = (basePrice * quantity) - discountAmount;
+
+return [{
+  json: {
+    quantity,
+    basePrice,
+    discountPercentage: discount * 100,
+    discountAmount,
+    finalPrice,
+    savings: discountAmount
+  }
+}];
+\`\`\`
+
+## Security Considerations
+
+### Available Security Features
+\`\`\`javascript
+// ✅ Crypto IS available despite editor warnings!
+const crypto = require('crypto');
+
+// Generate secure random values
+const randomBytes = crypto.randomBytes(32);
+const randomUUID = crypto.randomUUID();
+
+// Create hashes
+const hash = crypto.createHash('sha256')
+  .update('data to hash')
+  .digest('hex');
+
+// HMAC for signatures
+const hmac = crypto.createHmac('sha256', 'secret-key')
+  .update('data to sign')
+  .digest('hex');
+\`\`\`
+
+### Banned Operations
+- No file system access (fs module) - except read-only for some paths
+- No network requests except via $helpers.httpRequest
+- No child process execution
+- No external npm packages (only built-in Node.js modules)
+- No eval() or Function() constructor
+
+### Safe Practices
+\`\`\`javascript
+// ✅ SAFE - Use crypto for secure operations
+const crypto = require('crypto');
+const token = crypto.randomBytes(32).toString('hex');
+
+// ✅ SAFE - Use built-in JSON parsing
+const parsed = JSON.parse(jsonString);
+
+// ❌ UNSAFE - Never use eval
+const parsed = eval('(' + jsonString + ')');
+
+// ✅ SAFE - Validate input
+if (typeof item.json.userId !== 'string') {
+  throw new Error('userId must be a string');
+}
+
+// ✅ SAFE - Sanitize for logs
+const safeLog = String(userInput).substring(0, 100);
+
+// ✅ SAFE - Time-safe comparison for secrets
+const expectedToken = 'abc123';
+const providedToken = item.json.token;
+const tokensMatch = crypto.timingSafeEqual(
+  Buffer.from(expectedToken),
+  Buffer.from(providedToken || '')
+);
+\`\`\`
+
+## Debugging Tips
+
+### Console Output
+\`\`\`javascript
+// Console.log appears in n8n execution logs
+console.log('Processing item:', item.json.id);
+console.error('Error details:', error);
+
+// Return debug info in development
+return [{
+  json: {
+    result: processedData,
+    debug: {
+      itemCount: items.length,
+      executionId: $execution.id,
+      timestamp: new Date().toISOString()
+    }
+  }
+}];
+\`\`\`
+
+### Error Messages
+\`\`\`javascript
+// Provide helpful error context
+if (!item.json.requiredField) {
+  throw new Error(\`Missing required field 'requiredField' in item \${items.indexOf(item)}\`);
+}
+
+// Include original data in errors
+try {
+  // processing...
+} catch (error) {
+  throw new Error(\`Failed to process item \${item.json.id}: \${error.message}\`);
+}
+\`\`\`
+
+## Performance Best Practices
+
+1. **Avoid nested loops** when possible
+2. **Use array methods** (map, filter, reduce) for clarity
+3. **Limit HTTP requests** - batch when possible
+4. **Return early** for error conditions
+5. **Keep state minimal** - Code nodes are stateless between executions
+
+## Common Mistakes to Avoid
+
+1. **Forgetting to return an array**
+2. **Not wrapping in json property**
+3. **Modifying items array directly**
+4. **Using undefined variables**
+5. **Infinite loops with while statements**
+6. **Not handling missing data gracefully**
+7. **Forgetting await for async operations**`,
+            parameters: {
+                topic: { type: 'string', description: 'Specific Code node topic (optional)', required: false }
+            },
+            returns: 'Comprehensive Code node documentation and examples',
+            examples: [
+                'tools_documentation({topic: "code_node_guide"}) - Full guide',
+                'tools_documentation({topic: "code_node_guide", depth: "full"}) - Complete reference'
+            ],
+            useCases: [
+                'Learning Code node capabilities',
+                'Understanding built-in variables',
+                'Finding the right helper function',
+                'Debugging Code node issues',
+                'Building custom AI tools'
+            ],
+            performance: 'Instant - returns static documentation',
+            bestPractices: [
+                'Read before writing Code nodes',
+                'Reference for variable names',
+                'Copy examples as starting points',
+                'Check security considerations'
+            ],
+            pitfalls: [
+                'Not all Node.js features available',
+                'Python has limited libraries',
+                'State not preserved between executions'
+            ],
+            relatedTools: ['get_node_essentials', 'validate_node_operation', 'get_node_for_task']
+        }
     }
 };
 function getToolDocumentation(toolName, depth = 'essentials') {
@@ -481,6 +1194,7 @@ Welcome! Here's how to efficiently work with n8n nodes:
 
 ## Get Help
 - tools_documentation({topic: "search_nodes"}) - Get help for specific tool
+- tools_documentation({topic: "code_node_guide"}) - Essential Code node reference
 - tools_documentation({topic: "overview", depth: "full"}) - See complete guide
 - list_tasks() - See available task templates
 
@@ -547,6 +1261,72 @@ validate_workflow(workflow)
 n8n_create_workflow(workflow)
 \`\`\`
 
+### Working with Code Nodes
+The Code node is essential for custom logic. Always reference the guide:
+\`\`\`javascript
+// Get comprehensive Code node documentation
+tools_documentation({topic: "code_node_guide"})
+
+// Common Code node pattern
+get_node_essentials("n8n-nodes-base.code")
+// Returns minimal config with JavaScript/Python examples
+
+// Validate Code node configuration
+validate_node_operation("n8n-nodes-base.code", {
+  language: "javaScript",
+  jsCode: "return items.map(item => ({json: {...item.json, processed: true}}))"
+})
+\`\`\`
+
+### Node-Level Properties Reference
+⚠️ **CRITICAL**: These properties go at the NODE level, not inside parameters!
+
+\`\`\`javascript
+{
+  // Required properties
+  "id": "unique_id",
+  "name": "Node Name",
+  "type": "n8n-nodes-base.postgres",
+  "typeVersion": 2.6,
+  "position": [450, 300],
+  "parameters": { /* operation-specific params */ },
+  
+  // Optional properties (all at node level!)
+  "credentials": {
+    "postgres": {
+      "id": "cred-id",
+      "name": "My Postgres"
+    }
+  },
+  "disabled": false,              // Disable node execution
+  "notes": "Internal note",       // Node documentation
+  "notesInFlow": true,           // Show notes on canvas
+  "executeOnce": true,           // Execute only once per run
+  
+  // Error handling (at node level!)
+  "onError": "continueErrorOutput",  // or "continueRegularOutput", "stopWorkflow"
+  "retryOnFail": true,
+  "maxTries": 3,
+  "waitBetweenTries": 2000,
+  "alwaysOutputData": true,
+  
+  // Deprecated (use onError instead)
+  "continueOnFail": false
+}
+\`\`\`
+
+**Common properties explained:**
+- **credentials**: Links to credential sets (use credential ID and name)
+- **disabled**: Node won't execute when true
+- **notes**: Internal documentation for the node
+- **notesInFlow**: Display notes on workflow canvas
+- **executeOnce**: Execute node only once even with multiple input items
+- **onError**: Modern error handling - what to do on failure
+- **retryOnFail**: Automatically retry failed executions
+- **maxTries**: Number of retry attempts (with retryOnFail)
+- **waitBetweenTries**: Milliseconds between retries
+- **alwaysOutputData**: Output data even on error (for debugging)
+
 ### Using AI Tools
 Any node can be an AI tool! Connect it to an AI Agent's ai_tool port:
 \`\`\`javascript