@pagelines/n8n-mcp 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2025-01-13
+
+### Added
+
+#### Node Type Discovery & Validation
+- `node_types_list` - Search available node types by name/category
+- Pre-validation blocks invalid node types before `workflow_create` and `workflow_update`
+- Fuzzy matching suggests correct types when invalid types detected
+
+#### Auto-Cleanup Pipeline
+- Every `workflow_create` and `workflow_update` now automatically:
+  - Validates node types (blocks if invalid)
+  - Runs validation rules
+  - Auto-fixes fixable issues (snake_case, $json refs, AI settings)
+  - Formats workflow (sorts nodes, removes nulls)
+  - Returns only unfixable warnings
+
+#### Response Formatting
+- New `format` parameter on workflow/execution tools: `compact` (default), `summary`, `full`
+- Token-efficient responses (88% reduction with compact, 98% with summary)
+
+### Changed
+- Hardcoded secrets: severity `error` → `info` (recommend env vars, don't block)
+- Documentation updated with "opinionated" messaging throughout
+- Added PageLines logo to README
+
+## [0.2.1] - 2025-01-13
+
+### Added
+- [Node Config Guide](docs/node-config.md) - Human-editable node settings (`__rl` resource locator, Set node JSON mode, AI structured output)
+
+### Changed
+- Sharpened documentation (31% line reduction, higher data-ink ratio)
+- README: Lead with differentiation, compact tool/validation tables
+- Best Practices: Quick reference at top, focused on MCP-validated patterns
+- Architecture: Technical reference, removed redundant philosophy sections
+
 ## [0.2.0] - 2025-01-12
 
 ### Added

package/README.md

@@ -1,17 +1,34 @@
+<img src="logo.png" width="64" height="64" alt="PageLines">
+
 # n8n MCP Server
 
-> Version control, validation, and patch-based updates for n8n workflows.
+**Opinionated** workflow automation for n8n. Enforces best practices, auto-fixes issues, and prevents mistakes.
 
-[![npm version](https://img.shields.io/npm/v/@pagelines/n8n-mcp.svg)](https://www.npmjs.com/package/@pagelines/n8n-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+## Why This MCP?
 
-## Install
+**The problem:** Other n8n MCPs replace entire nodes when you update one field. Change a message? Lose your channel ID, auth settings, everything else. No undo. And they bundle 70MB of node docs you can just Google.
 
-```bash
-npx @pagelines/n8n-mcp
-```
+**This MCP is opinionated:**
+- **Patches, not replaces** - Update one field, keep everything else
+- **Auto-cleanup** - Every create/update validates, auto-fixes, and formats automatically
+- **Auto-snapshots** - Every mutation saves a version first. Always have rollback.
+- **Node type validation** - Blocks invalid node types with suggestions before they hit n8n
+- **Expression validation** - Catches `$json` refs that break on reorder, circular deps, missing nodes
+- **Enforces conventions** - snake_case naming, explicit references, recommends env vars
+- **Lightweight** - ~1,500 lines, zero runtime dependencies
+
+| | This MCP | Others |
+|--|----------|--------|
+| Update a node | Preserves untouched params | Loses them |
+| After create/update | Auto-validates, auto-fixes, formats | Manual cleanup |
+| Invalid node types | Blocked with suggestions | API error |
+| Before mutations | Auto-saves version | Hope you backed up |
+| Expression validation | Syntax, refs, circular deps | Basic |
+| Size | ~1,500 LOC | 10k+ LOC, 70MB SQLite |
+
+## Setup
 
-Add to MCP config (`~/.claude/mcp.json`):
+Add to your MCP client config:
 
 ```json
 {
@@ -28,58 +45,51 @@ Add to MCP config (`~/.claude/mcp.json`):
 }
 ```
 
-## Tools
-
-### Workflow Operations
-
-| Tool | Description |
-|------|-------------|
-| `workflow_list` | List all workflows |
-| `workflow_get` | Get workflow by ID |
-| `workflow_create` | Create new workflow |
-| `workflow_update` | Patch-based updates (preserves parameters) |
-| `workflow_delete` | Delete workflow |
-| `workflow_activate` | Enable triggers |
-| `workflow_deactivate` | Disable triggers |
-| `workflow_execute` | Execute via webhook |
-
-### Quality & Validation
-
-| Tool | Description |
-|------|-------------|
-| `workflow_validate` | Check best practices, expressions, circular refs |
-| `workflow_autofix` | Auto-fix snake_case, explicit refs, AI settings |
-| `workflow_format` | Sort nodes, clean nulls |
-
-### Version Control
-
-| Tool | Description |
-|------|-------------|
-| `version_list` | List saved versions |
-| `version_get` | Get specific version |
-| `version_save` | Manual snapshot |
-| `version_rollback` | Restore previous version |
-| `version_diff` | Compare versions |
-
-## Validation Rules
-
-| Rule | Severity |
-|------|----------|
-| `snake_case` naming | warning |
-| Explicit refs (`$('node')` not `$json`) | warning |
-| No hardcoded secrets | error |
-| No orphan nodes | warning |
-| AI structured output | warning |
-| Expression syntax | error |
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `N8N_API_URL` | Your n8n instance URL |
-| `N8N_API_KEY` | API key from n8n settings |
-| `N8N_MCP_VERSIONS` | Enable version control (default: true) |
-| `N8N_MCP_MAX_VERSIONS` | Max versions per workflow (default: 20) |
+No install step needed - npx handles it.
+
+---
+
+## Reference
+
+### Tools
+
+| Category | Tools |
+|----------|-------|
+| Workflow | `list` `get` `create` `update` `delete` `activate` `deactivate` `execute` |
+| Execution | `list` `get` |
+| Validation | `validate` `autofix` `format` |
+| Discovery | `node_types_list` |
+| Versions | `list` `get` `save` `rollback` `diff` `stats` |
+
+### Opinions Enforced
+
+These rules are checked and auto-fixed on every `workflow_create` and `workflow_update`:
+
+| Rule | Severity | Auto-fix |
+|------|----------|----------|
+| snake_case naming | warning | Yes |
+| Explicit refs (`$('node')` not `$json`) | warning | Yes |
+| AI structured output settings | warning | Yes |
+| Invalid node types | error | Blocked |
+| Hardcoded secrets | info | No |
+| Orphan nodes | warning | No |
+| Expression syntax | error | No |
+| Circular references | error | No |
+
+### Config
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `N8N_API_URL` | required | n8n instance URL |
+| `N8N_API_KEY` | required | API key |
+| `N8N_MCP_VERSIONS` | `true` | Enable version control |
+| `N8N_MCP_MAX_VERSIONS` | `20` | Max snapshots per workflow |
+
+### Docs
+
+- [Best Practices](docs/best-practices.md) - Expression patterns, config nodes, AI settings
+- [Node Config](docs/node-config.md) - Human-editable node settings
+- [Architecture](plans/architecture.md) - Technical reference
 
 ## License
 

package/dist/index.js

@@ -8,10 +8,11 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 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 { initVersionControl, saveVersion, listVersions, getVersion, diffWorkflows, getVersionStats, } from './versions.js';
+import { formatWorkflowResponse, formatExecutionResponse, formatExecutionListResponse, stringifyResponse, } from './response-format.js';
 // ─────────────────────────────────────────────────────────────
 // Configuration
 // ─────────────────────────────────────────────────────────────
@@ -36,7 +37,7 @@ initVersionControl({
 // ─────────────────────────────────────────────────────────────
 const server = new Server({
     name: '@pagelines/n8n-mcp',
-    version: '0.1.0',
+    version: '0.3.0',
 }, {
     capabilities: {
         tools: {},
@@ -55,7 +56,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),
                 },
             ],
         };
@@ -96,10 +98,27 @@ async function handleTool(name, args) {
         }
         case 'workflow_get': {
             const workflow = await client.getWorkflow(args.id);
-            return workflow;
+            const format = args.format || 'compact';
+            return formatWorkflowResponse(workflow, format);
         }
         case 'workflow_create': {
-            const nodes = args.nodes.map((n, i) => ({
+            const inputNodes = args.nodes;
+            // 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,
@@ -108,31 +127,78 @@ async function handleTool(name, args) {
                 parameters: n.parameters || {},
                 ...(n.credentials && { credentials: n.credentials }),
             }));
-            const workflow = await client.createWorkflow({
+            let workflow = await client.createWorkflow({
                 name: args.name,
                 nodes,
                 connections: args.connections || {},
                 settings: args.settings,
             });
-            // 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 || '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;
+            // Extract addNode operations that need validation
+            const addNodeOps = operations.filter((op) => 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);
             const versionSaved = await saveVersion(currentWorkflow, 'before_update');
-            const operations = args.operations;
-            const { workflow, warnings } = await client.patchWorkflow(args.id, operations);
-            // Also run validation
+            let { workflow, warnings } = await client.patchWorkflow(args.id, operations);
+            // 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, formatted);
+                formatted = workflow;
+            }
+            const format = args.format || '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,
             };
         }
@@ -167,14 +233,16 @@ async function handleTool(name, args) {
                 status: args.status,
                 limit: args.limit || 20,
             });
+            const format = args.format || 'compact';
             return {
-                executions: response.data,
+                executions: formatExecutionListResponse(response.data, format),
                 total: response.data.length,
             };
         }
         case 'execution_get': {
             const execution = await client.getExecution(args.id);
-            return execution;
+            const format = args.format || 'compact';
+            return formatExecutionResponse(execution, format);
         }
         // Validation & Quality
         case 'workflow_validate': {
@@ -229,6 +297,37 @@ async function handleTool(name, args) {
                 previewWorkflow: formatted,
             };
         }
+        // Node Discovery
+        case 'node_types_list': {
+            const nodeTypes = await client.listNodeTypes();
+            const search = args.search?.toLowerCase();
+            const category = args.category;
+            const limit = args.limit || 50;
+            let results = 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);
@@ -243,7 +342,11 @@ async function handleTool(name, args) {
             if (!version) {
                 throw new Error(`Version ${args.versionId} not found`);
             }
-            return version;
+            const format = args.format || 'compact';
+            return {
+                meta: version.meta,
+                workflow: formatWorkflowResponse(version.workflow, format),
+            };
         }
         case 'version_save': {
             const workflow = await client.getWorkflow(args.workflowId);
@@ -263,10 +366,11 @@ async function handleTool(name, args) {
             await saveVersion(currentWorkflow, 'before_rollback');
             // Apply the old version
             await client.updateWorkflow(args.workflowId, version.workflow);
+            const format = args.format || 'compact';
             return {
                 success: true,
                 restoredVersion: version.meta,
-                workflow: version.workflow,
+                workflow: formatWorkflowResponse(version.workflow, format),
             };
         }
         case 'version_diff': {

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, PatchOperation } from './types.js';
+import type { N8nWorkflow, N8nWorkflowListItem, N8nExecution, N8nExecutionListItem, N8nListResponse, N8nNode, N8nNodeType, PatchOperation } from './types.js';
 export interface N8nClientConfig {
     apiUrl: string;
     apiKey: string;
@@ -25,7 +25,7 @@ export declare class N8nClient {
         connections: N8nWorkflow['connections'];
         settings?: Record<string, unknown>;
     }): Promise<N8nWorkflow>;
-    updateWorkflow(id: string, workflow: Partial<Omit<N8nWorkflow, 'id' | 'createdAt' | 'updatedAt'>>): Promise<N8nWorkflow>;
+    updateWorkflow(id: string, workflow: Partial<N8nWorkflow>): Promise<N8nWorkflow>;
     deleteWorkflow(id: string): Promise<void>;
     activateWorkflow(id: string): Promise<N8nWorkflow>;
     deactivateWorkflow(id: string): Promise<N8nWorkflow>;
@@ -51,4 +51,5 @@ export declare class N8nClient {
         version?: string;
         error?: string;
     }>;
+    listNodeTypes(): Promise<N8nNodeType[]>;
 }

package/dist/n8n-client.js

@@ -56,7 +56,9 @@ export class N8nClient {
         return this.request('POST', '/api/v1/workflows', workflow);
     }
     async updateWorkflow(id, workflow) {
-        return this.request('PUT', `/api/v1/workflows/${id}`, workflow);
+        // Strip properties that n8n API doesn't accept on PUT
+        const { id: _id, createdAt, updatedAt, active, versionId, ...allowed } = workflow;
+        return this.request('PUT', `/api/v1/workflows/${id}`, allowed);
     }
     async deleteWorkflow(id) {
         await this.request('DELETE', `/api/v1/workflows/${id}`);
@@ -272,4 +274,10 @@ export class N8nClient {
             };
         }
     }
+    // ─────────────────────────────────────────────────────────────
+    // Node Types
+    // ─────────────────────────────────────────────────────────────
+    async listNodeTypes() {
+        return this.request('GET', '/api/v1/nodes');
+    }
 }

package/dist/n8n-client.test.js

@@ -181,4 +181,115 @@ 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], 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);
+            // Critical: these must NOT be in the request body
+            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']);
+        });
+    });
 });

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;