n8n-mcp 2.8.1 → 2.9.1

package/dist/mcp/server.js

@@ -44,6 +44,8 @@ const fs_1 = require("fs");
 const path_1 = __importDefault(require("path"));
 const tools_1 = require("./tools");
 const tools_n8n_manager_1 = require("./tools-n8n-manager");
+const tools_n8n_friendly_1 = require("./tools-n8n-friendly");
+const workflow_examples_1 = require("./workflow-examples");
 const logger_1 = require("../utils/logger");
 const node_repository_1 = require("../database/node-repository");
 const database_adapter_1 = require("../database/database-adapter");
@@ -60,12 +62,14 @@ const handlers_workflow_diff_1 = require("./handlers-workflow-diff");
 const tools_documentation_1 = require("./tools-documentation");
 const version_1 = require("../utils/version");
 const node_utils_1 = require("../utils/node-utils");
+const protocol_version_1 = require("../utils/protocol-version");
 class N8NDocumentationMCPServer {
     constructor() {
         this.db = null;
         this.repository = null;
         this.templateService = null;
         this.cache = new simple_cache_1.SimpleCache();
+        this.clientInfo = null;
         const envDbPath = process.env.NODE_DB_PATH;
         let dbPath = null;
         let possiblePaths = [];
@@ -140,9 +144,25 @@ class N8NDocumentationMCPServer {
         }
     }
     setupHandlers() {
-        this.server.setRequestHandler(types_js_1.InitializeRequestSchema, async () => {
+        this.server.setRequestHandler(types_js_1.InitializeRequestSchema, async (request) => {
+            const clientVersion = request.params.protocolVersion;
+            const clientCapabilities = request.params.capabilities;
+            const clientInfo = request.params.clientInfo;
+            logger_1.logger.info('MCP Initialize request received', {
+                clientVersion,
+                clientCapabilities,
+                clientInfo
+            });
+            this.clientInfo = clientInfo;
+            const negotiationResult = (0, protocol_version_1.negotiateProtocolVersion)(clientVersion, clientInfo, undefined, undefined);
+            (0, protocol_version_1.logProtocolNegotiation)(negotiationResult, logger_1.logger, 'MCP_INITIALIZE');
+            if (clientVersion && clientVersion !== negotiationResult.version) {
+                logger_1.logger.warn(`Protocol version negotiated: client requested ${clientVersion}, server will use ${negotiationResult.version}`, {
+                    reasoning: negotiationResult.reasoning
+                });
+            }
             const response = {
-                protocolVersion: '2024-11-05',
+                protocolVersion: negotiationResult.version,
                 capabilities: {
                     tools: {},
                 },
@@ -151,13 +171,11 @@ class N8NDocumentationMCPServer {
                     version: version_1.PROJECT_VERSION,
                 },
             };
-            if (process.env.DEBUG_MCP === 'true') {
-                logger_1.logger.debug('Initialize handler called', { response });
-            }
+            logger_1.logger.info('MCP Initialize response', { response });
             return response;
         });
-        this.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
-            const tools = [...tools_1.n8nDocumentationToolsFinal];
+        this.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async (request) => {
+            let tools = [...tools_1.n8nDocumentationToolsFinal];
             const isConfigured = (0, n8n_api_1.isN8nApiConfigured)();
             if (isConfigured) {
                 tools.push(...tools_n8n_manager_1.n8nManagementTools);
@@ -166,30 +184,124 @@ class N8NDocumentationMCPServer {
             else {
                 logger_1.logger.debug(`Tool listing: ${tools.length} tools available (documentation only)`);
             }
+            const clientInfo = this.clientInfo;
+            const isN8nClient = clientInfo?.name?.includes('n8n') ||
+                clientInfo?.name?.includes('langchain');
+            if (isN8nClient) {
+                logger_1.logger.info('Detected n8n client, using n8n-friendly tool descriptions');
+                tools = (0, tools_n8n_friendly_1.makeToolsN8nFriendly)(tools);
+            }
+            const validationTools = tools.filter(t => t.name.startsWith('validate_'));
+            validationTools.forEach(tool => {
+                logger_1.logger.info('Validation tool schema', {
+                    toolName: tool.name,
+                    inputSchema: JSON.stringify(tool.inputSchema, null, 2),
+                    hasOutputSchema: !!tool.outputSchema,
+                    description: tool.description
+                });
+            });
             return { tools };
         });
         this.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
             const { name, arguments: args } = request.params;
+            logger_1.logger.info('Tool call received - DETAILED DEBUG', {
+                toolName: name,
+                arguments: JSON.stringify(args, null, 2),
+                argumentsType: typeof args,
+                argumentsKeys: args ? Object.keys(args) : [],
+                hasNodeType: args && 'nodeType' in args,
+                hasConfig: args && 'config' in args,
+                configType: args && args.config ? typeof args.config : 'N/A',
+                rawRequest: JSON.stringify(request.params)
+            });
+            let processedArgs = args;
+            if (args && typeof args === 'object' && 'output' in args) {
+                try {
+                    const possibleNestedData = args.output;
+                    if (typeof possibleNestedData === 'string' && possibleNestedData.trim().startsWith('{')) {
+                        const parsed = JSON.parse(possibleNestedData);
+                        if (parsed && typeof parsed === 'object') {
+                            logger_1.logger.warn('Detected n8n nested output bug, attempting to extract actual arguments', {
+                                originalArgs: args,
+                                extractedArgs: parsed
+                            });
+                            if (this.validateExtractedArgs(name, parsed)) {
+                                processedArgs = parsed;
+                            }
+                            else {
+                                logger_1.logger.warn('Extracted arguments failed validation, using original args', {
+                                    toolName: name,
+                                    extractedArgs: parsed
+                                });
+                            }
+                        }
+                    }
+                }
+                catch (parseError) {
+                    logger_1.logger.debug('Failed to parse nested output, continuing with original args', {
+                        error: parseError instanceof Error ? parseError.message : String(parseError)
+                    });
+                }
+            }
             try {
-                logger_1.logger.debug(`Executing tool: ${name}`, { args });
-                const result = await this.executeTool(name, args);
+                logger_1.logger.debug(`Executing tool: ${name}`, { args: processedArgs });
+                const result = await this.executeTool(name, processedArgs);
                 logger_1.logger.debug(`Tool ${name} executed successfully`);
-                return {
+                let responseText;
+                let structuredContent = null;
+                try {
+                    if (name.startsWith('validate_') && typeof result === 'object' && result !== null) {
+                        const cleanResult = this.sanitizeValidationResult(result, name);
+                        structuredContent = cleanResult;
+                        responseText = JSON.stringify(cleanResult, null, 2);
+                    }
+                    else {
+                        responseText = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+                    }
+                }
+                catch (jsonError) {
+                    logger_1.logger.warn(`Failed to stringify tool result for ${name}:`, jsonError);
+                    responseText = String(result);
+                }
+                if (responseText.length > 1000000) {
+                    logger_1.logger.warn(`Tool ${name} response is very large (${responseText.length} chars), truncating`);
+                    responseText = responseText.substring(0, 999000) + '\n\n[Response truncated due to size limits]';
+                    structuredContent = null;
+                }
+                const mcpResponse = {
                     content: [
                         {
                             type: 'text',
-                            text: JSON.stringify(result, null, 2),
+                            text: responseText,
                         },
                     ],
                 };
+                if (name.startsWith('validate_') && structuredContent !== null) {
+                    mcpResponse.structuredContent = structuredContent;
+                }
+                return mcpResponse;
             }
             catch (error) {
                 logger_1.logger.error(`Error executing tool ${name}`, error);
+                const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+                let helpfulMessage = `Error executing tool ${name}: ${errorMessage}`;
+                if (errorMessage.includes('required') || errorMessage.includes('missing')) {
+                    helpfulMessage += '\n\nNote: This error often occurs when the AI agent sends incomplete or incorrectly formatted parameters. Please ensure all required fields are provided with the correct types.';
+                }
+                else if (errorMessage.includes('type') || errorMessage.includes('expected')) {
+                    helpfulMessage += '\n\nNote: This error indicates a type mismatch. The AI agent may be sending data in the wrong format (e.g., string instead of object).';
+                }
+                else if (errorMessage.includes('Unknown category') || errorMessage.includes('not found')) {
+                    helpfulMessage += '\n\nNote: The requested resource or category was not found. Please check the available options.';
+                }
+                if (name.startsWith('validate_') && (errorMessage.includes('config') || errorMessage.includes('nodeType'))) {
+                    helpfulMessage += '\n\nFor validation tools:\n- nodeType should be a string (e.g., "nodes-base.webhook")\n- config should be an object (e.g., {})';
+                }
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `Error executing tool ${name}: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                            text: helpfulMessage,
                         },
                     ],
                     isError: true,
@@ -197,82 +309,291 @@ class N8NDocumentationMCPServer {
             }
         });
     }
+    sanitizeValidationResult(result, toolName) {
+        if (!result || typeof result !== 'object') {
+            return result;
+        }
+        const sanitized = { ...result };
+        if (toolName === 'validate_node_minimal') {
+            const filtered = {
+                nodeType: String(sanitized.nodeType || ''),
+                displayName: String(sanitized.displayName || ''),
+                valid: Boolean(sanitized.valid),
+                missingRequiredFields: Array.isArray(sanitized.missingRequiredFields)
+                    ? sanitized.missingRequiredFields.map(String)
+                    : []
+            };
+            return filtered;
+        }
+        else if (toolName === 'validate_node_operation') {
+            let summary = sanitized.summary;
+            if (!summary || typeof summary !== 'object') {
+                summary = {
+                    hasErrors: Array.isArray(sanitized.errors) ? sanitized.errors.length > 0 : false,
+                    errorCount: Array.isArray(sanitized.errors) ? sanitized.errors.length : 0,
+                    warningCount: Array.isArray(sanitized.warnings) ? sanitized.warnings.length : 0,
+                    suggestionCount: Array.isArray(sanitized.suggestions) ? sanitized.suggestions.length : 0
+                };
+            }
+            const filtered = {
+                nodeType: String(sanitized.nodeType || ''),
+                workflowNodeType: String(sanitized.workflowNodeType || sanitized.nodeType || ''),
+                displayName: String(sanitized.displayName || ''),
+                valid: Boolean(sanitized.valid),
+                errors: Array.isArray(sanitized.errors) ? sanitized.errors : [],
+                warnings: Array.isArray(sanitized.warnings) ? sanitized.warnings : [],
+                suggestions: Array.isArray(sanitized.suggestions) ? sanitized.suggestions : [],
+                summary: summary
+            };
+            return filtered;
+        }
+        else if (toolName.startsWith('validate_workflow')) {
+            sanitized.valid = Boolean(sanitized.valid);
+            sanitized.errors = Array.isArray(sanitized.errors) ? sanitized.errors : [];
+            sanitized.warnings = Array.isArray(sanitized.warnings) ? sanitized.warnings : [];
+            if (toolName === 'validate_workflow') {
+                if (!sanitized.summary || typeof sanitized.summary !== 'object') {
+                    sanitized.summary = {
+                        totalNodes: 0,
+                        enabledNodes: 0,
+                        triggerNodes: 0,
+                        validConnections: 0,
+                        invalidConnections: 0,
+                        expressionsValidated: 0,
+                        errorCount: sanitized.errors.length,
+                        warningCount: sanitized.warnings.length
+                    };
+                }
+            }
+            else {
+                if (!sanitized.statistics || typeof sanitized.statistics !== 'object') {
+                    sanitized.statistics = {
+                        totalNodes: 0,
+                        triggerNodes: 0,
+                        validConnections: 0,
+                        invalidConnections: 0,
+                        expressionsValidated: 0
+                    };
+                }
+            }
+        }
+        return JSON.parse(JSON.stringify(sanitized));
+    }
+    validateToolParams(toolName, args, requiredParams) {
+        const missing = [];
+        for (const param of requiredParams) {
+            if (!(param in args) || args[param] === undefined || args[param] === null) {
+                missing.push(param);
+            }
+        }
+        if (missing.length > 0) {
+            throw new Error(`Missing required parameters for ${toolName}: ${missing.join(', ')}. Please provide the required parameters to use this tool.`);
+        }
+    }
+    validateExtractedArgs(toolName, args) {
+        if (!args || typeof args !== 'object') {
+            return false;
+        }
+        const allTools = [...tools_1.n8nDocumentationToolsFinal, ...tools_n8n_manager_1.n8nManagementTools];
+        const tool = allTools.find(t => t.name === toolName);
+        if (!tool || !tool.inputSchema) {
+            return true;
+        }
+        const schema = tool.inputSchema;
+        const required = schema.required || [];
+        const properties = schema.properties || {};
+        for (const requiredField of required) {
+            if (!(requiredField in args)) {
+                logger_1.logger.debug(`Extracted args missing required field: ${requiredField}`, {
+                    toolName,
+                    extractedArgs: args,
+                    required
+                });
+                return false;
+            }
+        }
+        for (const [fieldName, fieldValue] of Object.entries(args)) {
+            if (properties[fieldName]) {
+                const expectedType = properties[fieldName].type;
+                const actualType = Array.isArray(fieldValue) ? 'array' : typeof fieldValue;
+                if (expectedType && expectedType !== actualType) {
+                    if (expectedType === 'number' && actualType === 'string' && !isNaN(Number(fieldValue))) {
+                        continue;
+                    }
+                    logger_1.logger.debug(`Extracted args field type mismatch: ${fieldName}`, {
+                        toolName,
+                        expectedType,
+                        actualType,
+                        fieldValue
+                    });
+                    return false;
+                }
+            }
+        }
+        if (schema.additionalProperties === false) {
+            const allowedFields = Object.keys(properties);
+            const extraFields = Object.keys(args).filter(field => !allowedFields.includes(field));
+            if (extraFields.length > 0) {
+                logger_1.logger.debug(`Extracted args have extra fields`, {
+                    toolName,
+                    extraFields,
+                    allowedFields
+                });
+            }
+        }
+        return true;
+    }
     async executeTool(name, args) {
+        args = args || {};
+        logger_1.logger.info(`Tool execution: ${name}`, {
+            args: typeof args === 'object' ? JSON.stringify(args) : args,
+            argsType: typeof args,
+            argsKeys: typeof args === 'object' ? Object.keys(args) : 'not-object'
+        });
+        if (typeof args !== 'object' || args === null) {
+            throw new Error(`Invalid arguments for tool ${name}: expected object, got ${typeof args}`);
+        }
         switch (name) {
             case 'tools_documentation':
                 return this.getToolsDocumentation(args.topic, args.depth);
             case 'list_nodes':
                 return this.listNodes(args);
             case 'get_node_info':
+                this.validateToolParams(name, args, ['nodeType']);
                 return this.getNodeInfo(args.nodeType);
             case 'search_nodes':
-                return this.searchNodes(args.query, args.limit, { mode: args.mode });
+                this.validateToolParams(name, args, ['query']);
+                const limit = args.limit !== undefined ? Number(args.limit) || 20 : 20;
+                return this.searchNodes(args.query, limit, { mode: args.mode });
             case 'list_ai_tools':
                 return this.listAITools();
             case 'get_node_documentation':
+                this.validateToolParams(name, args, ['nodeType']);
                 return this.getNodeDocumentation(args.nodeType);
             case 'get_database_statistics':
                 return this.getDatabaseStatistics();
             case 'get_node_essentials':
+                this.validateToolParams(name, args, ['nodeType']);
                 return this.getNodeEssentials(args.nodeType);
             case 'search_node_properties':
-                return this.searchNodeProperties(args.nodeType, args.query, args.maxResults);
+                this.validateToolParams(name, args, ['nodeType', 'query']);
+                const maxResults = args.maxResults !== undefined ? Number(args.maxResults) || 20 : 20;
+                return this.searchNodeProperties(args.nodeType, args.query, maxResults);
             case 'get_node_for_task':
+                this.validateToolParams(name, args, ['task']);
                 return this.getNodeForTask(args.task);
             case 'list_tasks':
                 return this.listTasks(args.category);
             case 'validate_node_operation':
+                this.validateToolParams(name, args, ['nodeType', 'config']);
+                if (typeof args.config !== 'object' || args.config === null) {
+                    logger_1.logger.warn(`validate_node_operation called with invalid config type: ${typeof args.config}`);
+                    return {
+                        nodeType: args.nodeType || 'unknown',
+                        workflowNodeType: args.nodeType || 'unknown',
+                        displayName: 'Unknown Node',
+                        valid: false,
+                        errors: [{
+                                type: 'config',
+                                property: 'config',
+                                message: 'Invalid config format - expected object',
+                                fix: 'Provide config as an object with node properties'
+                            }],
+                        warnings: [],
+                        suggestions: [],
+                        summary: {
+                            hasErrors: true,
+                            errorCount: 1,
+                            warningCount: 0,
+                            suggestionCount: 0
+                        }
+                    };
+                }
                 return this.validateNodeConfig(args.nodeType, args.config, 'operation', args.profile);
             case 'validate_node_minimal':
+                this.validateToolParams(name, args, ['nodeType', 'config']);
+                if (typeof args.config !== 'object' || args.config === null) {
+                    logger_1.logger.warn(`validate_node_minimal called with invalid config type: ${typeof args.config}`);
+                    return {
+                        nodeType: args.nodeType || 'unknown',
+                        displayName: 'Unknown Node',
+                        valid: false,
+                        missingRequiredFields: ['Invalid config format - expected object']
+                    };
+                }
                 return this.validateNodeMinimal(args.nodeType, args.config);
             case 'get_property_dependencies':
+                this.validateToolParams(name, args, ['nodeType']);
                 return this.getPropertyDependencies(args.nodeType, args.config);
             case 'get_node_as_tool_info':
+                this.validateToolParams(name, args, ['nodeType']);
                 return this.getNodeAsToolInfo(args.nodeType);
             case 'list_node_templates':
-                return this.listNodeTemplates(args.nodeTypes, args.limit);
+                this.validateToolParams(name, args, ['nodeTypes']);
+                const templateLimit = args.limit !== undefined ? Number(args.limit) || 10 : 10;
+                return this.listNodeTemplates(args.nodeTypes, templateLimit);
             case 'get_template':
-                return this.getTemplate(args.templateId);
+                this.validateToolParams(name, args, ['templateId']);
+                const templateId = Number(args.templateId);
+                return this.getTemplate(templateId);
             case 'search_templates':
-                return this.searchTemplates(args.query, args.limit);
+                this.validateToolParams(name, args, ['query']);
+                const searchLimit = args.limit !== undefined ? Number(args.limit) || 20 : 20;
+                return this.searchTemplates(args.query, searchLimit);
             case 'get_templates_for_task':
+                this.validateToolParams(name, args, ['task']);
                 return this.getTemplatesForTask(args.task);
             case 'validate_workflow':
+                this.validateToolParams(name, args, ['workflow']);
                 return this.validateWorkflow(args.workflow, args.options);
             case 'validate_workflow_connections':
+                this.validateToolParams(name, args, ['workflow']);
                 return this.validateWorkflowConnections(args.workflow);
             case 'validate_workflow_expressions':
+                this.validateToolParams(name, args, ['workflow']);
                 return this.validateWorkflowExpressions(args.workflow);
             case 'n8n_create_workflow':
+                this.validateToolParams(name, args, ['name', 'nodes', 'connections']);
                 return n8nHandlers.handleCreateWorkflow(args);
             case 'n8n_get_workflow':
+                this.validateToolParams(name, args, ['id']);
                 return n8nHandlers.handleGetWorkflow(args);
             case 'n8n_get_workflow_details':
+                this.validateToolParams(name, args, ['id']);
                 return n8nHandlers.handleGetWorkflowDetails(args);
             case 'n8n_get_workflow_structure':
+                this.validateToolParams(name, args, ['id']);
                 return n8nHandlers.handleGetWorkflowStructure(args);
             case 'n8n_get_workflow_minimal':
+                this.validateToolParams(name, args, ['id']);
                 return n8nHandlers.handleGetWorkflowMinimal(args);
             case 'n8n_update_full_workflow':
+                this.validateToolParams(name, args, ['id']);
                 return n8nHandlers.handleUpdateWorkflow(args);
             case 'n8n_update_partial_workflow':
+                this.validateToolParams(name, args, ['id', 'operations']);
                 return (0, handlers_workflow_diff_1.handleUpdatePartialWorkflow)(args);
             case 'n8n_delete_workflow':
+                this.validateToolParams(name, args, ['id']);
                 return n8nHandlers.handleDeleteWorkflow(args);
             case 'n8n_list_workflows':
                 return n8nHandlers.handleListWorkflows(args);
             case 'n8n_validate_workflow':
+                this.validateToolParams(name, args, ['id']);
                 await this.ensureInitialized();
                 if (!this.repository)
                     throw new Error('Repository not initialized');
                 return n8nHandlers.handleValidateWorkflow(args, this.repository);
             case 'n8n_trigger_webhook_workflow':
+                this.validateToolParams(name, args, ['webhookUrl']);
                 return n8nHandlers.handleTriggerWebhookWorkflow(args);
             case 'n8n_get_execution':
+                this.validateToolParams(name, args, ['id']);
                 return n8nHandlers.handleGetExecution(args);
             case 'n8n_list_executions':
                 return n8nHandlers.handleListExecutions(args);
             case 'n8n_delete_execution':
+                this.validateToolParams(name, args, ['id']);
                 return n8nHandlers.handleDeleteExecution(args);
             case 'n8n_health_check':
                 return n8nHandlers.handleHealthCheck();
@@ -1463,6 +1784,50 @@ Full documentation is being prepared. For now, use get_node_essentials for confi
         await this.ensureInitialized();
         if (!this.repository)
             throw new Error('Repository not initialized');
+        logger_1.logger.info('Workflow validation requested', {
+            hasWorkflow: !!workflow,
+            workflowType: typeof workflow,
+            hasNodes: workflow?.nodes !== undefined,
+            nodesType: workflow?.nodes ? typeof workflow.nodes : 'undefined',
+            nodesIsArray: Array.isArray(workflow?.nodes),
+            nodesCount: Array.isArray(workflow?.nodes) ? workflow.nodes.length : 0,
+            hasConnections: workflow?.connections !== undefined,
+            connectionsType: workflow?.connections ? typeof workflow.connections : 'undefined',
+            options: options
+        });
+        if (!workflow || typeof workflow !== 'object') {
+            return {
+                valid: false,
+                errors: [{
+                        node: 'workflow',
+                        message: 'Workflow must be an object with nodes and connections',
+                        details: 'Expected format: ' + (0, workflow_examples_1.getWorkflowExampleString)()
+                    }],
+                summary: { errorCount: 1 }
+            };
+        }
+        if (!workflow.nodes || !Array.isArray(workflow.nodes)) {
+            return {
+                valid: false,
+                errors: [{
+                        node: 'workflow',
+                        message: 'Workflow must have a nodes array',
+                        details: 'Expected: workflow.nodes = [array of node objects]. ' + (0, workflow_examples_1.getWorkflowExampleString)()
+                    }],
+                summary: { errorCount: 1 }
+            };
+        }
+        if (!workflow.connections || typeof workflow.connections !== 'object') {
+            return {
+                valid: false,
+                errors: [{
+                        node: 'workflow',
+                        message: 'Workflow must have a connections object',
+                        details: 'Expected: workflow.connections = {} (can be empty object). ' + (0, workflow_examples_1.getWorkflowExampleString)()
+                    }],
+                summary: { errorCount: 1 }
+            };
+        }
         const validator = new workflow_validator_1.WorkflowValidator(this.repository, enhanced_config_validator_1.EnhancedConfigValidator);
         try {
             const result = await validator.validateWorkflow(workflow, options);