@pagelines/n8n-mcp 0.2.1 → 0.3.1

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

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

package/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[];

package/dist/validators.js

@@ -106,8 +106,8 @@ function checkForHardcodedSecrets(node, warnings) {
             warnings.push({
                 node: node.name,
                 rule: 'no_hardcoded_secrets',
-                message: `Node "${node.name}" may contain hardcoded secrets - use $env.VAR_NAME instead`,
-                severity: 'error',
+                message: `Node "${node.name}" may contain hardcoded secrets - consider using $env.VAR_NAME`,
+                severity: 'info',
             });
             break;
         }
@@ -236,3 +236,88 @@ export function validatePartialUpdate(currentWorkflow, nodeName, newParameters)
     }
     return warnings;
 }
+// ─────────────────────────────────────────────────────────────
+// Node Type Validation
+// ─────────────────────────────────────────────────────────────
+/**
+ * Validate that all node types in an array exist in the available types
+ * Returns errors for any invalid node types with suggestions
+ */
+export function validateNodeTypes(nodes, availableTypes) {
+    const errors = [];
+    for (const node of nodes) {
+        if (!availableTypes.has(node.type)) {
+            errors.push({
+                nodeType: node.type,
+                nodeName: node.name,
+                message: `Invalid node type "${node.type}" for node "${node.name}"`,
+                suggestions: findSimilarTypes(node.type, availableTypes),
+            });
+        }
+    }
+    return errors;
+}
+/**
+ * Find similar node types for suggestions (fuzzy matching)
+ * Returns up to 3 suggestions
+ */
+function findSimilarTypes(invalidType, availableTypes) {
+    const suggestions = [];
+    const searchTerm = invalidType.toLowerCase();
+    // Extract the last part after the dot (e.g., "webhook" from "n8n-nodes-base.webhook")
+    const typeParts = searchTerm.split('.');
+    const shortName = typeParts[typeParts.length - 1];
+    for (const validType of availableTypes) {
+        const validLower = validType.toLowerCase();
+        const validShortName = validLower.split('.').pop() || '';
+        // Check for partial matches (substring)
+        if (validLower.includes(shortName) ||
+            shortName.includes(validShortName) ||
+            validShortName.includes(shortName)) {
+            suggestions.push(validType);
+            if (suggestions.length >= 3)
+                break;
+            continue;
+        }
+        // Check for typos using Levenshtein distance
+        const distance = levenshteinDistance(shortName, validShortName);
+        const maxLen = Math.max(shortName.length, validShortName.length);
+        // Allow up to 2 character differences for short names, or 20% of length for longer ones
+        const threshold = Math.max(2, Math.floor(maxLen * 0.2));
+        if (distance <= threshold) {
+            suggestions.push(validType);
+            if (suggestions.length >= 3)
+                break;
+        }
+    }
+    return suggestions;
+}
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    // Initialize first column
+    for (let i = 0; i <= a.length; i++) {
+        matrix[i] = [i];
+    }
+    // Initialize first row
+    for (let j = 0; j <= b.length; j++) {
+        matrix[0][j] = j;
+    }
+    // Fill in the rest of the matrix
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, // deletion
+            matrix[i][j - 1] + 1, // insertion
+            matrix[i - 1][j - 1] + cost // substitution
+            );
+        }
+    }
+    return matrix[a.length][b.length];
+}

package/dist/validators.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { validateWorkflow, validatePartialUpdate } from './validators.js';
+import { validateWorkflow, validatePartialUpdate, validateNodeTypes } from './validators.js';
 const createWorkflow = (overrides = {}) => ({
     id: '1',
     name: 'test_workflow',
@@ -55,7 +55,7 @@ describe('validateWorkflow', () => {
             severity: 'warning',
         }));
     });
