@pagelines/n8n-mcp 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.1] - 2025-01-13
+
+### Fixed
+- **Critical bug**: `workflow_update`, `workflow_format`, and `workflow_autofix` failing with "request/body must NOT have additional properties" error
+- Root cause: n8n API returns additional read-only properties that were being sent back on PUT requests
+- Solution: Schema-driven field filtering using `N8N_WORKFLOW_WRITABLE_FIELDS` allowlist (source of truth: n8n OpenAPI spec at `/api/v1/openapi.yml`)
+
+### Changed
+- Refactored `updateWorkflow` to use schema-driven approach instead of property denylist
+- Added `pickFields` generic utility for type-safe field filtering
+- Added comprehensive tests for schema-driven filtering
+
 ## [0.3.0] - 2025-01-13
 
 ### Added

package/dist/index.js

@@ -37,7 +37,7 @@ initVersionControl({
 // ─────────────────────────────────────────────────────────────
 const server = new Server({
     name: '@pagelines/n8n-mcp',
-    version: '0.3.0',
+    version: '0.3.1',
 }, {
     capabilities: {
         tools: {},

package/dist/n8n-client.d.ts

@@ -2,7 +2,7 @@
  * n8n REST API Client
  * Clean, minimal implementation with built-in safety checks
  */
-import type { N8nWorkflow, N8nWorkflowListItem, N8nExecution, N8nExecutionListItem, N8nListResponse, N8nNode, N8nNodeType, PatchOperation } from './types.js';
+import { type N8nWorkflow, type N8nWorkflowListItem, type N8nExecution, type N8nExecutionListItem, type N8nListResponse, type N8nNode, type N8nNodeType, type PatchOperation } from './types.js';
 export interface N8nClientConfig {
     apiUrl: string;
     apiKey: string;

package/dist/n8n-client.js

@@ -2,6 +2,7 @@
  * n8n REST API Client
  * Clean, minimal implementation with built-in safety checks
  */
+import { N8N_WORKFLOW_WRITABLE_FIELDS, pickFields, } from './types.js';
 export class N8nClient {
     baseUrl;
     headers;
@@ -56,8 +57,8 @@ export class N8nClient {
         return this.request('POST', '/api/v1/workflows', workflow);
     }
     async updateWorkflow(id, workflow) {
-        // Strip properties that n8n API doesn't accept on PUT
-        const { id: _id, createdAt, updatedAt, active, versionId, ...allowed } = workflow;
+        // Schema-driven: only send fields n8n accepts (defined in types.ts)
+        const allowed = pickFields(workflow, N8N_WORKFLOW_WRITABLE_FIELDS);
         return this.request('PUT', `/api/v1/workflows/${id}`, allowed);
     }
     async deleteWorkflow(id) {

package/dist/n8n-client.test.js

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { N8nClient } from './n8n-client.js';
+import { N8N_WORKFLOW_WRITABLE_FIELDS, pickFields } from './types.js';
 // Mock fetch globally
 const mockFetch = vi.fn();
 global.fetch = mockFetch;
@@ -283,13 +284,99 @@ describe('N8nClient', () => {
             await client.updateWorkflow('zbB1fCxWgZXgpjB1', formattedWorkflow);
             const putCall = mockFetch.mock.calls[0];
             const putBody = JSON.parse(putCall[1].body);
-            // Critical: these must NOT be in the request body
+            // Only writable fields should be sent (schema-driven from N8N_WORKFLOW_WRITABLE_FIELDS)
+            const sentKeys = Object.keys(putBody).sort();
+            const expectedKeys = ['connections', 'name', 'nodes']; // Only non-undefined writable fields
+            expect(sentKeys).toEqual(expectedKeys);
+            // Read-only fields must NOT be in request
             expect(putBody.id).toBeUndefined();
             expect(putBody.createdAt).toBeUndefined();
             expect(putBody.updatedAt).toBeUndefined();
             expect(putBody.active).toBeUndefined();
-            // Only allowed properties should be sent
-            expect(Object.keys(putBody).sort()).toEqual(['connections', 'name', 'nodes']);
         });
+        it('filters out any unknown properties using schema-driven approach', async () => {
+            // Real n8n API returns many properties not in our type definition
+            // Schema-driven filtering ensures only N8N_WORKFLOW_WRITABLE_FIELDS are sent
+            const realN8nWorkflow = {
+                id: '123',
+                name: 'test_workflow',
+                active: true,
+                nodes: [{ id: 'n1', name: 'node1', type: 'test', typeVersion: 1, position: [0, 0], parameters: {} }],
+                connections: {},
+                settings: { timezone: 'UTC' },
+                staticData: { lastId: 5 },
+                tags: [{ id: 't1', name: 'production' }],
+                createdAt: '2024-01-01T00:00:00.000Z',
+                updatedAt: '2024-01-02T00:00:00.000Z',
+                versionId: 'v1',
+                // Properties that real n8n returns but aren't in writable fields:
+                homeProject: { id: 'proj1', type: 'personal', name: 'My Project' },
+                sharedWithProjects: [],
+                usedCredentials: [{ id: 'cred1', name: 'My API Key', type: 'apiKey' }],
+                meta: { instanceId: 'abc123' },
+                pinData: {},
+                triggerCount: 5,
+                unknownFutureField: 'whatever',
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                text: async () => JSON.stringify(realN8nWorkflow),
+            });
+            await client.updateWorkflow('123', realN8nWorkflow);
+            const putCall = mockFetch.mock.calls[0];
+            const putBody = JSON.parse(putCall[1].body);
+            // Request should ONLY contain fields from N8N_WORKFLOW_WRITABLE_FIELDS
+            const sentKeys = Object.keys(putBody).sort();
+            const allowedKeys = [...N8N_WORKFLOW_WRITABLE_FIELDS].sort();
+            // Every sent key must be in the allowed list
+            for (const key of sentKeys) {
+                expect(allowedKeys).toContain(key);
+            }
+            // Verify exact expected keys (all writable fields that had values)
+            expect(sentKeys).toEqual(['connections', 'name', 'nodes', 'settings', 'staticData', 'tags']);
+        });
+    });
+});
+// ─────────────────────────────────────────────────────────────
+// Schema utilities (types.ts)
+// ─────────────────────────────────────────────────────────────
+describe('pickFields utility', () => {
+    it('picks only specified fields', () => {
+        const obj = { a: 1, b: 2, c: 3, d: 4 };
+        const result = pickFields(obj, ['a', 'c']);
+        expect(result).toEqual({ a: 1, c: 3 });
+        expect(Object.keys(result)).toEqual(['a', 'c']);
+    });
+    it('ignores undefined values', () => {
+        const obj = { a: 1, b: undefined, c: 3 };
+        const result = pickFields(obj, ['a', 'b', 'c']);
+        expect(result).toEqual({ a: 1, c: 3 });
+        expect('b' in result).toBe(false);
+    });
+    it('ignores fields not in object', () => {
+        const obj = { a: 1 };
+        const result = pickFields(obj, ['a', 'missing']);
+        expect(result).toEqual({ a: 1 });
+    });
+    it('returns empty object for empty fields array', () => {
+        const obj = { a: 1, b: 2 };
+        const result = pickFields(obj, []);
+        expect(result).toEqual({});
+    });
+});
+describe('N8N_WORKFLOW_WRITABLE_FIELDS schema', () => {
+    it('contains expected writable fields', () => {
+        expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('name');
+        expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('nodes');
+        expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('connections');
+        expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('settings');
+        expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('staticData');
+        expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('tags');
+    });
+    it('does NOT contain read-only fields', () => {
+        const readOnlyFields = ['id', 'active', 'createdAt', 'updatedAt', 'versionId'];
+        for (const field of readOnlyFields) {
+            expect(N8N_WORKFLOW_WRITABLE_FIELDS).not.toContain(field);
+        }
     });
 });

package/dist/types.d.ts

@@ -130,6 +130,23 @@ export interface N8nListResponse<T> {
     data: T[];
     nextCursor?: string;
 }
+/**
+ * Fields that n8n API accepts on PUT /workflows/:id
+ * All other fields (id, createdAt, homeProject, etc.) are read-only
+ *
+ * Derived from: n8n OpenAPI spec (GET {n8n-url}/api/v1/openapi.yml)
+ * Path: /workflows/{id} → put → requestBody → content → application/json → schema
+ *
+ * If n8n adds new writable fields, check the OpenAPI spec and update this array.
+ */
+export declare const N8N_WORKFLOW_WRITABLE_FIELDS: readonly ["name", "nodes", "connections", "settings", "staticData", "tags"];
+export type N8nWorkflowWritableField = (typeof N8N_WORKFLOW_WRITABLE_FIELDS)[number];
+export type N8nWorkflowUpdate = Pick<N8nWorkflow, N8nWorkflowWritableField>;
+/**
+ * Pick only specified fields from an object (strips everything else)
+ * Generic utility for schema-driven field filtering
+ */
+export declare function pickFields<T, K extends keyof T>(obj: T, fields: readonly K[]): Pick<T, K>;
 export interface N8nNodeType {
     name: string;
     displayName: string;

package/dist/types.js

@@ -2,4 +2,37 @@
  * n8n API Types
  * Minimal types for workflow management
  */
-export {};
+// ─────────────────────────────────────────────────────────────
+// Schema-driven field definitions
+// Source of truth: n8n OpenAPI spec at /api/v1/openapi.yml
+// ─────────────────────────────────────────────────────────────
+/**
+ * Fields that n8n API accepts on PUT /workflows/:id
+ * All other fields (id, createdAt, homeProject, etc.) are read-only
+ *
+ * Derived from: n8n OpenAPI spec (GET {n8n-url}/api/v1/openapi.yml)
+ * Path: /workflows/{id} → put → requestBody → content → application/json → schema
+ *
+ * If n8n adds new writable fields, check the OpenAPI spec and update this array.
+ */
+export const N8N_WORKFLOW_WRITABLE_FIELDS = [
+    'name',
+    'nodes',
+    'connections',
+    'settings',
+    'staticData',
+    'tags',
+];
+/**
+ * Pick only specified fields from an object (strips everything else)
+ * Generic utility for schema-driven field filtering
+ */
+export function pickFields(obj, fields) {
+    const result = {};
+    for (const field of fields) {
+        if (field in obj && obj[field] !== undefined) {
+            result[field] = obj[field];
+        }
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pagelines/n8n-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Opinionated MCP server for n8n workflow automation",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -64,7 +64,7 @@ initVersionControl({
 const server = new Server(
   {
     name: '@pagelines/n8n-mcp',
-    version: '0.3.0',
+    version: '0.3.1',
   },
   {
     capabilities: {

package/src/n8n-client.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { N8nClient } from './n8n-client.js';
+import { N8N_WORKFLOW_WRITABLE_FIELDS, pickFields } from './types.js';
 
 // Mock fetch globally
 const mockFetch = vi.fn();
@@ -349,14 +350,118 @@ describe('N8nClient', () => {
       const putCall = mockFetch.mock.calls[0];
       const putBody = JSON.parse(putCall[1].body);
 
-      // Critical: these must NOT be in the request body
+      // Only writable fields should be sent (schema-driven from N8N_WORKFLOW_WRITABLE_FIELDS)
+      const sentKeys = Object.keys(putBody).sort();
+      const expectedKeys = ['connections', 'name', 'nodes']; // Only non-undefined writable fields
+      expect(sentKeys).toEqual(expectedKeys);
+
+      // Read-only fields must NOT be in request
       expect(putBody.id).toBeUndefined();
       expect(putBody.createdAt).toBeUndefined();
       expect(putBody.updatedAt).toBeUndefined();
       expect(putBody.active).toBeUndefined();
+    });
+
+    it('filters out any unknown properties using schema-driven approach', async () => {
+      // Real n8n API returns many properties not in our type definition
+      // Schema-driven filtering ensures only N8N_WORKFLOW_WRITABLE_FIELDS are sent
+      const realN8nWorkflow = {
+        id: '123',
+        name: 'test_workflow',
+        active: true,
+        nodes: [{ id: 'n1', name: 'node1', type: 'test', typeVersion: 1, position: [0, 0] as [number, number], parameters: {} }],
+        connections: {},
+        settings: { timezone: 'UTC' },
+        staticData: { lastId: 5 },
+        tags: [{ id: 't1', name: 'production' }],
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-02T00:00:00.000Z',
+        versionId: 'v1',
+        // Properties that real n8n returns but aren't in writable fields:
+        homeProject: { id: 'proj1', type: 'personal', name: 'My Project' },
+        sharedWithProjects: [],
+        usedCredentials: [{ id: 'cred1', name: 'My API Key', type: 'apiKey' }],
+        meta: { instanceId: 'abc123' },
+        pinData: {},
+        triggerCount: 5,
+        unknownFutureField: 'whatever',
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(realN8nWorkflow),
+      });
+
+      await client.updateWorkflow('123', realN8nWorkflow as any);
+
+      const putCall = mockFetch.mock.calls[0];
+      const putBody = JSON.parse(putCall[1].body);
 
-      // Only allowed properties should be sent
-      expect(Object.keys(putBody).sort()).toEqual(['connections', 'name', 'nodes']);
+      // Request should ONLY contain fields from N8N_WORKFLOW_WRITABLE_FIELDS
+      const sentKeys = Object.keys(putBody).sort();
+      const allowedKeys = [...N8N_WORKFLOW_WRITABLE_FIELDS].sort();
+
+      // Every sent key must be in the allowed list
+      for (const key of sentKeys) {
+        expect(allowedKeys).toContain(key);
+      }
+
+      // Verify exact expected keys (all writable fields that had values)
+      expect(sentKeys).toEqual(['connections', 'name', 'nodes', 'settings', 'staticData', 'tags']);
     });
   });
 });
+
+// ─────────────────────────────────────────────────────────────
+// Schema utilities (types.ts)
+// ─────────────────────────────────────────────────────────────
+
+describe('pickFields utility', () => {
+  it('picks only specified fields', () => {
+    const obj = { a: 1, b: 2, c: 3, d: 4 };
+    const result = pickFields(obj, ['a', 'c'] as const);
+
+    expect(result).toEqual({ a: 1, c: 3 });
+    expect(Object.keys(result)).toEqual(['a', 'c']);
+  });
+
+  it('ignores undefined values', () => {
+    const obj = { a: 1, b: undefined, c: 3 };
+    const result = pickFields(obj, ['a', 'b', 'c'] as const);
+
+    expect(result).toEqual({ a: 1, c: 3 });
+    expect('b' in result).toBe(false);
+  });
+
+  it('ignores fields not in object', () => {
+    const obj = { a: 1 };
+    const result = pickFields(obj as any, ['a', 'missing'] as const);
+
+    expect(result).toEqual({ a: 1 });
+  });
+
+  it('returns empty object for empty fields array', () => {
+    const obj = { a: 1, b: 2 };
+    const result = pickFields(obj, [] as const);
+
+    expect(result).toEqual({});
+  });
+});
+
+describe('N8N_WORKFLOW_WRITABLE_FIELDS schema', () => {
+  it('contains expected writable fields', () => {
+    expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('name');
+    expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('nodes');
+    expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('connections');
+    expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('settings');
+    expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('staticData');
+    expect(N8N_WORKFLOW_WRITABLE_FIELDS).toContain('tags');
+  });
+
+  it('does NOT contain read-only fields', () => {
+    const readOnlyFields = ['id', 'active', 'createdAt', 'updatedAt', 'versionId'];
+    for (const field of readOnlyFields) {
+      expect(N8N_WORKFLOW_WRITABLE_FIELDS).not.toContain(field);
+    }
+  });
+});

package/src/n8n-client.ts

@@ -3,15 +3,17 @@
  * Clean, minimal implementation with built-in safety checks
  */
 
-import type {
-  N8nWorkflow,
-  N8nWorkflowListItem,
-  N8nExecution,
-  N8nExecutionListItem,
-  N8nListResponse,
-  N8nNode,
-  N8nNodeType,
-  PatchOperation,
+import {
+  N8N_WORKFLOW_WRITABLE_FIELDS,
+  pickFields,
+  type N8nWorkflow,
+  type N8nWorkflowListItem,
+  type N8nExecution,
+  type N8nExecutionListItem,
+  type N8nListResponse,
+  type N8nNode,
+  type N8nNodeType,
+  type PatchOperation,
 } from './types.js';
 
 export interface N8nClientConfig {
@@ -98,8 +100,8 @@ export class N8nClient {
     id: string,
     workflow: Partial<N8nWorkflow>
   ): Promise<N8nWorkflow> {
-    // Strip properties that n8n API doesn't accept on PUT
-    const { id: _id, createdAt, updatedAt, active, versionId, ...allowed } = workflow as any;
+    // Schema-driven: only send fields n8n accepts (defined in types.ts)
+    const allowed = pickFields(workflow, N8N_WORKFLOW_WRITABLE_FIELDS);
     return this.request('PUT', `/api/v1/workflows/${id}`, allowed);
   }
 

package/src/types.ts

@@ -106,6 +106,49 @@ export interface N8nListResponse<T> {
   nextCursor?: string;
 }
 
+// ─────────────────────────────────────────────────────────────
+// Schema-driven field definitions
+// Source of truth: n8n OpenAPI spec at /api/v1/openapi.yml
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Fields that n8n API accepts on PUT /workflows/:id
+ * All other fields (id, createdAt, homeProject, etc.) are read-only
+ *
+ * Derived from: n8n OpenAPI spec (GET {n8n-url}/api/v1/openapi.yml)
+ * Path: /workflows/{id} → put → requestBody → content → application/json → schema
+ *
+ * If n8n adds new writable fields, check the OpenAPI spec and update this array.
+ */
+export const N8N_WORKFLOW_WRITABLE_FIELDS = [
+  'name',
+  'nodes',
+  'connections',
+  'settings',
+  'staticData',
+  'tags',
+] as const;
+
+export type N8nWorkflowWritableField = (typeof N8N_WORKFLOW_WRITABLE_FIELDS)[number];
+export type N8nWorkflowUpdate = Pick<N8nWorkflow, N8nWorkflowWritableField>;
+
+/**
+ * Pick only specified fields from an object (strips everything else)
+ * Generic utility for schema-driven field filtering
+ */
+export function pickFields<T, K extends keyof T>(
+  obj: T,
+  fields: readonly K[]
+): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+  for (const field of fields) {
+    if (field in (obj as object) && obj[field] !== undefined) {
+      result[field] = obj[field];
+    }
+  }
+  return result;
+}
+
 // Node type information from n8n API (GET /api/v1/nodes)
 export interface N8nNodeType {
   name: string;           // e.g., "n8n-nodes-base.webhook"