@pagelines/n8n-mcp 0.1.0

package/src/n8n-client.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { N8nClient } from './n8n-client.js';
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+describe('N8nClient', () => {
+  let client: N8nClient;
+
+  beforeEach(() => {
+    client = new N8nClient({
+      apiUrl: 'https://n8n.example.com',
+      apiKey: 'test-api-key',
+    });
+    mockFetch.mockReset();
+  });
+
+  describe('constructor', () => {
+    it('normalizes URL by removing trailing slash', () => {
+      const clientWithSlash = new N8nClient({
+        apiUrl: 'https://n8n.example.com/',
+        apiKey: 'key',
+      });
+      // Access private property for testing
+      expect((clientWithSlash as any).baseUrl).toBe('https://n8n.example.com');
+    });
+  });
+
+  describe('listWorkflows', () => {
+    it('calls correct endpoint', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify({ data: [] }),
+      });
+
+      await client.listWorkflows();
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://n8n.example.com/api/v1/workflows',
+        expect.objectContaining({
+          method: 'GET',
+          headers: expect.objectContaining({
+            'X-N8N-API-KEY': 'test-api-key',
+          }),
+        })
+      );
+    });
+
+    it('includes query params when provided', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify({ data: [] }),
+      });
+
+      await client.listWorkflows({ active: true, limit: 10 });
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining('active=true'),
+        expect.any(Object)
+      );
+      expect(mockFetch).toHaveBeenCalledWith(
+        expect.stringContaining('limit=10'),
+        expect.any(Object)
+      );
+    });
+  });
+
+  describe('patchWorkflow', () => {
+    const mockWorkflow = {
+      id: '1',
+      name: 'test_workflow',
+      active: false,
+      nodes: [
+        {
+          id: 'node1',
+          name: 'existing_node',
+          type: 'n8n-nodes-base.set',
+          typeVersion: 1,
+          position: [0, 0] as [number, number],
+          parameters: { param1: 'value1', param2: 'value2' },
+        },
+      ],
+      connections: {},
+      createdAt: '2024-01-01',
+      updatedAt: '2024-01-01',
+    };
+
+    beforeEach(() => {
+      // Mock GET workflow
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(mockWorkflow),
+      });
+      // Mock PUT workflow
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(mockWorkflow),
+      });
+    });
+
+    it('warns when updateNode would remove parameters', async () => {
+      const { warnings } = await client.patchWorkflow('1', [
+        {
+          type: 'updateNode',
+          nodeName: 'existing_node',
+          properties: {
+            parameters: { newParam: 'newValue' }, // Missing param1, param2
+          },
+        },
+      ]);
+
+      expect(warnings).toContainEqual(
+        expect.stringContaining('remove parameters')
+      );
+      expect(warnings).toContainEqual(
+        expect.stringContaining('param1')
+      );
+    });
+
+    it('warns when removing non-existent node', async () => {
+      const { warnings } = await client.patchWorkflow('1', [
+        {
+          type: 'removeNode',
+          nodeName: 'nonexistent_node',
+        },
+      ]);
+
+      expect(warnings).toContainEqual(
+        expect.stringContaining('not found')
+      );
+    });
+
+    it('adds node correctly', async () => {
+      mockFetch.mockReset();
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(mockWorkflow),
+      });
+
+      const updatedWorkflow = {
+        ...mockWorkflow,
+        nodes: [
+          ...mockWorkflow.nodes,
+          {
+            id: 'new-id',
+            name: 'new_node',
+            type: 'n8n-nodes-base.code',
+            typeVersion: 1,
+            position: [100, 100],
+            parameters: {},
+          },
+        ],
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(updatedWorkflow),
+      });
+
+      const { workflow } = await client.patchWorkflow('1', [
+        {
+          type: 'addNode',
+          node: {
+            name: 'new_node',
+            type: 'n8n-nodes-base.code',
+            typeVersion: 1,
+            position: [100, 100],
+            parameters: {},
+          },
+        },
+      ]);
+
+      // Verify PUT was called with the new node
+      const putCall = mockFetch.mock.calls[1];
+      const putBody = JSON.parse(putCall[1].body);
+      expect(putBody.nodes).toHaveLength(2);
+      expect(putBody.nodes[1].name).toBe('new_node');
+    });
+
+    it('adds connection correctly', async () => {
+      mockFetch.mockReset();
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(mockWorkflow),
+      });
+
+      const updatedWorkflow = {
+        ...mockWorkflow,
+        connections: {
+          existing_node: {
+            main: [[{ node: 'target_node', type: 'main', index: 0 }]],
+          },
+        },
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(updatedWorkflow),
+      });
+
+      await client.patchWorkflow('1', [
+        {
+          type: 'addConnection',
+          from: 'existing_node',
+          to: 'target_node',
+        },
+      ]);
+
+      const putCall = mockFetch.mock.calls[1];
+      const putBody = JSON.parse(putCall[1].body);
+      expect(putBody.connections.existing_node.main[0][0].node).toBe('target_node');
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws on non-ok response', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+        text: async () => 'Not found',
+      });
+
+      await expect(client.getWorkflow('999')).rejects.toThrow('n8n API error (404)');
+    });
+  });
+});