-    it('errors on hardcoded secrets', () => {
+    it('warns on hardcoded secrets', () => {
         const workflow = createWorkflow({
             nodes: [
                 {
@@ -69,10 +69,9 @@ describe('validateWorkflow', () => {
             ],
         });
         const result = validateWorkflow(workflow);
-        expect(result.valid).toBe(false);
         expect(result.warnings).toContainEqual(expect.objectContaining({
             rule: 'no_hardcoded_secrets',
-            severity: 'error',
+            severity: 'info',
         }));
     });
     it('warns on orphan nodes', () => {
@@ -229,3 +228,83 @@ describe('validatePartialUpdate', () => {
         expect(warnings).toHaveLength(0);
     });
 });
+describe('validateNodeTypes', () => {
+    const availableTypes = new Set([
+        'n8n-nodes-base.webhook',
+        'n8n-nodes-base.set',
+        'n8n-nodes-base.code',
+        'n8n-nodes-base.httpRequest',
+        '@n8n/n8n-nodes-langchain.agent',
+        '@n8n/n8n-nodes-langchain.chatTrigger',
+    ]);
+    it('passes when all node types are valid', () => {
+        const nodes = [
+            { name: 'webhook_trigger', type: 'n8n-nodes-base.webhook' },
+            { name: 'set_data', type: 'n8n-nodes-base.set' },
+            { name: 'ai_agent', type: '@n8n/n8n-nodes-langchain.agent' },
+        ];
+        const errors = validateNodeTypes(nodes, availableTypes);
+        expect(errors).toHaveLength(0);
+    });
+    it('returns error for invalid node type', () => {
+        const nodes = [
+            { name: 'my_node', type: 'n8n-nodes-base.nonexistent' },
+        ];
+        const errors = validateNodeTypes(nodes, availableTypes);
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toEqual(expect.objectContaining({
+            nodeType: 'n8n-nodes-base.nonexistent',
+            nodeName: 'my_node',
+        }));
+    });
+    it('returns errors for multiple invalid node types', () => {
+        const nodes = [
+            { name: 'valid_node', type: 'n8n-nodes-base.webhook' },
+            { name: 'invalid_one', type: 'n8n-nodes-base.fake' },
+            { name: 'invalid_two', type: 'n8n-nodes-base.bogus' },
+        ];
+        const errors = validateNodeTypes(nodes, availableTypes);
+        expect(errors).toHaveLength(2);
+        expect(errors.map((e) => e.nodeName)).toEqual(['invalid_one', 'invalid_two']);
+    });
+    it('provides suggestions for typos', () => {
+        const nodes = [
+            { name: 'trigger', type: 'n8n-nodes-base.webhok' }, // typo: webhok
+        ];
+        const errors = validateNodeTypes(nodes, availableTypes);
+        expect(errors).toHaveLength(1);
+        expect(errors[0].suggestions).toContain('n8n-nodes-base.webhook');
+    });
+    it('provides suggestions for partial matches', () => {
+        const nodes = [
+            { name: 'code_node', type: 'n8n-nodes-base.cod' }, // partial: cod
+        ];
+        const errors = validateNodeTypes(nodes, availableTypes);
+        expect(errors).toHaveLength(1);
+        expect(errors[0].suggestions).toContain('n8n-nodes-base.code');
+    });
+    it('returns empty suggestions when no matches found', () => {
+        const nodes = [
+            { name: 'xyz_node', type: 'n8n-nodes-base.xyz123completely_random' },
+        ];
+        const errors = validateNodeTypes(nodes, availableTypes);
+        expect(errors).toHaveLength(1);
+        expect(errors[0].suggestions).toHaveLength(0);
+    });
+    it('limits suggestions to 3', () => {
+        // Create a set with many similar types
+        const manyTypes = new Set([
+            'n8n-nodes-base.httpRequest',
+            'n8n-nodes-base.httpRequestTool',
+            'n8n-nodes-base.httpRequestV1',
+            'n8n-nodes-base.httpRequestV2',
+            'n8n-nodes-base.httpRequestV3',
+        ]);
+        const nodes = [
+            { name: 'http', type: 'n8n-nodes-base.http' }, // should match multiple
+        ];
+        const errors = validateNodeTypes(nodes, manyTypes);
+        expect(errors).toHaveLength(1);
+        expect(errors[0].suggestions.length).toBeLessThanOrEqual(3);
+    });
+});

package/docs/best-practices.md

@@ -1,5 +1,7 @@
 # n8n Best Practices
 
+> **These rules are automatically enforced.** The MCP validates, auto-fixes, and formats on every `workflow_create` and `workflow_update`. You'll only see warnings for issues that can't be auto-fixed.
+
 ## Quick Reference
 
 ```javascript
@@ -21,16 +23,16 @@
 
 ## The Rules
 
-### 1. snake_case
+### 1. snake_case (auto-fixed)
 
 ```
 Good: fetch_articles, check_approved, generate_content
 Bad:  FetchArticles, Check Approved, generate-content
 ```
 
-Why: Consistency, readability, auto-fixable.
+Why: Consistency, readability. **Auto-fixed:** renamed automatically with all references updated.
 
-### 2. Explicit References
+### 2. Explicit References (auto-fixed)
 
 ```javascript
 // Bad - breaks when flow changes
@@ -40,7 +42,7 @@ Why: Consistency, readability, auto-fixable.
 {{ $('node_name').item.json.field }}
 ```
 
-Why: `$json` references "previous node" implicitly. Reorder nodes, it breaks.
+Why: `$json` references "previous node" implicitly. Reorder nodes, it breaks. **Auto-fixed:** converted to explicit `$('prev_node')` references.
 
 ### 3. Config Node
 
@@ -63,16 +65,18 @@ Reference everywhere: `{{ $('config').item.json.channel_id }}`
 
 Why: Change once, not in 5 nodes.
 
-### 4. Secrets in Environment
+### 4. Secrets in Environment (recommended)
 
 ```javascript
-// Bad
+// Hardcoded (works, but less portable)
 { "apiKey": "sk_live_abc123" }
 
-// Good
+// Environment variable (recommended)
 {{ $env.API_KEY }}
 ```
 
+Why: Env vars make workflows portable across environments and avoid committing secrets.
+
 ## Parameter Preservation
 
 **Critical:** Partial updates REPLACE the entire `parameters` object.
@@ -107,9 +111,9 @@ Before updating: read current state with `workflow_get`.
 
 ## AI Nodes
 
-### Structured Output
+### Structured Output (auto-fixed)
 
-Always set for predictable JSON:
+Always set for predictable JSON. **Auto-fixed:** `promptType: "define"` and `hasOutputParser: true` added automatically.
 
 | Setting | Value |
 |---------|-------|
@@ -149,7 +153,8 @@ When code IS necessary:
 | 2. List versions | Know rollback point |
 | 3. Read full workflow | Understand current state |
 | 4. Make targeted change | Minimal surface area |
-| 5. Validate after | Catch issues immediately |
+
+> **Note:** Validation and cleanup are now automatic. Every create/update validates, auto-fixes, and formats automatically.
 
 ## Node-Specific Settings
 

package/docs/node-config.md

@@ -1,6 +1,8 @@
 # Node Configuration Guidelines
 
-> Settings that make AI-created nodes human-editable
+> Settings that make AI-created nodes human-editable.
+>
+> **Node types are validated.** Invalid types are blocked with suggestions before hitting n8n. Use `node_types_list` to discover available nodes.
 
 ## Resource Locator Pattern
 

package/package.json

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