@pagelines/n8n-mcp 0.1.0 → 0.2.0

package/dist/expressions.js

@@ -0,0 +1,209 @@
+/**
+ * n8n expression validation
+ * Parses and validates expressions in workflow parameters
+ */
+/**
+ * Validate all expressions in a workflow
+ */
+export function validateExpressions(workflow) {
+    const issues = [];
+    const nodeNames = new Set(workflow.nodes.map((n) => n.name));
+    for (const node of workflow.nodes) {
+        const nodeIssues = validateNodeExpressions(node, nodeNames);
+        issues.push(...nodeIssues);
+    }
+    return issues;
+}
+/**
+ * Validate expressions in a single node
+ */
+function validateNodeExpressions(node, nodeNames) {
+    const issues = [];
+    const expressions = extractExpressions(node.parameters);
+    for (const { path, expression } of expressions) {
+        const exprIssues = validateExpression(expression, nodeNames);
+        for (const issue of exprIssues) {
+            issues.push({
+                node: node.name,
+                parameter: path,
+                expression,
+                ...issue,
+            });
+        }
+    }
+    return issues;
+}
+/**
+ * Extract all expressions from parameters
+ */
+function extractExpressions(params, basePath = '') {
+    const results = [];
+    for (const [key, value] of Object.entries(params)) {
+        const path = basePath ? `${basePath}.${key}` : key;
+        if (typeof value === 'string') {
+            // Check for expression patterns
+            const exprMatches = value.match(/\{\{.*?\}\}/g) || [];
+            for (const match of exprMatches) {
+                results.push({ path, expression: match });
+            }
+            // Also check for ={{ prefix (common in n8n)
+            if (value.startsWith('={{')) {
+                results.push({ path, expression: value });
+            }
+        }
+        else if (typeof value === 'object' && value !== null) {
+            if (Array.isArray(value)) {
+                for (let i = 0; i < value.length; i++) {
+                    if (typeof value[i] === 'object' && value[i] !== null) {
+                        results.push(...extractExpressions(value[i], `${path}[${i}]`));
+                    }
+                    else if (typeof value[i] === 'string') {
+                        const strVal = value[i];
+                        const exprMatches = strVal.match(/\{\{.*?\}\}/g) || [];
+                        for (const match of exprMatches) {
+                            results.push({ path: `${path}[${i}]`, expression: match });
+                        }
+                    }
+                }
+            }
+            else {
+                results.push(...extractExpressions(value, path));
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Validate a single expression
+ */
+function validateExpression(expression, nodeNames) {
+    const issues = [];
+    // Strip wrapper
+    let inner = expression;
+    if (inner.startsWith('={{')) {
+        inner = inner.slice(3).trim();
+    }
+    else if (inner.startsWith('{{') && inner.endsWith('}}')) {
+        inner = inner.slice(2, -2).trim();
+    }
+    // Check for $json usage (should use explicit reference)
+    if (/\$json\./.test(inner) && !/\$\(['"]/.test(inner)) {
+        issues.push({
+            issue: 'Uses $json instead of explicit node reference',
+            severity: 'warning',
+            suggestion: "Use $('node_name').item.json.field instead",
+        });
+    }
+    // Check for $input usage (acceptable but check context)
+    if (/\$input\./.test(inner)) {
+        issues.push({
+            issue: '$input reference found - ensure this is intentional',
+            severity: 'info',
+            suggestion: "Consider explicit $('node_name') for clarity",
+        });
+    }
+    // Check for node references that don't exist
+    const nodeRefMatches = inner.matchAll(/\$\(['"]([^'"]+)['"]\)/g);
+    for (const match of nodeRefMatches) {
+        const refNodeName = match[1];
+        if (!nodeNames.has(refNodeName)) {
+            issues.push({
+                issue: `References non-existent node "${refNodeName}"`,
+                severity: 'error',
+                suggestion: `Check if the node exists or was renamed`,
+            });
+        }
+    }
+    // Check for common syntax errors
+    if (expression.includes('{{') && !expression.includes('}}')) {
+        issues.push({
+            issue: 'Missing closing }}',
+            severity: 'error',
+        });
+    }
+    // Check for unmatched parentheses
+    const openParens = (inner.match(/\(/g) || []).length;
+    const closeParens = (inner.match(/\)/g) || []).length;
+    if (openParens !== closeParens) {
+        issues.push({
+            issue: 'Unmatched parentheses',
+            severity: 'error',
+        });
+    }
+    // Check for unmatched brackets
+    const openBrackets = (inner.match(/\[/g) || []).length;
+    const closeBrackets = (inner.match(/\]/g) || []).length;
+    if (openBrackets !== closeBrackets) {
+        issues.push({
+            issue: 'Unmatched brackets',
+            severity: 'error',
+        });
+    }
+    // Check for deprecated patterns
+    if (/\$node\./.test(inner)) {
+        issues.push({
+            issue: '$node is deprecated',
+            severity: 'warning',
+            suggestion: "Use $('node_name') instead",
+        });
+    }
+    // Check for potential undefined access
+    if (/\.json\.[a-zA-Z_]+\.[a-zA-Z_]+/.test(inner) && !/\?\./g.test(inner)) {
+        issues.push({
+            issue: 'Deep property access without optional chaining',
+            severity: 'info',
+            suggestion: 'Consider using ?. for safer access: obj?.nested?.field',
+        });
+    }
+    return issues;
+}
+/**
+ * Get all referenced nodes from expressions
+ */
+export function getReferencedNodes(workflow) {
+    const references = new Map();
+    for (const node of workflow.nodes) {
+        const expressions = extractExpressions(node.parameters);
+        const refsForNode = [];
+        for (const { expression } of expressions) {
+            const matches = expression.matchAll(/\$\(['"]([^'"]+)['"]\)/g);
+            for (const match of matches) {
+                const refName = match[1];
+                if (!refsForNode.includes(refName)) {
+                    refsForNode.push(refName);
+                }
+            }
+        }
+        if (refsForNode.length > 0) {
+            references.set(node.name, refsForNode);
+        }
+    }
+    return references;
+}
+/**
+ * Check for circular references in expressions
+ */
+export function checkCircularReferences(workflow) {
+    const references = getReferencedNodes(workflow);
+    const cycles = [];
+    function findCycle(start, path = []) {
+        if (path.includes(start)) {
+            const cycleStart = path.indexOf(start);
+            cycles.push([...path.slice(cycleStart), start]);
+            return;
+        }
+        const refs = references.get(start) || [];
+        for (const ref of refs) {
+            findCycle(ref, [...path, start]);
+        }
+    }
+    for (const nodeName of references.keys()) {
+        findCycle(nodeName);
+    }
+    // Deduplicate cycles
+    const uniqueCycles = cycles.filter((cycle, index) => {
+        const key = [...cycle].sort().join(',');
+        return cycles.findIndex((c) => [...c].sort().join(',') === key) === index;
+    });
+    return uniqueCycles;
+}

package/dist/index.js

@@ -9,6 +9,9 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { N8nClient } from './n8n-client.js';
 import { tools } from './tools.js';
 import { validateWorkflow } from './validators.js';
+import { validateExpressions, checkCircularReferences } from './expressions.js';
+import { autofixWorkflow, formatWorkflow } from './autofix.js';
+import { initVersionControl, saveVersion, listVersions, getVersion, diffWorkflows, getVersionStats, } from './versions.js';
 // ─────────────────────────────────────────────────────────────
 // Configuration
 // ─────────────────────────────────────────────────────────────
@@ -23,6 +26,11 @@ const client = new N8nClient({
     apiUrl: N8N_API_URL,
     apiKey: N8N_API_KEY,
 });
+// Initialize version control
+initVersionControl({
+    enabled: process.env.N8N_MCP_VERSIONS !== 'false',
+    maxVersions: parseInt(process.env.N8N_MCP_MAX_VERSIONS || '20', 10),
+});
 // ─────────────────────────────────────────────────────────────
 // MCP Server
 // ─────────────────────────────────────────────────────────────
@@ -114,6 +122,9 @@ async function handleTool(name, args) {
             };
         }
         case 'workflow_update': {
+            // Save version before updating
+            const currentWorkflow = await client.getWorkflow(args.id);
+            const versionSaved = await saveVersion(currentWorkflow, 'before_update');
             const operations = args.operations;
             const { workflow, warnings } = await client.patchWorkflow(args.id, operations);
             // Also run validation
@@ -122,6 +133,7 @@ async function handleTool(name, args) {
                 workflow,
                 patchWarnings: warnings,
                 validation,
+                versionSaved: versionSaved ? versionSaved.id : null,
             };
         }
         case 'workflow_delete': {
@@ -164,16 +176,127 @@ async function handleTool(name, args) {
             const execution = await client.getExecution(args.id);
             return execution;
         }
-        // Validation
+        // Validation & Quality
         case 'workflow_validate': {
             const workflow = await client.getWorkflow(args.id);
             const validation = validateWorkflow(workflow);
+            const expressionIssues = validateExpressions(workflow);
+            const circularRefs = checkCircularReferences(workflow);
             return {
                 workflowId: workflow.id,
                 workflowName: workflow.name,
                 ...validation,
+                expressionIssues,
+                circularReferences: circularRefs.length > 0 ? circularRefs : null,
+            };
+        }
+        case 'workflow_autofix': {
+            const workflow = await client.getWorkflow(args.id);
+            const validation = validateWorkflow(workflow);
+            const result = autofixWorkflow(workflow, validation.warnings);
+            if (args.apply && result.fixes.length > 0) {
+                // Save version before applying fixes
+                await saveVersion(workflow, 'before_autofix');
+                // Apply the fixed workflow
+                await client.updateWorkflow(args.id, result.workflow);
+                return {
+                    applied: true,
+                    fixes: result.fixes,
+                    unfixable: result.unfixable,
+                    workflow: result.workflow,
+                };
+            }
+            return {
+                applied: false,
+                fixes: result.fixes,
+                unfixable: result.unfixable,
+                previewWorkflow: result.workflow,
             };
         }
+        case 'workflow_format': {
+            const workflow = await client.getWorkflow(args.id);
+            const formatted = formatWorkflow(workflow);
+            if (args.apply) {
+                await saveVersion(workflow, 'before_format');
+                await client.updateWorkflow(args.id, formatted);
+                return {
+                    applied: true,
+                    workflow: formatted,
+                };
+            }
+            return {
+                applied: false,
+                previewWorkflow: formatted,
+            };
+        }
+        // Version Control
+        case 'version_list': {
+            const versions = await listVersions(args.workflowId);
+            return {
+                workflowId: args.workflowId,
+                versions,
+                total: versions.length,
+            };
+        }
+        case 'version_get': {
+            const version = await getVersion(args.workflowId, args.versionId);
+            if (!version) {
+                throw new Error(`Version ${args.versionId} not found`);
+            }
+            return version;
+        }
+        case 'version_save': {
+            const workflow = await client.getWorkflow(args.workflowId);
+            const version = await saveVersion(workflow, args.reason || 'manual');
+            if (!version) {
+                return { saved: false, message: 'No changes detected since last version' };
+            }
+            return { saved: true, version };
+        }
+        case 'version_rollback': {
+            const version = await getVersion(args.workflowId, args.versionId);
+            if (!version) {
+                throw new Error(`Version ${args.versionId} not found`);
+            }
+            // Save current state before rollback
+            const currentWorkflow = await client.getWorkflow(args.workflowId);
+            await saveVersion(currentWorkflow, 'before_rollback');
+            // Apply the old version
+            await client.updateWorkflow(args.workflowId, version.workflow);
+            return {
+                success: true,
+                restoredVersion: version.meta,
+                workflow: version.workflow,
+            };
+        }
+        case 'version_diff': {
+            const toVersion = await getVersion(args.workflowId, args.toVersionId);
+            if (!toVersion) {
+                throw new Error(`Version ${args.toVersionId} not found`);
+            }
+            let fromWorkflow;
+            if (args.fromVersionId) {
+                const fromVersion = await getVersion(args.workflowId, args.fromVersionId);
+                if (!fromVersion) {
+                    throw new Error(`Version ${args.fromVersionId} not found`);
+                }
+                fromWorkflow = fromVersion.workflow;
+            }
+            else {
+                // Compare against current workflow state
+                fromWorkflow = await client.getWorkflow(args.workflowId);
+            }
+            const diff = diffWorkflows(fromWorkflow, toVersion.workflow);
+            return {
+                from: args.fromVersionId || 'current',
+                to: args.toVersionId,
+                diff,
+            };
+        }
+        case 'version_stats': {
+            const stats = await getVersionStats();
+            return stats;
+        }
         default:
             throw new Error(`Unknown tool: ${name}`);
     }

package/dist/tools.js

@@ -236,16 +236,17 @@ Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "proper
         },
     },
     // ─────────────────────────────────────────────────────────────
-    // Validation
+    // Validation & Quality
     // ─────────────────────────────────────────────────────────────
     {
         name: 'workflow_validate',
         description: `Validate a workflow against best practices:
 - snake_case naming
 - Explicit node references (no $json)
-- No hardcoded IDs
-- No hardcoded secrets
-- No orphan nodes`,
+- No hardcoded IDs or secrets
+- No orphan nodes
+- AI node structured output
+- Expression syntax validation`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -257,4 +258,146 @@ Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "proper
             required: ['id'],
         },
     },
+    {
+        name: 'workflow_autofix',
+        description: `Auto-fix common validation issues:
+- Convert names to snake_case
+- Replace $json with explicit node references
+- Add AI structured output settings
+
+Returns the fixed workflow and list of changes made.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID to fix',
+                },
+                apply: {
+                    type: 'boolean',
+                    description: 'Apply fixes to n8n (default: false, dry-run)',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'workflow_format',
+        description: 'Format a workflow: sort nodes by position, clean up null values.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID to format',
+                },
+                apply: {
+                    type: 'boolean',
+                    description: 'Apply formatting to n8n (default: false)',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    // ─────────────────────────────────────────────────────────────
+    // Version Control
+    // ─────────────────────────────────────────────────────────────
+    {
+        name: 'version_list',
+        description: 'List saved versions of a workflow (local snapshots).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workflowId: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+            },
+            required: ['workflowId'],
+        },
+    },
+    {
+        name: 'version_get',
+        description: 'Get a specific saved version of a workflow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workflowId: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+                versionId: {
+                    type: 'string',
+                    description: 'Version ID (from version_list)',
+                },
+            },
+            required: ['workflowId', 'versionId'],
+        },
+    },
+    {
+        name: 'version_save',
+        description: 'Manually save a version snapshot of a workflow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workflowId: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Reason for saving (default: "manual")',
+                },
+            },
+            required: ['workflowId'],
+        },
+    },
+    {
+        name: 'version_rollback',
+        description: 'Restore a workflow to a previous version.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workflowId: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+                versionId: {
+                    type: 'string',
+                    description: 'Version ID to restore',
+                },
+            },
+            required: ['workflowId', 'versionId'],
+        },
+    },
+    {
+        name: 'version_diff',
+        description: 'Compare two versions of a workflow or current state vs a version.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workflowId: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+                fromVersionId: {
+                    type: 'string',
+                    description: 'First version ID (omit for current workflow state)',
+                },
+                toVersionId: {
+                    type: 'string',
+                    description: 'Second version ID',
+                },
+            },
+            required: ['workflowId', 'toVersionId'],
+        },
+    },
+    {
+        name: 'version_stats',
+        description: 'Get version control statistics.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
 ];

