@pagelines/n8n-mcp 0.2.0 → 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,107 +1,88 @@
 # n8n Best Practices
 
-> Enforced by `@pagelines/n8n-mcp`
+> **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.
 
-## Guiding Principle
-
-**What is most stable and easiest to maintain?**
+## Quick Reference
 
-| Rule | Why |
-|------|-----|
-| Minimize nodes | Fewer failure points, easier debugging |
-| YAGNI | Build only what's needed now |
-| Explicit references | `$('node_name')` not `$json` - traceable, stable |
-| snake_case | `node_name` not `NodeName` - consistent, readable |
+```javascript
+// Explicit reference (always use this)
+{{ $('node_name').item.json.field }}
 
----
+// Environment variable
+{{ $env.API_KEY }}
 
-## Naming Convention
+// Config node reference
+{{ $('config').item.json.setting }}
 
-**snake_case everywhere**
+// Fallback
+{{ $('source').item.json.text || 'default' }}
 
-```
-Workflows: content_factory, publish_linkedin, upload_image
-Nodes: trigger_webhook, fetch_articles, check_approved
+// Date
+{{ $now.format('yyyy-MM-dd') }}
 ```
 
-Never `NodeName`. Always `node_name`.
+## The Rules
 
----
+### 1. snake_case (auto-fixed)
 
-## Expression References
+```
+Good: fetch_articles, check_approved, generate_content
+Bad:  FetchArticles, Check Approved, generate-content
+```
 
-**NEVER use `$json`. Always explicit node references.**
+Why: Consistency, readability. **Auto-fixed:** renamed automatically with all references updated.
+
+### 2. Explicit References (auto-fixed)
 
 ```javascript
 // Bad - breaks when flow changes
 {{ $json.field }}
 
-// Good - traceable and debuggable
+// Good - traceable, stable
 {{ $('node_name').item.json.field }}
-
-// Parallel branch (lookup nodes)
-{{ $('lookup_node').all().length > 0 }}
-
-// Environment variable
-{{ $env.API_KEY }}
-
-// Fallback pattern
-{{ $('source').item.json.text || $('source').item.json.media_url }}
 ```
 
----
+Why: `$json` references "previous node" implicitly. Reorder nodes, it breaks. **Auto-fixed:** converted to explicit `$('prev_node')` references.
 
-## Secrets and Configuration
+### 3. Config Node
 
-**Secrets in environment variables. Always.**
-
-```javascript
-// Bad
-{ "apiKey": "sk_live_abc123" }
-
-// Good
-{{ $env.API_KEY }}
-```
-
-**For workflow-specific settings, use a config node:**
+Single source for workflow settings:
 
 ```
 [trigger] → [config] → [rest of workflow]
 ```
 
-Config node uses JSON output mode:
+Config node (JSON mode):
 ```javascript
 ={
-  "channel_id": "{{ $json.body.channelId || '1234567890' }}",
+  "channel_id": "{{ $json.body.channelId || '123456' }}",
   "max_items": 10,
   "ai_model": "gpt-4.1-mini"
 }
 ```
 
-Then reference: `{{ $('config').item.json.channel_id }}`
-
----
+Reference everywhere: `{{ $('config').item.json.channel_id }}`
 
-## Workflow Editing Safety
+Why: Change once, not in 5 nodes.
 
-### The Golden Rule
+### 4. Secrets in Environment (recommended)
 
-**Never edit a workflow without explicit confirmation and backup.**
+```javascript
+// Hardcoded (works, but less portable)
+{ "apiKey": "sk_live_abc123" }
 
-### Pre-Edit Checklist
+// Environment variable (recommended)
+{{ $env.API_KEY }}
+```
 
-1. **Confirm** - Get explicit user approval
-2. **List versions** - Know your rollback point
-3. **Read full state** - Understand current config
-4. **Make targeted change** - Use patch operations only
-5. **Verify** - Confirm expected state
+Why: Env vars make workflows portable across environments and avoid committing secrets.
 
-### Parameter Preservation
+## Parameter Preservation
 
-**CRITICAL:** Partial updates REPLACE the entire `parameters` object.
+**Critical:** Partial updates REPLACE the entire `parameters` object.
 
 ```javascript
-// Bad: Only updates messageId, loses operation and labelIds
+// Bad - loses operation and labelIds
 {
   "type": "updateNode",
   "nodeName": "archive_email",
@@ -112,7 +93,7 @@ Then reference: `{{ $('config').item.json.channel_id }}`
   }
 }
 
