n8n-MCP

Instructions

Implementation Reference

• src/mcp/tools-documentation.ts:3-66 (handler)

  Core handler function implementing tools_documentation logic. Handles topic parameter, special guides (JS/Python code nodes), and returns formatted markdown documentation at 'essentials' or 'full' depth using pre-loaded toolsDocumentation data.

  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.`;
    }
  
    if (depth === 'essentials') {
      const { essentials } = tool;
      return `# ${tool.name}
  
  ${essentials.description}
  
  **Example**: ${essentials.example}
  
  **Key parameters**: ${essentials.keyParameters.join(', ')}
  
  **Performance**: ${essentials.performance}
  
  **Tips**:
  ${essentials.tips.map(tip => `- ${tip}`).join('\n')}
  
  For full documentation, use: tools_documentation({topic: "${toolName}", depth: "full"})`;
    }
  
    // Full documentation
    const { full } = tool;
    return `# ${tool.name}
  
  ${full.description}
  
  ## Parameters
  ${Object.entries(full.parameters).map(([param, info]) => 
    `- **${param}** (${info.type}${info.required ? ', required' : ''}): ${info.description}`
  ).join('\n')}
  
  ## Returns
  ${full.returns}
  
  ## Examples
  ${full.examples.map(ex => `\`\`\`javascript\n${ex}\n\`\`\``).join('\n\n')}
  
  ## Common Use Cases
  ${full.useCases.map(uc => `- ${uc}`).join('\n')}
  
  ## Performance
  ${full.performance}
  
  ## Best Practices
  ${full.bestPractices.map(bp => `- ${bp}`).join('\n')}
  
  ## Common Pitfalls
  ${full.pitfalls.map(p => `- ${p}`).join('\n')}
  
  ## Related Tools
  ${full.relatedTools.map(t => `- ${t}`).join('\n')}`;
  }

• src/mcp/tools.ts:10-28 (registration)

  Tool registration definition including name, description, and inputSchema as part of n8nDocumentationToolsFinal array used by MCP server.

  {
    name: 'tools_documentation',
    description: `Get documentation for n8n MCP tools. Call without parameters for quick start guide. Use topic parameter to get documentation for specific tools. Use depth='full' for comprehensive documentation.`,
    inputSchema: {
      type: 'object',
      properties: {
        topic: {
          type: 'string',
          description: 'Tool name (e.g., "search_nodes") or "overview" for general guide. Leave empty for quick reference.',
        },
        depth: {
          type: 'string',
          enum: ['essentials', 'full'],
          description: 'Level of detail. "essentials" (default) for quick reference, "full" for comprehensive docs.',
          default: 'essentials',
        },
      },
    },
  },

• src/mcp/tool-docs/system/tools-documentation.ts:1-63 (schema)

  Detailed ToolDocumentation schema defining parameters, returns, examples, use cases, best practices, pitfalls, and related tools for self-documentation.

  import { ToolDocumentation } from '../types';
  
  export const toolsDocumentationDoc: ToolDocumentation = {
    name: 'tools_documentation',
    category: 'system',
    essentials: {
      description: 'The meta-documentation tool. Returns documentation for any MCP tool, including itself. Call without parameters for a comprehensive overview of all available tools. This is your starting point for discovering n8n MCP capabilities.',
      keyParameters: ['topic', 'depth'],
      example: 'tools_documentation({topic: "search_nodes"})',
      performance: 'Instant (static content)',
      tips: [
        'Call without parameters first to see all tools',
        'Can document itself: tools_documentation({topic: "tools_documentation"})',
        'Use depth:"full" for comprehensive details'
      ]
    },
    full: {
      description: 'The self-referential documentation system for all MCP tools. This tool can document any other tool, including itself. It\'s the primary discovery mechanism for understanding what tools are available and how to use them. Returns utilitarian documentation optimized for AI agent consumption.',
      parameters: {
        topic: { type: 'string', description: 'Tool name (e.g., "search_nodes"), special topic ("javascript_code_node_guide", "python_code_node_guide"), or "overview". Leave empty for quick reference.', required: false },
        depth: { type: 'string', description: 'Level of detail: "essentials" (default, concise) or "full" (comprehensive with examples)', required: false }
      },
      returns: 'Markdown-formatted documentation tailored for the requested tool and depth. For essentials: key info, parameters, example, tips. For full: complete details, all examples, use cases, best practices.',
      examples: [
        '// Get started - see all available tools',
        'tools_documentation()',
        '',
        '// Learn about a specific tool',
        'tools_documentation({topic: "search_nodes"})',
        '',
        '// Get comprehensive details',
        'tools_documentation({topic: "validate_workflow", depth: "full"})',
        '',
        '// Self-referential example - document this tool',
        'tools_documentation({topic: "tools_documentation", depth: "full"})',
        '',
        '// Code node guides',
        'tools_documentation({topic: "javascript_code_node_guide"})',
        'tools_documentation({topic: "python_code_node_guide"})'
      ],
      useCases: [
        'Initial discovery of available MCP tools',
        'Learning how to use specific tools',
        'Finding required and optional parameters',
        'Getting working examples to copy',
        'Understanding tool performance characteristics',
        'Discovering related tools for workflows'
      ],
      performance: 'Instant - all documentation is pre-loaded in memory',
      bestPractices: [
        'Always start with tools_documentation() to see available tools',
        'Use essentials for quick parameter reference during coding',
        'Switch to full depth when debugging or learning new tools',
        'Check Code node guides when working with Code nodes'
      ],
      pitfalls: [
        'Tool names must match exactly - use the overview to find correct names',
        'Not all internal functions are documented',
        'Special topics (code guides) require exact names'
      ],
      relatedTools: ['n8n_health_check for verifying API connection', 'search_templates for workflow examples', 'search_nodes for finding nodes']
    }
  };

• src/mcp/tools-documentation.ts:68-186 (helper)

  Helper function getToolsOverview that provides comprehensive overview of all tools when tools_documentation() is called without topic parameter.

  export function getToolsOverview(depth: 'essentials' | 'full' = 'essentials'): string {
    // Get version info from package.json
    const packageJson = require('../../package.json');
    const supportedN8nVersion = packageJson.dependencies?.n8n?.replace(/[^0-9.]/g, '') || 'latest';
    
    if (depth === 'essentials') {
      return `# n8n MCP Tools Reference
  
  ## Important: Compatibility Notice
  ⚠️ This MCP server is tested with n8n version ${supportedN8nVersion}. 
  Inform the user to check their n8n version matches or is compatible with the supported version listed above.
  
  ## 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
  
  ## Standard Workflow Pattern
  
  ⚠️ **CRITICAL**: Always call get_node() with detail='standard' FIRST before configuring any node!
  
  1. **Find** the node you need:
     - search_nodes({query: "slack"}) - Search by keyword
     - search_nodes({query: "communication"}) - Search by category name
     - search_nodes({query: "AI langchain"}) - Search for AI-capable nodes
  
  2. **Configure** the node (ALWAYS START WITH STANDARD DETAIL):
     - ✅ get_node({nodeType: "nodes-base.slack", detail: "standard"}) - Get essential properties FIRST (~1-2KB, shows required fields)
     - get_node({nodeType: "nodes-base.slack", detail: "full"}) - Get complete schema only if standard insufficient (~100KB+)
     - get_node({nodeType: "nodes-base.slack", mode: "docs"}) - Get readable markdown documentation
     - get_node({nodeType: "nodes-base.slack", mode: "search_properties", propertyQuery: "auth"}) - Find specific properties
  
  3. **Validate** before deployment:
     - validate_node({nodeType: "nodes-base.slack", config: {...}, mode: "minimal"}) - Quick required fields check
     - validate_node({nodeType: "nodes-base.slack", config: {...}}) - Full validation with errors/warnings/suggestions
     - validate_workflow({workflow: {...}}) - Validate entire workflow
  
  ## Tool Categories (19 Tools Total)
  
  **Discovery Tools** (1 tool)
  - search_nodes - Full-text search across all nodes (supports OR, AND, FUZZY modes)
  
  **Configuration Tools** (1 consolidated tool)
  - get_node - Unified node information tool:
    - detail='minimal'/'standard'/'full': Progressive detail levels
    - mode='docs': Readable markdown documentation
    - mode='search_properties': Find specific properties
    - mode='versions'/'compare'/'breaking'/'migrations': Version management
  
  **Validation Tools** (2 tools)
  - validate_node - Unified validation with mode='full' or mode='minimal'
  - validate_workflow - Complete workflow validation (nodes, connections, expressions)
  
  **Template Tools** (2 tools)
  - get_template - Get complete workflow JSON by ID
  - search_templates - Unified template search:
    - searchMode='keyword': Text search (default)
    - searchMode='by_nodes': Find templates using specific nodes
    - searchMode='by_task': Curated task-based templates
    - searchMode='by_metadata': Filter by complexity/services
  
  **n8n API Tools** (13 tools, requires N8N_API_URL configuration)
  - n8n_create_workflow - Create new workflows
  - n8n_get_workflow - Get workflow with mode='full'/'details'/'structure'/'minimal'
  - n8n_update_full_workflow - Full workflow replacement
  - n8n_update_partial_workflow - Incremental diff-based updates
  - n8n_delete_workflow - Delete workflow
  - n8n_list_workflows - List workflows with filters
  - n8n_validate_workflow - Validate workflow by ID
  - n8n_autofix_workflow - Auto-fix common issues
  - n8n_test_workflow - Test/trigger workflows (webhook, form, chat, execute)
  - n8n_executions - Unified execution management (action='get'/'list'/'delete')
  - n8n_health_check - Check n8n API connectivity
  - n8n_workflow_versions - Version history and rollback
  - n8n_deploy_template - Deploy templates directly to n8n instance
  
  ## Performance Characteristics
  - Instant (<10ms): search_nodes, get_node (minimal/standard)
  - Fast (<100ms): validate_node, get_template
  - Moderate (100-500ms): validate_workflow, get_node (full detail)
  - Network-dependent: All n8n_* tools
  
  For comprehensive documentation on any tool:
  tools_documentation({topic: "tool_name", depth: "full"})`;
    }
  
    const categories = getAllCategories();
    return `# n8n MCP Tools - Complete Reference
  
  ## Important: Compatibility Notice
  ⚠️ This MCP server is tested with n8n version ${supportedN8nVersion}. 
  Run n8n_health_check() to verify your n8n instance compatibility and API connectivity.
  
  ## 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);
    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')}
  
  ## Usage Notes
  - All node types require the "nodes-base." or "nodes-langchain." prefix
  - Use get_node() with detail='standard' first for most tasks (~95% smaller than detail='full')
  - Validation profiles: minimal (editing), runtime (default), strict (deployment)
  - n8n API tools only available when N8N_API_URL and N8N_API_KEY are configured
  
  For detailed documentation on any tool:
  tools_documentation({topic: "tool_name", depth: "full"})`;
  }