n8n-MCP

Instructions

Implementation Reference

• src/services/workflow-validator.ts:97-212 (handler)

  Core handler implementing the full 'validate_workflow' logic: validates structure, nodes, connections, expressions, AI nodes, generates suggestions and statistics.
  async validateWorkflow( workflow: WorkflowJson, options: { validateNodes?: boolean; validateConnections?: boolean; validateExpressions?: boolean; profile?: 'minimal' | 'runtime' | 'ai-friendly' | 'strict'; } = {} ): Promise<WorkflowValidationResult> { // Store current workflow for access in helper methods this.currentWorkflow = workflow; const { validateNodes = true, validateConnections = true, validateExpressions = true, profile = 'runtime' } = options; const result: WorkflowValidationResult = { valid: true, errors: [], warnings: [], statistics: { totalNodes: 0, enabledNodes: 0, triggerNodes: 0, validConnections: 0, invalidConnections: 0, expressionsValidated: 0, }, suggestions: [] }; try { // Handle null/undefined workflow if (!workflow) { result.errors.push({ type: 'error', message: 'Invalid workflow structure: workflow is null or undefined' }); result.valid = false; return result; } // Update statistics after null check (exclude sticky notes from counts) const executableNodes = Array.isArray(workflow.nodes) ? workflow.nodes.filter(n => !isNonExecutableNode(n.type)) : []; result.statistics.totalNodes = executableNodes.length; result.statistics.enabledNodes = executableNodes.filter(n => !n.disabled).length; // Basic workflow structure validation this.validateWorkflowStructure(workflow, result); // Only continue if basic structure is valid if (workflow.nodes && Array.isArray(workflow.nodes) && workflow.connections && typeof workflow.connections === 'object') { // Validate each node if requested if (validateNodes && workflow.nodes.length > 0) { await this.validateAllNodes(workflow, result, profile); } // Validate connections if requested if (validateConnections) { this.validateConnections(workflow, result, profile); } // Validate expressions if requested if (validateExpressions && workflow.nodes.length > 0) { this.validateExpressions(workflow, result, profile); } // Check workflow patterns and best practices if (workflow.nodes.length > 0) { this.checkWorkflowPatterns(workflow, result, profile); } // Validate AI-specific nodes (AI Agent, Chat Trigger, AI tools) if (workflow.nodes.length > 0 && hasAINodes(workflow)) { const aiIssues = validateAISpecificNodes(workflow); // Convert AI validation issues to workflow validation format for (const issue of aiIssues) { const validationIssue: ValidationIssue = { type: issue.severity === 'error' ? 'error' : 'warning', nodeId: issue.nodeId, nodeName: issue.nodeName, message: issue.message, details: issue.code ? { code: issue.code } : undefined }; if (issue.severity === 'error') { result.errors.push(validationIssue); } else { result.warnings.push(validationIssue); } } } // Add suggestions based on findings this.generateSuggestions(workflow, result); // Add AI-specific recovery suggestions if there are errors if (result.errors.length > 0) { this.addErrorRecoverySuggestions(result); } } } catch (error) { logger.error('Error validating workflow:', error); result.errors.push({ type: 'error', message: `Workflow validation failed: ${error instanceof Error ? error.message : 'Unknown error'}` }); } result.valid = result.errors.length === 0; return result; }
• src/mcp-tools-engine.ts:110-112 (handler)

  MCP engine handler method for 'validate_workflow' tool that receives args and delegates to WorkflowValidator.
  async validateWorkflow(args: any): Promise<WorkflowValidationResult> { return this.workflowValidator.validateWorkflow(args.workflow, args.options); }
• src/mcp/tools.ts:308-391 (registration)

  Tool registration/definition with inputSchema and outputSchema used for MCP tool registration.
  name: 'validate_workflow', description: `Full workflow validation: structure, connections, expressions, AI tools. Returns errors/warnings/fixes. Essential before deploy.`, inputSchema: { type: 'object', properties: { workflow: { type: 'object', description: 'The complete workflow JSON to validate. Must include nodes array and connections object.', }, options: { type: 'object', properties: { validateNodes: { type: 'boolean', description: 'Validate individual node configurations. Default true.', default: true, }, validateConnections: { type: 'boolean', description: 'Validate node connections and flow. Default true.', default: true, }, validateExpressions: { type: 'boolean', description: 'Validate n8n expressions syntax and references. Default true.', default: true, }, profile: { type: 'string', enum: ['minimal', 'runtime', 'ai-friendly', 'strict'], description: 'Validation profile for node validation. Default "runtime".', default: 'runtime', }, }, description: 'Optional validation settings', }, }, required: ['workflow'], additionalProperties: false, }, outputSchema: { type: 'object', properties: { valid: { type: 'boolean' }, summary: { type: 'object', properties: { totalNodes: { type: 'number' }, enabledNodes: { type: 'number' }, triggerNodes: { type: 'number' }, validConnections: { type: 'number' }, invalidConnections: { type: 'number' }, expressionsValidated: { type: 'number' }, errorCount: { type: 'number' }, warningCount: { type: 'number' } } }, errors: { type: 'array', items: { type: 'object', properties: { node: { type: 'string' }, message: { type: 'string' }, details: { type: 'string' } } } }, warnings: { type: 'array', items: { type: 'object', properties: { node: { type: 'string' }, message: { type: 'string' }, details: { type: 'string' } } } }, suggestions: { type: 'array', items: { type: 'string' } } }, required: ['valid', 'summary'] }, },
