@pagelines/n8n-mcp 0.1.0

package/dist/validators.test.js

@@ -0,0 +1,148 @@
+import { describe, it, expect } from 'vitest';
+import { validateWorkflow, validatePartialUpdate } from './validators.js';
+const createWorkflow = (overrides = {}) => ({
+    id: '1',
+    name: 'test_workflow',
+    active: false,
+    nodes: [],
+    connections: {},
+    createdAt: '2024-01-01',
+    updatedAt: '2024-01-01',
+    ...overrides,
+});
+describe('validateWorkflow', () => {
+    it('passes for valid snake_case workflow', () => {
+        const workflow = createWorkflow({
+            name: 'my_workflow',
+            nodes: [
+                {
+                    id: '1',
+                    name: 'webhook_trigger',
+                    type: 'n8n-nodes-base.webhook',
+                    typeVersion: 1,
+                    position: [0, 0],
+                    parameters: { path: 'test' },
+                },
+            ],
+        });
+        const result = validateWorkflow(workflow);
+        expect(result.valid).toBe(true);
+    });
+    it('warns on non-snake_case workflow name', () => {
+        const workflow = createWorkflow({ name: 'My-Workflow-Name' });
+        const result = validateWorkflow(workflow);
+        expect(result.warnings).toContainEqual(expect.objectContaining({
+            rule: 'snake_case',
+            severity: 'warning',
+        }));
+    });
+    it('warns on $json usage', () => {
+        const workflow = createWorkflow({
+            nodes: [
+                {
+                    id: '1',
+                    name: 'set_node',
+                    type: 'n8n-nodes-base.set',
+                    typeVersion: 1,
+                    position: [0, 0],
+                    parameters: { value: '={{ $json.field }}' },
+                },
+            ],
+        });
+        const result = validateWorkflow(workflow);
+        expect(result.warnings).toContainEqual(expect.objectContaining({
+            rule: 'explicit_reference',
+            severity: 'warning',
+        }));
+    });
+    it('errors on hardcoded secrets', () => {
+        const workflow = createWorkflow({
+            nodes: [
+                {
+                    id: '1',
+                    name: 'http_node',
+                    type: 'n8n-nodes-base.httpRequest',
+                    typeVersion: 1,
+                    position: [0, 0],
+                    parameters: { apiKey: 'sk_live_abc123def456' },
+                },
+            ],
+        });
+        const result = validateWorkflow(workflow);
+        expect(result.valid).toBe(false);
+        expect(result.warnings).toContainEqual(expect.objectContaining({
+            rule: 'no_hardcoded_secrets',
+            severity: 'error',
+        }));
+    });
+    it('warns on orphan nodes', () => {
+        const workflow = createWorkflow({
+            nodes: [
+                {
+                    id: '1',
+                    name: 'orphan_node',
+                    type: 'n8n-nodes-base.set',
+                    typeVersion: 1,
+                    position: [0, 0],
+                    parameters: {},
+                },
+            ],
+            connections: {},
+        });
+        const result = validateWorkflow(workflow);
+        expect(result.warnings).toContainEqual(expect.objectContaining({
+            rule: 'orphan_node',
+            severity: 'warning',
+        }));
+    });
+});
+describe('validatePartialUpdate', () => {
+    it('errors when node not found', () => {
+        const workflow = createWorkflow();
+        const warnings = validatePartialUpdate(workflow, 'nonexistent', {});
+        expect(warnings).toContainEqual(expect.objectContaining({
+            rule: 'node_exists',
+            severity: 'error',
+        }));
+    });
+    it('errors on parameter loss', () => {
+        const workflow = createWorkflow({
+            nodes: [
+                {
+                    id: '1',
+                    name: 'my_node',
+                    type: 'n8n-nodes-base.set',
+                    typeVersion: 1,
+                    position: [0, 0],
+                    parameters: { existingParam: 'value', anotherParam: 'value2' },
+                },
+            ],
+        });
+        const warnings = validatePartialUpdate(workflow, 'my_node', {
+            newParam: 'value', // Missing existingParam and anotherParam
+        });
+        expect(warnings).toContainEqual(expect.objectContaining({
+            rule: 'parameter_preservation',
+            severity: 'error',
+        }));
+    });
+    it('passes when all parameters preserved', () => {
+        const workflow = createWorkflow({
+            nodes: [
+                {
+                    id: '1',
+                    name: 'my_node',
+                    type: 'n8n-nodes-base.set',
+                    typeVersion: 1,
+                    position: [0, 0],
+                    parameters: { existingParam: 'value' },
+                },
+            ],
+        });
+        const warnings = validatePartialUpdate(workflow, 'my_node', {
+            existingParam: 'value',
+            newParam: 'new',
+        });
+        expect(warnings).toHaveLength(0);
+    });
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pagelines/n8n-mcp",
+  "version": "0.1.0",
+  "description": "Opinionated MCP server for n8n workflow automation",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "pl-n8n-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "n8n",
+    "mcp",
+    "model-context-protocol",
+    "workflow",
+    "automation",
+    "pagelines"
+  ],
+  "author": "PageLines",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PageLines/n8n-mcp"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  }
+}

