diff --git a/CHANGELOG.md b/CHANGELOG.md index a1a3949..6c2e94a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.26.2] - 2025-11-25 + +### 🔧 Fixed + +- **Tool Documentation Cleanup**: Synchronized `tool-docs/` with v2.26.0 tool consolidation + - Deleted 23 obsolete documentation files for removed tools (get_node_info, get_node_essentials, validate_node_operation, etc.) + - Created consolidated documentation for `get_node` (covers all modes: info, docs, search_properties, versions, compare, breaking, migrations) + - Created consolidated documentation for `validate_node` (covers modes: full, minimal; profiles: minimal, runtime, ai-friendly, strict) + - Created consolidated documentation for `n8n_executions` (covers actions: get, list, delete) + - Updated `search_templates` documentation with all searchModes (keyword, by_nodes, by_task, by_metadata) + - Updated `n8n_get_workflow` documentation with all modes (full, details, structure, minimal) + - Fixed stale `relatedTools` references pointing to removed tools + - Updated `tools-documentation.ts` overview to accurately reflect 19 consolidated tools + ## [2.26.1] - 2025-11-25 ### 🔄 Updated diff --git a/package.json b/package.json index 0e8d124..25bfcda 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "n8n-mcp", - "version": "2.26.1", + "version": "2.26.2", "description": "Integration between n8n workflow automation and Model Context Protocol (MCP)", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/src/mcp/tool-docs/configuration/get-node-as-tool-info.ts b/src/mcp/tool-docs/configuration/get-node-as-tool-info.ts deleted file mode 100644 index 12a5e1f..0000000 --- a/src/mcp/tool-docs/configuration/get-node-as-tool-info.ts +++ /dev/null @@ -1,71 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const getNodeAsToolInfoDoc: ToolDocumentation = { - name: 'get_node_as_tool_info', - category: 'configuration', - essentials: { - description: 'Explains how to use ANY node as an AI tool with requirements and examples.', - keyParameters: ['nodeType'], - example: 'get_node_as_tool_info({nodeType: "nodes-base.slack"})', - performance: 'Fast - returns guidance and examples', - tips: [ - 'ANY node can be used as AI tool, not just AI-marked ones', - 'Community nodes need N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true', - 'Provides specific use cases and connection requirements' - ] - }, - full: { - description: `Shows how to use any n8n node as an AI tool in AI Agent workflows. In n8n, ANY node can be connected to an AI Agent's tool port, allowing the AI to use that node's functionality. This tool provides specific guidance, requirements, and examples for using a node as an AI tool.`, - parameters: { - nodeType: { - type: 'string', - required: true, - description: 'Full node type WITH prefix: "nodes-base.slack", "nodes-base.googleSheets", etc.', - examples: [ - 'nodes-base.slack', - 'nodes-base.httpRequest', - 'nodes-base.googleSheets', - 'nodes-langchain.documentLoader' - ] - } - }, - returns: `Object containing: -- nodeType: The node's full type identifier -- displayName: Human-readable name -- isMarkedAsAITool: Whether node has usableAsTool property -- aiToolCapabilities: Detailed AI tool usage information including: - - canBeUsedAsTool: Always true in n8n - - requiresEnvironmentVariable: For community nodes - - commonUseCases: Specific AI tool use cases - - requirements: Connection and environment setup - - examples: Code examples for common scenarios - - tips: Best practices for AI tool usage`, - examples: [ - 'get_node_as_tool_info({nodeType: "nodes-base.slack"}) - Get AI tool guidance for Slack', - 'get_node_as_tool_info({nodeType: "nodes-base.httpRequest"}) - Learn to use HTTP Request as AI tool', - 'get_node_as_tool_info({nodeType: "nodes-base.postgres"}) - Database queries as AI tools' - ], - useCases: [ - 'Understanding how to connect any node to AI Agent', - 'Learning environment requirements for community nodes', - 'Getting specific use case examples for AI tool usage', - 'Checking if a node is optimized for AI usage', - 'Understanding credential requirements for AI tools' - ], - performance: 'Very fast - returns pre-computed guidance and examples', - bestPractices: [ - 'Use this before configuring nodes as AI tools', - 'Check environment requirements for community nodes', - 'Review common use cases to understand best applications', - 'Test nodes independently before connecting to AI Agent', - 'Give tools descriptive names in AI Agent configuration' - ], - pitfalls: [ - 'Community nodes require environment variable to be used as tools', - 'Not all nodes make sense as AI tools (e.g., triggers)', - 'Some nodes require specific credentials configuration', - 'Tool descriptions in AI Agent must be clear and detailed' - ], - relatedTools: ['list_ai_tools', 'get_node_essentials', 'validate_node_operation'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/configuration/get-node-documentation.ts b/src/mcp/tool-docs/configuration/get-node-documentation.ts deleted file mode 100644 index 9b01d8c..0000000 --- a/src/mcp/tool-docs/configuration/get-node-documentation.ts +++ /dev/null @@ -1,45 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const getNodeDocumentationDoc: ToolDocumentation = { - name: 'get_node_documentation', - category: 'configuration', - essentials: { - description: 'Get readable docs with examples/auth/patterns. Better than raw schema! 87% coverage. Format: "nodes-base.slack"', - keyParameters: ['nodeType'], - example: 'get_node_documentation({nodeType: "nodes-base.slack"})', - performance: 'Fast - pre-parsed', - tips: [ - '87% coverage', - 'Includes auth examples', - 'Human-readable format' - ] - }, - full: { - description: 'Returns human-readable documentation parsed from n8n-docs including examples, authentication setup, and common patterns. More useful than raw schema for understanding node usage.', - parameters: { - nodeType: { type: 'string', required: true, description: 'Full node type with prefix (e.g., "nodes-base.slack")' } - }, - returns: 'Parsed markdown documentation with examples, authentication guides, common patterns', - examples: [ - 'get_node_documentation({nodeType: "nodes-base.slack"}) - Slack usage guide', - 'get_node_documentation({nodeType: "nodes-base.googleSheets"}) - Sheets examples' - ], - useCases: [ - 'Understanding authentication setup', - 'Finding usage examples', - 'Learning common patterns' - ], - performance: 'Fast - Pre-parsed documentation stored in database', - bestPractices: [ - 'Use for learning node usage', - 'Check coverage with get_database_statistics', - 'Combine with get_node_essentials' - ], - pitfalls: [ - 'Not all nodes have docs (87% coverage)', - 'May be outdated for new features', - 'Requires full node type prefix' - ], - relatedTools: ['get_node_info', 'get_node_essentials', 'search_nodes'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/configuration/get-node-essentials.ts b/src/mcp/tool-docs/configuration/get-node-essentials.ts deleted file mode 100644 index cc49df0..0000000 --- a/src/mcp/tool-docs/configuration/get-node-essentials.ts +++ /dev/null @@ -1,86 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const getNodeEssentialsDoc: ToolDocumentation = { - name: 'get_node_essentials', - category: 'configuration', - essentials: { - description: 'Returns only the most commonly-used properties for a node (10-20 fields). Response is 95% smaller than get_node_info (5KB vs 100KB+). Essential properties include required fields, common options, and authentication settings. Use validate_node_operation for working configurations.', - keyParameters: ['nodeType'], - example: 'get_node_essentials({nodeType: "nodes-base.slack"})', - performance: '<10ms, ~5KB response', - tips: [ - 'Always use this before get_node_info', - 'Use validate_node_operation for examples', - 'Perfect for understanding node structure' - ] - }, - full: { - description: 'Returns a curated subset of node properties focusing on the most commonly-used fields. Essential properties are hand-picked for each node type and include: required fields, primary operations, authentication options, and the most frequent configuration patterns. NOTE: Examples have been removed to avoid confusion - use validate_node_operation to get working configurations with proper validation.', - parameters: { - nodeType: { type: 'string', description: 'Full node type with prefix, e.g., "nodes-base.slack", "nodes-base.httpRequest"', required: true } - }, - returns: `Object containing: -{ - "nodeType": "nodes-base.slack", - "displayName": "Slack", - "description": "Consume Slack API", - "category": "output", - "version": "2.3", - "requiredProperties": [], // Most nodes have no strictly required fields - "commonProperties": [ - { - "name": "resource", - "displayName": "Resource", - "type": "options", - "options": ["channel", "message", "user"], - "default": "message" - }, - { - "name": "operation", - "displayName": "Operation", - "type": "options", - "options": ["post", "update", "delete"], - "default": "post" - }, - // ... 10-20 most common properties - ], - "operations": [ - {"name": "Post", "description": "Post a message"}, - {"name": "Update", "description": "Update a message"} - ], - "metadata": { - "totalProperties": 121, - "isAITool": false, - "hasCredentials": true - } -}`, - examples: [ - 'get_node_essentials({nodeType: "nodes-base.httpRequest"}) - HTTP configuration basics', - 'get_node_essentials({nodeType: "nodes-base.slack"}) - Slack messaging essentials', - 'get_node_essentials({nodeType: "nodes-base.googleSheets"}) - Sheets operations', - '// Workflow: search → essentials → validate', - 'const nodes = search_nodes({query: "database"});', - 'const mysql = get_node_essentials({nodeType: "nodes-base.mySql"});', - 'validate_node_operation("nodes-base.mySql", {operation: "select"}, "minimal");' - ], - useCases: [ - 'Quickly understand node structure without information overload', - 'Identify which properties are most important', - 'Learn node basics before diving into advanced features', - 'Build workflows faster with curated property sets' - ], - performance: '<10ms response time, ~5KB payload (vs 100KB+ for full schema)', - bestPractices: [ - 'Always start with essentials, only use get_node_info if needed', - 'Use validate_node_operation to get working configurations', - 'Check authentication requirements first', - 'Use search_node_properties if specific property not in essentials' - ], - pitfalls: [ - 'Advanced properties not included - use get_node_info for complete schema', - 'Node-specific validators may require additional fields', - 'Some nodes have 50+ properties, essentials shows only top 10-20' - ], - relatedTools: ['get_node_info for complete schema', 'search_node_properties for finding specific fields', 'validate_node_minimal to check configuration'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/configuration/get-node-info.ts b/src/mcp/tool-docs/configuration/get-node-info.ts deleted file mode 100644 index ae5ca5a..0000000 --- a/src/mcp/tool-docs/configuration/get-node-info.ts +++ /dev/null @@ -1,98 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const getNodeInfoDoc: ToolDocumentation = { - name: 'get_node_info', - category: 'configuration', - essentials: { - description: 'Returns complete node schema with ALL properties (100KB+ response). Only use when you need advanced properties not in get_node_essentials. Contains 200+ properties for complex nodes like HTTP Request. Requires full prefix like "nodes-base.httpRequest".', - keyParameters: ['nodeType'], - example: 'get_node_info({nodeType: "nodes-base.slack"})', - performance: '100-500ms, 50-500KB response', - tips: [ - 'Try get_node_essentials first (95% smaller)', - 'Use only for advanced configurations', - 'Response may have 200+ properties' - ] - }, - full: { - description: 'Returns the complete JSON schema for a node including all properties, operations, authentication methods, version information, and metadata. Response sizes range from 50KB to 500KB. Use this only when get_node_essentials doesn\'t provide the specific property you need.', - parameters: { - nodeType: { type: 'string', required: true, description: 'Full node type with prefix. Examples: "nodes-base.slack", "nodes-base.httpRequest", "nodes-langchain.openAi"' } - }, - returns: `Complete node object containing: -{ - "displayName": "Slack", - "name": "slack", - "type": "nodes-base.slack", - "typeVersion": 2.2, - "description": "Consume Slack API", - "defaults": {"name": "Slack"}, - "inputs": ["main"], - "outputs": ["main"], - "credentials": [ - { - "name": "slackApi", - "required": true, - "displayOptions": {...} - } - ], - "properties": [ - // 200+ property definitions including: - { - "displayName": "Resource", - "name": "resource", - "type": "options", - "options": ["channel", "message", "user", "file", ...], - "default": "message" - }, - { - "displayName": "Operation", - "name": "operation", - "type": "options", - "displayOptions": { - "show": {"resource": ["message"]} - }, - "options": ["post", "update", "delete", "get", ...], - "default": "post" - }, - // ... 200+ more properties with complex conditions - ], - "version": 2.2, - "subtitle": "={{$parameter[\"operation\"] + \": \" + $parameter[\"resource\"]}}", - "codex": {...}, - "supportedWebhooks": [...] -}`, - examples: [ - 'get_node_info({nodeType: "nodes-base.httpRequest"}) - 300+ properties for HTTP requests', - 'get_node_info({nodeType: "nodes-base.googleSheets"}) - Complex operations and auth', - '// When to use get_node_info:', - '// 1. First try essentials', - 'const essentials = get_node_essentials({nodeType: "nodes-base.slack"});', - '// 2. If property missing, search for it', - 'const props = search_node_properties({nodeType: "nodes-base.slack", query: "thread"});', - '// 3. Only if needed, get full schema', - 'const full = get_node_info({nodeType: "nodes-base.slack"});' - ], - useCases: [ - 'Analyzing all available operations for a node', - 'Understanding complex property dependencies', - 'Discovering all authentication methods', - 'Building UI that shows all node options', - 'Debugging property visibility conditions' - ], - performance: '100-500ms depending on node complexity. HTTP Request node: ~300KB, Simple nodes: ~50KB', - bestPractices: [ - 'Always try get_node_essentials first - it\'s 95% smaller', - 'Use search_node_properties to find specific advanced properties', - 'Cache results locally - schemas rarely change', - 'Parse incrementally - don\'t load entire response into memory at once' - ], - pitfalls: [ - 'Response can exceed 500KB for complex nodes', - 'Contains many rarely-used properties that add noise', - 'Property conditions can be deeply nested and complex', - 'Must use full node type with prefix (nodes-base.X not just X)' - ], - relatedTools: ['get_node_essentials for common properties', 'search_node_properties to find specific fields', 'get_property_dependencies to understand conditions'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/configuration/get-node.ts b/src/mcp/tool-docs/configuration/get-node.ts new file mode 100644 index 0000000..4fbe112 --- /dev/null +++ b/src/mcp/tool-docs/configuration/get-node.ts @@ -0,0 +1,90 @@ +import { ToolDocumentation } from '../types'; + +export const getNodeDoc: ToolDocumentation = { + name: 'get_node', + category: 'configuration', + essentials: { + description: 'Unified node information tool with progressive detail levels and multiple modes. Get node schema, docs, search properties, or version info.', + keyParameters: ['nodeType', 'detail', 'mode', 'includeTypeInfo', 'includeExamples'], + example: 'get_node({nodeType: "nodes-base.httpRequest", detail: "standard"})', + performance: 'Instant (<10ms) for minimal/standard, moderate for full', + tips: [ + 'Use detail="standard" (default) for most tasks - shows required fields', + 'Use mode="docs" for readable markdown documentation', + 'Use mode="search_properties" with propertyQuery to find specific fields', + 'Use mode="versions" to check version history and breaking changes', + 'Add includeExamples=true to get real-world configuration examples' + ] + }, + full: { + description: `Unified tool for all node information needs. Replaces get_node_info, get_node_essentials, get_node_documentation, and search_node_properties with a single versatile API. + +**Detail Levels (mode="info", default):** +- minimal (~200 tokens): Basic metadata only - nodeType, displayName, description, category +- standard (~1-2K tokens): Essential properties + operations - recommended for most tasks +- full (~3-8K tokens): Complete node schema - use only when standard insufficient + +**Operation Modes:** +- info (default): Node schema with configurable detail level +- docs: Readable markdown documentation with examples and patterns +- search_properties: Find specific properties within a node +- versions: List all available versions with breaking changes summary +- compare: Compare two versions with property-level changes +- breaking: Show only breaking changes between versions +- migrations: Show auto-migratable changes between versions`, + parameters: { + nodeType: { type: 'string', required: true, description: 'Full node type with prefix: "nodes-base.httpRequest" or "nodes-langchain.agent"' }, + detail: { type: 'string', required: false, description: 'Detail level for mode=info: "minimal", "standard" (default), "full"' }, + mode: { type: 'string', required: false, description: 'Operation mode: "info" (default), "docs", "search_properties", "versions", "compare", "breaking", "migrations"' }, + includeTypeInfo: { type: 'boolean', required: false, description: 'Include type structure metadata (validation rules, JS types). Adds ~80-120 tokens per property' }, + includeExamples: { type: 'boolean', required: false, description: 'Include real-world configuration examples from templates. Adds ~200-400 tokens per example' }, + propertyQuery: { type: 'string', required: false, description: 'For mode=search_properties: search term to find properties (e.g., "auth", "header", "body")' }, + maxPropertyResults: { type: 'number', required: false, description: 'For mode=search_properties: max results (default 20)' }, + fromVersion: { type: 'string', required: false, description: 'For compare/breaking/migrations modes: source version (e.g., "1.0")' }, + toVersion: { type: 'string', required: false, description: 'For compare mode: target version (e.g., "2.0"). Defaults to latest' } + }, + returns: `Depends on mode: +- info: Node schema with properties based on detail level +- docs: Markdown documentation string +- search_properties: Array of matching property paths with descriptions +- versions: Version history with breaking changes flags +- compare/breaking/migrations: Version comparison details`, + examples: [ + '// Standard detail (recommended for AI agents)\nget_node({nodeType: "nodes-base.httpRequest"})', + '// Minimal for quick metadata check\nget_node({nodeType: "nodes-base.slack", detail: "minimal"})', + '// Full detail with examples\nget_node({nodeType: "nodes-base.googleSheets", detail: "full", includeExamples: true})', + '// Get readable documentation\nget_node({nodeType: "nodes-base.webhook", mode: "docs"})', + '// Search for authentication properties\nget_node({nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth"})', + '// Check version history\nget_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"})', + '// Compare specific versions\nget_node({nodeType: "nodes-base.httpRequest", mode: "compare", fromVersion: "3.0", toVersion: "4.1"})' + ], + useCases: [ + 'Configure nodes for workflow building (use detail=standard)', + 'Find specific configuration options (use mode=search_properties)', + 'Get human-readable node documentation (use mode=docs)', + 'Check for breaking changes before version upgrades (use mode=breaking)', + 'Understand complex types with includeTypeInfo=true' + ], + performance: `Token costs by detail level: +- minimal: ~200 tokens +- standard: ~1000-2000 tokens (default) +- full: ~3000-8000 tokens +- includeTypeInfo: +80-120 tokens per property +- includeExamples: +200-400 tokens per example +- Version modes: ~400-1200 tokens`, + bestPractices: [ + 'Start with detail="standard" - it covers 95% of use cases', + 'Only use detail="full" if standard is missing required properties', + 'Use mode="docs" when explaining nodes to users', + 'Combine includeTypeInfo=true for complex nodes (filter, resourceMapper)', + 'Check version history before configuring versioned nodes' + ], + pitfalls: [ + 'detail="full" returns large responses (~100KB) - use sparingly', + 'Node type must include prefix (nodes-base. or nodes-langchain.)', + 'includeExamples only works with mode=info and detail=standard', + 'Version modes require nodes with multiple versions in database' + ], + relatedTools: ['search_nodes', 'validate_node', 'validate_workflow'] + } +}; diff --git a/src/mcp/tool-docs/configuration/get-property-dependencies.ts b/src/mcp/tool-docs/configuration/get-property-dependencies.ts deleted file mode 100644 index 6156254..0000000 --- a/src/mcp/tool-docs/configuration/get-property-dependencies.ts +++ /dev/null @@ -1,79 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const getPropertyDependenciesDoc: ToolDocumentation = { - name: 'get_property_dependencies', - category: 'configuration', - essentials: { - description: 'Shows property dependencies and visibility rules - which fields appear when.', - keyParameters: ['nodeType', 'config?'], - example: 'get_property_dependencies({nodeType: "nodes-base.httpRequest"})', - performance: 'Fast - analyzes property conditions', - tips: [ - 'Shows which properties depend on other property values', - 'Test visibility impact with optional config parameter', - 'Helps understand complex conditional property displays' - ] - }, - full: { - description: `Analyzes property dependencies and visibility conditions for a node. Shows which properties control the visibility of other properties (e.g., sendBody=true reveals body-related fields). Optionally test how a specific configuration affects property visibility.`, - parameters: { - nodeType: { - type: 'string', - required: true, - description: 'The node type to analyze (e.g., "nodes-base.httpRequest")', - examples: [ - 'nodes-base.httpRequest', - 'nodes-base.slack', - 'nodes-base.if', - 'nodes-base.switch' - ] - }, - config: { - type: 'object', - required: false, - description: 'Optional partial configuration to check visibility impact', - examples: [ - '{ method: "POST", sendBody: true }', - '{ operation: "create", resource: "contact" }', - '{ mode: "rules" }' - ] - } - }, - returns: `Object containing: -- nodeType: The analyzed node type -- displayName: Human-readable node name -- controllingProperties: Properties that control visibility of others -- dependentProperties: Properties whose visibility depends on others -- complexDependencies: Multi-condition dependencies -- currentConfig: If config provided, shows: - - providedValues: The configuration you passed - - visibilityImpact: Which properties are visible/hidden`, - examples: [ - 'get_property_dependencies({nodeType: "nodes-base.httpRequest"}) - Analyze HTTP Request dependencies', - 'get_property_dependencies({nodeType: "nodes-base.httpRequest", config: {sendBody: true}}) - Test visibility with sendBody enabled', - 'get_property_dependencies({nodeType: "nodes-base.if", config: {mode: "rules"}}) - Check If node in rules mode' - ], - useCases: [ - 'Understanding which properties control others', - 'Debugging why certain fields are not visible', - 'Building dynamic UIs that match n8n behavior', - 'Testing configurations before applying them', - 'Understanding complex node property relationships' - ], - performance: 'Fast - analyzes property metadata without database queries', - bestPractices: [ - 'Use before configuring complex nodes with many conditional fields', - 'Test different config values to understand visibility rules', - 'Check dependencies when properties seem to be missing', - 'Use for nodes with multiple operation modes (Slack, Google Sheets)', - 'Combine with search_node_properties to find specific fields' - ], - pitfalls: [ - 'Some properties have complex multi-condition dependencies', - 'Visibility rules can be nested (property A controls B which controls C)', - 'Not all hidden properties are due to dependencies (some are deprecated)', - 'Config parameter only tests visibility, does not validate values' - ], - relatedTools: ['search_node_properties', 'get_node_essentials', 'validate_node_operation'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/configuration/index.ts b/src/mcp/tool-docs/configuration/index.ts index 09d00ff..fad8f75 100644 --- a/src/mcp/tool-docs/configuration/index.ts +++ b/src/mcp/tool-docs/configuration/index.ts @@ -1,6 +1 @@ -export { getNodeInfoDoc } from './get-node-info'; -export { getNodeEssentialsDoc } from './get-node-essentials'; -export { getNodeDocumentationDoc } from './get-node-documentation'; -export { searchNodePropertiesDoc } from './search-node-properties'; -export { getNodeAsToolInfoDoc } from './get-node-as-tool-info'; -export { getPropertyDependenciesDoc } from './get-property-dependencies'; \ No newline at end of file +export { getNodeDoc } from './get-node'; diff --git a/src/mcp/tool-docs/configuration/search-node-properties.ts b/src/mcp/tool-docs/configuration/search-node-properties.ts deleted file mode 100644 index 0c0383a..0000000 --- a/src/mcp/tool-docs/configuration/search-node-properties.ts +++ /dev/null @@ -1,97 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const searchNodePropertiesDoc: ToolDocumentation = { - name: 'search_node_properties', - category: 'configuration', - essentials: { - description: 'Find specific properties in a node without downloading all 200+ properties.', - keyParameters: ['nodeType', 'query'], - example: 'search_node_properties({nodeType: "nodes-base.httpRequest", query: "auth"})', - performance: 'Fast - searches indexed properties', - tips: [ - 'Search for "auth", "header", "body", "json", "credential"', - 'Returns property paths and descriptions', - 'Much faster than get_node_info for finding specific fields' - ] - }, - full: { - description: `Searches for specific properties within a node's configuration schema. Essential for finding authentication fields, headers, body parameters, or any specific property without downloading the entire node schema (which can be 100KB+). Returns matching properties with their paths, types, and descriptions.`, - parameters: { - nodeType: { - type: 'string', - required: true, - description: 'Full type with prefix', - examples: [ - 'nodes-base.httpRequest', - 'nodes-base.slack', - 'nodes-base.postgres', - 'nodes-base.googleSheets' - ] - }, - query: { - type: 'string', - required: true, - description: 'Property to find: "auth", "header", "body", "json"', - examples: [ - 'auth', - 'header', - 'body', - 'json', - 'credential', - 'timeout', - 'retry', - 'pagination' - ] - }, - maxResults: { - type: 'number', - required: false, - description: 'Max results (default 20)', - default: 20 - } - }, - returns: `Object containing: -- nodeType: The searched node type -- query: Your search term -- matches: Array of matching properties with: - - name: Property identifier - - displayName: Human-readable name - - type: Property type (string, number, options, etc.) - - description: Property description - - path: Full path to property (for nested properties) - - required: Whether property is required - - default: Default value if any - - options: Available options for selection properties - - showWhen: Visibility conditions -- totalMatches: Number of matches found -- searchedIn: Total properties searched`, - examples: [ - 'search_node_properties({nodeType: "nodes-base.httpRequest", query: "auth"}) - Find authentication fields', - 'search_node_properties({nodeType: "nodes-base.slack", query: "channel"}) - Find channel-related properties', - 'search_node_properties({nodeType: "nodes-base.postgres", query: "query"}) - Find query fields', - 'search_node_properties({nodeType: "nodes-base.webhook", query: "response"}) - Find response options' - ], - useCases: [ - 'Finding authentication/credential fields quickly', - 'Locating specific parameters without full node info', - 'Discovering header or body configuration options', - 'Finding nested properties in complex nodes', - 'Checking if a node supports specific features (retry, pagination, etc.)' - ], - performance: 'Very fast - searches pre-indexed property metadata', - bestPractices: [ - 'Use before get_node_info to find specific properties', - 'Search for common terms: auth, header, body, credential', - 'Check showWhen conditions to understand visibility', - 'Use with get_property_dependencies for complete understanding', - 'Limit results if you only need to check existence' - ], - pitfalls: [ - 'Some properties may be hidden due to visibility conditions', - 'Property names may differ from display names', - 'Nested properties show full path (e.g., "options.retry.limit")', - 'Search is case-sensitive for property names' - ], - relatedTools: ['get_node_essentials', 'get_property_dependencies', 'get_node_info'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/discovery/get-database-statistics.ts b/src/mcp/tool-docs/discovery/get-database-statistics.ts deleted file mode 100644 index be162dd..0000000 --- a/src/mcp/tool-docs/discovery/get-database-statistics.ts +++ /dev/null @@ -1,67 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const getDatabaseStatisticsDoc: ToolDocumentation = { - name: 'get_database_statistics', - category: 'discovery', - essentials: { - description: 'Returns database health metrics and node inventory. Shows 525 total nodes, 263 AI-capable nodes, 104 triggers, with 87% documentation coverage. Primary use: verify MCP connection is working correctly.', - keyParameters: [], - example: 'get_database_statistics()', - performance: 'Instant', - tips: [ - 'First tool to call when testing MCP connection', - 'Shows exact counts for all node categories', - 'Documentation coverage indicates data quality' - ] - }, - full: { - description: 'Returns comprehensive database statistics showing the complete inventory of n8n nodes, their categories, documentation coverage, and package distribution. Essential for verifying MCP connectivity and understanding available resources.', - parameters: {}, - returns: `Object containing: -{ - "total_nodes": 525, // All nodes in database - "nodes_with_properties": 520, // Nodes with extracted properties (99%) - "nodes_with_operations": 334, // Nodes with multiple operations (64%) - "ai_tools": 263, // AI-capable nodes - "triggers": 104, // Workflow trigger nodes - "documentation_coverage": "87%", // Nodes with official docs - "packages": { - "n8n-nodes-base": 456, // Core n8n nodes - "@n8n/n8n-nodes-langchain": 69 // AI/LangChain nodes - }, - "categories": { - "trigger": 104, - "transform": 250, - "output": 45, - "input": 38, - "AI": 88 - } -}`, - examples: [ - 'get_database_statistics() - Returns complete statistics object', - '// Common check:', - 'const stats = get_database_statistics();', - 'if (stats.total_nodes < 500) console.error("Database incomplete!");' - ], - useCases: [ - 'Verify MCP server is connected and responding', - 'Check if database rebuild is needed (low node count)', - 'Monitor documentation coverage improvements', - 'Validate AI tools availability for workflows', - 'Audit node distribution across packages' - ], - performance: 'Instant (<1ms) - Statistics are pre-calculated and cached', - bestPractices: [ - 'Call this first to verify MCP connection before other operations', - 'Check total_nodes >= 500 to ensure complete database', - 'Monitor documentation_coverage for data quality', - 'Use ai_tools count to verify AI capabilities' - ], - pitfalls: [ - 'Statistics are cached at database build time, not real-time', - 'Won\'t reflect changes until database is rebuilt', - 'Package counts may vary with n8n version updates' - ], - relatedTools: ['list_nodes for detailed node listing', 'list_ai_tools for AI nodes', 'n8n_health_check for API connectivity'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/discovery/index.ts b/src/mcp/tool-docs/discovery/index.ts index b2d4a50..3c44050 100644 --- a/src/mcp/tool-docs/discovery/index.ts +++ b/src/mcp/tool-docs/discovery/index.ts @@ -1,4 +1 @@ export { searchNodesDoc } from './search-nodes'; -export { listNodesDoc } from './list-nodes'; -export { listAiToolsDoc } from './list-ai-tools'; -export { getDatabaseStatisticsDoc } from './get-database-statistics'; \ No newline at end of file diff --git a/src/mcp/tool-docs/discovery/list-ai-tools.ts b/src/mcp/tool-docs/discovery/list-ai-tools.ts deleted file mode 100644 index bccda19..0000000 --- a/src/mcp/tool-docs/discovery/list-ai-tools.ts +++ /dev/null @@ -1,51 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const listAiToolsDoc: ToolDocumentation = { - name: 'list_ai_tools', - category: 'discovery', - essentials: { - description: 'DEPRECATED: Basic list of 263 AI nodes. For comprehensive AI Agent guidance, use tools_documentation({topic: "ai_agents_guide"}). That guide covers architecture, connections, tools, validation, and best practices. Use search_nodes({query: "AI", includeExamples: true}) for AI nodes with working examples.', - keyParameters: [], - example: 'tools_documentation({topic: "ai_agents_guide"}) // Recommended alternative', - performance: 'Instant (cached)', - tips: [ - 'NEW: Use ai_agents_guide for comprehensive AI workflow documentation', - 'Use search_nodes({includeExamples: true}) for AI nodes with real-world examples', - 'ANY node can be an AI tool - not limited to AI-specific nodes', - 'Use get_node_as_tool_info for guidance on any node' - ] - }, - full: { - description: '**DEPRECATED in favor of ai_agents_guide**. Lists 263 nodes with built-in AI capabilities. For comprehensive documentation on building AI Agent workflows, use tools_documentation({topic: "ai_agents_guide"}) which covers architecture, the 8 AI connection types, validation, and best practices with real examples. IMPORTANT: This basic list is NOT a complete guide - use the full AI Agents guide instead.', - parameters: {}, - returns: 'Array of 263 AI-optimized nodes. RECOMMENDED: Use ai_agents_guide for comprehensive guidance, or search_nodes({query: "AI", includeExamples: true}) for AI nodes with working configuration examples.', - examples: [ - '// RECOMMENDED: Use the comprehensive AI Agents guide', - 'tools_documentation({topic: "ai_agents_guide"})', - '', - '// Or search for AI nodes with real-world examples', - 'search_nodes({query: "AI Agent", includeExamples: true})', - '', - '// Basic list (deprecated)', - 'list_ai_tools() - Returns 263 AI-optimized nodes' - ], - useCases: [ - 'Discover AI model integrations (OpenAI, Anthropic, Google AI)', - 'Find vector databases for RAG applications', - 'Locate embedding generators and processors', - 'Build AI agent tool chains with ANY n8n node' - ], - performance: 'Instant - results are pre-cached in memory', - bestPractices: [ - 'Remember: ANY node works as an AI tool when connected to AI Agent', - 'Common non-AI nodes used as tools: Slack (messaging), Google Sheets (data), HTTP Request (APIs), Code (custom logic)', - 'For community nodes: set N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true' - ], - pitfalls: [ - 'This list is NOT exhaustive - it only shows nodes with AI-specific features', - 'Don\'t limit yourself to this list when building AI workflows', - 'Community nodes require environment variable to work as tools' - ], - relatedTools: ['get_node_as_tool_info for any node usage', 'search_nodes to find specific nodes', 'get_node_essentials to configure nodes'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/discovery/list-nodes.ts b/src/mcp/tool-docs/discovery/list-nodes.ts deleted file mode 100644 index ce6ec74..0000000 --- a/src/mcp/tool-docs/discovery/list-nodes.ts +++ /dev/null @@ -1,52 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const listNodesDoc: ToolDocumentation = { - name: 'list_nodes', - category: 'discovery', - essentials: { - description: 'Lists n8n nodes with filtering options. Returns up to 525 total nodes. Default limit is 50, use limit:200 to get all nodes. Filter by category to find specific node types like triggers (104 nodes) or AI nodes (263 nodes).', - keyParameters: ['category', 'package', 'limit', 'isAITool'], - example: 'list_nodes({limit:200})', - performance: '<10ms for any query size', - tips: [ - 'Use limit:200 to get all 525 nodes', - 'Categories: trigger (104), transform (250+), output/input (50+)', - 'Use search_nodes for keyword search' - ] - }, - full: { - description: 'Lists n8n nodes with comprehensive filtering options. Returns an array of node metadata including type, name, description, and category. Database contains 525 total nodes: 456 from n8n-nodes-base package and 69 from @n8n/n8n-nodes-langchain package.', - parameters: { - category: { type: 'string', description: 'Filter by category: "trigger" (104 nodes), "transform" (250+ nodes), "output", "input", or "AI"', required: false }, - package: { type: 'string', description: 'Filter by package: "n8n-nodes-base" (456 core nodes) or "@n8n/n8n-nodes-langchain" (69 AI nodes)', required: false }, - limit: { type: 'number', description: 'Maximum results to return. Default: 50. Use 200+ to get all 525 nodes', required: false }, - isAITool: { type: 'boolean', description: 'Filter to show only AI-capable nodes (263 nodes)', required: false }, - developmentStyle: { type: 'string', description: 'Filter by style: "programmatic" or "declarative". Most nodes are programmatic', required: false } - }, - returns: 'Array of node objects, each containing: nodeType (e.g., "nodes-base.webhook"), displayName (e.g., "Webhook"), description, category, package, isAITool flag', - examples: [ - 'list_nodes({limit:200}) - Returns all 525 nodes', - 'list_nodes({category:"trigger"}) - Returns 104 trigger nodes (Webhook, Schedule, Email Trigger, etc.)', - 'list_nodes({package:"@n8n/n8n-nodes-langchain"}) - Returns 69 AI/LangChain nodes', - 'list_nodes({isAITool:true}) - Returns 263 AI-capable nodes', - 'list_nodes({category:"trigger", isAITool:true}) - Combines filters for AI-capable triggers' - ], - useCases: [ - 'Browse all available nodes when building workflows', - 'Find all trigger nodes to start workflows', - 'Discover AI/ML nodes for intelligent automation', - 'Check available nodes in specific packages' - ], - performance: '<10ms for any query size. Results are cached in memory', - bestPractices: [ - 'Use limit:200 when you need the complete node inventory', - 'Filter by category for focused discovery', - 'Combine with get_node_essentials to configure selected nodes' - ], - pitfalls: [ - 'No text search capability - use search_nodes for keyword search', - 'developmentStyle filter rarely useful - most nodes are "programmatic"' - ], - relatedTools: ['search_nodes for keyword search', 'list_ai_tools for AI-specific discovery', 'get_node_essentials to configure nodes'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/discovery/search-nodes.ts b/src/mcp/tool-docs/discovery/search-nodes.ts index 43b9799..3b9d280 100644 --- a/src/mcp/tool-docs/discovery/search-nodes.ts +++ b/src/mcp/tool-docs/discovery/search-nodes.ts @@ -49,6 +49,6 @@ export const searchNodesDoc: ToolDocumentation = { 'FUZZY mode with very short queries (1-2 chars) may return unexpected results', 'Exact matches in quotes are case-sensitive' ], - relatedTools: ['list_nodes for browsing by category', 'get_node_essentials to configure found nodes', 'list_ai_tools for AI-specific search'] + relatedTools: ['get_node to configure found nodes', 'search_templates to find workflow examples', 'validate_node to check configurations'] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/guides/ai-agents-guide.ts b/src/mcp/tool-docs/guides/ai-agents-guide.ts index 5ad1a03..ce24665 100644 --- a/src/mcp/tool-docs/guides/ai-agents-guide.ts +++ b/src/mcp/tool-docs/guides/ai-agents-guide.ts @@ -690,7 +690,7 @@ n8n_validate_workflow({id: "workflow_id"}) - **FINAL_AI_VALIDATION_SPEC.md**: Complete validation rules - **n8n_update_partial_workflow**: Workflow modification tool - **search_nodes({query: "AI", includeExamples: true})**: Find AI nodes with examples -- **get_node_essentials({nodeType: "...", includeExamples: true})**: Node details with examples +- **get_node({nodeType: "...", detail: "standard", includeExamples: true})**: Node details with examples --- @@ -731,8 +731,7 @@ n8n_validate_workflow({id: "workflow_id"}) 'n8n_update_partial_workflow', 'n8n_validate_workflow', 'search_nodes', - 'get_node_essentials', - 'list_ai_tools' + 'get_node' ] } }; diff --git a/src/mcp/tool-docs/index.ts b/src/mcp/tool-docs/index.ts index 6b51ae1..8dd9b30 100644 --- a/src/mcp/tool-docs/index.ts +++ b/src/mcp/tool-docs/index.ts @@ -1,45 +1,20 @@ import { ToolDocumentation } from './types'; // Import all tool documentations -import { searchNodesDoc, listNodesDoc, listAiToolsDoc, getDatabaseStatisticsDoc } from './discovery'; -import { - getNodeEssentialsDoc, - getNodeInfoDoc, - getNodeDocumentationDoc, - searchNodePropertiesDoc, - getNodeAsToolInfoDoc, - getPropertyDependenciesDoc -} from './configuration'; -import { - validateNodeMinimalDoc, - validateNodeOperationDoc, - validateWorkflowDoc, - validateWorkflowConnectionsDoc, - validateWorkflowExpressionsDoc -} from './validation'; -import { - listTasksDoc, - listNodeTemplatesDoc, - getTemplateDoc, - searchTemplatesDoc, - searchTemplatesByMetadataDoc, - getTemplatesForTaskDoc -} from './templates'; +import { searchNodesDoc } from './discovery'; +import { getNodeDoc } from './configuration'; +import { validateNodeDoc, validateWorkflowDoc } from './validation'; +import { getTemplateDoc, searchTemplatesDoc } from './templates'; import { toolsDocumentationDoc, n8nDiagnosticDoc, n8nHealthCheckDoc, n8nListAvailableToolsDoc } from './system'; -import { - aiAgentsGuide -} from './guides'; +import { aiAgentsGuide } from './guides'; import { n8nCreateWorkflowDoc, n8nGetWorkflowDoc, - n8nGetWorkflowDetailsDoc, - n8nGetWorkflowStructureDoc, - n8nGetWorkflowMinimalDoc, n8nUpdateFullWorkflowDoc, n8nUpdatePartialWorkflowDoc, n8nDeleteWorkflowDoc, @@ -47,12 +22,11 @@ import { n8nValidateWorkflowDoc, n8nAutofixWorkflowDoc, n8nTriggerWebhookWorkflowDoc, - n8nGetExecutionDoc, - n8nListExecutionsDoc, - n8nDeleteExecutionDoc + n8nExecutionsDoc } from './workflow_management'; // Combine all tool documentations into a single object +// Total: 19 tools after v2.26.0 consolidation export const toolsDocumentation: Record = { // System tools tools_documentation: toolsDocumentationDoc, @@ -65,39 +39,21 @@ export const toolsDocumentation: Record = { // Discovery tools search_nodes: searchNodesDoc, - list_nodes: listNodesDoc, - list_ai_tools: listAiToolsDoc, - get_database_statistics: getDatabaseStatisticsDoc, - - // Configuration tools - get_node_essentials: getNodeEssentialsDoc, - get_node_info: getNodeInfoDoc, - get_node_documentation: getNodeDocumentationDoc, - search_node_properties: searchNodePropertiesDoc, - get_node_as_tool_info: getNodeAsToolInfoDoc, - get_property_dependencies: getPropertyDependenciesDoc, - - // Validation tools - validate_node_minimal: validateNodeMinimalDoc, - validate_node_operation: validateNodeOperationDoc, - validate_workflow: validateWorkflowDoc, - validate_workflow_connections: validateWorkflowConnectionsDoc, - validate_workflow_expressions: validateWorkflowExpressionsDoc, - - // Template tools - list_tasks: listTasksDoc, - list_node_templates: listNodeTemplatesDoc, + + // Configuration tools (consolidated) + get_node: getNodeDoc, // Replaces: get_node_info, get_node_essentials, get_node_documentation, search_node_properties + + // Validation tools (consolidated) + validate_node: validateNodeDoc, // Replaces: validate_node_operation, validate_node_minimal + validate_workflow: validateWorkflowDoc, // Options replace: validate_workflow_connections, validate_workflow_expressions + + // Template tools (consolidated) get_template: getTemplateDoc, - search_templates: searchTemplatesDoc, - search_templates_by_metadata: searchTemplatesByMetadataDoc, - get_templates_for_task: getTemplatesForTaskDoc, - + search_templates: searchTemplatesDoc, // Modes replace: list_node_templates, search_templates_by_metadata, get_templates_for_task + // Workflow Management tools (n8n API) n8n_create_workflow: n8nCreateWorkflowDoc, - n8n_get_workflow: n8nGetWorkflowDoc, - n8n_get_workflow_details: n8nGetWorkflowDetailsDoc, - n8n_get_workflow_structure: n8nGetWorkflowStructureDoc, - n8n_get_workflow_minimal: n8nGetWorkflowMinimalDoc, + n8n_get_workflow: n8nGetWorkflowDoc, // Modes replace: n8n_get_workflow_details, n8n_get_workflow_structure, n8n_get_workflow_minimal n8n_update_full_workflow: n8nUpdateFullWorkflowDoc, n8n_update_partial_workflow: n8nUpdatePartialWorkflowDoc, n8n_delete_workflow: n8nDeleteWorkflowDoc, @@ -105,9 +61,7 @@ export const toolsDocumentation: Record = { n8n_validate_workflow: n8nValidateWorkflowDoc, n8n_autofix_workflow: n8nAutofixWorkflowDoc, n8n_trigger_webhook_workflow: n8nTriggerWebhookWorkflowDoc, - n8n_get_execution: n8nGetExecutionDoc, - n8n_list_executions: n8nListExecutionsDoc, - n8n_delete_execution: n8nDeleteExecutionDoc + n8n_executions: n8nExecutionsDoc // Actions replace: n8n_get_execution, n8n_list_executions, n8n_delete_execution }; // Re-export types diff --git a/src/mcp/tool-docs/system/tools-documentation.ts b/src/mcp/tool-docs/system/tools-documentation.ts index f895d4d..0c1938b 100644 --- a/src/mcp/tool-docs/system/tools-documentation.ts +++ b/src/mcp/tool-docs/system/tools-documentation.ts @@ -58,6 +58,6 @@ export const toolsDocumentationDoc: ToolDocumentation = { 'Not all internal functions are documented', 'Special topics (code guides) require exact names' ], - relatedTools: ['n8n_health_check for verifying API connection', 'get_node_for_task for common configurations', 'search_nodes for finding nodes'] + relatedTools: ['n8n_health_check for verifying API connection', 'search_templates for workflow examples', 'search_nodes for finding nodes'] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/templates/get-template.ts b/src/mcp/tool-docs/templates/get-template.ts index cc98a4f..bf78267 100644 --- a/src/mcp/tool-docs/templates/get-template.ts +++ b/src/mcp/tool-docs/templates/get-template.ts @@ -4,12 +4,12 @@ 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.', + description: 'Get complete workflow JSON by ID. Ready to import. IDs from 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', + 'Get template IDs from search_templates first', 'Returns complete workflow JSON ready for import into n8n', 'Includes all nodes, connections, and settings' ] @@ -20,7 +20,7 @@ export const getTemplateDoc: ToolDocumentation = { templateId: { type: 'number', required: true, - description: 'The numeric ID of the template to retrieve. Get IDs from list_node_templates or search_templates' + description: 'The numeric ID of the template to retrieve. Get IDs from search_templates' } }, returns: `Returns an object containing: @@ -69,6 +69,6 @@ export const getTemplateDoc: ToolDocumentation = { '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'] + relatedTools: ['search_templates', 'n8n_create_workflow'] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/templates/get-templates-for-task.ts b/src/mcp/tool-docs/templates/get-templates-for-task.ts deleted file mode 100644 index 89439ea..0000000 --- a/src/mcp/tool-docs/templates/get-templates-for-task.ts +++ /dev/null @@ -1,74 +0,0 @@ -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', - 'Available tasks: ai_automation, data_sync, webhook_processing, email_automation, slack_integration, etc.', - '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'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/templates/index.ts b/src/mcp/tool-docs/templates/index.ts index df67c56..dab3165 100644 --- a/src/mcp/tool-docs/templates/index.ts +++ b/src/mcp/tool-docs/templates/index.ts @@ -1,6 +1,2 @@ -export { listTasksDoc } from './list-tasks'; -export { listNodeTemplatesDoc } from './list-node-templates'; export { getTemplateDoc } from './get-template'; export { searchTemplatesDoc } from './search-templates'; -export { searchTemplatesByMetadataDoc } from './search-templates-by-metadata'; -export { getTemplatesForTaskDoc } from './get-templates-for-task'; \ No newline at end of file diff --git a/src/mcp/tool-docs/templates/list-node-templates.ts b/src/mcp/tool-docs/templates/list-node-templates.ts deleted file mode 100644 index a88f72d..0000000 --- a/src/mcp/tool-docs/templates/list-node-templates.ts +++ /dev/null @@ -1,78 +0,0 @@ -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'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/templates/list-tasks.ts b/src/mcp/tool-docs/templates/list-tasks.ts deleted file mode 100644 index 1a03d69..0000000 --- a/src/mcp/tool-docs/templates/list-tasks.ts +++ /dev/null @@ -1,46 +0,0 @@ -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'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/templates/search-templates-by-metadata.ts b/src/mcp/tool-docs/templates/search-templates-by-metadata.ts deleted file mode 100644 index 8974a0f..0000000 --- a/src/mcp/tool-docs/templates/search-templates-by-metadata.ts +++ /dev/null @@ -1,118 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const searchTemplatesByMetadataDoc: ToolDocumentation = { - name: 'search_templates_by_metadata', - category: 'templates', - essentials: { - description: 'Search templates using AI-generated metadata filters. Find templates by complexity, setup time, required services, or target audience. Enables smart template discovery beyond simple text search.', - keyParameters: ['category', 'complexity', 'maxSetupMinutes', 'targetAudience'], - example: 'search_templates_by_metadata({complexity: "simple", maxSetupMinutes: 30})', - performance: 'Fast (<100ms) - JSON extraction queries', - tips: [ - 'All filters are optional - combine them for precise results', - 'Use getAvailableCategories() to see valid category values', - 'Complexity levels: simple, medium, complex', - 'Setup time is in minutes (5-480 range)' - ] - }, - full: { - description: `Advanced template search using AI-generated metadata. Each template has been analyzed by GPT-4 to extract structured information about its purpose, complexity, setup requirements, and target users. This enables intelligent filtering beyond simple keyword matching, helping you find templates that match your specific needs, skill level, and available time.`, - parameters: { - category: { - type: 'string', - required: false, - description: 'Filter by category like "automation", "integration", "data processing", "communication". Use template service getAvailableCategories() for full list.' - }, - complexity: { - type: 'string (enum)', - required: false, - description: 'Filter by implementation complexity: "simple" (beginner-friendly), "medium" (some experience needed), or "complex" (advanced features)' - }, - maxSetupMinutes: { - type: 'number', - required: false, - description: 'Maximum acceptable setup time in minutes (5-480). Find templates you can implement within your time budget.' - }, - minSetupMinutes: { - type: 'number', - required: false, - description: 'Minimum setup time in minutes (5-480). Find more substantial templates that offer comprehensive solutions.' - }, - requiredService: { - type: 'string', - required: false, - description: 'Filter by required external service like "openai", "slack", "google", "shopify". Ensures you have necessary accounts/APIs.' - }, - targetAudience: { - type: 'string', - required: false, - description: 'Filter by intended users: "developers", "marketers", "analysts", "operations", "sales". Find templates for your role.' - }, - limit: { - type: 'number', - required: false, - description: 'Maximum results to return. Default 20, max 100.' - }, - offset: { - type: 'number', - required: false, - description: 'Pagination offset for results. Default 0.' - } - }, - returns: `Returns an object containing: -- items: Array of matching templates with full metadata - - id: Template ID - - name: Template name - - description: Purpose and functionality - - author: Creator details - - nodes: Array of nodes used - - views: Popularity count - - metadata: AI-generated structured data - - categories: Primary use categories - - complexity: Difficulty level - - use_cases: Specific applications - - estimated_setup_minutes: Time to implement - - required_services: External dependencies - - key_features: Main capabilities - - target_audience: Intended users -- total: Total matching templates -- filters: Applied filter criteria -- filterSummary: Human-readable filter description -- availableCategories: Suggested categories if no results -- availableAudiences: Suggested audiences if no results -- tip: Contextual guidance`, - examples: [ - 'search_templates_by_metadata({complexity: "simple"}) - Find beginner-friendly templates', - 'search_templates_by_metadata({category: "automation", maxSetupMinutes: 30}) - Quick automation templates', - 'search_templates_by_metadata({targetAudience: "marketers"}) - Marketing-focused workflows', - 'search_templates_by_metadata({requiredService: "openai", complexity: "medium"}) - AI templates with moderate complexity', - 'search_templates_by_metadata({minSetupMinutes: 60, category: "integration"}) - Comprehensive integration solutions' - ], - useCases: [ - 'Finding beginner-friendly templates by setting complexity:"simple"', - 'Discovering templates you can implement quickly with maxSetupMinutes:30', - 'Finding role-specific workflows with targetAudience filter', - 'Identifying templates that need specific APIs with requiredService filter', - 'Combining multiple filters for precise template discovery' - ], - performance: 'Fast (<100ms) - Uses SQLite JSON extraction on pre-generated metadata. 97.5% coverage (2,534/2,598 templates).', - bestPractices: [ - 'Start with broad filters and narrow down based on results', - 'Use getAvailableCategories() to discover valid category values', - 'Combine complexity and setup time for skill-appropriate templates', - 'Check required services before selecting templates to ensure you have necessary accounts' - ], - pitfalls: [ - 'Not all templates have metadata (97.5% coverage)', - 'Setup time estimates assume basic n8n familiarity', - 'Categories/audiences use partial matching - be specific', - 'Metadata is AI-generated and may occasionally be imprecise' - ], - relatedTools: [ - 'list_templates', - 'search_templates', - 'list_node_templates', - 'get_templates_for_task' - ] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/templates/search-templates.ts b/src/mcp/tool-docs/templates/search-templates.ts index 363e278..b45e966 100644 --- a/src/mcp/tool-docs/templates/search-templates.ts +++ b/src/mcp/tool-docs/templates/search-templates.ts @@ -4,86 +4,140 @@ 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', 'fields'], - example: 'search_templates({query: "chatbot", fields: ["id", "name"]})', + description: 'Unified template search with multiple modes: keyword search, by node types, by task type, or by metadata. 2,700+ templates available.', + keyParameters: ['searchMode', 'query', 'nodeTypes', 'task', 'limit'], + example: 'search_templates({searchMode: "by_task", task: "webhook_processing"})', 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', - 'Use fields parameter to get only specific data (reduces response by 70-90%)' + 'searchMode="keyword" (default): Search by name/description', + 'searchMode="by_nodes": Find templates using specific nodes', + 'searchMode="by_task": Get curated templates for common tasks', + 'searchMode="by_metadata": Filter by complexity, services, audience' ] }, 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.`, + description: `Unified template search tool with four search modes. Replaces search_templates, list_node_templates, search_templates_by_metadata, and get_templates_for_task. + +**Search Modes:** +- keyword (default): Full-text search across template names and descriptions +- by_nodes: Find templates that use specific node types +- by_task: Get curated templates for predefined task categories +- by_metadata: Filter by complexity, setup time, required services, or target audience + +**Available Task Types (for searchMode="by_task"):** +ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations`, parameters: { + searchMode: { + type: 'string', + required: false, + description: 'Search mode: "keyword" (default), "by_nodes", "by_task", "by_metadata"' + }, 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.' + required: false, + description: 'For searchMode=keyword: Search keywords (e.g., "chatbot", "automation")' + }, + nodeTypes: { + type: 'array', + required: false, + description: 'For searchMode=by_nodes: Array of node types (e.g., ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"])' + }, + task: { + type: 'string', + required: false, + description: 'For searchMode=by_task: Task type (ai_automation, data_sync, webhook_processing, email_automation, slack_integration, data_transformation, file_processing, scheduling, api_integration, database_operations)' + }, + complexity: { + type: 'string', + required: false, + description: 'For searchMode=by_metadata: Filter by complexity ("simple", "medium", "complex")' + }, + maxSetupMinutes: { + type: 'number', + required: false, + description: 'For searchMode=by_metadata: Maximum setup time in minutes (5-480)' + }, + minSetupMinutes: { + type: 'number', + required: false, + description: 'For searchMode=by_metadata: Minimum setup time in minutes (5-480)' + }, + requiredService: { + type: 'string', + required: false, + description: 'For searchMode=by_metadata: Filter by required service (e.g., "openai", "slack", "google")' + }, + targetAudience: { + type: 'string', + required: false, + description: 'For searchMode=by_metadata: Filter by target audience (e.g., "developers", "marketers")' + }, + category: { + type: 'string', + required: false, + description: 'For searchMode=by_metadata: Filter by category (e.g., "automation", "integration")' }, fields: { type: 'array', required: false, - description: 'Fields to include in response. Options: "id", "name", "description", "author", "nodes", "views", "created", "url", "metadata". Default: all fields. Example: ["id", "name"] for minimal response.' + description: 'For searchMode=keyword: Fields to include (id, name, description, author, nodes, views, created, url, metadata)' }, limit: { type: 'number', required: false, - description: 'Maximum number of results. Default 20, max 100' + description: 'Maximum results (default 20, max 100)' + }, + offset: { + type: 'number', + required: false, + description: 'Pagination offset (default 0)' } }, returns: `Returns an object containing: -- templates: Array of matching templates sorted by relevance - - id: Template ID for retrieval - - name: Template name (with match highlights) +- templates: Array of matching templates + - id: Template ID for get_template() + - name: Template name - description: What the workflow does - author: Creator information - - nodes: Array of all nodes used + - nodes: Array of node types used - views: Popularity metric - created: Creation date - url: Link to template - - relevanceScore: Search match score + - metadata: AI-generated metadata (complexity, services, etc.) - totalFound: Total matching templates -- searchQuery: The processed search query -- tip: Helpful hints if no results`, +- searchMode: The mode used`, 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', - 'search_templates({query: "slack", fields: ["id", "name"]}) - Get only IDs and names of Slack templates', - 'search_templates({query: "automation", fields: ["id", "name", "description"]}) - Get minimal info for automation templates' + '// Keyword search (default)\nsearch_templates({query: "chatbot"})', + '// Find templates using specific nodes\nsearch_templates({searchMode: "by_nodes", nodeTypes: ["n8n-nodes-base.httpRequest", "n8n-nodes-base.slack"]})', + '// Get templates for a task type\nsearch_templates({searchMode: "by_task", task: "webhook_processing"})', + '// Filter by metadata\nsearch_templates({searchMode: "by_metadata", complexity: "simple", requiredService: "openai"})', + '// Combine metadata filters\nsearch_templates({searchMode: "by_metadata", maxSetupMinutes: 30, targetAudience: "developers"})' ], 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' + 'Find workflows by business purpose (keyword search)', + 'Find templates using specific integrations (by_nodes)', + 'Get pre-built solutions for common tasks (by_task)', + 'Filter by complexity for team skill level (by_metadata)', + 'Find templates requiring specific services (by_metadata)' ], - 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`, + performance: `Fast performance across all modes: +- keyword: <50ms with FTS5 indexing +- by_nodes: <100ms with indexed lookups +- by_task: <50ms from curated cache +- by_metadata: <100ms with filtered queries`, 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' + 'Use searchMode="by_task" for common automation patterns', + 'Use searchMode="by_nodes" when you know which integrations you need', + 'Use searchMode="keyword" for general discovery', + 'Combine by_metadata filters for precise matching', + 'Use get_template(id) to get the full workflow JSON' ], 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' + 'searchMode="keyword" searches names/descriptions, not node types', + 'by_nodes requires full node type with prefix (n8n-nodes-base.xxx)', + 'by_metadata filters may return fewer results', + 'Not all templates have complete metadata' ], - relatedTools: ['list_node_templates', 'get_templates_for_task', 'get_template', 'search_nodes'] + relatedTools: ['get_template', 'search_nodes', 'validate_workflow'] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/validation/index.ts b/src/mcp/tool-docs/validation/index.ts index 1a247da..ba060a3 100644 --- a/src/mcp/tool-docs/validation/index.ts +++ b/src/mcp/tool-docs/validation/index.ts @@ -1,5 +1,2 @@ -export { validateNodeMinimalDoc } from './validate-node-minimal'; -export { validateNodeOperationDoc } from './validate-node-operation'; +export { validateNodeDoc } from './validate-node'; export { validateWorkflowDoc } from './validate-workflow'; -export { validateWorkflowConnectionsDoc } from './validate-workflow-connections'; -export { validateWorkflowExpressionsDoc } from './validate-workflow-expressions'; \ No newline at end of file diff --git a/src/mcp/tool-docs/validation/validate-node-minimal.ts b/src/mcp/tool-docs/validation/validate-node-minimal.ts deleted file mode 100644 index 6eba21d..0000000 --- a/src/mcp/tool-docs/validation/validate-node-minimal.ts +++ /dev/null @@ -1,47 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const validateNodeMinimalDoc: ToolDocumentation = { - name: 'validate_node_minimal', - category: 'validation', - essentials: { - description: 'Fast check for missing required fields only. No warnings/suggestions. Returns: list of missing fields.', - keyParameters: ['nodeType', 'config'], - example: 'validate_node_minimal("nodes-base.slack", {resource: "message"})', - performance: 'Instant', - tips: [ - 'Returns only missing required fields', - 'No warnings or suggestions', - 'Perfect for real-time validation' - ] - }, - full: { - description: 'Minimal validation that only checks for missing required fields. Returns array of missing field names without any warnings or suggestions. Ideal for quick validation during node configuration.', - parameters: { - nodeType: { type: 'string', required: true, description: 'Node type with prefix (e.g., "nodes-base.slack")' }, - config: { type: 'object', required: true, description: 'Node configuration to validate' } - }, - returns: 'Array of missing required field names (empty if valid)', - examples: [ - 'validate_node_minimal("nodes-base.slack", {resource: "message", operation: "post"}) - Check Slack config', - 'validate_node_minimal("nodes-base.httpRequest", {method: "GET"}) - Check HTTP config' - ], - useCases: [ - 'Real-time form validation', - 'Quick configuration checks', - 'Pre-deployment validation', - 'Interactive configuration builders' - ], - performance: 'Instant - Simple field checking without complex validation', - bestPractices: [ - 'Use for quick feedback loops', - 'Follow with validate_node_operation for thorough check', - 'Check return array length for validity' - ], - pitfalls: [ - 'Only checks required fields', - 'No type validation', - 'No operation-specific validation' - ], - relatedTools: ['validate_node_operation', 'get_node_essentials', 'get_property_dependencies'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/validation/validate-node-operation.ts b/src/mcp/tool-docs/validation/validate-node-operation.ts deleted file mode 100644 index 7773863..0000000 --- a/src/mcp/tool-docs/validation/validate-node-operation.ts +++ /dev/null @@ -1,98 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const validateNodeOperationDoc: ToolDocumentation = { - name: 'validate_node_operation', - category: 'validation', - essentials: { - description: 'Validates node configuration with operation awareness. Checks required fields, data types, and operation-specific rules. Returns specific errors with automated fix suggestions. Different profiles for different validation needs.', - keyParameters: ['nodeType', 'config', 'profile'], - example: 'validate_node_operation({nodeType: "nodes-base.slack", config: {resource: "message", operation: "post", text: "Hi"}})', - performance: '<100ms', - tips: [ - 'Profile choices: minimal (editing), runtime (execution), ai-friendly (balanced), strict (deployment)', - 'Returns fixes you can apply directly', - 'Operation-aware - knows Slack post needs text', - 'Validates operator structures for IF and Switch nodes with conditions' - ] - }, - full: { - description: 'Comprehensive node configuration validation that understands operation context. For example, it knows Slack message posting requires text field, while channel listing doesn\'t. Provides different validation profiles for different stages of workflow development.', - parameters: { - nodeType: { type: 'string', required: true, description: 'Full node type with prefix: "nodes-base.slack", "nodes-base.httpRequest"' }, - config: { type: 'object', required: true, description: 'Node configuration. Must include operation fields (resource/operation/action) if the node has multiple operations' }, - profile: { type: 'string', required: false, description: 'Validation profile - controls what\'s checked. Default: "ai-friendly"' } - }, - returns: `Object containing: -{ - "isValid": false, - "errors": [ - { - "field": "channel", - "message": "Required field 'channel' is missing", - "severity": "error", - "fix": "#general" - } - ], - "warnings": [ - { - "field": "retryOnFail", - "message": "Consider enabling retry for reliability", - "severity": "warning", - "fix": true - } - ], - "suggestions": [ - { - "field": "timeout", - "message": "Set timeout to prevent hanging", - "fix": 30000 - } - ], - "fixes": { - "channel": "#general", - "retryOnFail": true, - "timeout": 30000 - } -}`, - examples: [ - '// Missing required field', - 'validate_node_operation({nodeType: "nodes-base.slack", config: {resource: "message", operation: "post"}})', - '// Returns: {isValid: false, errors: [{field: "text", message: "Required field missing"}], fixes: {text: "Message text"}}', - '', - '// Validate with strict profile for production', - 'validate_node_operation({nodeType: "nodes-base.httpRequest", config: {method: "POST", url: "https://api.example.com"}, profile: "strict"})', - '', - '// Apply fixes automatically', - 'const result = validate_node_operation({nodeType: "nodes-base.slack", config: myConfig});', - 'if (!result.isValid) {', - ' myConfig = {...myConfig, ...result.fixes};', - '}' - ], - useCases: [ - 'Validate configuration before workflow execution', - 'Debug why a node isn\'t working as expected', - 'Generate configuration fixes automatically', - 'Different validation for editing vs production', - 'Check IF/Switch operator structures (binary vs unary operators)', - 'Validate conditions.options metadata for filter-based nodes' - ], - performance: '<100ms for most nodes, <200ms for complex nodes with many conditions', - bestPractices: [ - 'Use "minimal" profile during user editing for fast feedback', - 'Use "runtime" profile (default) before execution', - 'Use "ai-friendly" when AI configures nodes', - 'Use "strict" profile before production deployment', - 'Always include operation fields (resource/operation) in config', - 'Apply suggested fixes to resolve issues quickly' - ], - pitfalls: [ - 'Must include operation fields for multi-operation nodes', - 'Fixes are suggestions - review before applying', - 'Profile affects what\'s validated - minimal skips many checks', - '**Binary vs Unary operators**: Binary operators (equals, contains, greaterThan) must NOT have singleValue:true. Unary operators (isEmpty, isNotEmpty, true, false) REQUIRE singleValue:true', - '**IF and Switch nodes with conditions**: Must have complete conditions.options structure: {version: 2, leftValue: "", caseSensitive: true/false, typeValidation: "strict"}', - '**Operator type field**: Must be data type (string/number/boolean/dateTime/array/object), NOT operation name (e.g., use type:"string" operation:"equals", not type:"equals")' - ], - relatedTools: ['validate_node_minimal for quick checks', 'get_node_essentials for valid examples', 'validate_workflow for complete workflow validation'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/validation/validate-node.ts b/src/mcp/tool-docs/validation/validate-node.ts new file mode 100644 index 0000000..83631f2 --- /dev/null +++ b/src/mcp/tool-docs/validation/validate-node.ts @@ -0,0 +1,82 @@ +import { ToolDocumentation } from '../types'; + +export const validateNodeDoc: ToolDocumentation = { + name: 'validate_node', + category: 'validation', + essentials: { + description: 'Validate n8n node configuration. Use mode="full" for comprehensive validation with errors/warnings/suggestions, mode="minimal" for quick required fields check.', + keyParameters: ['nodeType', 'config', 'mode', 'profile'], + example: 'validate_node({nodeType: "nodes-base.slack", config: {resource: "channel", operation: "create"}})', + performance: 'Fast (<100ms)', + tips: [ + 'Always call get_node({detail:"standard"}) first to see required fields', + 'Use mode="minimal" for quick checks during development', + 'Use mode="full" with profile="strict" before production deployment', + 'Includes automatic structure validation for filter, resourceMapper, etc.' + ] + }, + full: { + description: `Unified node configuration validator. Replaces validate_node_operation and validate_node_minimal with a single tool. + +**Validation Modes:** +- full (default): Comprehensive validation with errors, warnings, suggestions, and automatic structure validation +- minimal: Quick check for required fields only - fast but less thorough + +**Validation Profiles (for mode="full"):** +- minimal: Very lenient, basic checks only +- runtime: Standard validation (default) +- ai-friendly: Balanced for AI agent workflows +- strict: Most thorough, recommended for production + +**Automatic Structure Validation:** +Validates complex n8n types automatically: +- filter (FilterValue): 40+ operations (equals, contains, regex, etc.) +- resourceMapper (ResourceMapperValue): Data mapping configuration +- assignmentCollection (AssignmentCollectionValue): Variable assignments +- resourceLocator (INodeParameterResourceLocator): Resource selection modes`, + parameters: { + nodeType: { type: 'string', required: true, description: 'Node type with prefix: "nodes-base.slack"' }, + config: { type: 'object', required: true, description: 'Configuration object to validate. Use {} for empty config' }, + mode: { type: 'string', required: false, description: 'Validation mode: "full" (default) or "minimal"' }, + profile: { type: 'string', required: false, description: 'Validation profile for mode=full: "minimal", "runtime" (default), "ai-friendly", "strict"' } + }, + returns: `Object containing: +- nodeType: The validated node type +- workflowNodeType: Type to use in workflow JSON +- displayName: Human-readable node name +- valid: Boolean indicating if configuration is valid +- errors: Array of error objects with type, property, message, fix +- warnings: Array of warning objects with suggestions +- suggestions: Array of improvement suggestions +- missingRequiredFields: (mode=minimal only) Array of missing required field names +- summary: Object with hasErrors, errorCount, warningCount, suggestionCount`, + examples: [ + '// Full validation with default profile\nvalidate_node({nodeType: "nodes-base.slack", config: {resource: "channel", operation: "create"}})', + '// Quick required fields check\nvalidate_node({nodeType: "nodes-base.webhook", config: {}, mode: "minimal"})', + '// Strict validation for production\nvalidate_node({nodeType: "nodes-base.httpRequest", config: {...}, mode: "full", profile: "strict"})', + '// Validate IF node with filter\nvalidate_node({nodeType: "nodes-base.if", config: {conditions: {combinator: "and", conditions: [...]}}})' + ], + useCases: [ + 'Validate node configuration before adding to workflow', + 'Quick check for required fields during development', + 'Pre-production validation with strict profile', + 'Validate complex structures (filters, resource mappers)', + 'Get suggestions for improving node configuration' + ], + performance: 'Fast validation: <50ms for minimal mode, <100ms for full mode. Structure validation adds minimal overhead.', + bestPractices: [ + 'Always call get_node() first to understand required fields', + 'Use mode="minimal" for rapid iteration during development', + 'Use profile="strict" before deploying to production', + 'Pay attention to warnings - they often prevent runtime issues', + 'Validate after any configuration changes' + ], + pitfalls: [ + 'Empty config {} is valid for some nodes (e.g., manual trigger)', + 'mode="minimal" only checks required fields, not value validity', + 'Some warnings may be acceptable for specific use cases', + 'Credential validation requires runtime context' + ], + relatedTools: ['get_node', 'validate_workflow', 'n8n_autofix_workflow'] + } +}; diff --git a/src/mcp/tool-docs/validation/validate-workflow-connections.ts b/src/mcp/tool-docs/validation/validate-workflow-connections.ts deleted file mode 100644 index 07c36c3..0000000 --- a/src/mcp/tool-docs/validation/validate-workflow-connections.ts +++ /dev/null @@ -1,56 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const validateWorkflowConnectionsDoc: ToolDocumentation = { - name: 'validate_workflow_connections', - category: 'validation', - essentials: { - description: 'Check workflow connections only: valid nodes, no cycles, proper triggers, AI tool links. Fast structure validation.', - keyParameters: ['workflow'], - example: 'validate_workflow_connections({workflow: {nodes: [...], connections: {...}}})', - performance: 'Fast (<100ms)', - tips: [ - 'Use for quick structure checks when editing connections', - 'Detects orphaned nodes and circular dependencies', - 'Validates AI Agent tool connections to ensure proper node references' - ] - }, - full: { - description: 'Validates only the connection structure of a workflow without checking node configurations or expressions. This focused validation checks that all referenced nodes exist, detects circular dependencies, ensures proper trigger node placement, validates AI tool connections, and identifies orphaned or unreachable nodes.', - parameters: { - workflow: { - type: 'object', - required: true, - description: 'The workflow JSON with nodes array and connections object.' - } - }, - returns: 'Object with valid (boolean), errors (array), warnings (array), and statistics about connections', - examples: [ - 'validate_workflow_connections({workflow: myWorkflow}) - Check all connections', - 'validate_workflow_connections({workflow: {nodes: [...], connections: {...}}}) - Validate structure only' - ], - useCases: [ - 'Quick validation when modifying workflow connections', - 'Ensure all node references in connections are valid', - 'Detect circular dependencies that would cause infinite loops', - 'Validate AI Agent nodes have proper tool connections', - 'Check workflow has at least one trigger node', - 'Find orphaned nodes not connected to any flow' - ], - performance: 'Fast (<100ms). Only validates structure, not node content. Scales linearly with connection count.', - bestPractices: [ - 'Run after adding or removing connections', - 'Use before validate_workflow for quick structural checks', - 'Check for warnings about orphaned nodes', - 'Ensure trigger nodes are properly positioned', - 'Validate after using n8n_update_partial_workflow with connection operations' - ], - pitfalls: [ - 'Does not validate node configurations - use validate_workflow for full validation', - 'Cannot detect logical errors in connection flow', - 'Some valid workflows may have intentionally disconnected nodes', - 'Circular dependency detection only catches direct loops', - 'Does not validate connection types match node capabilities' - ], - relatedTools: ['validate_workflow', 'validate_workflow_expressions', 'n8n_update_partial_workflow'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/validation/validate-workflow-expressions.ts b/src/mcp/tool-docs/validation/validate-workflow-expressions.ts deleted file mode 100644 index 5d8a3e7..0000000 --- a/src/mcp/tool-docs/validation/validate-workflow-expressions.ts +++ /dev/null @@ -1,56 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const validateWorkflowExpressionsDoc: ToolDocumentation = { - name: 'validate_workflow_expressions', - category: 'validation', - essentials: { - description: 'Validate n8n expressions: syntax {{}}, variables ($json/$node), references. Returns errors with locations.', - keyParameters: ['workflow'], - example: 'validate_workflow_expressions({workflow: {nodes: [...], connections: {...}}})', - performance: 'Fast (<100ms)', - tips: [ - 'Catches syntax errors in {{}} expressions before runtime', - 'Validates $json, $node, and other n8n variables', - 'Shows exact location of expression errors in node parameters' - ] - }, - full: { - description: 'Validates all n8n expressions within a workflow for syntax correctness and reference validity. This tool scans all node parameters for n8n expressions (enclosed in {{}}), checks expression syntax, validates variable references like $json and $node("NodeName"), ensures referenced nodes exist in the workflow, and provides detailed error locations for debugging.', - parameters: { - workflow: { - type: 'object', - required: true, - description: 'The workflow JSON to check for expression errors.' - } - }, - returns: 'Object with valid (boolean), errors (array with node ID, parameter path, and error details), and expression count', - examples: [ - 'validate_workflow_expressions({workflow: myWorkflow}) - Check all expressions', - 'validate_workflow_expressions({workflow: {nodes: [...], connections: {...}}}) - Validate expression syntax' - ], - useCases: [ - 'Catch expression syntax errors before workflow execution', - 'Validate node references in $node() expressions exist', - 'Find typos in variable names like $json or $input', - 'Ensure complex expressions are properly formatted', - 'Debug expression errors with exact parameter locations', - 'Validate expressions after workflow modifications' - ], - performance: 'Fast (<100ms). Scans all string parameters in all nodes. Performance scales with workflow size and expression count.', - bestPractices: [ - 'Run after modifying any expressions in node parameters', - 'Check all $node() references when renaming nodes', - 'Validate expressions before workflow deployment', - 'Pay attention to nested object paths in expressions', - 'Use with validate_workflow for comprehensive validation' - ], - pitfalls: [ - 'Cannot validate expression logic, only syntax', - 'Runtime data availability not checked (e.g., if $json.field exists)', - 'Complex JavaScript in expressions may need runtime testing', - 'Does not validate expression return types', - 'Some valid expressions may use advanced features not fully parsed' - ], - relatedTools: ['validate_workflow', 'validate_workflow_connections', 'validate_node_operation'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/validation/validate-workflow.ts b/src/mcp/tool-docs/validation/validate-workflow.ts index 192ca2a..68b0d8e 100644 --- a/src/mcp/tool-docs/validation/validate-workflow.ts +++ b/src/mcp/tool-docs/validation/validate-workflow.ts @@ -79,6 +79,6 @@ export const validateWorkflowDoc: ToolDocumentation = { 'Validation cannot catch all runtime errors (e.g., API failures)', 'Profile setting only affects node validation, not connection/expression checks' ], - relatedTools: ['validate_workflow_connections', 'validate_workflow_expressions', 'validate_node_operation', 'n8n_create_workflow', 'n8n_update_partial_workflow', 'n8n_autofix_workflow'] + relatedTools: ['validate_node', 'n8n_create_workflow', 'n8n_update_partial_workflow', 'n8n_autofix_workflow'] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/index.ts b/src/mcp/tool-docs/workflow_management/index.ts index da49e21..7b4dfad 100644 --- a/src/mcp/tool-docs/workflow_management/index.ts +++ b/src/mcp/tool-docs/workflow_management/index.ts @@ -1,8 +1,5 @@ export { n8nCreateWorkflowDoc } from './n8n-create-workflow'; export { n8nGetWorkflowDoc } from './n8n-get-workflow'; -export { n8nGetWorkflowDetailsDoc } from './n8n-get-workflow-details'; -export { n8nGetWorkflowStructureDoc } from './n8n-get-workflow-structure'; -export { n8nGetWorkflowMinimalDoc } from './n8n-get-workflow-minimal'; export { n8nUpdateFullWorkflowDoc } from './n8n-update-full-workflow'; export { n8nUpdatePartialWorkflowDoc } from './n8n-update-partial-workflow'; export { n8nDeleteWorkflowDoc } from './n8n-delete-workflow'; @@ -10,6 +7,4 @@ export { n8nListWorkflowsDoc } from './n8n-list-workflows'; export { n8nValidateWorkflowDoc } from './n8n-validate-workflow'; export { n8nAutofixWorkflowDoc } from './n8n-autofix-workflow'; export { n8nTriggerWebhookWorkflowDoc } from './n8n-trigger-webhook-workflow'; -export { n8nGetExecutionDoc } from './n8n-get-execution'; -export { n8nListExecutionsDoc } from './n8n-list-executions'; -export { n8nDeleteExecutionDoc } from './n8n-delete-execution'; \ No newline at end of file +export { n8nExecutionsDoc } from './n8n-executions'; diff --git a/src/mcp/tool-docs/workflow_management/n8n-autofix-workflow.ts b/src/mcp/tool-docs/workflow_management/n8n-autofix-workflow.ts index c3e946c..674dbbd 100644 --- a/src/mcp/tool-docs/workflow_management/n8n-autofix-workflow.ts +++ b/src/mcp/tool-docs/workflow_management/n8n-autofix-workflow.ts @@ -153,9 +153,8 @@ Requires N8N_API_URL and N8N_API_KEY environment variables to be configured.`, relatedTools: [ 'n8n_validate_workflow', 'validate_workflow', - 'n8n_update_partial_workflow', - 'validate_workflow_expressions', - 'validate_node_operation' + 'validate_node', + 'n8n_update_partial_workflow' ] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-delete-execution.ts b/src/mcp/tool-docs/workflow_management/n8n-delete-execution.ts deleted file mode 100644 index 29d35da..0000000 --- a/src/mcp/tool-docs/workflow_management/n8n-delete-execution.ts +++ /dev/null @@ -1,57 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const n8nDeleteExecutionDoc: ToolDocumentation = { - name: 'n8n_delete_execution', - category: 'workflow_management', - essentials: { - description: 'Delete an execution record. This only removes the execution history, not any data processed.', - keyParameters: ['id'], - example: 'n8n_delete_execution({id: "12345"})', - performance: 'Immediate deletion, no undo available', - tips: [ - 'Deletion is permanent - execution cannot be recovered', - 'Only removes execution history, not external data changes', - 'Use for cleanup of test executions or sensitive data' - ] - }, - full: { - description: `Permanently deletes a workflow execution record from n8n's history. This removes the execution metadata, logs, and any stored input/output data. However, it does NOT undo any actions the workflow performed (API calls, database changes, file operations, etc.). Use this for cleaning up test executions, removing sensitive data, or managing storage.`, - parameters: { - id: { - type: 'string', - required: true, - description: 'The execution ID to delete. This action cannot be undone' - } - }, - returns: `Confirmation of deletion or error if execution not found. No data is returned about the deleted execution.`, - examples: [ - 'n8n_delete_execution({id: "12345"}) - Delete a specific execution', - 'n8n_delete_execution({id: "test-run-567"}) - Clean up test execution', - 'n8n_delete_execution({id: "sensitive-data-890"}) - Remove execution with sensitive data', - 'n8n_delete_execution({id: "failed-execution-123"}) - Delete failed execution after debugging' - ], - useCases: [ - 'Clean up test or development execution history', - 'Remove executions containing sensitive or personal data', - 'Manage storage by deleting old execution records', - 'Clean up after debugging failed workflows', - 'Comply with data retention policies' - ], - performance: `Deletion is immediate and permanent. The operation is fast (< 100ms) as it only removes database records. No external systems or data are affected.`, - bestPractices: [ - 'Verify execution ID before deletion - action cannot be undone', - 'Consider exporting execution data before deletion if needed', - 'Use list_executions to find executions to delete', - 'Document why executions were deleted for audit trails', - 'Remember deletion only affects n8n records, not external changes' - ], - pitfalls: [ - 'Deletion is PERMANENT - no undo or recovery possible', - 'Does NOT reverse workflow actions (API calls, DB changes, etc.)', - 'Deleting executions breaks audit trails and debugging history', - 'Cannot delete currently running executions (waiting status)', - 'Bulk deletion not supported - must delete one at a time' - ], - relatedTools: ['n8n_list_executions', 'n8n_get_execution', 'n8n_trigger_webhook_workflow'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-delete-workflow.ts b/src/mcp/tool-docs/workflow_management/n8n-delete-workflow.ts index c8f76e8..31475ae 100644 --- a/src/mcp/tool-docs/workflow_management/n8n-delete-workflow.ts +++ b/src/mcp/tool-docs/workflow_management/n8n-delete-workflow.ts @@ -45,6 +45,6 @@ export const n8nDeleteWorkflowDoc: ToolDocumentation = { 'Active workflows can be deleted', 'No built-in confirmation' ], - relatedTools: ['n8n_get_workflow_minimal', 'n8n_list_workflows', 'n8n_update_partial_workflow', 'n8n_delete_execution'] + relatedTools: ['n8n_get_workflow', 'n8n_list_workflows', 'n8n_update_partial_workflow', 'n8n_executions'] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-executions.ts b/src/mcp/tool-docs/workflow_management/n8n-executions.ts new file mode 100644 index 0000000..5747844 --- /dev/null +++ b/src/mcp/tool-docs/workflow_management/n8n-executions.ts @@ -0,0 +1,84 @@ +import { ToolDocumentation } from '../types'; + +export const n8nExecutionsDoc: ToolDocumentation = { + name: 'n8n_executions', + category: 'workflow_management', + essentials: { + description: 'Manage workflow executions: get details, list, or delete. Unified tool for all execution operations.', + keyParameters: ['action', 'id', 'workflowId', 'status'], + example: 'n8n_executions({action: "list", workflowId: "abc123", status: "error"})', + performance: 'Fast (50-200ms)', + tips: [ + 'action="get": Get execution details by ID', + 'action="list": List executions with filters', + 'action="delete": Delete execution record', + 'Use mode parameter for action=get to control detail level' + ] + }, + full: { + description: `Unified execution management tool. Replaces n8n_get_execution, n8n_list_executions, and n8n_delete_execution. + +**Actions:** +- get: Retrieve execution details by ID with configurable detail level +- list: List executions with filtering and pagination +- delete: Remove an execution record from history + +**Detail Modes for action="get":** +- preview: Structure only, no data +- summary: 2 items per node (default) +- filtered: Custom items limit, optionally filter by node names +- full: All execution data (can be very large)`, + parameters: { + action: { type: 'string', required: true, description: 'Operation: "get", "list", or "delete"' }, + id: { type: 'string', required: false, description: 'Execution ID (required for action=get or action=delete)' }, + mode: { type: 'string', required: false, description: 'For action=get: "preview", "summary" (default), "filtered", "full"' }, + nodeNames: { type: 'array', required: false, description: 'For action=get with mode=filtered: Filter to specific nodes by name' }, + itemsLimit: { type: 'number', required: false, description: 'For action=get with mode=filtered: Items per node (0=structure, 2=default, -1=unlimited)' }, + includeInputData: { type: 'boolean', required: false, description: 'For action=get: Include input data in addition to output (default: false)' }, + workflowId: { type: 'string', required: false, description: 'For action=list: Filter by workflow ID' }, + status: { type: 'string', required: false, description: 'For action=list: Filter by status ("success", "error", "waiting")' }, + limit: { type: 'number', required: false, description: 'For action=list: Number of results (1-100, default: 100)' }, + cursor: { type: 'string', required: false, description: 'For action=list: Pagination cursor from previous response' }, + projectId: { type: 'string', required: false, description: 'For action=list: Filter by project ID (enterprise)' }, + includeData: { type: 'boolean', required: false, description: 'For action=list: Include execution data (default: false)' } + }, + returns: `Depends on action: +- get: Execution object with data based on mode +- list: { data: [...executions], nextCursor?: string } +- delete: { success: boolean, message: string }`, + examples: [ + '// List recent executions for a workflow\nn8n_executions({action: "list", workflowId: "abc123", limit: 10})', + '// List failed executions\nn8n_executions({action: "list", status: "error"})', + '// Get execution summary\nn8n_executions({action: "get", id: "exec_456"})', + '// Get full execution data\nn8n_executions({action: "get", id: "exec_456", mode: "full"})', + '// Get specific nodes from execution\nn8n_executions({action: "get", id: "exec_456", mode: "filtered", nodeNames: ["HTTP Request", "Slack"]})', + '// Delete an execution\nn8n_executions({action: "delete", id: "exec_456"})' + ], + useCases: [ + 'Debug workflow failures (get with mode=full)', + 'Monitor workflow health (list with status filter)', + 'Audit execution history', + 'Clean up old execution records', + 'Analyze specific node outputs' + ], + performance: `Response times: +- list: 50-150ms depending on filters +- get (preview/summary): 30-100ms +- get (full): 100-500ms+ depending on data size +- delete: 30-80ms`, + bestPractices: [ + 'Use mode="summary" (default) for debugging - shows enough data', + 'Use mode="filtered" with nodeNames for large workflows', + 'Filter by workflowId when listing to reduce results', + 'Use cursor for pagination through large result sets', + 'Delete old executions to save storage' + ], + pitfalls: [ + 'Requires N8N_API_URL and N8N_API_KEY configured', + 'mode="full" can return very large responses for complex workflows', + 'Execution must exist or returns 404', + 'Delete is permanent - cannot undo' + ], + relatedTools: ['n8n_get_workflow', 'n8n_trigger_webhook_workflow', 'n8n_validate_workflow'] + } +}; diff --git a/src/mcp/tool-docs/workflow_management/n8n-get-execution.ts b/src/mcp/tool-docs/workflow_management/n8n-get-execution.ts deleted file mode 100644 index 7c5e462..0000000 --- a/src/mcp/tool-docs/workflow_management/n8n-get-execution.ts +++ /dev/null @@ -1,283 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const n8nGetExecutionDoc: ToolDocumentation = { - name: 'n8n_get_execution', - category: 'workflow_management', - essentials: { - description: 'Get execution details with smart filtering to avoid token limits. Use preview mode first to assess data size, then fetch appropriately.', - keyParameters: ['id', 'mode', 'itemsLimit', 'nodeNames'], - example: ` -// RECOMMENDED WORKFLOW: -// 1. Preview first -n8n_get_execution({id: "12345", mode: "preview"}) -// Returns: structure, counts, size estimate, recommendation - -// 2. Based on recommendation, fetch data: -n8n_get_execution({id: "12345", mode: "summary"}) // 2 items per node -n8n_get_execution({id: "12345", mode: "filtered", itemsLimit: 5}) // 5 items -n8n_get_execution({id: "12345", nodeNames: ["HTTP Request"]}) // Specific node -`, - performance: 'Preview: <50ms, Summary: <200ms, Full: depends on data size', - tips: [ - 'ALWAYS use preview mode first for large datasets', - 'Preview shows structure + counts without consuming tokens for data', - 'Summary mode (2 items per node) is safe default', - 'Use nodeNames to focus on specific nodes only', - 'itemsLimit: 0 = structure only, -1 = unlimited', - 'Check recommendation.suggestedMode from preview' - ] - }, - full: { - description: `Retrieves and intelligently filters execution data to enable inspection without exceeding token limits. This tool provides multiple modes for different use cases, from quick previews to complete data retrieval. - -**The Problem**: Workflows processing large datasets (50+ database records) generate execution data that exceeds token/response limits, making traditional full-data fetching impossible. - -**The Solution**: Four retrieval modes with smart filtering: -1. **Preview**: Structure + counts only (no actual data) -2. **Summary**: 2 sample items per node (safe default) -3. **Filtered**: Custom limits and node selection -4. **Full**: Complete data (use with caution) - -**Recommended Workflow**: -1. Start with preview mode to assess size -2. Use recommendation to choose appropriate mode -3. Fetch filtered data as needed`, - - parameters: { - id: { - type: 'string', - required: true, - description: 'The execution ID to retrieve. Obtained from list_executions or webhook trigger responses' - }, - mode: { - type: 'string', - required: false, - description: `Retrieval mode (default: auto-detect from other params): -- 'preview': Structure, counts, size estimates - NO actual data (fastest) -- 'summary': Metadata + 2 sample items per node (safe default) -- 'filtered': Custom filtering with itemsLimit/nodeNames -- 'full': Complete execution data (use with caution)` - }, - nodeNames: { - type: 'array', - required: false, - description: 'Filter to specific nodes by name. Example: ["HTTP Request", "Filter"]. Useful when you only need to inspect specific nodes.' - }, - itemsLimit: { - type: 'number', - required: false, - description: `Items to return per node (default: 2): -- 0: Structure only (see data shape without values) -- 1-N: Return N items per node -- -1: Unlimited (return all items) - -Note: Structure-only mode (0) shows JSON schema without actual values.` - }, - includeInputData: { - type: 'boolean', - required: false, - description: 'Include input data in addition to output data (default: false). Useful for debugging data transformations.' - }, - includeData: { - type: 'boolean', - required: false, - description: 'DEPRECATED: Legacy parameter. Use mode instead. If true, maps to mode="summary" for backward compatibility.' - } - }, - - returns: `**Preview Mode Response**: -{ - mode: 'preview', - preview: { - totalNodes: number, - executedNodes: number, - estimatedSizeKB: number, - nodes: { - [nodeName]: { - status: 'success' | 'error', - itemCounts: { input: number, output: number }, - dataStructure: {...}, // JSON schema - estimatedSizeKB: number - } - } - }, - recommendation: { - canFetchFull: boolean, - suggestedMode: 'preview'|'summary'|'filtered'|'full', - suggestedItemsLimit?: number, - reason: string - } -} - -**Summary/Filtered/Full Mode Response**: -{ - mode: 'summary' | 'filtered' | 'full', - summary: { - totalNodes: number, - executedNodes: number, - totalItems: number, - hasMoreData: boolean // true if truncated - }, - nodes: { - [nodeName]: { - executionTime: number, - itemsInput: number, - itemsOutput: number, - status: 'success' | 'error', - error?: string, - data: { - output: [...], // Actual data items - metadata: { - totalItems: number, - itemsShown: number, - truncated: boolean - } - } - } - } -}`, - - examples: [ - `// Example 1: Preview workflow (RECOMMENDED FIRST STEP) -n8n_get_execution({id: "exec_123", mode: "preview"}) -// Returns structure, counts, size, recommendation -// Use this to decide how to fetch data`, - - `// Example 2: Follow recommendation -const preview = n8n_get_execution({id: "exec_123", mode: "preview"}); -if (preview.recommendation.canFetchFull) { - n8n_get_execution({id: "exec_123", mode: "full"}); -} else { - n8n_get_execution({ - id: "exec_123", - mode: "filtered", - itemsLimit: preview.recommendation.suggestedItemsLimit - }); -}`, - - `// Example 3: Summary mode (safe default for unknown datasets) -n8n_get_execution({id: "exec_123", mode: "summary"}) -// Gets 2 items per node - safe for most cases`, - - `// Example 4: Filter to specific node -n8n_get_execution({ - id: "exec_123", - mode: "filtered", - nodeNames: ["HTTP Request"], - itemsLimit: 5 -}) -// Gets only HTTP Request node, 5 items`, - - `// Example 5: Structure only (see data shape) -n8n_get_execution({ - id: "exec_123", - mode: "filtered", - itemsLimit: 0 -}) -// Returns JSON schema without actual values`, - - `// Example 6: Debug with input data -n8n_get_execution({ - id: "exec_123", - mode: "filtered", - nodeNames: ["Transform"], - itemsLimit: 2, - includeInputData: true -}) -// See both input and output for debugging`, - - `// Example 7: Backward compatibility (legacy) -n8n_get_execution({id: "exec_123"}) // Minimal data -n8n_get_execution({id: "exec_123", includeData: true}) // Maps to summary mode` - ], - - useCases: [ - 'Monitor status of triggered workflows', - 'Debug failed workflows by examining error messages and partial data', - 'Inspect large datasets without exceeding token limits', - 'Validate data transformations between nodes', - 'Understand execution flow and timing', - 'Track workflow performance metrics', - 'Verify successful completion before proceeding', - 'Extract specific data from execution results' - ], - - performance: `**Response Times** (approximate): -- Preview mode: <50ms (no data, just structure) -- Summary mode: <200ms (2 items per node) -- Filtered mode: 50-500ms (depends on filters) -- Full mode: 200ms-5s (depends on data size) - -**Token Consumption**: -- Preview: ~500 tokens (no data values) -- Summary (2 items): ~2-5K tokens -- Filtered (5 items): ~5-15K tokens -- Full (50+ items): 50K+ tokens (may exceed limits) - -**Optimization Tips**: -- Use preview for all large datasets -- Use nodeNames to focus on relevant nodes only -- Start with small itemsLimit and increase if needed -- Use itemsLimit: 0 to see structure without data`, - - bestPractices: [ - 'ALWAYS use preview mode first for unknown datasets', - 'Trust the recommendation.suggestedMode from preview', - 'Use nodeNames to filter to relevant nodes only', - 'Start with summary mode if preview indicates moderate size', - 'Use itemsLimit: 0 to understand data structure', - 'Check hasMoreData to know if results are truncated', - 'Store execution IDs from triggers for later inspection', - 'Use mode="filtered" with custom limits for large datasets', - 'Include input data only when debugging transformations', - 'Monitor summary.totalItems to understand dataset size' - ], - - pitfalls: [ - 'DON\'T fetch full mode without previewing first - may timeout', - 'DON\'T assume all data fits - always check hasMoreData', - 'DON\'T ignore the recommendation from preview mode', - 'Execution data is retained based on n8n settings - old executions may be purged', - 'Binary data (files, images) is not fully included - only metadata', - 'Status "waiting" indicates execution is still running', - 'Error executions may have partial data from successful nodes', - 'Very large individual items (>1MB) may be truncated', - 'Preview mode estimates may be off by 10-20% for complex structures', - 'Node names are case-sensitive in nodeNames filter' - ], - - modeComparison: `**When to use each mode**: - -**Preview**: -- ALWAYS use first for unknown datasets -- When you need to know if data is safe to fetch -- To see data structure without consuming tokens -- To get size estimates and recommendations - -**Summary** (default): -- Safe default for most cases -- When you need representative samples -- When preview recommends it -- For quick data inspection - -**Filtered**: -- When you need specific nodes only -- When you need more than 2 items but not all -- When preview recommends it with itemsLimit -- For targeted data extraction - -**Full**: -- ONLY when preview says canFetchFull: true -- For small executions (< 20 items total) -- When you genuinely need all data -- When you're certain data fits in token limit`, - - relatedTools: [ - 'n8n_list_executions - Find execution IDs', - 'n8n_trigger_webhook_workflow - Trigger and get execution ID', - 'n8n_delete_execution - Clean up old executions', - 'n8n_get_workflow - Get workflow structure', - 'validate_workflow - Validate before executing' - ] - } -}; diff --git a/src/mcp/tool-docs/workflow_management/n8n-get-workflow-details.ts b/src/mcp/tool-docs/workflow_management/n8n-get-workflow-details.ts deleted file mode 100644 index cf34d6e..0000000 --- a/src/mcp/tool-docs/workflow_management/n8n-get-workflow-details.ts +++ /dev/null @@ -1,49 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const n8nGetWorkflowDetailsDoc: ToolDocumentation = { - name: 'n8n_get_workflow_details', - category: 'workflow_management', - essentials: { - description: 'Get workflow details with metadata, version, execution stats. More info than get_workflow.', - keyParameters: ['id'], - example: 'n8n_get_workflow_details({id: "workflow_123"})', - performance: 'Fast (100-300ms)', - tips: [ - 'Includes execution statistics', - 'Shows version history info', - 'Contains metadata like tags' - ] - }, - full: { - description: 'Retrieves comprehensive workflow details including metadata, execution statistics, version information, and usage analytics. Provides more information than get_workflow, including data not typically needed for editing but useful for monitoring and analysis.', - parameters: { - id: { type: 'string', required: true, description: 'Workflow ID to retrieve details for' } - }, - returns: 'Extended workflow object with: id, name, nodes, connections, settings, plus metadata (tags, owner, shared users), execution stats (success/error counts, average runtime), version info, created/updated timestamps', - examples: [ - 'n8n_get_workflow_details({id: "abc123"}) - Get workflow with stats', - 'const details = n8n_get_workflow_details({id: "xyz789"}); // Analyze performance' - ], - useCases: [ - 'Monitor workflow performance', - 'Analyze execution patterns', - 'View workflow metadata', - 'Check version information', - 'Audit workflow usage' - ], - performance: 'Slightly slower than get_workflow due to additional metadata - typically 100-300ms. Stats may be cached.', - bestPractices: [ - 'Use for monitoring and analysis', - 'Check execution stats before optimization', - 'Review error counts for debugging', - 'Monitor average execution times' - ], - pitfalls: [ - 'Requires N8N_API_URL and N8N_API_KEY configured', - 'More data than needed for simple edits', - 'Stats may have slight delay', - 'Not all n8n versions support all fields' - ], - relatedTools: ['n8n_get_workflow', 'n8n_list_executions', 'n8n_get_execution', 'n8n_list_workflows'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-get-workflow-minimal.ts b/src/mcp/tool-docs/workflow_management/n8n-get-workflow-minimal.ts deleted file mode 100644 index 0e6a517..0000000 --- a/src/mcp/tool-docs/workflow_management/n8n-get-workflow-minimal.ts +++ /dev/null @@ -1,49 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const n8nGetWorkflowMinimalDoc: ToolDocumentation = { - name: 'n8n_get_workflow_minimal', - category: 'workflow_management', - essentials: { - description: 'Get minimal info: ID, name, active status, tags. Fast for listings.', - keyParameters: ['id'], - example: 'n8n_get_workflow_minimal({id: "workflow_123"})', - performance: 'Very fast (<50ms)', - tips: [ - 'Fastest way to check workflow exists', - 'Perfect for status checks', - 'Use in list displays' - ] - }, - full: { - description: 'Retrieves only essential workflow information without nodes or connections. Returns minimal data needed for listings, status checks, and quick lookups. Optimized for performance when full workflow data is not needed.', - parameters: { - id: { type: 'string', required: true, description: 'Workflow ID to retrieve minimal info for' } - }, - returns: 'Minimal workflow object with: id, name, active status, tags array, createdAt, updatedAt. No nodes, connections, or settings included.', - examples: [ - 'n8n_get_workflow_minimal({id: "abc123"}) - Quick existence check', - 'const info = n8n_get_workflow_minimal({id: "xyz789"}); // Check if active' - ], - useCases: [ - 'Quick workflow existence checks', - 'Display workflow lists', - 'Check active/inactive status', - 'Get workflow tags', - 'Performance-critical operations' - ], - performance: 'Extremely fast - typically under 50ms. Returns only database metadata without loading workflow definition.', - bestPractices: [ - 'Use for list displays and dashboards', - 'Ideal for existence checks before operations', - 'Cache results for UI responsiveness', - 'Combine with list_workflows for bulk checks' - ], - pitfalls: [ - 'Requires N8N_API_URL and N8N_API_KEY configured', - 'No workflow content - cannot edit or validate', - 'Tags may be empty array', - 'Must use get_workflow for actual workflow data' - ], - relatedTools: ['n8n_list_workflows', 'n8n_get_workflow', 'n8n_get_workflow_structure', 'n8n_update_partial_workflow'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-get-workflow-structure.ts b/src/mcp/tool-docs/workflow_management/n8n-get-workflow-structure.ts deleted file mode 100644 index a2d3d70..0000000 --- a/src/mcp/tool-docs/workflow_management/n8n-get-workflow-structure.ts +++ /dev/null @@ -1,49 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const n8nGetWorkflowStructureDoc: ToolDocumentation = { - name: 'n8n_get_workflow_structure', - category: 'workflow_management', - essentials: { - description: 'Get workflow structure: nodes and connections only. No parameter details.', - keyParameters: ['id'], - example: 'n8n_get_workflow_structure({id: "workflow_123"})', - performance: 'Fast (75-150ms)', - tips: [ - 'Shows workflow topology', - 'Node types without parameters', - 'Perfect for visualization' - ] - }, - full: { - description: 'Retrieves workflow structural information including node types, positions, and connections, but without detailed node parameters. Ideal for understanding workflow topology, creating visualizations, or analyzing workflow complexity without the overhead of full parameter data.', - parameters: { - id: { type: 'string', required: true, description: 'Workflow ID to retrieve structure for' } - }, - returns: 'Workflow structure with: id, name, nodes array (id, name, type, position only), connections object. No node parameters, credentials, or settings included.', - examples: [ - 'n8n_get_workflow_structure({id: "abc123"}) - Visualize workflow', - 'const structure = n8n_get_workflow_structure({id: "xyz789"}); // Analyze complexity' - ], - useCases: [ - 'Generate workflow visualizations', - 'Analyze workflow complexity', - 'Understand node relationships', - 'Create workflow diagrams', - 'Quick topology validation' - ], - performance: 'Fast retrieval - typically 75-150ms. Faster than get_workflow as parameters are stripped.', - bestPractices: [ - 'Use for visualization tools', - 'Ideal for workflow analysis', - 'Good for connection validation', - 'Cache for UI diagram rendering' - ], - pitfalls: [ - 'Requires N8N_API_URL and N8N_API_KEY configured', - 'No parameter data for configuration', - 'Cannot validate node settings', - 'Must use get_workflow for editing' - ], - relatedTools: ['n8n_get_workflow', 'n8n_validate_workflow_connections', 'n8n_get_workflow_minimal', 'validate_workflow_connections'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-get-workflow.ts b/src/mcp/tool-docs/workflow_management/n8n-get-workflow.ts index 6c01ab3..9862982 100644 --- a/src/mcp/tool-docs/workflow_management/n8n-get-workflow.ts +++ b/src/mcp/tool-docs/workflow_management/n8n-get-workflow.ts @@ -4,46 +4,65 @@ export const n8nGetWorkflowDoc: ToolDocumentation = { name: 'n8n_get_workflow', category: 'workflow_management', essentials: { - description: 'Get a workflow by ID. Returns the complete workflow including nodes, connections, and settings.', - keyParameters: ['id'], - example: 'n8n_get_workflow({id: "workflow_123"})', + description: 'Get workflow by ID with different detail levels. Use mode to control response size and content.', + keyParameters: ['id', 'mode'], + example: 'n8n_get_workflow({id: "workflow_123", mode: "structure"})', performance: 'Fast (50-200ms)', tips: [ - 'Returns complete workflow JSON', - 'Includes all node parameters', - 'Use get_workflow_minimal for faster listings' + 'mode="full" (default): Complete workflow with all data', + 'mode="details": Full workflow + execution stats', + 'mode="structure": Just nodes and connections (topology)', + 'mode="minimal": Only id, name, active status, tags' ] }, full: { - description: 'Retrieves a complete workflow from n8n by its ID. Returns full workflow definition including all nodes with their parameters, connections between nodes, and workflow settings. This is the primary tool for fetching workflows for viewing, editing, or cloning.', + description: `Unified workflow retrieval with configurable detail levels. Replaces n8n_get_workflow, n8n_get_workflow_details, n8n_get_workflow_structure, and n8n_get_workflow_minimal. + +**Modes:** +- full (default): Complete workflow including all nodes with parameters, connections, and settings +- details: Full workflow plus execution statistics (success/error counts, last execution time) +- structure: Nodes and connections only - useful for topology analysis +- minimal: Just id, name, active status, and tags - fastest response`, parameters: { - id: { type: 'string', required: true, description: 'Workflow ID to retrieve' } + id: { type: 'string', required: true, description: 'Workflow ID to retrieve' }, + mode: { type: 'string', required: false, description: 'Detail level: "full" (default), "details", "structure", "minimal"' } }, - returns: 'Complete workflow object containing: id, name, active status, nodes array (with full parameters), connections object, settings, createdAt, updatedAt', + returns: `Depends on mode: +- full: Complete workflow object (id, name, active, nodes[], connections{}, settings, createdAt, updatedAt) +- details: Full workflow + executionStats (successCount, errorCount, lastExecution, etc.) +- structure: { nodes: [...], connections: {...} } - topology only +- minimal: { id, name, active, tags, createdAt, updatedAt }`, examples: [ - 'n8n_get_workflow({id: "abc123"}) - Get workflow for editing', - 'const wf = n8n_get_workflow({id: "xyz789"}); // Clone workflow structure' + '// Get complete workflow (default)\nn8n_get_workflow({id: "abc123"})', + '// Get workflow with execution stats\nn8n_get_workflow({id: "abc123", mode: "details"})', + '// Get just the topology\nn8n_get_workflow({id: "abc123", mode: "structure"})', + '// Quick metadata check\nn8n_get_workflow({id: "abc123", mode: "minimal"})' ], useCases: [ - 'View workflow configuration', - 'Export workflow for backup', - 'Clone workflow structure', - 'Debug workflow issues', - 'Prepare for updates' + 'View and edit workflow (mode=full)', + 'Analyze workflow performance (mode=details)', + 'Clone or compare workflow structure (mode=structure)', + 'List workflows with status (mode=minimal)', + 'Debug workflow issues' ], - performance: 'Fast retrieval - typically 50-200ms depending on workflow size. Cached by n8n for performance.', + performance: `Response times vary by mode: +- minimal: ~20-50ms (smallest response) +- structure: ~30-80ms (nodes + connections only) +- full: ~50-200ms (complete workflow) +- details: ~100-300ms (includes execution queries)`, bestPractices: [ - 'Check workflow exists before updating', - 'Use for complete workflow data needs', - 'Cache results when making multiple operations', - 'Validate after retrieving if modifying' + 'Use mode="minimal" when listing or checking status', + 'Use mode="structure" for workflow analysis or cloning', + 'Use mode="full" (default) when editing', + 'Use mode="details" for debugging execution issues', + 'Validate workflow after retrieval if planning modifications' ], pitfalls: [ 'Requires N8N_API_URL and N8N_API_KEY configured', - 'Returns all data - use minimal/structure for performance', - 'Workflow must exist or returns 404', - 'Credentials are referenced but not included' + 'mode="details" adds database queries for execution stats', + 'Workflow must exist or returns 404 error', + 'Credentials are referenced by ID but values not included' ], - relatedTools: ['n8n_get_workflow_minimal', 'n8n_get_workflow_structure', 'n8n_update_full_workflow', 'n8n_validate_workflow'] + relatedTools: ['n8n_list_workflows', 'n8n_update_full_workflow', 'n8n_update_partial_workflow', 'n8n_validate_workflow'] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-list-executions.ts b/src/mcp/tool-docs/workflow_management/n8n-list-executions.ts deleted file mode 100644 index 94e8223..0000000 --- a/src/mcp/tool-docs/workflow_management/n8n-list-executions.ts +++ /dev/null @@ -1,84 +0,0 @@ -import { ToolDocumentation } from '../types'; - -export const n8nListExecutionsDoc: ToolDocumentation = { - name: 'n8n_list_executions', - category: 'workflow_management', - essentials: { - description: 'List workflow executions with optional filters. Supports pagination for large result sets.', - keyParameters: ['workflowId', 'status', 'limit'], - example: 'n8n_list_executions({workflowId: "abc123", status: "error"})', - performance: 'Fast metadata retrieval, use pagination for large datasets', - tips: [ - 'Filter by status (success/error/waiting) to find specific execution types', - 'Use workflowId to see all executions for a specific workflow', - 'Pagination via cursor allows retrieving large execution histories' - ] - }, - full: { - description: `Lists workflow executions with powerful filtering options. This tool is essential for monitoring workflow performance, finding failed executions, and tracking workflow activity. Supports pagination for retrieving large execution histories and filtering by workflow, status, and project.`, - parameters: { - limit: { - type: 'number', - required: false, - description: 'Number of executions to return (1-100, default: 100). Use with cursor for pagination' - }, - cursor: { - type: 'string', - required: false, - description: 'Pagination cursor from previous response. Used to retrieve next page of results' - }, - workflowId: { - type: 'string', - required: false, - description: 'Filter executions by specific workflow ID. Shows all executions for that workflow' - }, - projectId: { - type: 'string', - required: false, - description: 'Filter by project ID (enterprise feature). Groups executions by project' - }, - status: { - type: 'string', - required: false, - enum: ['success', 'error', 'waiting'], - description: 'Filter by execution status. Success = completed, Error = failed, Waiting = running' - }, - includeData: { - type: 'boolean', - required: false, - description: 'Include execution data in results (default: false). Significantly increases response size' - } - }, - returns: `Array of execution objects with metadata, pagination cursor for next page, and optionally execution data. Each execution includes ID, status, start/end times, and workflow reference.`, - examples: [ - 'n8n_list_executions({limit: 10}) - Get 10 most recent executions', - 'n8n_list_executions({workflowId: "abc123"}) - All executions for specific workflow', - 'n8n_list_executions({status: "error", limit: 50}) - Find failed executions', - 'n8n_list_executions({status: "waiting"}) - Monitor currently running workflows', - 'n8n_list_executions({cursor: "next-page-token"}) - Get next page of results' - ], - useCases: [ - 'Monitor workflow execution history and patterns', - 'Find and debug failed workflow executions', - 'Track currently running workflows (waiting status)', - 'Analyze workflow performance and execution frequency', - 'Generate execution reports for specific workflows' - ], - performance: `Listing executions is fast for metadata only. Including data (includeData: true) significantly impacts performance. Use pagination (limit + cursor) for large result sets. Default limit of 100 balances performance with usability.`, - bestPractices: [ - 'Use status filters to focus on specific execution types', - 'Implement pagination for large execution histories', - 'Avoid includeData unless you need execution details', - 'Filter by workflowId when monitoring specific workflows', - 'Check for cursor in response to detect more pages' - ], - pitfalls: [ - 'Large limits with includeData can cause timeouts', - 'Execution retention depends on n8n configuration', - 'Cursor tokens expire - use them promptly', - 'Status "waiting" includes both running and queued executions', - 'Deleted workflows still show in execution history' - ], - relatedTools: ['n8n_get_execution', 'n8n_trigger_webhook_workflow', 'n8n_delete_execution', 'n8n_list_workflows'] - } -}; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-list-workflows.ts b/src/mcp/tool-docs/workflow_management/n8n-list-workflows.ts index 8cee1d2..fd5c949 100644 --- a/src/mcp/tool-docs/workflow_management/n8n-list-workflows.ts +++ b/src/mcp/tool-docs/workflow_management/n8n-list-workflows.ts @@ -50,6 +50,6 @@ export const n8nListWorkflowsDoc: ToolDocumentation = { 'Server may return fewer than requested limit', 'returned field is count of current page only, not system total' ], - relatedTools: ['n8n_get_workflow_minimal', 'n8n_get_workflow', 'n8n_update_partial_workflow', 'n8n_list_executions'] + relatedTools: ['n8n_get_workflow', 'n8n_update_partial_workflow', 'n8n_executions'] } }; \ No newline at end of file diff --git a/src/mcp/tool-docs/workflow_management/n8n-trigger-webhook-workflow.ts b/src/mcp/tool-docs/workflow_management/n8n-trigger-webhook-workflow.ts index decf7e0..c555074 100644 --- a/src/mcp/tool-docs/workflow_management/n8n-trigger-webhook-workflow.ts +++ b/src/mcp/tool-docs/workflow_management/n8n-trigger-webhook-workflow.ts @@ -64,13 +64,13 @@ export const n8nTriggerWebhookWorkflowDoc: ToolDocumentation = { When a webhook trigger fails, the error response now includes specific guidance to help debug the issue: **Error with Execution ID** (workflow started but failed): -- Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_get_execution({id: '{executionId}', mode: 'preview'}) to investigate the error." +- Format: "Workflow {workflowId} execution {executionId} failed. Use n8n_executions({action: 'get', id: '{executionId}', mode: 'preview'}) to investigate the error." - Response includes: executionId and workflowId fields for direct access -- Recommended action: Use n8n_get_execution with mode='preview' for fast, efficient error inspection +- Recommended action: Use n8n_executions with action='get' and mode='preview' for fast, efficient error inspection **Error without Execution ID** (workflow didn't start): -- Format: "Workflow failed to execute. Use n8n_list_executions to find recent executions, then n8n_get_execution with mode='preview' to investigate." -- Recommended action: Check recent executions with n8n_list_executions +- Format: "Workflow failed to execute. Use n8n_executions({action: 'list'}) to find recent executions, then n8n_executions({action: 'get', mode: 'preview'}) to investigate." +- Recommended action: Check recent executions with n8n_executions({action: 'list'}) **Why mode='preview'?** - Fast: <50ms response time @@ -92,7 +92,7 @@ When a webhook trigger fails, the error response now includes specific guidance **Investigation Workflow**: 1. Trigger returns error with execution ID -2. Call n8n_get_execution({id: executionId, mode: 'preview'}) to see structure and error +2. Call n8n_executions({action: 'get', id: executionId, mode: 'preview'}) to see structure and error 3. Based on preview recommendation, fetch more data if needed 4. Fix issues in workflow and retry`, bestPractices: [ @@ -101,7 +101,7 @@ When a webhook trigger fails, the error response now includes specific guidance 'Use async mode (waitForResponse: false) for long-running workflows', 'Include authentication headers when webhook requires them', 'Test webhook URL manually first to ensure it works', - 'When errors occur, use n8n_get_execution with mode="preview" first for efficient debugging', + 'When errors occur, use n8n_executions with action="get" and mode="preview" first for efficient debugging', 'Store execution IDs from error responses for later investigation' ], pitfalls: [ @@ -110,9 +110,9 @@ When a webhook trigger fails, the error response now includes specific guidance 'Webhook node must be the trigger node in the workflow', 'Timeout errors occur with long workflows in sync mode', 'Data format must match webhook node expectations', - 'Error messages always include n8n_get_execution guidance - follow the suggested steps for efficient debugging', + 'Error messages always include n8n_executions guidance - follow the suggested steps for efficient debugging', 'Execution IDs in error responses are crucial for debugging - always check for and use them' ], - relatedTools: ['n8n_get_execution', 'n8n_list_executions', 'n8n_get_workflow', 'n8n_create_workflow'] + relatedTools: ['n8n_executions', 'n8n_get_workflow', 'n8n_create_workflow'] } }; \ No newline at end of file diff --git a/src/mcp/tools-documentation.ts b/src/mcp/tools-documentation.ts index 10543da..d5b8028 100644 --- a/src/mcp/tools-documentation.ts +++ b/src/mcp/tools-documentation.ts @@ -92,52 +92,57 @@ When working with Code nodes, always start by calling the relevant guide: - search_nodes({query: "AI langchain"}) - Search for AI-capable nodes 2. **Configure** the node (ALWAYS START WITH STANDARD DETAIL): - - ✅ get_node("nodes-base.slack", {detail: 'standard'}) - Get essential properties FIRST (~1-2KB, shows required fields) - - get_node("nodes-base.slack", {detail: 'full'}) - Get complete schema only if standard insufficient (~100KB+) - - get_node("nodes-base.slack", {detail: 'minimal'}) - Get basic metadata only (~200 tokens) - - search_node_properties("nodes-base.slack", "auth") - Find specific properties + - ✅ 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_minimal("nodes-base.slack", config) - Check required fields (includes automatic structure validation) - - validate_node_operation("nodes-base.slack", config) - Full validation with fixes (includes automatic structure validation) - - validate_workflow(workflow) - Validate entire workflow + - 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 +## Tool Categories (19 Tools Total) -**Discovery Tools** +**Discovery Tools** (1 tool) - search_nodes - Full-text search across all nodes (supports OR, AND, FUZZY modes) -**Configuration Tools** -- get_node - ✅ Unified node information tool with progressive detail levels: - - detail='minimal': Basic metadata (~200 tokens) - - detail='standard': Essential properties (default, ~1-2KB) - USE THIS FIRST! - - detail='full': Complete schema (~100KB+, use only when standard insufficient) - - mode='versions': View version history and breaking changes - - includeTypeInfo=true: Add type structure metadata -- search_node_properties - Search for specific properties within a node -- get_property_dependencies - Analyze property visibility dependencies +**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** -- validate_node_minimal - Quick validation of required fields (includes structure validation) -- validate_node_operation - Full validation with operation awareness (includes structure validation) -- validate_workflow - Complete workflow validation including connections +**Validation Tools** (2 tools) +- validate_node - Unified validation with mode='full' or mode='minimal' +- validate_workflow - Complete workflow validation (nodes, connections, expressions) -**Template Tools** -- get_node_for_task - Get pre-configured node for specific tasks -- search_templates - Search workflow templates by keyword +**Template Tools** (2 tools) - get_template - Get complete workflow JSON by ID -- list_node_templates - Find templates using specific nodes -- get_templates_for_task - Get curated templates by task type +- 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** (requires N8N_API_URL configuration) +**n8n API Tools** (12 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 +- 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_trigger_webhook_workflow - Trigger via webhook +- n8n_executions - Unified execution management (action='get'/'list'/'delete') +- n8n_health_check - Check n8n API connectivity +- n8n_workflow_versions - Version history and rollback ## Performance Characteristics - Instant (<10ms): search_nodes, get_node (minimal/standard) -- Fast (<100ms): validate_node_minimal, get_node_for_task +- Fast (<100ms): validate_node, get_template - Moderate (100-500ms): validate_workflow, get_node (full detail) - Network-dependent: All n8n_* tools diff --git a/src/mcp/tools-n8n-friendly.ts b/src/mcp/tools-n8n-friendly.ts index d9b1020..f72c009 100644 --- a/src/mcp/tools-n8n-friendly.ts +++ b/src/mcp/tools-n8n-friendly.ts @@ -13,25 +13,18 @@ export const n8nFriendlyDescriptions: Record; }> = { - // Validation tools - most prone to errors - validate_node_operation: { - description: 'Validate n8n node. ALWAYS pass two parameters: nodeType (string) and config (object). Example call: {"nodeType": "nodes-base.slack", "config": {"resource": "channel", "operation": "create"}}', + // Consolidated validation tool (replaces validate_node_operation and validate_node_minimal) + validate_node: { + description: 'Validate n8n node config. Pass nodeType (string) and config (object). Use mode="full" for comprehensive validation, mode="minimal" for quick check. Example: {"nodeType": "nodes-base.slack", "config": {"resource": "channel", "operation": "create"}}', params: { nodeType: 'String value like "nodes-base.slack"', config: 'Object value like {"resource": "channel", "operation": "create"} or empty object {}', + mode: 'Optional string: "full" (default) or "minimal"', profile: 'Optional string: "minimal" or "runtime" or "ai-friendly" or "strict"' } }, - - validate_node_minimal: { - description: 'Check required fields. MUST pass: nodeType (string) and config (object). Example: {"nodeType": "nodes-base.webhook", "config": {}}', - params: { - nodeType: 'String like "nodes-base.webhook"', - config: 'Object, use {} for empty' - } - }, - - // Search and info tools + + // Search tool search_nodes: { description: 'Search nodes. Pass query (string). Example: {"query": "webhook"}', params: { @@ -39,98 +32,53 @@ export const n8nFriendlyDescriptions: Record { depth: 'full' }}); - expect(((response as any).content[0]).text.length).toBeGreaterThan(5000); + // Reduced from 5000 after v2.26.0 tool consolidation (31→19 tools) + expect(((response as any).content[0]).text.length).toBeGreaterThan(4000); expect(((response as any).content[0]).text).toBeDefined(); });