@pagelines/n8n-mcp 0.2.1 → 0.3.1

package/dist/response-format.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Response Format Transformers
+ * Reduces response size for MCP to prevent context overflow
+ */
+import type { N8nWorkflow, N8nExecution, N8nExecutionListItem } from './types.js';
+export type ResponseFormat = 'full' | 'compact' | 'summary';
+export interface WorkflowSummary {
+    id: string;
+    name: string;
+    active: boolean;
+    nodeCount: number;
+    connectionCount: number;
+    updatedAt: string;
+    nodeTypes: string[];
+}
+export interface WorkflowCompact {
+    id: string;
+    name: string;
+    active: boolean;
+    updatedAt: string;
+    nodes: CompactNode[];
+    connections: Record<string, string[]>;
+    settings?: Record<string, unknown>;
+}
+export interface CompactNode {
+    name: string;
+    type: string;
+    position: [number, number];
+    hasCredentials: boolean;
+    disabled?: boolean;
+}
+/**
+ * Format a workflow based on the requested format level
+ */
+export declare function formatWorkflowResponse(workflow: N8nWorkflow, format?: ResponseFormat): N8nWorkflow | WorkflowCompact | WorkflowSummary;
+export interface ExecutionSummary {
+    id: string;
+    workflowId: string;
+    status: string;
+    mode: string;
+    startedAt: string;
+    stoppedAt?: string;
+    durationMs?: number;
+    hasError: boolean;
+    errorMessage?: string;
+}
+export interface ExecutionCompact {
+    id: string;
+    workflowId: string;
+    status: string;
+    mode: string;
+    startedAt: string;
+    stoppedAt?: string;
+    finished: boolean;
+    error?: {
+        message: string;
+    };
+    nodeResults?: NodeResultSummary[];
+}
+export interface NodeResultSummary {
+    nodeName: string;
+    itemCount: number;
+    success: boolean;
+}
+/**
+ * Format an execution based on the requested format level
+ */
+export declare function formatExecutionResponse(execution: N8nExecution, format?: ResponseFormat): N8nExecution | ExecutionCompact | ExecutionSummary;
+/**
+ * Format execution list items
+ */
+export declare function formatExecutionListResponse(executions: N8nExecutionListItem[], format?: ResponseFormat): N8nExecutionListItem[] | Array<{
+    id: string;
+    status: string;
+    startedAt: string;
+}>;
+/**
+ * Remove null/undefined values and empty objects to reduce size
+ */
+export declare function cleanResponse<T>(obj: T): T;
+/**
+ * Stringify with optional minification
+ */
+export declare function stringifyResponse(obj: unknown, minify?: boolean): string;

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)`);
+    });
+});