• src/mcp/tool-docs/validation/validate-workflow.ts:3-84 (schema)

  Detailed tool documentation and schema including parameters, examples, best practices, pitfalls.
  export const validateWorkflowDoc: ToolDocumentation = { name: 'validate_workflow', category: 'validation', essentials: { description: 'Full workflow validation: structure, connections, expressions, AI tools. Returns errors/warnings/fixes. Essential before deploy.', keyParameters: ['workflow', 'options'], example: 'validate_workflow({workflow: {nodes: [...], connections: {...}}})', performance: 'Moderate (100-500ms)', tips: [ 'Always validate before n8n_create_workflow to catch errors early', 'Use options.profile="minimal" for quick checks during development', 'AI tool connections are automatically validated for proper node references', 'Detects operator structure issues (binary vs unary, singleValue requirements)' ] }, full: { description: 'Performs comprehensive validation of n8n workflows including structure, node configurations, connections, and expressions. This is a three-layer validation system that catches errors before deployment, validates complex multi-node workflows, checks all n8n expressions for syntax errors, and ensures proper node connections and data flow.', parameters: { workflow: { type: 'object', required: true, description: 'The complete workflow JSON to validate. Must include nodes array and connections object.' }, options: { type: 'object', required: false, description: 'Validation options object' }, 'options.validateNodes': { type: 'boolean', required: false, description: 'Validate individual node configurations. Default: true' }, 'options.validateConnections': { type: 'boolean', required: false, description: 'Validate node connections and flow. Default: true' }, 'options.validateExpressions': { type: 'boolean', required: false, description: 'Validate n8n expressions syntax and references. Default: true' }, 'options.profile': { type: 'string', required: false, description: 'Validation profile for node validation: minimal, runtime (default), ai-friendly, strict' } }, returns: 'Object with valid (boolean), errors (array), warnings (array), statistics (object), and suggestions (array)', examples: [ 'validate_workflow({workflow: myWorkflow}) - Full validation with default settings', 'validate_workflow({workflow: myWorkflow, options: {profile: "minimal"}}) - Quick validation for editing', 'validate_workflow({workflow: myWorkflow, options: {validateExpressions: false}}) - Skip expression validation' ], useCases: [ 'Pre-deployment validation to catch all workflow issues', 'Quick validation during workflow development', 'Validate workflows with AI Agent nodes and tool connections', 'Check expression syntax before workflow execution', 'Ensure workflow structure integrity after modifications' ], performance: 'Moderate (100-500ms). Depends on workflow size and validation options. Expression validation adds ~50-100ms.', bestPractices: [ 'Always validate workflows before creating or updating in n8n', 'Use minimal profile during development, strict profile before production', 'Pay attention to warnings - they often indicate potential runtime issues', 'Validate after any workflow modifications, especially connection changes', 'Check statistics to understand workflow complexity', '**Auto-sanitization runs during create/update**: Operator structures and missing metadata are automatically fixed when workflows are created or updated, but validation helps catch issues before they reach n8n', 'If validation detects operator issues, they will be auto-fixed during n8n_create_workflow or n8n_update_partial_workflow' ], pitfalls: [ 'Large workflows (100+ nodes) may take longer to validate', 'Expression validation requires proper node references to exist', 'Some warnings may be acceptable depending on use case', 'Validation cannot catch all runtime errors (e.g., API failures)', 'Profile setting only affects node validation, not connection/expression checks' ], relatedTools: ['validate_node', 'n8n_create_workflow', 'n8n_update_partial_workflow', 'n8n_autofix_workflow'] } };