@pagelines/n8n-mcp 0.2.1 → 0.3.0

package/dist/response-format.js

@@ -0,0 +1,183 @@
+/**
+ * Response Format Transformers
+ * Reduces response size for MCP to prevent context overflow
+ */
+/**
+ * Format a workflow based on the requested format level
+ */
+export function formatWorkflowResponse(workflow, format = 'compact') {
+    switch (format) {
+        case 'summary':
+            return toWorkflowSummary(workflow);
+        case 'compact':
+            return toWorkflowCompact(workflow);
+        case 'full':
+        default:
+            return workflow;
+    }
+}
+function toWorkflowSummary(workflow) {
+    const connectionCount = Object.values(workflow.connections).reduce((acc, outputs) => {
+        return acc + Object.values(outputs).reduce((a, conns) => {
+            return a + conns.reduce((b, c) => b + c.length, 0);
+        }, 0);
+    }, 0);
+    return {
+        id: workflow.id,
+        name: workflow.name,
+        active: workflow.active,
+        nodeCount: workflow.nodes.length,
+        connectionCount,
+        updatedAt: workflow.updatedAt,
+        nodeTypes: [...new Set(workflow.nodes.map((n) => n.type))],
+    };
+}
+function toWorkflowCompact(workflow) {
+    // Simplify connections to just show flow: nodeName -> [targetNodeNames]
+    const simpleConnections = {};
+    for (const [nodeName, outputs] of Object.entries(workflow.connections)) {
+        const targets = [];
+        for (const conns of Object.values(outputs)) {
+            for (const connList of conns) {
+                for (const conn of connList) {
+                    if (!targets.includes(conn.node)) {
+                        targets.push(conn.node);
+                    }
+                }
+            }
+        }
+        if (targets.length > 0) {
+            simpleConnections[nodeName] = targets;
+        }
+    }
+    return {
+        id: workflow.id,
+        name: workflow.name,
+        active: workflow.active,
+        updatedAt: workflow.updatedAt,
+        nodes: workflow.nodes.map(toCompactNode),
+        connections: simpleConnections,
+        ...(workflow.settings && Object.keys(workflow.settings).length > 0 && { settings: workflow.settings }),
+    };
+}
+function toCompactNode(node) {
+    return {
+        name: node.name,
+        type: node.type,
+        position: node.position,
+        hasCredentials: !!node.credentials && Object.keys(node.credentials).length > 0,
+        ...(node.disabled && { disabled: true }),
+    };
+}
+/**
+ * Format an execution based on the requested format level
+ */
+export function formatExecutionResponse(execution, format = 'compact') {
+    switch (format) {
+        case 'summary':
+            return toExecutionSummary(execution);
+        case 'compact':
+            return toExecutionCompact(execution);
+        case 'full':
+        default:
+            return execution;
+    }
+}
+function toExecutionSummary(execution) {
+    const durationMs = execution.stoppedAt && execution.startedAt
+        ? new Date(execution.stoppedAt).getTime() - new Date(execution.startedAt).getTime()
+        : undefined;
+    return {
+        id: execution.id,
+        workflowId: execution.workflowId,
+        status: execution.status,
+        mode: execution.mode,
+        startedAt: execution.startedAt,
+        stoppedAt: execution.stoppedAt,
+        durationMs,
+        hasError: execution.status === 'error',
+        errorMessage: execution.data?.resultData?.error?.message,
+    };
+}
+function toExecutionCompact(execution) {
+    const nodeResults = [];
+    if (execution.data?.resultData?.runData) {
+        for (const [nodeName, runs] of Object.entries(execution.data.resultData.runData)) {
+            // runData is Record<string, unknown>, so we need to handle it carefully
+            const runArray = runs;
+            if (Array.isArray(runArray) && runArray.length > 0) {
+                const lastRun = runArray[runArray.length - 1];
+                const itemCount = lastRun?.data?.main?.[0]?.length ?? 0;
+                nodeResults.push({
+                    nodeName,
+                    itemCount,
+                    success: true,
+                });
+            }
+        }
+    }
+    return {
+        id: execution.id,
+        workflowId: execution.workflowId,
+        status: execution.status,
+        mode: execution.mode,
+        startedAt: execution.startedAt,
+        stoppedAt: execution.stoppedAt,
+        finished: execution.finished,
+        ...(execution.data?.resultData?.error && { error: { message: execution.data.resultData.error.message } }),
+        ...(nodeResults.length > 0 && { nodeResults }),
+    };
+}
+/**
+ * Format execution list items
+ */
+export function formatExecutionListResponse(executions, format = 'compact') {
+    if (format === 'summary') {
+        return executions.map((e) => ({
+            id: e.id,
+            status: e.status,
+            startedAt: e.startedAt,
+        }));
+    }
+    // compact and full are the same for list items (already minimal)
+    return executions;
+}
+// ─────────────────────────────────────────────────────────────
+// Generic Response Utilities
+// ─────────────────────────────────────────────────────────────
+/**
+ * Remove null/undefined values and empty objects to reduce size
+ */
+export function cleanResponse(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(cleanResponse);
+    }
+    if (typeof obj === 'object') {
+        const cleaned = {};
+        for (const [key, value] of Object.entries(obj)) {
+            if (value !== null && value !== undefined) {
+                const cleanedValue = cleanResponse(value);
+                // Skip empty objects and arrays
+                if (typeof cleanedValue === 'object' && cleanedValue !== null) {
+                    if (Array.isArray(cleanedValue) && cleanedValue.length === 0)
+                        continue;
+                    if (!Array.isArray(cleanedValue) && Object.keys(cleanedValue).length === 0)
+                        continue;
+                }
+                cleaned[key] = cleanedValue;
+            }
+        }
+        return cleaned;
+    }
+    return obj;
+}
+/**
+ * Stringify with optional minification
+ */
+export function stringifyResponse(obj, minify = true) {
+    const cleaned = cleanResponse(obj);
+    return minify ? JSON.stringify(cleaned) : JSON.stringify(cleaned, null, 2);
+}