package/dist/validators.js

@@ -26,6 +26,12 @@ function validateNode(node, warnings) {
     checkForHardcodedIds(node, warnings);
     // Check for hardcoded secrets
     checkForHardcodedSecrets(node, warnings);
+    // Check for code node usage (should be last resort)
+    checkForCodeNodeUsage(node, warnings);
+    // Check for AI node structured output settings
+    checkForAIStructuredOutput(node, warnings);
+    // Check for in-memory storage (non-persistent)
+    checkForInMemoryStorage(node, warnings);
 }
 function validateSnakeCase(name, context, warnings) {
     // Allow spaces for readability, but check the underlying format
@@ -107,6 +113,67 @@ function checkForHardcodedSecrets(node, warnings) {
         }
     }
 }
+function checkForCodeNodeUsage(node, warnings) {
+    // Detect code nodes - they should be last resort
+    const codeNodeTypes = [
+        'n8n-nodes-base.code',
+        'n8n-nodes-base.function',
+        'n8n-nodes-base.functionItem',
+    ];
+    if (codeNodeTypes.some((t) => node.type.includes(t))) {
+        warnings.push({
+            node: node.name,
+            rule: 'code_node_usage',
+            message: `Node "${node.name}" is a code node - ensure built-in nodes can't achieve this`,
+            severity: 'info',
+        });
+    }
+}
+function checkForAIStructuredOutput(node, warnings) {
+    // Check AI/LLM nodes for structured output settings
+    const aiNodeTypes = [
+        'langchain.agent',
+        'langchain.chainLlm',
+        'langchain.lmChatOpenAi',
+        'langchain.lmChatAnthropic',
+        'langchain.lmChatGoogleGemini',
+    ];
+    const isAINode = aiNodeTypes.some((t) => node.type.toLowerCase().includes(t.toLowerCase()));
+    if (!isAINode)
+        return;
+    // Check for structured output settings
+    const params = node.parameters;
+    const hasPromptType = params.promptType === 'define';
+    const hasOutputParser = params.hasOutputParser === true;
+    // Only warn if it looks like they want structured output but missed settings
+    if (params.outputParser || params.schemaType) {
+        if (!hasPromptType || !hasOutputParser) {
+            warnings.push({
+                node: node.name,
+                rule: 'ai_structured_output',
+                message: `Node "${node.name}" may need promptType: "define" and hasOutputParser: true for reliable structured output`,
+                severity: 'warning',
+            });
+        }
+    }
+}
+function checkForInMemoryStorage(node, warnings) {
+    // Detect in-memory storage nodes that don't persist across restarts
+    const inMemoryTypes = [
+        'memoryBufferWindow',
+        'memoryVectorStore',
+        'vectorStoreInMemory',
+    ];
+    const isInMemory = inMemoryTypes.some((t) => node.type.toLowerCase().includes(t.toLowerCase()));
+    if (isInMemory) {
+        warnings.push({
+            node: node.name,
+            rule: 'in_memory_storage',
+            message: `Node "${node.name}" uses in-memory storage - consider Postgres for production persistence`,
+            severity: 'warning',
+        });
+    }
+}
 function validateConnections(workflow, warnings) {
     const connectedNodes = new Set();
     // Collect all nodes that have connections (as source or target)