@pagelines/n8n-mcp 0.2.1 → 0.3.0

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.0",
   "description": "Opinionated MCP server for n8n workflow automation",
   "type": "module",
   "main": "dist/index.js",

package/plans/architecture.md

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