@pagelines/n8n-mcp 0.1.0

package/src/tools.ts

@@ -0,0 +1,273 @@
+/**
+ * MCP Tool Definitions
+ * Minimal, focused toolset for workflow management
+ */
+
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const tools: Tool[] = [
+  // ─────────────────────────────────────────────────────────────
+  // Workflow Operations
+  // ─────────────────────────────────────────────────────────────
+  {
+    name: 'workflow_list',
+    description: 'List all workflows. Returns id, name, active status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        active: {
+          type: 'boolean',
+          description: 'Filter by active status',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results (default 100)',
+        },
+      },
+    },
+  },
+
+  {
+    name: 'workflow_get',
+    description: 'Get a workflow by ID. Returns full workflow with nodes, connections, settings.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Workflow ID',
+        },
+      },
+      required: ['id'],
+    },
+  },
+
+  {
+    name: 'workflow_create',
+    description: 'Create a new workflow. Returns the created workflow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          description: 'Workflow name (use snake_case)',
+        },
+        nodes: {
+          type: 'array',
+          description: 'Array of node definitions',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              type: { type: 'string' },
+              typeVersion: { type: 'number' },
+              position: {
+                type: 'array',
+                items: { type: 'number' },
+                minItems: 2,
+                maxItems: 2,
+              },
+              parameters: { type: 'object' },
+              credentials: { type: 'object' },
+            },
+            required: ['name', 'type', 'typeVersion', 'position', 'parameters'],
+          },
+        },
+        connections: {
+          type: 'object',
+          description: 'Connection map: { "NodeName": { "main": [[{ "node": "TargetNode", "type": "main", "index": 0 }]] } }',
+        },
+        settings: {
+          type: 'object',
+          description: 'Workflow settings',
+        },
+      },
+      required: ['name', 'nodes', 'connections'],
+    },
+  },
+
+  {
+    name: 'workflow_update',
+    description: `Update a workflow using patch operations. ALWAYS preserves existing data.
+
+Operations:
+- addNode: Add a new node
+- removeNode: Remove a node and its connections
+- updateNode: Update node properties (INCLUDE ALL existing parameters to preserve them)
+- addConnection: Connect two nodes
+- removeConnection: Disconnect two nodes
+- updateSettings: Update workflow settings
+- updateName: Rename the workflow
+
+Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "properties": { "parameters": { ...allExistingParams, "newParam": "value" } } }] }`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Workflow ID',
+        },
+        operations: {
+          type: 'array',
+          description: 'Array of patch operations',
+          items: {
+            type: 'object',
+            properties: {
+              type: {
+                type: 'string',
+                enum: ['addNode', 'removeNode', 'updateNode', 'addConnection', 'removeConnection', 'updateSettings', 'updateName'],
+              },
+              // For addNode
+              node: { type: 'object' },
+              // For removeNode, updateNode
+              nodeName: { type: 'string' },
+              // For updateNode
+              properties: { type: 'object' },
+              // For connections
+              from: { type: 'string' },
+              to: { type: 'string' },
+              fromOutput: { type: 'number' },
+              toInput: { type: 'number' },
+              outputType: { type: 'string' },
+              inputType: { type: 'string' },
+              // For updateSettings
+              settings: { type: 'object' },
+              // For updateName
+              name: { type: 'string' },
+            },
+            required: ['type'],
+          },
+        },
+      },
+      required: ['id', 'operations'],
+    },
+  },
+
+  {
+    name: 'workflow_delete',
+    description: 'Delete a workflow permanently.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Workflow ID',
+        },
+      },
+      required: ['id'],
+    },
+  },
+
+  {
+    name: 'workflow_activate',
+    description: 'Activate a workflow (enable triggers).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Workflow ID',
+        },
+      },
+      required: ['id'],
+    },
+  },
+
+  {
+    name: 'workflow_deactivate',
+    description: 'Deactivate a workflow (disable triggers).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Workflow ID',
+        },
+      },
+      required: ['id'],
+    },
+  },
+
+  {
+    name: 'workflow_execute',
+    description: 'Execute a workflow via its webhook trigger. Workflow must have a webhook node.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Workflow ID',
+        },
+        data: {
+          type: 'object',
+          description: 'Data to send to the webhook',
+        },
+      },
+      required: ['id'],
+    },
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Execution Operations
+  // ─────────────────────────────────────────────────────────────
+  {
+    name: 'execution_list',
+    description: 'List workflow executions. Filter by workflow or status.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workflowId: {
+          type: 'string',
+          description: 'Filter by workflow ID',
+        },
+        status: {
+          type: 'string',
+          enum: ['success', 'error', 'waiting'],
+          description: 'Filter by status',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results (default 20)',
+        },
+      },
+    },
+  },
+
+  {
+    name: 'execution_get',
+    description: 'Get execution details including run data and errors.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Execution ID',
+        },
+      },
+      required: ['id'],
+    },
+  },
+
+  // ─────────────────────────────────────────────────────────────
+  // Validation
+  // ─────────────────────────────────────────────────────────────
+  {
+    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`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: {
+          type: 'string',
+          description: 'Workflow ID to validate',
+        },
+      },
+      required: ['id'],
+    },
+  },
+];

package/src/types.ts

@@ -0,0 +1,107 @@
+/**
+ * n8n API Types
+ * Minimal types for workflow management
+ */
+
+export interface N8nNode {
+  id: string;
+  name: string;
+  type: string;
+  typeVersion: number;
+  position: [number, number];
+  parameters: Record<string, unknown>;
+  credentials?: Record<string, { id: string; name: string }>;
+  disabled?: boolean;
+  notes?: string;
+  notesInFlow?: boolean;
+}
+
+export interface N8nConnection {
+  node: string;
+  type: string;
+  index: number;
+}
+
+export interface N8nConnections {
+  [nodeName: string]: {
+    [outputType: string]: N8nConnection[][];
+  };
+}
+
+export interface N8nWorkflow {
+  id: string;
+  name: string;
+  active: boolean;
+  nodes: N8nNode[];
+  connections: N8nConnections;
+  settings?: Record<string, unknown>;
+  staticData?: Record<string, unknown>;
+  tags?: { id: string; name: string }[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface N8nWorkflowListItem {
+  id: string;
+  name: string;
+  active: boolean;
+  createdAt: string;
+  updatedAt: string;
+  tags?: { id: string; name: string }[];
+}
+
+export interface N8nExecution {
+  id: string;
+  workflowId: string;
+  finished: boolean;
+  mode: string;
+  startedAt: string;
+  stoppedAt?: string;
+  status: 'success' | 'error' | 'waiting' | 'running';
+  data?: {
+    resultData?: {
+      runData?: Record<string, unknown>;
+      error?: { message: string };
+    };
+  };
+}
+
+export interface N8nExecutionListItem {
+  id: string;
+  workflowId: string;
+  status: string;
+  startedAt: string;
+  stoppedAt?: string;
+  mode: string;
+}
+
+// Patch operations for partial updates
+export type PatchOperation =
+  | { type: 'addNode'; node: Omit<N8nNode, 'id'> & { id?: string } }
+  | { type: 'removeNode'; nodeName: string }
+  | { type: 'updateNode'; nodeName: string; properties: Partial<N8nNode> }
+  | { type: 'addConnection'; from: string; to: string; fromOutput?: number; toInput?: number; outputType?: string; inputType?: string }
+  | { type: 'removeConnection'; from: string; to: string; fromOutput?: number; toInput?: number; outputType?: string }
+  | { type: 'updateSettings'; settings: Record<string, unknown> }
+  | { type: 'updateName'; name: string }
+  | { type: 'activate' }
+  | { type: 'deactivate' };
+
+// Validation
+export interface ValidationWarning {
+  node?: string;
+  rule: string;
+  message: string;
+  severity: 'error' | 'warning' | 'info';
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  warnings: ValidationWarning[];
+}
+
+// API response wrappers
+export interface N8nListResponse<T> {
+  data: T[];
+  nextCursor?: string;
+}

package/src/validators.test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect } from 'vitest';
+import { validateWorkflow, validatePartialUpdate } from './validators.js';
+import type { N8nWorkflow } from './types.js';
+
+const createWorkflow = (overrides: Partial<N8nWorkflow> = {}): N8nWorkflow => ({
+  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);
+  });
+});