-// Good: Include ALL required parameters
+// Good - include ALL parameters
 {
   "type": "updateNode",
   "nodeName": "archive_email",
@@ -120,122 +101,65 @@ Then reference: `{{ $('config').item.json.channel_id }}`
     "parameters": {
       "operation": "addLabels",
       "messageId": "={{ $json.message_id }}",
-      "labelIds": ["Label_123", "Label_456"]
+      "labelIds": ["Label_123"]
     }
   }
 }
 ```
 
----
-
-## Code Nodes
-
-**Code nodes are a last resort.** Exhaust built-in options first:
+Before updating: read current state with `workflow_get`.
 
-| Need | Use Instead |
-|------|-------------|
-| Transform fields | Set node with expressions |
-| Filter items | Filter node or If/Switch |
-| Merge data | Merge node |
-| Loop processing | n8n processes arrays natively |
-| Date formatting | `{{ $now.format('yyyy-MM-dd') }}` |
+## AI Nodes
 
-**When code IS necessary:**
-- Re-establishing `pairedItem` after chain breaks
-- Complex conditional logic
-- API response parsing expressions can't handle
+### Structured Output (auto-fixed)
 
-**Code node rules:**
-- Single responsibility (one clear purpose)
-- Name it for what it does: `merge_context`, `parse_response`
-- No side effects - pure data transformation
+Always set for predictable JSON. **Auto-fixed:** `promptType: "define"` and `hasOutputParser: true` added automatically.
 
----
+| Setting | Value |
+|---------|-------|
+| `promptType` | `"define"` |
+| `hasOutputParser` | `true` |
+| `schemaType` | `"manual"` (for nullable fields) |
 
-## AI Agent Best Practices
-
-### Structured Output
-
-**Always enable "Require Specific Output Format"** for reliable JSON:
-
-```javascript
-{
-  "promptType": "define",
-  "hasOutputParser": true,
-  "schemaType": "manual"  // Required for nullable fields
-}
-```
-
-Without these, AI outputs are unpredictable.
-
-### Memory Storage
-
-**Never use in-memory storage in production:**
+### Memory
 
 | Don't Use | Use Instead |
 |-----------|-------------|
 | Windowed Buffer Memory | Postgres Chat Memory |
 | In-Memory Vector Store | Postgres pgvector |
 
-In-memory dies with restart and doesn't scale.
-
----
-
-## Architecture Patterns
-
-### Single Responsibility
-
-Don't build monolith workflows:
-
-```
-Bad: One workflow doing signup → email → CRM → calendar → reports
-
-Good: Five focused workflows that communicate via webhooks
-```
-
-### Switch > If Node
-
-Always use Switch instead of If:
-- Named outputs (not just true/false)
-- Unlimited conditional branches
-- Send to all matching option
+In-memory dies on restart, doesn't scale.
 
----
+## Code Nodes: Last Resort
 
-## Validation Rules Enforced
-
-| 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 |
-| `orphan_node` | warning | Node has no connections |
-| `parameter_preservation` | error | Update would remove parameters |
-| `code_node_usage` | info | Code node detected |
-| `ai_structured_output` | warning | AI node missing structured output |
-| `in_memory_storage` | warning | Using non-persistent storage |
-
----
-
-## Quick Reference
+| Need | Use Instead |
+|------|-------------|
+| Transform fields | Set node with expressions |
+| Filter items | Filter node or Switch |
+| Merge data | Merge node |
+| Loop | n8n processes arrays natively |
+| Date formatting | `{{ $now.format('yyyy-MM-dd') }}` |
 
-```javascript
-// Explicit reference
-{{ $('node_name').item.json.field }}
+When code IS necessary:
+- Re-establishing `pairedItem` after chain breaks
+- Complex conditional logic
+- API parsing expressions can't handle
 
-// Environment variable
-{{ $env.VAR_NAME }}
+## Pre-Edit Checklist
 
-// Config node reference
-{{ $('config').item.json.setting }}
+| Step | Why |
+|------|-----|
+| 1. Get explicit user approval | Don't surprise |
+| 2. List versions | Know rollback point |
+| 3. Read full workflow | Understand current state |
+| 4. Make targeted change | Minimal surface area |
 
-// Parallel branch query
-{{ $('lookup').all().some(i => i.json.id === $json.id) }}
+> **Note:** Validation and cleanup are now automatic. Every create/update validates, auto-fixes, and formats automatically.
 
-// Date formatting
-{{ $now.format('yyyy-MM-dd') }}
+## Node-Specific Settings
 
-// Fallback
-{{ $json.text || $json.description || 'default' }}
-```
+See [Node Config](node-config.md) for:
+- Resource locator (`__rl`) format with `cachedResultName`
+- Google Sheets, Gmail, Discord required fields
+- Set node JSON mode vs manual mapping
+- Error handling options