@pagelines/n8n-mcp 0.1.0 → 0.2.0

package/src/index.ts

@@ -14,6 +14,16 @@ import {
 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';
 import type { PatchOperation, N8nConnections } from './types.js';
 
 // ─────────────────────────────────────────────────────────────
@@ -34,6 +44,12 @@ const client = new N8nClient({
   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
 // ─────────────────────────────────────────────────────────────
@@ -146,6 +162,10 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
     }
 
     case 'workflow_update': {
+      // Save version before updating
+      const currentWorkflow = await client.getWorkflow(args.id as string);
+      const versionSaved = await saveVersion(currentWorkflow, 'before_update');
+
       const operations = args.operations as PatchOperation[];
       const { workflow, warnings } = await client.patchWorkflow(
         args.id as string,
@@ -159,6 +179,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         workflow,
         patchWarnings: warnings,
         validation,
+        versionSaved: versionSaved ? versionSaved.id : null,
       };
     }
 
@@ -211,17 +232,164 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       return execution;
     }
 
-    // Validation
+    // Validation & Quality
     case 'workflow_validate': {
       const workflow = await client.getWorkflow(args.id as string);
       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 as string);
+      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 as string, 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 as string);
+      const formatted = formatWorkflow(workflow);
+
+      if (args.apply) {
+        await saveVersion(workflow, 'before_format');
+        await client.updateWorkflow(args.id as string, formatted);
+
+        return {
+          applied: true,
+          workflow: formatted,
+        };
+      }
+
+      return {
+        applied: false,
+        previewWorkflow: formatted,
+      };
+    }
+
+    // Version Control
+    case 'version_list': {
+      const versions = await listVersions(args.workflowId as string);
+      return {
+        workflowId: args.workflowId,
+        versions,
+        total: versions.length,
       };
     }
 
+    case 'version_get': {
+      const version = await getVersion(
+        args.workflowId as string,
+        args.versionId as string
+      );
+      if (!version) {
+        throw new Error(`Version ${args.versionId} not found`);
+      }
+      return version;
+    }
+
+    case 'version_save': {
+      const workflow = await client.getWorkflow(args.workflowId as string);
+      const version = await saveVersion(
+        workflow,
+        (args.reason as string) || '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 as string,
+        args.versionId as string
+      );
+      if (!version) {
+        throw new Error(`Version ${args.versionId} not found`);
+      }
+
+      // Save current state before rollback
+      const currentWorkflow = await client.getWorkflow(args.workflowId as string);
+      await saveVersion(currentWorkflow, 'before_rollback');
+
+      // Apply the old version
+      await client.updateWorkflow(args.workflowId as string, version.workflow);
+
+      return {
+        success: true,
+        restoredVersion: version.meta,
+        workflow: version.workflow,
+      };
+    }
+
+    case 'version_diff': {
+      const toVersion = await getVersion(
+        args.workflowId as string,
+        args.toVersionId as string
+      );
+      if (!toVersion) {
+        throw new Error(`Version ${args.toVersionId} not found`);
+      }
+
+      let fromWorkflow;
+      if (args.fromVersionId) {
+        const fromVersion = await getVersion(
+          args.workflowId as string,
+          args.fromVersionId as string
+        );
+        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 as string);
+      }
+
+      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/src/tools.ts

@@ -249,16 +249,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: {
@@ -270,4 +271,154 @@ 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/src/validators.test.ts

@@ -115,6 +115,103 @@ describe('validateWorkflow', () => {
       })
     );
   });
+
+  it('info on code node usage', () => {
+    const workflow = createWorkflow({
+      nodes: [
+        {
+          id: '1',
+          name: 'my_code',
+          type: 'n8n-nodes-base.code',
+          typeVersion: 1,
+          position: [0, 0],
+          parameters: { jsCode: 'return items;' },
+        },
+      ],
+    });
+
+    const result = validateWorkflow(workflow);
+    expect(result.warnings).toContainEqual(
+      expect.objectContaining({
+        rule: 'code_node_usage',
+        severity: 'info',
+      })
+    );
+  });
+
+  it('warns on AI node without structured output settings', () => {
+    const workflow = createWorkflow({
+      nodes: [
+        {
+          id: '1',
+          name: 'ai_agent',
+          type: '@n8n/n8n-nodes-langchain.agent',
+          typeVersion: 1,
+          position: [0, 0],
+          parameters: {
+            outputParser: true,
+            schemaType: 'manual',
+            // Missing promptType: 'define' and hasOutputParser: true
+          },
+        },
+      ],
+    });
+
+    const result = validateWorkflow(workflow);
+    expect(result.warnings).toContainEqual(
+      expect.objectContaining({
+        rule: 'ai_structured_output',
+        severity: 'warning',
+      })
+    );
+  });
+
+  it('passes AI node with correct structured output settings', () => {
+    const workflow = createWorkflow({
+      nodes: [
+        {
+          id: '1',
+          name: 'ai_agent',
+          type: '@n8n/n8n-nodes-langchain.agent',
+          typeVersion: 1,
+          position: [0, 0],
+          parameters: {
+            outputParser: true,
+            schemaType: 'manual',
+            promptType: 'define',
+            hasOutputParser: true,
+          },
+        },
+      ],
+    });
+
+    const result = validateWorkflow(workflow);
+    const aiWarnings = result.warnings.filter((w) => w.rule === 'ai_structured_output');
+    expect(aiWarnings).toHaveLength(0);
+  });
+
+  it('warns on in-memory storage nodes', () => {
+    const workflow = createWorkflow({
+      nodes: [
+        {
+          id: '1',
+          name: 'memory_buffer',
+          type: '@n8n/n8n-nodes-langchain.memoryBufferWindow',
+          typeVersion: 1,
+          position: [0, 0],
+          parameters: {},
+        },
+      ],
+    });
+
+    const result = validateWorkflow(workflow);
+    expect(result.warnings).toContainEqual(
+      expect.objectContaining({
+        rule: 'in_memory_storage',
+        severity: 'warning',
+      })
+    );
+  });
 });
 
 describe('validatePartialUpdate', () => {

package/src/validators.ts

@@ -37,6 +37,15 @@ function validateNode(node: N8nNode, warnings: ValidationWarning[]): void {
 
   // 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: string, context: string, warnings: ValidationWarning[]): void {
@@ -132,6 +141,74 @@ function checkForHardcodedSecrets(node: N8nNode, warnings: ValidationWarning[]):
   }
 }
 
+function checkForCodeNodeUsage(node: N8nNode, warnings: ValidationWarning[]): void {
+  // 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: N8nNode, warnings: ValidationWarning[]): void {
+  // 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 as Record<string, unknown>;
+  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: N8nNode, warnings: ValidationWarning[]): void {
+  // 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: N8nWorkflow, warnings: ValidationWarning[]): void {
   const connectedNodes = new Set<string>();