package/dist/response-format.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/response-format.test.js

@@ -0,0 +1,291 @@
+import { describe, it, expect } from 'vitest';
+import { formatWorkflowResponse, formatExecutionResponse, formatExecutionListResponse, cleanResponse, stringifyResponse, } from './response-format.js';
+const createWorkflow = (overrides = {}) => ({
+    id: '1',
+    name: 'test_workflow',
+    active: false,
+    nodes: [
+        {
+            id: 'node1',
+            name: 'webhook_trigger',
+            type: 'n8n-nodes-base.webhook',
+            typeVersion: 1,
+            position: [0, 0],
+            parameters: { path: 'test', httpMethod: 'POST' },
+        },
+        {
+            id: 'node2',
+            name: 'set_data',
+            type: 'n8n-nodes-base.set',
+            typeVersion: 1,
+            position: [200, 0],
+            parameters: { values: { string: [{ name: 'key', value: 'value' }] } },
+            credentials: { httpBasicAuth: { id: '1', name: 'My Auth' } },
+        },
+    ],
+    connections: {
+        webhook_trigger: {
+            main: [[{ node: 'set_data', type: 'main', index: 0 }]],
+        },
+    },
+    createdAt: '2024-01-01T00:00:00.000Z',
+    updatedAt: '2024-01-02T00:00:00.000Z',
+    ...overrides,
+});
+const createExecution = (overrides = {}) => ({
+    id: 'exec1',
+    workflowId: '1',
+    finished: true,
+    mode: 'manual',
+    startedAt: '2024-01-01T00:00:00.000Z',
+    stoppedAt: '2024-01-01T00:00:05.000Z',
+    status: 'success',
+    data: {
+        resultData: {
+            runData: {
+                webhook_trigger: [{ data: { main: [[{ json: { test: 'data' } }]] } }],
+                set_data: [{ data: { main: [[{ json: { key: 'value' } }]] } }],
+            },
+        },
+    },
+    ...overrides,
+});
+describe('formatWorkflowResponse', () => {
+    describe('summary format', () => {
+        it('returns minimal workflow info', () => {
+            const workflow = createWorkflow();
+            const result = formatWorkflowResponse(workflow, 'summary');
+            expect(result.id).toBe('1');
+            expect(result.name).toBe('test_workflow');
+            expect(result.active).toBe(false);
+            expect(result.nodeCount).toBe(2);
+            expect(result.connectionCount).toBe(1);
+            expect(result.updatedAt).toBe('2024-01-02T00:00:00.000Z');
+            expect(result.nodeTypes).toContain('n8n-nodes-base.webhook');
+            expect(result.nodeTypes).toContain('n8n-nodes-base.set');
+            // Should not have full nodes or connections
+            expect(result.nodes).toBeUndefined();
+            expect(result.connections).toBeUndefined();
+        });
+    });
+    describe('compact format', () => {
+        it('returns nodes without parameters', () => {
+            const workflow = createWorkflow();
+            const result = formatWorkflowResponse(workflow, 'compact');
+            expect(result.id).toBe('1');
+            expect(result.name).toBe('test_workflow');
+            expect(result.nodes).toHaveLength(2);
+            // Nodes should have name, type, position but no parameters
+            expect(result.nodes[0].name).toBe('webhook_trigger');
+            expect(result.nodes[0].type).toBe('n8n-nodes-base.webhook');
+            expect(result.nodes[0].position).toEqual([0, 0]);
+            expect(result.nodes[0].hasCredentials).toBe(false);
+            expect(result.nodes[0].parameters).toBeUndefined();
+            // Second node has credentials
+            expect(result.nodes[1].hasCredentials).toBe(true);
+        });
+        it('simplifies connections to node -> [targets] map', () => {
+            const workflow = createWorkflow();
+            const result = formatWorkflowResponse(workflow, 'compact');
+            expect(result.connections).toEqual({
+                webhook_trigger: ['set_data'],
+            });
+        });
+        it('marks disabled nodes', () => {
+            const workflow = createWorkflow({
+                nodes: [
+                    {
+                        id: 'node1',
+                        name: 'disabled_node',
+                        type: 'n8n-nodes-base.set',
+                        typeVersion: 1,
+                        position: [0, 0],
+                        parameters: {},
+                        disabled: true,
+                    },
+                ],
+            });
+            const result = formatWorkflowResponse(workflow, 'compact');
+            expect(result.nodes[0].disabled).toBe(true);
+        });
+    });
+    describe('full format', () => {
+        it('returns complete workflow', () => {
+            const workflow = createWorkflow();
+            const result = formatWorkflowResponse(workflow, 'full');
+            expect(result).toEqual(workflow);
+            expect(result.nodes[0].parameters).toEqual({ path: 'test', httpMethod: 'POST' });
+        });
+    });
+    describe('default format', () => {
+        it('defaults to compact', () => {
+            const workflow = createWorkflow();
+            const result = formatWorkflowResponse(workflow);
+            // Should be compact (no parameters)
+            expect(result.nodes[0].parameters).toBeUndefined();
+        });
+    });
+});
+describe('formatExecutionResponse', () => {
+    describe('summary format', () => {
+        it('returns minimal execution info', () => {
+            const execution = createExecution();
+            const result = formatExecutionResponse(execution, 'summary');
+            expect(result.id).toBe('exec1');
+            expect(result.workflowId).toBe('1');
+            expect(result.status).toBe('success');
+            expect(result.mode).toBe('manual');
+            expect(result.durationMs).toBe(5000);
+            expect(result.hasError).toBe(false);
+            // Should not have runData
+            expect(result.data).toBeUndefined();
+        });
+        it('includes error message when present', () => {
+            const execution = createExecution({
+                status: 'error',
+                data: {
+                    resultData: {
+                        error: { message: 'Something went wrong' },
+                    },
+                },
+            });
+            const result = formatExecutionResponse(execution, 'summary');
+            expect(result.hasError).toBe(true);
+            expect(result.errorMessage).toBe('Something went wrong');
+        });
+    });
+    describe('compact format', () => {
+        it('returns execution without runData but with node summaries', () => {
+            const execution = createExecution();
+            const result = formatExecutionResponse(execution, 'compact');
+            expect(result.id).toBe('exec1');
+            expect(result.status).toBe('success');
+            expect(result.finished).toBe(true);
+            // Should have node result summaries
+            expect(result.nodeResults).toHaveLength(2);
+            expect(result.nodeResults[0].nodeName).toBe('webhook_trigger');
+            expect(result.nodeResults[0].itemCount).toBe(1);
+            // Should not have full runData
+            expect(result.data).toBeUndefined();
+        });
+        it('includes error in compact format', () => {
+            const execution = createExecution({
+                status: 'error',
+                data: {
+                    resultData: {
+                        error: { message: 'Failed' },
+                    },
+                },
+            });
+            const result = formatExecutionResponse(execution, 'compact');
+            expect(result.error).toEqual({ message: 'Failed' });
+        });
+    });
+    describe('full format', () => {
+        it('returns complete execution with runData', () => {
+            const execution = createExecution();
+            const result = formatExecutionResponse(execution, 'full');
+            expect(result).toEqual(execution);
+            expect(result.data?.resultData?.runData).toBeDefined();
+        });
+    });
+});
+describe('formatExecutionListResponse', () => {
+    const executions = [
+        { id: '1', workflowId: 'w1', status: 'success', startedAt: '2024-01-01', mode: 'manual' },
+        { id: '2', workflowId: 'w1', status: 'error', startedAt: '2024-01-02', mode: 'webhook' },
+    ];
+    it('summary returns id, status, startedAt only', () => {
+        const result = formatExecutionListResponse(executions, 'summary');
+        expect(result).toHaveLength(2);
+        expect(result[0]).toEqual({ id: '1', status: 'success', startedAt: '2024-01-01' });
+        expect(result[0].workflowId).toBeUndefined();
+        expect(result[0].mode).toBeUndefined();
+    });
+    it('compact and full return same as input', () => {
+        const compactResult = formatExecutionListResponse(executions, 'compact');
+        const fullResult = formatExecutionListResponse(executions, 'full');
+        expect(compactResult).toEqual(executions);
+        expect(fullResult).toEqual(executions);
+    });
+});
+describe('cleanResponse', () => {
+    it('removes null values', () => {
+        const obj = { a: 1, b: null, c: 'test' };
+        const result = cleanResponse(obj);
+        expect(result).toEqual({ a: 1, c: 'test' });
+    });
+    it('removes undefined values', () => {
+        const obj = { a: 1, b: undefined, c: 'test' };
+        const result = cleanResponse(obj);
+        expect(result).toEqual({ a: 1, c: 'test' });
+    });
+    it('removes empty objects', () => {
+        const obj = { a: 1, b: {}, c: 'test' };
+        const result = cleanResponse(obj);
+        expect(result).toEqual({ a: 1, c: 'test' });
+    });
+    it('removes empty arrays', () => {
+        const obj = { a: 1, b: [], c: 'test' };
+        const result = cleanResponse(obj);
+        expect(result).toEqual({ a: 1, c: 'test' });
+    });
+    it('handles nested objects', () => {
+        const obj = { a: { b: null, c: 1 }, d: { e: {} } };
+        const result = cleanResponse(obj);
+        expect(result).toEqual({ a: { c: 1 } });
+    });
+    it('handles arrays', () => {
+        const arr = [{ a: 1, b: null }, { c: 2 }];
+        const result = cleanResponse(arr);
+        expect(result).toEqual([{ a: 1 }, { c: 2 }]);
+    });
+});
+describe('stringifyResponse', () => {
+    it('minifies by default', () => {
+        const obj = { a: 1, b: 'test' };
+        const result = stringifyResponse(obj);
+        expect(result).toBe('{"a":1,"b":"test"}');
+        expect(result).not.toContain('\n');
+    });
+    it('can pretty print when minify=false', () => {
+        const obj = { a: 1 };
+        const result = stringifyResponse(obj, false);
+        expect(result).toContain('\n');
+    });
+    it('cleans null values before stringifying', () => {
+        const obj = { a: 1, b: null };
+        const result = stringifyResponse(obj);
+        expect(result).toBe('{"a":1}');
+    });
+});
+describe('token reduction estimates', () => {
+    it('compact format significantly reduces workflow size', () => {
+        const workflow = createWorkflow({
+            nodes: Array.from({ length: 10 }, (_, i) => ({
+                id: `node${i}`,
+                name: `node_${i}`,
+                type: 'n8n-nodes-base.set',
+                typeVersion: 1,
+                position: [i * 200, 0],
+                parameters: {
+                    values: {
+                        string: Array.from({ length: 10 }, (_, j) => ({
+                            name: `param_${j}`,
+                            value: `This is a long value that takes up tokens ${j}`,
+                        })),
+                    },
+                },
+            })),
+        });
+        const fullJson = JSON.stringify(workflow);
+        const compactJson = stringifyResponse(formatWorkflowResponse(workflow, 'compact'));
+        const summaryJson = stringifyResponse(formatWorkflowResponse(workflow, 'summary'));
+        // Compact should be significantly smaller than full
+        expect(compactJson.length).toBeLessThan(fullJson.length * 0.5);
+        // Summary should be smallest
+        expect(summaryJson.length).toBeLessThan(compactJson.length);
+        console.log(`Full: ${fullJson.length} chars, Compact: ${compactJson.length} chars, Summary: ${summaryJson.length} chars`);
+        console.log(`Reduction: ${Math.round((1 - compactJson.length / fullJson.length) * 100)}% (compact), ${Math.round((1 - summaryJson.length / fullJson.length) * 100)}% (summary)`);
+    });
+});