package/server.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://registry.modelcontextprotocol.io/schema/server.json",
+  "name": "io.github.pagelines/n8n-mcp",
+  "displayName": "pl-n8n-mcp",
+  "description": "Opinionated MCP server for n8n workflow automation with built-in validation and safety features",
+  "version": "0.1.0",
+  "author": {
+    "name": "PageLines",
+    "url": "https://github.com/pagelines"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/PageLines/n8n-mcp"
+  },
+  "license": "MIT",
+  "packages": {
+    "npm": "@pagelines/n8n-mcp"
+  },
+  "runtime": {
+    "command": "npx",
+    "args": ["-y", "@pagelines/n8n-mcp"],
+    "env": {
+      "N8N_API_URL": {
+        "description": "n8n instance URL",
+        "required": true
+      },
+      "N8N_API_KEY": {
+        "description": "n8n API key",
+        "required": true,
+        "secret": true
+      }
+    }
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": false,
+    "prompts": false
+  },
+  "tools": [
+    "workflow_list",
+    "workflow_get",
+    "workflow_create",
+    "workflow_update",
+    "workflow_delete",
+    "workflow_activate",
+    "workflow_deactivate",
+    "workflow_execute",
+    "workflow_validate",
+    "execution_list",
+    "execution_get"
+  ],
+  "keywords": [
+    "n8n",
+    "workflow",
+    "automation",
+    "mcp"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * @pagelines/n8n-mcp
+ * Opinionated MCP server for n8n workflow automation
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { N8nClient } from './n8n-client.js';
+import { tools } from './tools.js';
+import { validateWorkflow } from './validators.js';
+import type { PatchOperation, N8nConnections } from './types.js';
+
+// ─────────────────────────────────────────────────────────────
+// Configuration
+// ─────────────────────────────────────────────────────────────
+
+const N8N_API_URL = process.env.N8N_API_URL || process.env.N8N_HOST || '';
+const N8N_API_KEY = process.env.N8N_API_KEY || '';
+
+if (!N8N_API_URL || !N8N_API_KEY) {
+  console.error('Error: N8N_API_URL and N8N_API_KEY environment variables are required');
+  console.error('Set them in your MCP server configuration or environment');
+  process.exit(1);
+}
+
+const client = new N8nClient({
+  apiUrl: N8N_API_URL,
+  apiKey: N8N_API_KEY,
+});
+
+// ─────────────────────────────────────────────────────────────
+// MCP Server
+// ─────────────────────────────────────────────────────────────
+
+const server = new Server(
+  {
+    name: '@pagelines/n8n-mcp',
+    version: '0.1.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools,
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    const result = await handleTool(name, args || {});
+    return {
+      content: [
+        {
+          type: 'text',
+          text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// ─────────────────────────────────────────────────────────────
+// Tool Handlers
+// ─────────────────────────────────────────────────────────────
+
+async function handleTool(name: string, args: Record<string, unknown>): Promise<unknown> {
+  switch (name) {
+    // Workflow operations
+    case 'workflow_list': {
+      const response = await client.listWorkflows({
+        active: args.active as boolean | undefined,
+        limit: (args.limit as number) || 100,
+      });
+      return {
+        workflows: response.data.map((w) => ({
+          id: w.id,
+          name: w.name,
+          active: w.active,
+          updatedAt: w.updatedAt,
+        })),
+        total: response.data.length,
+      };
+    }
+
+    case 'workflow_get': {
+      const workflow = await client.getWorkflow(args.id as string);
+      return workflow;
+    }
+
+    case 'workflow_create': {
+      const nodes = (args.nodes as Array<{
+        name: string;
+        type: string;
+        typeVersion: number;
+        position: [number, number];
+        parameters: Record<string, unknown>;
+        credentials?: Record<string, { id: string; name: string }>;
+      }>).map((n, i) => ({
+        id: crypto.randomUUID(),
+        name: n.name,
+        type: n.type,
+        typeVersion: n.typeVersion,
+        position: n.position || [250, 250 + i * 100],
+        parameters: n.parameters || {},
+        ...(n.credentials && { credentials: n.credentials }),
+      }));
+
+      const workflow = await client.createWorkflow({
+        name: args.name as string,
+        nodes,
+        connections: (args.connections as N8nConnections) || {},
+        settings: args.settings as Record<string, unknown>,
+      });
+
+      // Validate the new workflow
+      const validation = validateWorkflow(workflow);
+
+      return {
+        workflow,
+        validation,
+      };
+    }
+
+    case 'workflow_update': {
+      const operations = args.operations as PatchOperation[];
+      const { workflow, warnings } = await client.patchWorkflow(
+        args.id as string,
+        operations
+      );
+
+      // Also run validation
+      const validation = validateWorkflow(workflow);
+
+      return {
+        workflow,
+        patchWarnings: warnings,
+        validation,
+      };
+    }
+
+    case 'workflow_delete': {
+      await client.deleteWorkflow(args.id as string);
+      return { success: true, message: `Workflow ${args.id} deleted` };
+    }
+
+    case 'workflow_activate': {
+      const workflow = await client.activateWorkflow(args.id as string);
+      return {
+        id: workflow.id,
+        name: workflow.name,
+        active: workflow.active,
+      };
+    }
+
+    case 'workflow_deactivate': {
+      const workflow = await client.deactivateWorkflow(args.id as string);
+      return {
+        id: workflow.id,
+        name: workflow.name,
+        active: workflow.active,
+      };
+    }
+
+    case 'workflow_execute': {
+      const result = await client.executeWorkflow(
+        args.id as string,
+        args.data as Record<string, unknown>
+      );
+      return result;
+    }
+
+    // Execution operations
+    case 'execution_list': {
+      const response = await client.listExecutions({
+        workflowId: args.workflowId as string | undefined,
+        status: args.status as 'success' | 'error' | 'waiting' | undefined,
+        limit: (args.limit as number) || 20,
+      });
+      return {
+        executions: response.data,
+        total: response.data.length,
+      };
+    }
+
+    case 'execution_get': {
+      const execution = await client.getExecution(args.id as string);
+      return execution;
+    }
+
+    // Validation
+    case 'workflow_validate': {
+      const workflow = await client.getWorkflow(args.id as string);
+      const validation = validateWorkflow(workflow);
+      return {
+        workflowId: workflow.id,
+        workflowName: workflow.name,
+        ...validation,
+      };
+    }
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Start Server
+// ─────────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('@pagelines/n8n-mcp server started');
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});