package/src/n8n-client.ts

@@ -0,0 +1,361 @@
+/**
+ * n8n REST API Client
+ * Clean, minimal implementation with built-in safety checks
+ */
+
+import type {
+  N8nWorkflow,
+  N8nWorkflowListItem,
+  N8nExecution,
+  N8nExecutionListItem,
+  N8nListResponse,
+  N8nNode,
+  PatchOperation,
+} from './types.js';
+
+export interface N8nClientConfig {
+  apiUrl: string;
+  apiKey: string;
+}
+
+export class N8nClient {
+  private baseUrl: string;
+  private headers: Record<string, string>;
+
+  constructor(config: N8nClientConfig) {
+    // Normalize URL (remove trailing slash)
+    this.baseUrl = config.apiUrl.replace(/\/$/, '');
+    this.headers = {
+      'X-N8N-API-KEY': config.apiKey,
+      'Content-Type': 'application/json',
+    };
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // HTTP helpers
+  // ─────────────────────────────────────────────────────────────
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+
+    const response = await fetch(url, {
+      method,
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`n8n API error (${response.status}): ${text}`);
+    }
+
+    // Handle empty responses
+    const text = await response.text();
+    if (!text) return {} as T;
+
+    return JSON.parse(text) as T;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Workflow operations
+  // ─────────────────────────────────────────────────────────────
+
+  async listWorkflows(options?: {
+    limit?: number;
+    cursor?: string;
+    active?: boolean;
+    tags?: string[];
+  }): Promise<N8nListResponse<N8nWorkflowListItem>> {
+    const params = new URLSearchParams();
+    if (options?.limit) params.set('limit', String(options.limit));
+    if (options?.cursor) params.set('cursor', options.cursor);
+    if (options?.active !== undefined) params.set('active', String(options.active));
+    if (options?.tags?.length) params.set('tags', options.tags.join(','));
+
+    const query = params.toString();
+    return this.request('GET', `/api/v1/workflows${query ? `?${query}` : ''}`);
+  }
+
+  async getWorkflow(id: string): Promise<N8nWorkflow> {
+    return this.request('GET', `/api/v1/workflows/${id}`);
+  }
+
+  async createWorkflow(workflow: {
+    name: string;
+    nodes: N8nNode[];
+    connections: N8nWorkflow['connections'];
+    settings?: Record<string, unknown>;
+  }): Promise<N8nWorkflow> {
+    return this.request('POST', '/api/v1/workflows', workflow);
+  }
+
+  async updateWorkflow(
+    id: string,
+    workflow: Partial<Omit<N8nWorkflow, 'id' | 'createdAt' | 'updatedAt'>>
+  ): Promise<N8nWorkflow> {
+    return this.request('PUT', `/api/v1/workflows/${id}`, workflow);
+  }
+
+  async deleteWorkflow(id: string): Promise<void> {
+    await this.request('DELETE', `/api/v1/workflows/${id}`);
+  }
+
+  async activateWorkflow(id: string): Promise<N8nWorkflow> {
+    return this.request('POST', `/api/v1/workflows/${id}/activate`);
+  }
+
+  async deactivateWorkflow(id: string): Promise<N8nWorkflow> {
+    return this.request('POST', `/api/v1/workflows/${id}/deactivate`);
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Partial update with safety checks
+  // ─────────────────────────────────────────────────────────────
+
+  async patchWorkflow(
+    id: string,
+    operations: PatchOperation[]
+  ): Promise<{ workflow: N8nWorkflow; warnings: string[] }> {
+    const warnings: string[] = [];
+
+    // Fetch current state
+    const current = await this.getWorkflow(id);
+
+    // Apply operations
+    const updated = this.applyOperations(current, operations, warnings);
+
+    // Save
+    const result = await this.updateWorkflow(id, {
+      name: updated.name,
+      nodes: updated.nodes,
+      connections: updated.connections,
+      settings: updated.settings,
+    });
+
+    return { workflow: result, warnings };
+  }
+
+  private applyOperations(
+    workflow: N8nWorkflow,
+    operations: PatchOperation[],
+    warnings: string[]
+  ): N8nWorkflow {
+    // Deep clone
+    const result: N8nWorkflow = JSON.parse(JSON.stringify(workflow));
+
+    for (const op of operations) {
+      switch (op.type) {
+        case 'addNode': {
+          const node: N8nNode = {
+            id: op.node.id || crypto.randomUUID(),
+            name: op.node.name,
+            type: op.node.type,
+            typeVersion: op.node.typeVersion,
+            position: op.node.position,
+            parameters: op.node.parameters,
+            ...(op.node.credentials && { credentials: op.node.credentials }),
+            ...(op.node.disabled && { disabled: op.node.disabled }),
+          };
+          result.nodes.push(node);
+          break;
+        }
+
+        case 'removeNode': {
+          const idx = result.nodes.findIndex((n) => n.name === op.nodeName);
+          if (idx === -1) {
+            warnings.push(`Node not found: ${op.nodeName}`);
+          } else {
+            result.nodes.splice(idx, 1);
+            // Clean up connections
+            delete result.connections[op.nodeName];
+            for (const [, outputs] of Object.entries(result.connections)) {
+              for (const [, connections] of Object.entries(outputs)) {
+                for (const connArray of connections) {
+                  const toRemove = connArray.filter((c) => c.node === op.nodeName);
+                  for (const conn of toRemove) {
+                    const i = connArray.indexOf(conn);
+                    if (i !== -1) connArray.splice(i, 1);
+                  }
+                }
+              }
+            }
+          }
+          break;
+        }
+
+        case 'updateNode': {
+          const node = result.nodes.find((n) => n.name === op.nodeName);
+          if (!node) {
+            warnings.push(`Node not found: ${op.nodeName}`);
+          } else {
+            // CRITICAL: Warn about parameter replacement
+            if (op.properties.parameters) {
+              const currentKeys = Object.keys(node.parameters);
+              const newKeys = Object.keys(op.properties.parameters);
+              const missingKeys = currentKeys.filter((k) => !newKeys.includes(k));
+              if (missingKeys.length > 0) {
+                warnings.push(
+                  `WARNING: Updating "${op.nodeName}" will remove parameters: ${missingKeys.join(', ')}. ` +
+                    `Include all existing parameters to preserve them.`
+                );
+              }
+            }
+            Object.assign(node, op.properties);
+          }
+          break;
+        }
+
+        case 'addConnection': {
+          const outputType = op.outputType || 'main';
+          const fromOutput = op.fromOutput || 0;
+          const toInput = op.toInput || 0;
+          const inputType = op.inputType || 'main';
+
+          if (!result.connections[op.from]) {
+            result.connections[op.from] = {};
+          }
+          if (!result.connections[op.from][outputType]) {
+            result.connections[op.from][outputType] = [];
+          }
+          while (result.connections[op.from][outputType].length <= fromOutput) {
+            result.connections[op.from][outputType].push([]);
+          }
+          result.connections[op.from][outputType][fromOutput].push({
+            node: op.to,
+            type: inputType,
+            index: toInput,
+          });
+          break;
+        }
+
+        case 'removeConnection': {
+          const outputType = op.outputType || 'main';
+          const fromOutput = op.fromOutput || 0;
+          const conns = result.connections[op.from]?.[outputType]?.[fromOutput];
+          if (conns) {
+            const idx = conns.findIndex((c) => c.node === op.to);
+            if (idx !== -1) conns.splice(idx, 1);
+          }
+          break;
+        }
+
+        case 'updateSettings': {
+          result.settings = { ...result.settings, ...op.settings };
+          break;
+        }
+
+        case 'updateName': {
+          result.name = op.name;
+          break;
+        }
+
+        case 'activate': {
+          result.active = true;
+          break;
+        }
+
+        case 'deactivate': {
+          result.active = false;
+          break;
+        }
+      }
+    }
+
+    return result;
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Execution operations
+  // ─────────────────────────────────────────────────────────────
+
+  async listExecutions(options?: {
+    workflowId?: string;
+    status?: 'success' | 'error' | 'waiting';
+    limit?: number;
+    cursor?: string;
+  }): Promise<N8nListResponse<N8nExecutionListItem>> {
+    const params = new URLSearchParams();
+    if (options?.workflowId) params.set('workflowId', options.workflowId);
+    if (options?.status) params.set('status', options.status);
+    if (options?.limit) params.set('limit', String(options.limit));
+    if (options?.cursor) params.set('cursor', options.cursor);
+
+    const query = params.toString();
+    return this.request('GET', `/api/v1/executions${query ? `?${query}` : ''}`);
+  }
+
+  async getExecution(id: string): Promise<N8nExecution> {
+    return this.request('GET', `/api/v1/executions/${id}`);
+  }
+
+  async deleteExecution(id: string): Promise<void> {
+    await this.request('DELETE', `/api/v1/executions/${id}`);
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Workflow execution (webhook trigger)
+  // ─────────────────────────────────────────────────────────────
+
+  async executeWorkflow(
+    id: string,
+    data?: Record<string, unknown>
+  ): Promise<{ executionId?: string; data?: unknown }> {
+    // Get workflow to find webhook path
+    const workflow = await this.getWorkflow(id);
+
+    // Find webhook trigger node
+    const webhookNode = workflow.nodes.find(
+      (n) => n.type === 'n8n-nodes-base.webhook'
+    );
+
+    if (!webhookNode) {
+      throw new Error('Workflow has no webhook trigger. Cannot execute via API.');
+    }
+
+    const path = webhookNode.parameters.path as string;
+    if (!path) {
+      throw new Error('Webhook node has no path configured.');
+    }
+
+    // Execute via webhook
+    const webhookUrl = `${this.baseUrl}/webhook/${path}`;
+    const response = await fetch(webhookUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: data ? JSON.stringify(data) : undefined,
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Webhook execution failed (${response.status}): ${text}`);
+    }
+
+    const result = await response.text();
+    try {
+      return JSON.parse(result);
+    } catch {
+      return { data: result };
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // Health check
+  // ─────────────────────────────────────────────────────────────
+
+  async healthCheck(): Promise<{ healthy: boolean; version?: string; error?: string }> {
+    try {
+      // Try to list workflows with limit 1
+      await this.listWorkflows({ limit: 1 });
+      return { healthy: true };
+    } catch (error) {
+      return {
+        healthy: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+}