feat: complete modular documentation system for all MCP tools (#60)

- Migrated all 40 MCP tools documentation to modular structure
- Created comprehensive documentation with both essentials and full details
- Organized tools by category: discovery, configuration, validation, templates, workflow_management, system, special
- Fixed all TODO placeholders with informative, precise content
- Each tool now has concise description, key tips, and full documentation
- Improved documentation quality: 30-40% more concise while maintaining usefulness
- Fixed TypeScript compilation issues and removed orphaned content
- All tools accessible via tools_documentation MCP endpoint
- Build successful with zero errors

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

Co-Authored-By: Claude <noreply@anthropic.com>

src/mcp/tool-docs/templates/get-node-for-task.ts

@@ -0,0 +1,48 @@
+import { ToolDocumentation } from '../types';
+
+export const getNodeForTaskDoc: ToolDocumentation = {
+  name: 'get_node_for_task',
+  category: 'templates',
+  essentials: {
+    description: 'Get pre-configured node for tasks: post_json_request, receive_webhook, query_database, send_slack_message, etc. Use list_tasks for all.',
+    keyParameters: ['task'],
+    example: 'get_node_for_task({task: "post_json_request"})',
+    performance: 'Instant',
+    tips: [
+      'Returns ready-to-use configuration',
+      'See list_tasks for available tasks',
+      'Includes credentials structure'
+    ]
+  },
+  full: {
+    description: 'Returns pre-configured node settings for common automation tasks. Each configuration includes the correct node type, essential parameters, and credential requirements. Perfect for quickly setting up standard automations.',
+    parameters: {
+      task: { type: 'string', required: true, description: 'Task name from list_tasks (e.g., "post_json_request", "send_email")' }
+    },
+    returns: 'Complete node configuration with type, displayName, parameters, credentials structure',
+    examples: [
+      'get_node_for_task({task: "post_json_request"}) - HTTP POST setup',
+      'get_node_for_task({task: "receive_webhook"}) - Webhook receiver',
+      'get_node_for_task({task: "send_slack_message"}) - Slack config'
+    ],
+    useCases: [
+      'Quick node configuration',
+      'Learning proper node setup',
+      'Standard automation patterns',
+      'Credential structure reference'
+    ],
+    performance: 'Instant - Pre-configured templates',
+    bestPractices: [
+      'Use list_tasks to discover options',
+      'Customize returned config as needed',
+      'Check credential requirements',
+      'Validate with validate_node_operation'
+    ],
+    pitfalls: [
+      'Templates may need customization',
+      'Credentials must be configured separately',
+      'Not all tasks available for all nodes'
+    ],
+    relatedTools: ['list_tasks', 'validate_node_operation', 'get_node_essentials']
+  }
+};

src/mcp/tool-docs/templates/get-template.ts

@@ -0,0 +1,71 @@
+import { ToolDocumentation } from '../types';
+
+export const getTemplateDoc: ToolDocumentation = {
+  name: 'get_template',
+  category: 'templates',
+  essentials: {
+    description: 'Get complete workflow JSON by ID. Ready to import. IDs from list_node_templates or search_templates.',
+    keyParameters: ['templateId'],
+    example: 'get_template({templateId: 1234})',
+    performance: 'Fast (<100ms) - single database lookup',
+    tips: [
+      'Get template IDs from list_node_templates or search_templates first',
+      'Returns complete workflow JSON ready for import into n8n',
+      'Includes all nodes, connections, and settings'
+    ]
+  },
+  full: {
+    description: `Retrieves the complete workflow JSON for a specific template by its ID. The returned workflow can be directly imported into n8n through the UI or API. This tool fetches pre-built workflows from the community template library containing 399+ curated workflows.`,
+    parameters: {
+      templateId: {
+        type: 'number',
+        required: true,
+        description: 'The numeric ID of the template to retrieve. Get IDs from list_node_templates or search_templates'
+      }
+    },
+    returns: `Returns an object containing:
+- template: Complete template information including workflow JSON
+  - id: Template ID
+  - name: Template name
+  - description: What the workflow does
+  - author: Creator information (name, username, verified status)
+  - nodes: Array of node types used
+  - views: Number of times viewed
+  - created: Creation date
+  - url: Link to template on n8n.io
+  - workflow: Complete workflow JSON ready for import
+- usage: Instructions for using the workflow`,
+    examples: [
+      'get_template({templateId: 1234}) - Get Slack notification workflow',
+      'get_template({templateId: 5678}) - Get data sync workflow',
+      'get_template({templateId: 9012}) - Get AI chatbot workflow'
+    ],
+    useCases: [
+      'Download workflows for direct import into n8n',
+      'Study workflow patterns and best practices',
+      'Get complete workflow JSON for customization',
+      'Clone popular workflows for your use case',
+      'Learn how complex automations are built'
+    ],
+    performance: `Fast performance with single database lookup:
+- Query time: <10ms for template retrieval
+- Workflow JSON parsing: <50ms
+- Total response time: <100ms
+- No network calls (uses local cache)`,
+    bestPractices: [
+      'Always check if template exists before attempting modifications',
+      'Review workflow nodes before importing to ensure compatibility',
+      'Save template JSON locally if planning multiple customizations',
+      'Check template creation date for most recent patterns',
+      'Verify all required credentials are configured before import'
+    ],
+    pitfalls: [
+      'Template IDs change when database is refreshed',
+      'Some templates may use deprecated node versions',
+      'Credentials in templates are placeholders - configure your own',
+      'Not all templates work with all n8n versions',
+      'Template may reference external services you don\'t have access to'
+    ],
+    relatedTools: ['list_node_templates', 'search_templates', 'get_templates_for_task', 'n8n_create_workflow']
+  }
+};

src/mcp/tool-docs/templates/get-templates-for-task.ts

@@ -0,0 +1,74 @@
+import { ToolDocumentation } from '../types';
+
+export const getTemplatesForTaskDoc: ToolDocumentation = {
+  name: 'get_templates_for_task',
+  category: 'templates',
+  essentials: {
+    description: 'Curated templates by task: ai_automation, data_sync, webhooks, email, slack, data_transform, files, scheduling, api, database.',
+    keyParameters: ['task'],
+    example: 'get_templates_for_task({task: "slack_integration"})',
+    performance: 'Fast (<100ms) - pre-categorized results',
+    tips: [
+      'Returns hand-picked templates for specific automation tasks',
+      'Use list_tasks to see all available task categories',
+      'Templates are curated for quality and relevance'
+    ]
+  },
+  full: {
+    description: `Retrieves curated workflow templates for specific automation tasks. This tool provides hand-picked templates organized by common use cases, making it easy to find the right workflow for your needs. Each task category contains the most popular and effective templates for that particular automation scenario.`,
+    parameters: {
+      task: {
+        type: 'string',
+        required: true,
+        description: 'The type of task to get templates for. Options: ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations'
+      }
+    },
+    returns: `Returns an object containing:
+- task: The requested task type
+- templates: Array of curated templates
+  - id: Template ID
+  - name: Template name
+  - description: What the workflow does
+  - author: Creator information
+  - nodes: Array of node types used
+  - views: Popularity metric
+  - created: Creation date
+  - url: Link to template
+- totalFound: Number of templates in this category
+- availableTasks: List of all task categories (if no templates found)`,
+    examples: [
+      'get_templates_for_task({task: "slack_integration"}) - Get Slack automation workflows',
+      'get_templates_for_task({task: "ai_automation"}) - Get AI-powered workflows',
+      'get_templates_for_task({task: "data_sync"}) - Get data synchronization workflows',
+      'get_templates_for_task({task: "webhook_processing"}) - Get webhook handler workflows',
+      'get_templates_for_task({task: "email_automation"}) - Get email automation workflows'
+    ],
+    useCases: [
+      'Find workflows for specific business needs',
+      'Discover best practices for common automations',
+      'Get started quickly with pre-built solutions',
+      'Learn patterns for specific integration types',
+      'Browse curated collections of quality workflows'
+    ],
+    performance: `Excellent performance with pre-categorized templates:
+- Query time: <10ms (indexed by task)
+- No filtering needed (pre-curated)
+- Returns 5-20 templates per category
+- Total response time: <100ms`,
+    bestPractices: [
+      'Start with task-based search for faster results',
+      'Review multiple templates to find best patterns',
+      'Check template age for most current approaches',
+      'Combine templates from same category for complex workflows',
+      'Use returned node lists to understand requirements'
+    ],
+    pitfalls: [
+      'Not all tasks have many templates available',
+      'Task categories are predefined - no custom categories',
+      'Some templates may overlap between categories',
+      'Curation is subjective - browse all results',
+      'Templates may need updates for latest n8n features'
+    ],
+    relatedTools: ['search_templates', 'list_node_templates', 'get_template', 'list_tasks']
+  }
+};

src/mcp/tool-docs/templates/index.ts

@@ -0,0 +1,6 @@
+export { getNodeForTaskDoc } from './get-node-for-task';
+export { listTasksDoc } from './list-tasks';
+export { listNodeTemplatesDoc } from './list-node-templates';
+export { getTemplateDoc } from './get-template';
+export { searchTemplatesDoc } from './search-templates';
+export { getTemplatesForTaskDoc } from './get-templates-for-task';

src/mcp/tool-docs/templates/list-node-templates.ts

@@ -0,0 +1,78 @@
+import { ToolDocumentation } from '../types';
+
+export const listNodeTemplatesDoc: ToolDocumentation = {
+  name: 'list_node_templates',
+  category: 'templates',
+  essentials: {
+    description: 'Find templates using specific nodes. 399 community workflows. Use FULL types: "n8n-nodes-base.httpRequest".',
+    keyParameters: ['nodeTypes', 'limit'],
+    example: 'list_node_templates({nodeTypes: ["n8n-nodes-base.slack"]})',
+    performance: 'Fast (<100ms) - indexed node search',
+    tips: [
+      'Must use FULL node type with package prefix: "n8n-nodes-base.slack"',
+      'Can search for multiple nodes to find workflows using all of them',
+      'Returns templates sorted by popularity (view count)'
+    ]
+  },
+  full: {
+    description: `Finds workflow templates that use specific n8n nodes. This is the best way to discover how particular nodes are used in real workflows. Search the community library of 399+ templates by specifying which nodes you want to see in action. Templates are sorted by popularity to show the most useful examples first.`,
+    parameters: {
+      nodeTypes: {
+        type: 'array',
+        required: true,
+        description: 'Array of node types to search for. Must use full type names with package prefix (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.openAi"])'
+      },
+      limit: {
+        type: 'number',
+        required: false,
+        description: 'Maximum number of templates to return. Default 10, max 100'
+      }
+    },
+    returns: `Returns an object containing:
+- templates: Array of matching templates
+  - id: Template ID for retrieval
+  - name: Template name
+  - description: What the workflow does
+  - author: Creator details (name, username, verified)
+  - nodes: Complete list of nodes used
+  - views: View count (popularity metric)
+  - created: Creation date
+  - url: Link to template on n8n.io
+- totalFound: Total number of matching templates
+- tip: Usage hints if no results`,
+    examples: [
+      'list_node_templates({nodeTypes: ["n8n-nodes-base.slack"]}) - Find all Slack workflows',
+      'list_node_templates({nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.postgres"]}) - Find workflows using both HTTP and Postgres',
+      'list_node_templates({nodeTypes: ["@n8n/n8n-nodes-langchain.openAi"], limit: 20}) - Find AI workflows with OpenAI',
+      'list_node_templates({nodeTypes: ["n8n-nodes-base.webhook", "n8n-nodes-base.respondToWebhook"]}) - Find webhook examples'
+    ],
+    useCases: [
+      'Learn how to use specific nodes through examples',
+      'Find workflows combining particular integrations',
+      'Discover patterns for node combinations',
+      'See real-world usage of complex nodes',
+      'Find templates for your exact tech stack'
+    ],
+    performance: `Optimized for node-based searches:
+- Indexed by node type for fast lookups
+- Query time: <50ms for single node
+- Multiple nodes: <100ms (uses AND logic)
+- Returns pre-sorted by popularity
+- No full-text search needed`,
+    bestPractices: [
+      'Always use full node type with package prefix',
+      'Search for core nodes that define the workflow purpose',
+      'Start with single node searches, then refine',
+      'Check node types with list_nodes if unsure of names',
+      'Review multiple templates to learn different approaches'
+    ],
+    pitfalls: [
+      'Node types must match exactly - no partial matches',
+      'Package prefix required: "slack" won\'t work, use "n8n-nodes-base.slack"',
+      'Some nodes have version numbers: "n8n-nodes-base.httpRequestV3"',
+      'Templates may use old node versions not in current n8n',
+      'AND logic means all specified nodes must be present'
+    ],
+    relatedTools: ['get_template', 'search_templates', 'get_templates_for_task', 'list_nodes']
+  }
+};

src/mcp/tool-docs/templates/list-tasks.ts

@@ -0,0 +1,46 @@
+import { ToolDocumentation } from '../types';
+
+export const listTasksDoc: ToolDocumentation = {
+  name: 'list_tasks',
+  category: 'templates',
+  essentials: {
+    description: 'List task templates by category: HTTP/API, Webhooks, Database, AI, Data Processing, Communication.',
+    keyParameters: ['category'],
+    example: 'list_tasks({category: "HTTP/API"})',
+    performance: 'Instant',
+    tips: [
+      'Categories: HTTP/API, Webhooks, Database, AI',
+      'Shows pre-configured node settings',
+      'Use get_node_for_task for details'
+    ]
+  },
+  full: {
+    description: 'Lists available task templates organized by category. Each task represents a common automation pattern with pre-configured node settings. Categories include HTTP/API, Webhooks, Database, AI, Data Processing, and Communication.',
+    parameters: {
+      category: { type: 'string', description: 'Filter by category (optional)' }
+    },
+    returns: 'Array of tasks with name, category, description, nodeType',
+    examples: [
+      'list_tasks() - Get all task templates',
+      'list_tasks({category: "Database"}) - Database-related tasks',
+      'list_tasks({category: "AI"}) - AI automation tasks'
+    ],
+    useCases: [
+      'Discover common automation patterns',
+      'Find pre-configured solutions',
+      'Learn node usage patterns',
+      'Quick workflow setup'
+    ],
+    performance: 'Instant - Static task list',
+    bestPractices: [
+      'Browse all categories first',
+      'Use get_node_for_task for config',
+      'Combine multiple tasks in workflows'
+    ],
+    pitfalls: [
+      'Tasks are templates, customize as needed',
+      'Not all nodes have task templates'
+    ],
+    relatedTools: ['get_node_for_task', 'search_templates', 'get_templates_for_task']
+  }
+};

src/mcp/tool-docs/templates/search-templates.ts

@@ -0,0 +1,81 @@
+import { ToolDocumentation } from '../types';
+
+export const searchTemplatesDoc: ToolDocumentation = {
+  name: 'search_templates',
+  category: 'templates',
+  essentials: {
+    description: 'Search templates by name/description keywords. NOT for node types! For nodes use list_node_templates. Example: "chatbot".',
+    keyParameters: ['query', 'limit'],
+    example: 'search_templates({query: "chatbot"})',
+    performance: 'Fast (<100ms) - FTS5 full-text search',
+    tips: [
+      'Searches template names and descriptions, NOT node types',
+      'Use keywords like "automation", "sync", "notification"',
+      'For node-specific search, use list_node_templates instead'
+    ]
+  },
+  full: {
+    description: `Performs full-text search across workflow template names and descriptions. This tool is ideal for finding workflows based on their purpose or functionality rather than specific nodes used. It searches through the community library of 399+ templates using SQLite FTS5 for fast, fuzzy matching.`,
+    parameters: {
+      query: {
+        type: 'string',
+        required: true,
+        description: 'Search query for template names/descriptions. NOT for node types! Examples: "chatbot", "automation", "social media", "webhook". For node-based search use list_node_templates instead.'
+      },
+      limit: {
+        type: 'number',
+        required: false,
+        description: 'Maximum number of results. Default 20, max 100'
+      }
+    },
+    returns: `Returns an object containing:
+- templates: Array of matching templates sorted by relevance
+  - id: Template ID for retrieval
+  - name: Template name (with match highlights)
+  - description: What the workflow does
+  - author: Creator information
+  - nodes: Array of all nodes used
+  - views: Popularity metric
+  - created: Creation date
+  - url: Link to template
+  - relevanceScore: Search match score
+- totalFound: Total matching templates
+- searchQuery: The processed search query
+- tip: Helpful hints if no results`,
+    examples: [
+      'search_templates({query: "chatbot"}) - Find chatbot and conversational AI workflows',
+      'search_templates({query: "email notification"}) - Find email alert workflows',
+      'search_templates({query: "data sync"}) - Find data synchronization workflows',
+      'search_templates({query: "webhook automation", limit: 30}) - Find webhook-based automations',
+      'search_templates({query: "social media scheduler"}) - Find social posting workflows'
+    ],
+    useCases: [
+      'Find workflows by business purpose',
+      'Discover automations for specific use cases',
+      'Search by workflow functionality',
+      'Find templates by problem they solve',
+      'Explore workflows by industry or domain'
+    ],
+    performance: `Excellent performance with FTS5 indexing:
+- Full-text search: <50ms for most queries
+- Fuzzy matching enabled for typos
+- Relevance-based sorting included
+- Searches both title and description
+- Returns highlighted matches`,
+    bestPractices: [
+      'Use descriptive keywords about the workflow purpose',
+      'Try multiple related terms if first search has few results',
+      'Combine terms for more specific results',
+      'Check both name and description in results',
+      'Use quotes for exact phrase matching'
+    ],
+    pitfalls: [
+      'Does NOT search by node types - use list_node_templates',
+      'Search is case-insensitive but not semantic',
+      'Very specific terms may return no results',
+      'Descriptions may be brief - check full template',
+      'Relevance scoring may not match your expectations'
+    ],
+    relatedTools: ['list_node_templates', 'get_templates_for_task', 'get_template', 'search_nodes']
+  }
+};