package/dist/tools.js

@@ -25,7 +25,7 @@ export const tools = [
     },
     {
         name: 'workflow_get',
-        description: 'Get a workflow by ID. Returns full workflow with nodes, connections, settings.',
+        description: 'Get a workflow by ID. Use format=summary for minimal response, compact (default) for nodes without parameters, full for everything.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -33,13 +33,18 @@ export const tools = [
                     type: 'string',
                     description: 'Workflow ID',
                 },
+                format: {
+                    type: 'string',
+                    enum: ['summary', 'compact', 'full'],
+                    description: 'Response detail level. summary=minimal, compact=nodes without params (default), full=everything',
+                },
             },
             required: ['id'],
         },
     },
     {
         name: 'workflow_create',
-        description: 'Create a new workflow. Returns the created workflow.',
+        description: 'Create a new workflow. Returns the created workflow with validation.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -76,6 +81,11 @@ export const tools = [
                     type: 'object',
                     description: 'Workflow settings',
                 },
+                format: {
+                    type: 'string',
+                    enum: ['summary', 'compact', 'full'],
+                    description: 'Response detail level (default: compact)',
+                },
             },
             required: ['name', 'nodes', 'connections'],
         },
@@ -132,6 +142,11 @@ Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "proper
                         required: ['type'],
                     },
                 },
