n8n-MCP

Instructions

Implementation Reference

• dist/mcp-tools-engine.js:84-86 (handler)

  MCP tool handler: receives tool arguments and delegates to WorkflowValidator for execution.
  async validateWorkflow(args) { return this.workflowValidator.validateWorkflow(args.workflow, args.options); }
• dist/services/workflow-validator.js:26-102 (helper)

  Core implementation: performs structure validation, node validation, connection checks, expression validation, AI node checks, cycle detection, pattern analysis, and generates suggestions.
  async validateWorkflow(workflow, options = {}) { this.currentWorkflow = workflow; const { validateNodes = true, validateConnections = true, validateExpressions = true, profile = 'runtime' } = options; const result = { valid: true, errors: [], warnings: [], statistics: { totalNodes: 0, enabledNodes: 0, triggerNodes: 0, validConnections: 0, invalidConnections: 0, expressionsValidated: 0, }, suggestions: [] }; try { if (!workflow) { result.errors.push({ type: 'error', message: 'Invalid workflow structure: workflow is null or undefined' }); result.valid = false; return result; } const executableNodes = Array.isArray(workflow.nodes) ? workflow.nodes.filter(n => !(0, node_classification_1.isNonExecutableNode)(n.type)) : []; result.statistics.totalNodes = executableNodes.length; result.statistics.enabledNodes = executableNodes.filter(n => !n.disabled).length; this.validateWorkflowStructure(workflow, result); if (workflow.nodes && Array.isArray(workflow.nodes) && workflow.connections && typeof workflow.connections === 'object') { if (validateNodes && workflow.nodes.length > 0) { await this.validateAllNodes(workflow, result, profile); } if (validateConnections) { this.validateConnections(workflow, result, profile); } if (validateExpressions && workflow.nodes.length > 0) { this.validateExpressions(workflow, result, profile); } if (workflow.nodes.length > 0) { this.checkWorkflowPatterns(workflow, result, profile); } if (workflow.nodes.length > 0 && (0, ai_node_validator_1.hasAINodes)(workflow)) { const aiIssues = (0, ai_node_validator_1.validateAISpecificNodes)(workflow); for (const issue of aiIssues) { const 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); } } } this.generateSuggestions(workflow, result); 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/tool-docs/validation/validate-workflow.ts:3-84 (schema)

  ToolDocumentation: detailed schema definition, input/output parameters, examples, performance notes, best practices, and related tools.
  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'] } };
• dist/mcp/tools.js:297-382 (registration)

  Tool definition registration: inputSchema and outputSchema used by MCP server for tool registration and validation.
  { 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'] }, }, ];