@pagelines/n8n-mcp 0.2.1 → 0.3.1

package/plans/architecture.md

@@ -1,30 +1,36 @@
 # Architecture
 
+**Opinionated** n8n workflow automation. Enforces conventions, blocks mistakes, auto-fixes issues.
+
 ## vs czlonkowski/n8n-mcp
 
 | Concern | czlonkowski | @pagelines |
 |---------|-------------|------------|
+| Philosophy | Permissive | Opinionated |
 | Node docs | 70MB SQLite, 1084 nodes | None (use Google) |
 | Templates | 2,709 indexed | None (use n8n.io) |
 | Update mode | Full replace | Patch (preserves params) |
+| After mutations | Nothing | Auto-validate, auto-fix, format |
+| Invalid node types | API error | Blocked with suggestions |
 | Version control | Limited | Auto-snapshot, diff, rollback |
 | Validation | Basic | Rules + expressions + circular refs |
-| Auto-fix | No | Yes |
+| Auto-fix | No | Yes (automatic) |
 | Dependencies | SQLite, heavy | Zero runtime |
-| Lines of code | ~10k+ | ~1,200 |
+| Lines of code | ~10k+ | ~1,500 |
 
 ## Modules
 
 ```
 src/
-├── index.ts        # MCP server, tool dispatch
-├── types.ts        # Type definitions
-├── tools.ts        # Tool schemas (JSON Schema)
-├── n8n-client.ts   # n8n REST API client
-├── validators.ts   # Validation rules
-├── expressions.ts  # Expression parsing ({{ }})
-├── autofix.ts      # Auto-fix transforms
-└── versions.ts     # Version control (local fs)
+├── index.ts           # MCP server, tool dispatch
+├── types.ts           # Type definitions
+├── tools.ts           # Tool schemas (JSON Schema)
+├── n8n-client.ts      # n8n REST API client
+├── validators.ts      # Validation rules + node type validation
+├── expressions.ts     # Expression parsing ({{ }})
+├── autofix.ts         # Auto-fix transforms
+├── versions.ts        # Version control (local fs)
+└── response-format.ts # Token-efficient response formatting
 ```
 
 ## Data Flow
@@ -39,21 +45,35 @@ Tool Handler
 ┌─────────────────────────────────┐
 │  n8n-client     validators      │
 │  expressions    autofix         │