+                format: {
+                    type: 'string',
+                    enum: ['summary', 'compact', 'full'],
+                    description: 'Response detail level (default: compact)',
+                },
             },
             required: ['id', 'operations'],
         },
@@ -218,12 +233,17 @@ Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "proper
                     type: 'number',
                     description: 'Max results (default 20)',
                 },
+                format: {
+                    type: 'string',
+                    enum: ['summary', 'compact', 'full'],
+                    description: 'Response detail level (default: compact)',
+                },
             },
         },
     },
     {
         name: 'execution_get',
-        description: 'Get execution details including run data and errors.',
+        description: 'Get execution details. Use format=summary for status only, compact (default) omits runData, full for everything including runData.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -231,6 +251,11 @@ Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "proper
                     type: 'string',
                     description: 'Execution ID',
                 },
+                format: {
+                    type: 'string',
+                    enum: ['summary', 'compact', 'full'],
+                    description: 'Response detail level. summary=status only, compact=no runData (default), full=everything',
+                },
             },
             required: ['id'],
         },
@@ -300,6 +325,35 @@ Returns the fixed workflow and list of changes made.`,
         },
     },
     // ─────────────────────────────────────────────────────────────
+    // Node Discovery
+    // ─────────────────────────────────────────────────────────────
+    {
+        name: 'node_types_list',
+        description: `List available n8n node types. Use this to discover valid node types BEFORE creating workflows.
+
+Returns: type name, display name, description, category, and version for each node.
+Use the search parameter to filter by keyword (searches type name, display name, and description).
+
+IMPORTANT: Always check node types exist before using them in workflow_create or workflow_update.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                search: {
+                    type: 'string',
+                    description: 'Filter nodes by keyword (searches name, type, description)',
+                },
+                category: {
+                    type: 'string',
+                    description: 'Filter by category (e.g., "Core Nodes", "Flow", "AI")',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results (default 50)',
+                },
+            },
+        },
+    },
+    // ─────────────────────────────────────────────────────────────
     // Version Control
     // ─────────────────────────────────────────────────────────────
     {
@@ -330,6 +384,11 @@ Returns the fixed workflow and list of changes made.`,
                     type: 'string',
                     description: 'Version ID (from version_list)',
                 },
+                format: {
+                    type: 'string',
+                    enum: ['summary', 'compact', 'full'],
+                    description: 'Response detail level (default: compact)',
+                },
             },
             required: ['workflowId', 'versionId'],
         },
@@ -366,6 +425,11 @@ Returns the fixed workflow and list of changes made.`,
                     type: 'string',
                     description: 'Version ID to restore',
                 },
+                format: {
+                    type: 'string',
+                    enum: ['summary', 'compact', 'full'],
+                    description: 'Response detail level (default: compact)',
+                },
             },
             required: ['workflowId', 'versionId'],
         },

package/dist/types.d.ts

@@ -130,3 +130,30 @@ export interface N8nListResponse<T> {
     data: T[];
     nextCursor?: string;
 }
+export interface N8nNodeType {
+    name: string;
+    displayName: string;
+    description: string;
+    group: string[];
+    version: number;
+    defaults?: {
+        name: string;
+    };
+    codex?: {
+        categories?: string[];
+        alias?: string[];
+    };
+}
+export interface N8nNodeTypeSummary {
+    type: string;
+    name: string;
+    description: string;
+    category: string;
+    version: number;
+}
+export interface NodeTypeValidationError {
+    nodeType: string;
+    nodeName: string;
+    message: string;
+    suggestions?: string[];
+}

package/dist/validators.d.ts

@@ -2,9 +2,17 @@
  * Opinion-based workflow validation
  * Enforces best practices from n8n-best-practices.md
  */
-import type { N8nWorkflow, ValidationResult, ValidationWarning } from './types.js';
+import type { N8nWorkflow, ValidationResult, ValidationWarning, NodeTypeValidationError } from './types.js';
 export declare function validateWorkflow(workflow: N8nWorkflow): ValidationResult;
 /**
  * Validate a partial update to ensure it won't cause issues
  */
 export declare function validatePartialUpdate(currentWorkflow: N8nWorkflow, nodeName: string, newParameters: Record<string, unknown>): ValidationWarning[];
+/**
+ * Validate that all node types in an array exist in the available types
+ * Returns errors for any invalid node types with suggestions
+ */
+export declare function validateNodeTypes(nodes: Array<{
+    name: string;
+    type: string;
+}>, availableTypes: Set<string>): NodeTypeValidationError[];