-│  versions                       │
+│  versions       response-format │
 └─────────────────────────────────┘
     ↓
 JSON Response → Claude
 ```
 
-## Tools (19 total)
+## Auto-Cleanup Pipeline
+
+Every `workflow_create` and `workflow_update` runs this automatically:
+
+```
+1. Validate node types → Block if invalid (with suggestions)
+2. Execute operation
+3. Validate workflow → Get warnings
+4. Auto-fix fixable issues → snake_case, $json refs, AI settings
+5. Format workflow → Sort nodes, remove nulls
+6. Update if changes → Apply cleanup to n8n
+7. Return result → Only unfixable warnings shown
+```
+
+## Tools (20 total)
 
 ### Workflow (8)
 | Tool | Description |
 |------|-------------|
 | `workflow_list` | List workflows, filter by active |
 | `workflow_get` | Get full workflow |
-| `workflow_create` | Create with nodes/connections |
-| `workflow_update` | Patch operations |
+| `workflow_create` | Create with nodes/connections (auto-validates, auto-fixes) |
+| `workflow_update` | Patch operations (auto-validates, auto-fixes) |
 | `workflow_delete` | Delete workflow |
 | `workflow_activate` | Enable triggers |
 | `workflow_deactivate` | Disable triggers |
@@ -72,6 +92,11 @@ JSON Response → Claude
 | `workflow_autofix` | Fix auto-fixable issues (dry-run default) |
 | `workflow_format` | Sort nodes, clean nulls |
 
+### Discovery (1)
+| Tool | Description |
+|------|-------------|
+| `node_types_list` | Search available node types by name/category |
+
 ### Version Control (6)
 | Tool | Description |
 |------|-------------|
@@ -94,20 +119,38 @@ updateSettings, updateName
 
 Key: Preserves unmodified parameters.
 
+## Node Type Validation
+
+Before `workflow_create` or `workflow_update` with `addNode`:
+
+1. Fetch available types from n8n API
+2. Validate all node types exist
+3. **Block** if invalid with suggestions (fuzzy matching)
+
+```
+Error: Invalid node types detected:
+Invalid node type "n8n-nodes-base.webhok" for node "trigger".
+Did you mean: n8n-nodes-base.webhook?
+
+Use node_types_list to discover available node types.
+```
+
 ## Validation Rules
 
-| Rule | Severity | Description |
-|------|----------|-------------|
-| `snake_case` | warning | Names should be snake_case |
-| `explicit_reference` | warning | Use `$('node')` not `$json` |
-| `no_hardcoded_ids` | info | Avoid hardcoded IDs |
-| `no_hardcoded_secrets` | error | Never hardcode secrets |
-| `code_node_usage` | info | Code node detected |
-| `ai_structured_output` | warning | AI node missing structured output |
-| `in_memory_storage` | warning | Non-persistent storage |
-| `orphan_node` | warning | Node has no connections |
-| `node_exists` | error | Node doesn't exist (for updates) |
-| `parameter_preservation` | error | Update would lose parameters |
+All rules are checked automatically on every `workflow_create` and `workflow_update`:
+
+| Rule | Severity | Auto-fix | Description |
+|------|----------|----------|-------------|
+| `snake_case` | warning | Yes | Names should be snake_case |
+| `explicit_reference` | warning | Yes | Use `$('node')` not `$json` |
+| `ai_structured_output` | warning | Yes | AI node missing structured output |
+| `no_hardcoded_ids` | info | No | Avoid hardcoded IDs |
+| `no_hardcoded_secrets` | info | No | Consider using $env vars |
+| `code_node_usage` | info | No | Code node detected |
+| `in_memory_storage` | warning | No | Non-persistent storage |
+| `orphan_node` | warning | No | Node has no connections |
+| `node_exists` | error | No | Node doesn't exist (for updates) |
+| `parameter_preservation` | error | No | Update would lose parameters |
 
 ## Expression Validation
 

package/src/index.ts

@@ -13,7 +13,7 @@ import {
 
 import { N8nClient } from './n8n-client.js';
 import { tools } from './tools.js';
-import { validateWorkflow } from './validators.js';
+import { validateWorkflow, validateNodeTypes } from './validators.js';
 import { validateExpressions, checkCircularReferences } from './expressions.js';
 import { autofixWorkflow, formatWorkflow } from './autofix.js';
 import {
@@ -24,7 +24,14 @@ import {
   diffWorkflows,
   getVersionStats,
 } from './versions.js';
-import type { PatchOperation, N8nConnections } from './types.js';
+import {
+  formatWorkflowResponse,
+  formatExecutionResponse,
+  formatExecutionListResponse,
+  stringifyResponse,
+  type ResponseFormat,
+} from './response-format.js';
+import type { PatchOperation, N8nConnections, N8nNodeTypeSummary } from './types.js';
 
 // ─────────────────────────────────────────────────────────────
 // Configuration
@@ -57,7 +64,7 @@ initVersionControl({
 const server = new Server(
   {
     name: '@pagelines/n8n-mcp',
-    version: '0.1.0',
+    version: '0.3.1',
   },
   {
     capabilities: {
@@ -81,7 +88,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       content: [
         {
           type: 'text',
-          text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+          // Use minified JSON to reduce token usage
+          text: typeof result === 'string' ? result : stringifyResponse(result),
         },
       ],
     };
@@ -124,18 +132,40 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
 
     case 'workflow_get': {
       const workflow = await client.getWorkflow(args.id as string);
-      return workflow;
+      const format = (args.format as ResponseFormat) || 'compact';
+      return formatWorkflowResponse(workflow, format);
     }
 
     case 'workflow_create': {
-      const nodes = (args.nodes as Array<{
+      const inputNodes = 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) => ({
+      }>;
+
+      // Validate node types BEFORE creating workflow
+      const availableTypes = await client.listNodeTypes();
+      const validTypeSet = new Set(availableTypes.map((nt) => nt.name));
+      const typeErrors = validateNodeTypes(inputNodes, validTypeSet);
+
+      if (typeErrors.length > 0) {
+        const errorMessages = typeErrors.map((e) => {
+          let msg = e.message;
+          if (e.suggestions && e.suggestions.length > 0) {
+            msg += `. Did you mean: ${e.suggestions.join(', ')}?`;
+          }
+          return msg;
+        });
+        throw new Error(
+          `Invalid node types detected:\n${errorMessages.join('\n')}\n\n` +
+            `Use node_types_list to discover available node types.`
+        );
+      }
+
+      const nodes = inputNodes.map((n, i) => ({
         id: crypto.randomUUID(),
         name: n.name,
         type: n.type,
@@ -145,40 +175,100 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         ...(n.credentials && { credentials: n.credentials }),
       }));
 
-      const workflow = await client.createWorkflow({
+      let 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
+      // Validate and auto-cleanup
       const validation = validateWorkflow(workflow);
+      const autofix = autofixWorkflow(workflow, validation.warnings);
+      let formatted = formatWorkflow(autofix.workflow);
+
+      // Apply cleanup if there were fixes or formatting changes
+      if (autofix.fixes.length > 0 || JSON.stringify(workflow) !== JSON.stringify(formatted)) {
+        workflow = await client.updateWorkflow(workflow.id, formatted);
+        formatted = workflow;
+      }
+
+      const format = (args.format as ResponseFormat) || 'compact';
 
       return {
-        workflow,
-        validation,
+        workflow: formatWorkflowResponse(formatted, format),
+        validation: {
+          ...validation,
+          warnings: autofix.unfixable, // Only show unfixable warnings
+        },
+        autoFixed: autofix.fixes.length > 0 ? autofix.fixes : undefined,
       };
     }
 
     case 'workflow_update': {
+      const operations = args.operations as PatchOperation[];
+
+      // Extract addNode operations that need validation
+      const addNodeOps = operations.filter(
+        (op): op is Extract<PatchOperation, { type: 'addNode' }> =>
+          op.type === 'addNode'
+      );
+
+      if (addNodeOps.length > 0) {
+        // Fetch available types and validate
+        const availableTypes = await client.listNodeTypes();
+        const validTypeSet = new Set(availableTypes.map((nt) => nt.name));
+        const nodesToValidate = addNodeOps.map((op) => ({
+          name: op.node.name,
+          type: op.node.type,
+        }));
+        const typeErrors = validateNodeTypes(nodesToValidate, validTypeSet);
+
+        if (typeErrors.length > 0) {
+          const errorMessages = typeErrors.map((e) => {
+            let msg = e.message;
+            if (e.suggestions && e.suggestions.length > 0) {
+              msg += `. Did you mean: ${e.suggestions.join(', ')}?`;
+            }
+            return msg;
+          });
+          throw new Error(
+            `Invalid node types in addNode operations:\n${errorMessages.join('\n')}\n\n` +
+              `Use node_types_list to discover available node types.`
+          );
+        }
+      }
+
       // 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(
+      let { workflow, warnings } = await client.patchWorkflow(
         args.id as string,
         operations
       );
 
-      // Also run validation
+      // Validate and auto-cleanup
       const validation = validateWorkflow(workflow);
+      const autofix = autofixWorkflow(workflow, validation.warnings);
+      let formatted = formatWorkflow(autofix.workflow);
+
+      // Apply cleanup if there were fixes or formatting changes
+      if (autofix.fixes.length > 0 || JSON.stringify(workflow) !== JSON.stringify(formatted)) {
+        workflow = await client.updateWorkflow(args.id as string, formatted);
+        formatted = workflow;
+      }
+
+      const format = (args.format as ResponseFormat) || 'compact';
 
       return {
-        workflow,
+        workflow: formatWorkflowResponse(formatted, format),
         patchWarnings: warnings,
-        validation,
+        validation: {
+          ...validation,
+          warnings: autofix.unfixable, // Only show unfixable warnings
+        },
+        autoFixed: autofix.fixes.length > 0 ? autofix.fixes : undefined,
         versionSaved: versionSaved ? versionSaved.id : null,
       };
     }
@@ -221,15 +311,17 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         status: args.status as 'success' | 'error' | 'waiting' | undefined,
         limit: (args.limit as number) || 20,
       });
+      const format = (args.format as ResponseFormat) || 'compact';
       return {
-        executions: response.data,
+        executions: formatExecutionListResponse(response.data, format),
         total: response.data.length,
       };
     }
 
     case 'execution_get': {
       const execution = await client.getExecution(args.id as string);
-      return execution;
+      const format = (args.format as ResponseFormat) || 'compact';
+      return formatExecutionResponse(execution, format);
     }
 
     // Validation & Quality
@@ -296,6 +388,48 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       };
     }
 
+    // Node Discovery
+    case 'node_types_list': {
+      const nodeTypes = await client.listNodeTypes();
+      const search = (args.search as string)?.toLowerCase();
+      const category = args.category as string;
+      const limit = (args.limit as number) || 50;
+
+      let results: N8nNodeTypeSummary[] = nodeTypes.map((nt) => ({
+        type: nt.name,
+        name: nt.displayName,
+        description: nt.description,
+        category: nt.codex?.categories?.[0] || nt.group?.[0] || 'Other',
+        version: nt.version,
+      }));
+
+      // Apply search filter
+      if (search) {
+        results = results.filter(
+          (nt) =>
+            nt.type.toLowerCase().includes(search) ||
+            nt.name.toLowerCase().includes(search) ||
+            nt.description.toLowerCase().includes(search)
+        );
+      }
+
+      // Apply category filter
+      if (category) {
+        results = results.filter((nt) =>
+          nt.category.toLowerCase().includes(category.toLowerCase())
+        );
+      }
+
+      // Apply limit
+      results = results.slice(0, limit);
+
+      return {
+        nodeTypes: results,
+        total: results.length,
+        hint: 'Use the "type" field value when creating nodes (e.g., "n8n-nodes-base.webhook")',
+      };
+    }
+
     // Version Control
     case 'version_list': {
       const versions = await listVersions(args.workflowId as string);
@@ -314,7 +448,11 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       if (!version) {
         throw new Error(`Version ${args.versionId} not found`);
       }
-      return version;
+      const format = (args.format as ResponseFormat) || 'compact';
+      return {
+        meta: version.meta,
+        workflow: formatWorkflowResponse(version.workflow, format),
+      };
     }
 
     case 'version_save': {
@@ -344,11 +482,12 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
 
       // Apply the old version
       await client.updateWorkflow(args.workflowId as string, version.workflow);
+      const format = (args.format as ResponseFormat) || 'compact';
 
       return {
         success: true,
         restoredVersion: version.meta,
-        workflow: version.workflow,
+        workflow: formatWorkflowResponse(version.workflow, format),
       };
     }
 

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();
@@ -224,4 +225,243 @@ describe('N8nClient', () => {
       await expect(client.getWorkflow('999')).rejects.toThrow('n8n API error (404)');
     });
   });
+
+  describe('listNodeTypes', () => {
+    it('calls correct endpoint', async () => {
+      const mockNodeTypes = [
+        {
+          name: 'n8n-nodes-base.webhook',
+          displayName: 'Webhook',
+          description: 'Starts workflow on webhook call',
+          group: ['trigger'],
+          version: 2,
+        },
+        {
+          name: 'n8n-nodes-base.set',
+          displayName: 'Set',
+          description: 'Set values',
+          group: ['transform'],
+          version: 3,
+        },
+      ];
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(mockNodeTypes),
+      });
+
+      const result = await client.listNodeTypes();
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        'https://n8n.example.com/api/v1/nodes',
+        expect.objectContaining({
+          method: 'GET',
+          headers: expect.objectContaining({
+            'X-N8N-API-KEY': 'test-api-key',
+          }),
+        })
+      );
+
+      expect(result).toHaveLength(2);
+      expect(result[0].name).toBe('n8n-nodes-base.webhook');
+      expect(result[1].name).toBe('n8n-nodes-base.set');
+    });
+  });
+
+  describe('updateWorkflow', () => {
+    it('strips disallowed properties before sending to API', async () => {
+      const fullWorkflow = {
+        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' },
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-02T00:00:00.000Z',
+        versionId: 'v1',
+        staticData: undefined,
+        tags: [{ id: 't1', name: 'tag1' }],
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(fullWorkflow),
+      });
+
+      await client.updateWorkflow('123', fullWorkflow);
+
+      // Verify the request body does NOT contain disallowed properties
+      const putCall = mockFetch.mock.calls[0];
+      const putBody = JSON.parse(putCall[1].body);
+
+      // These should be stripped
+      expect(putBody.id).toBeUndefined();
+      expect(putBody.createdAt).toBeUndefined();
+      expect(putBody.updatedAt).toBeUndefined();
+      expect(putBody.active).toBeUndefined();
+      expect(putBody.versionId).toBeUndefined();
+
+      // These should be preserved
+      expect(putBody.name).toBe('test_workflow');
+      expect(putBody.nodes).toHaveLength(1);
+      expect(putBody.connections).toEqual({});
+      expect(putBody.settings).toEqual({ timezone: 'UTC' });
+      expect(putBody.staticData).toBeUndefined();
+      expect(putBody.tags).toEqual([{ id: 't1', name: 'tag1' }]);
+    });
+
+    it('works with partial workflow (only some fields)', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify({ id: '123', name: 'updated' }),
+      });
+
+      await client.updateWorkflow('123', { name: 'updated', nodes: [] });
+
+      const putCall = mockFetch.mock.calls[0];
+      const putBody = JSON.parse(putCall[1].body);
+
+      expect(putBody.name).toBe('updated');
+      expect(putBody.nodes).toEqual([]);
+    });
+
+    it('handles workflow from formatWorkflow (simulating workflow_format apply)', async () => {
+      // This simulates the exact scenario that caused the bug:
+      // workflow_format returns a full N8nWorkflow object with id, createdAt, etc.
+      const formattedWorkflow = {
+        id: 'zbB1fCxWgZXgpjB1',
+        name: 'my_workflow',
+        active: false,
+        nodes: [],
+        connections: {},
+        createdAt: '2024-01-01T00:00:00.000Z',
+        updatedAt: '2024-01-02T00:00:00.000Z',
+      };
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify(formattedWorkflow),
+      });
+
+      // This should NOT throw "must NOT have additional properties"
+      await client.updateWorkflow('zbB1fCxWgZXgpjB1', formattedWorkflow);
+
+      const putCall = mockFetch.mock.calls[0];
+      const putBody = JSON.parse(putCall[1].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);
+
+      // 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);
+    }
+  });
 });