@pagelines/n8n-mcp 0.3.0 → 0.3.2

package/dist/validators.test.js

@@ -1,310 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { validateWorkflow, validatePartialUpdate, validateNodeTypes } from './validators.js';
-const createWorkflow = (overrides = {}) => ({
-    id: '1',
-    name: 'test_workflow',
-    active: false,
-    nodes: [],
-    connections: {},
-    createdAt: '2024-01-01',
-    updatedAt: '2024-01-01',
-    ...overrides,
-});
-describe('validateWorkflow', () => {
-    it('passes for valid snake_case workflow', () => {
-        const workflow = createWorkflow({
-            name: 'my_workflow',
-            nodes: [
-                {
-                    id: '1',
-                    name: 'webhook_trigger',
-                    type: 'n8n-nodes-base.webhook',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: { path: 'test' },
-                },
-            ],
-        });
-        const result = validateWorkflow(workflow);
-        expect(result.valid).toBe(true);
-    });
-    it('warns on non-snake_case workflow name', () => {
-        const workflow = createWorkflow({ name: 'My-Workflow-Name' });
-        const result = validateWorkflow(workflow);
-        expect(result.warnings).toContainEqual(expect.objectContaining({
-            rule: 'snake_case',
-            severity: 'warning',
-        }));
-    });
-    it('warns on $json usage', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'set_node',
-                    type: 'n8n-nodes-base.set',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: { value: '={{ $json.field }}' },
-                },
-            ],
-        });
-        const result = validateWorkflow(workflow);
-        expect(result.warnings).toContainEqual(expect.objectContaining({
-            rule: 'explicit_reference',
-            severity: 'warning',
-        }));
-    });
-    it('warns on hardcoded secrets', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'http_node',
-                    type: 'n8n-nodes-base.httpRequest',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: { apiKey: 'sk_live_abc123def456' },
-                },
-            ],
-        });
-        const result = validateWorkflow(workflow);
-        expect(result.warnings).toContainEqual(expect.objectContaining({
-            rule: 'no_hardcoded_secrets',
-            severity: 'info',
-        }));
-    });
-    it('warns on orphan nodes', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'orphan_node',
-                    type: 'n8n-nodes-base.set',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: {},
-                },
-            ],
-            connections: {},
-        });
-        const result = validateWorkflow(workflow);
-        expect(result.warnings).toContainEqual(expect.objectContaining({
-            rule: 'orphan_node',
-            severity: 'warning',
-        }));
-    });
-    it('info on code node usage', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'my_code',
-                    type: 'n8n-nodes-base.code',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: { jsCode: 'return items;' },
-                },
-            ],
-        });
-        const result = validateWorkflow(workflow);
-        expect(result.warnings).toContainEqual(expect.objectContaining({
-            rule: 'code_node_usage',
-            severity: 'info',
-        }));
-    });
-    it('warns on AI node without structured output settings', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'ai_agent',
-                    type: '@n8n/n8n-nodes-langchain.agent',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: {
-                        outputParser: true,
-                        schemaType: 'manual',
-                        // Missing promptType: 'define' and hasOutputParser: true
-                    },
-                },
-            ],
-        });
-        const result = validateWorkflow(workflow);
-        expect(result.warnings).toContainEqual(expect.objectContaining({
-            rule: 'ai_structured_output',
-            severity: 'warning',
-        }));
-    });
-    it('passes AI node with correct structured output settings', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'ai_agent',
-                    type: '@n8n/n8n-nodes-langchain.agent',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: {
-                        outputParser: true,
-                        schemaType: 'manual',
-                        promptType: 'define',
-                        hasOutputParser: true,
-                    },
-                },
-            ],
-        });
-        const result = validateWorkflow(workflow);
-        const aiWarnings = result.warnings.filter((w) => w.rule === 'ai_structured_output');
-        expect(aiWarnings).toHaveLength(0);
-    });
-    it('warns on in-memory storage nodes', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'memory_buffer',
-                    type: '@n8n/n8n-nodes-langchain.memoryBufferWindow',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: {},
-                },
-            ],
-        });
-        const result = validateWorkflow(workflow);
-        expect(result.warnings).toContainEqual(expect.objectContaining({
-            rule: 'in_memory_storage',
-            severity: 'warning',
-        }));
-    });
-});
-describe('validatePartialUpdate', () => {
-    it('errors when node not found', () => {
-        const workflow = createWorkflow();
-        const warnings = validatePartialUpdate(workflow, 'nonexistent', {});
-        expect(warnings).toContainEqual(expect.objectContaining({
-            rule: 'node_exists',
-            severity: 'error',
-        }));
-    });
-    it('errors on parameter loss', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'my_node',
-                    type: 'n8n-nodes-base.set',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: { existingParam: 'value', anotherParam: 'value2' },
-                },
-            ],
-        });
-        const warnings = validatePartialUpdate(workflow, 'my_node', {
-            newParam: 'value', // Missing existingParam and anotherParam
-        });
-        expect(warnings).toContainEqual(expect.objectContaining({
-            rule: 'parameter_preservation',
-            severity: 'error',
-        }));
-    });
-    it('passes when all parameters preserved', () => {
-        const workflow = createWorkflow({
-            nodes: [
-                {
-                    id: '1',
-                    name: 'my_node',
-                    type: 'n8n-nodes-base.set',
-                    typeVersion: 1,
-                    position: [0, 0],
-                    parameters: { existingParam: 'value' },
-                },
-            ],
-        });
-        const warnings = validatePartialUpdate(workflow, 'my_node', {
-            existingParam: 'value',
-            newParam: 'new',
-        });
-        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,165 +0,0 @@
-# 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
-// Explicit reference (always use this)
-{{ $('node_name').item.json.field }}
-
-// Environment variable
-{{ $env.API_KEY }}
-
-// Config node reference
-{{ $('config').item.json.setting }}
-
-// Fallback
-{{ $('source').item.json.text || 'default' }}
-
-// Date
-{{ $now.format('yyyy-MM-dd') }}
-```
-
-## The Rules
-
-### 1. snake_case (auto-fixed)
-
-```
-Good: fetch_articles, check_approved, generate_content
-Bad:  FetchArticles, Check Approved, generate-content
-```
-
-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, stable
-{{ $('node_name').item.json.field }}
-```
-
-Why: `$json` references "previous node" implicitly. Reorder nodes, it breaks. **Auto-fixed:** converted to explicit `$('prev_node')` references.
-
-### 3. Config Node
-
-Single source for workflow settings:
-
-```
-[trigger] → [config] → [rest of workflow]
-```
-
-Config node (JSON mode):
-```javascript
-={
-  "channel_id": "{{ $json.body.channelId || '123456' }}",
-  "max_items": 10,
-  "ai_model": "gpt-4.1-mini"
-}
-```
-
-Reference everywhere: `{{ $('config').item.json.channel_id }}`
-
-Why: Change once, not in 5 nodes.
-
-### 4. Secrets in Environment (recommended)
-
-```javascript
-// Hardcoded (works, but less portable)
-{ "apiKey": "sk_live_abc123" }
-
-// 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.
-
-```javascript
-// Bad - loses operation and labelIds
-{
-  "type": "updateNode",
-  "nodeName": "archive_email",
-  "properties": {
-    "parameters": {
-      "messageId": "={{ $json.message_id }}"
-    }
-  }
-}
-
-// Good - include ALL parameters
-{
-  "type": "updateNode",
-  "nodeName": "archive_email",
-  "properties": {
-    "parameters": {
-      "operation": "addLabels",
-      "messageId": "={{ $json.message_id }}",
-      "labelIds": ["Label_123"]
-    }
-  }
-}
-```
-
-Before updating: read current state with `workflow_get`.
-
-## AI Nodes
-
-### Structured Output (auto-fixed)
-
-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) |
-
-### Memory
-
-| Don't Use | Use Instead |
-|-----------|-------------|
-| Windowed Buffer Memory | Postgres Chat Memory |
-| In-Memory Vector Store | Postgres pgvector |
-
-In-memory dies on restart, doesn't scale.
-
-## Code Nodes: Last Resort
-
-| 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') }}` |
-
-When code IS necessary:
-- Re-establishing `pairedItem` after chain breaks
-- Complex conditional logic
-- API parsing expressions can't handle
-
-## Pre-Edit Checklist
-
-| 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 |
-
-> **Note:** Validation and cleanup are now automatic. Every create/update validates, auto-fixes, and formats automatically.
-
-## Node-Specific Settings
-
-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

package/docs/node-config.md

@@ -1,205 +0,0 @@
-# Node Configuration Guidelines
-
-> 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
-
-n8n uses `__rl` (resource locator) format for dropdown fields. Always include `cachedResultName` so humans see friendly names.
-
-```javascript
-// Human-editable: shows "My Spreadsheet" in UI
-"documentId": {
-  "__rl": true,
-  "value": "1abc123...",
-  "mode": "list",
-  "cachedResultName": "My Spreadsheet",
-  "cachedResultUrl": "https://docs.google.com/spreadsheets/d/1abc123"
-}
-
-// Hard to edit: shows raw ID only
-"documentId": {
-  "__rl": true,
-  "value": "1abc123...",
-  "mode": "id"
-}
-```
-
-| Mode | When to Use |
-|------|-------------|
-| `list` | Default. Shows dropdown with cached name |
-| `id` | Only when ID is dynamic (from expression) |
-
-## Set Node
-
-**Use JSON mode** for MCP-created nodes. Manual mapping is error-prone via API.
-
-```javascript
-// JSON mode (reliable)
-{
-  "mode": "raw",
-  "jsonOutput": "={ \"channel_id\": \"{{ $json.channelId || '123' }}\" }"
-}
-
-// Manual mapping (fragile via API)
-{
-  "mode": "manual",
-  "assignments": { ... }  // Complex structure, easy to break
-}
-```
-
-## Google Sheets
-
-Required fields (partial updates lose these):
-
-```javascript
-{
-  "operation": "append",
-  "documentId": {
-    "__rl": true,
-    "value": "1abc...",
-    "mode": "list",
-    "cachedResultName": "Sheet Name"
-  },
-  "sheetName": {
-    "__rl": true,
-    "value": "gid=0",
-    "mode": "list",
-    "cachedResultName": "Sheet1"
-  },
-  "columns": { /* mappings */ }
-}
-```
-
-## Gmail
-
-Required fields:
-
-```javascript
-{
-  "operation": "addLabels",  // or send, get, etc.
-  "messageId": "={{ $('source').item.json.id }}",
-  "labelIds": ["Label_123", "Label_456"]
-}
-```
-
-Labels need full IDs (`Label_xxx`), not display names.
-
-## Discord
-
-```javascript
-{
-  "authentication": "webhook",
-  "webhookUri": {
-    "__rl": true,
-    "value": "={{ $env.DISCORD_WEBHOOK }}",
-    "mode": "id"
-  },
-  "content": "Message text"
-}
-```
-
-For bot mode with guild/channel selection:
-
-```javascript
-{
-  "guildId": {
-    "__rl": true,
-    "value": "123456789",
-    "mode": "list",
-    "cachedResultName": "My Server"
-  },
-  "channelId": {
-    "__rl": true,
-    "value": "987654321",
-    "mode": "list",
-    "cachedResultName": "#general"
-  }
-}
-```
-
-## AI Nodes (Agent, Chain)
-
-Always include structured output settings:
-
-```javascript
-{
-  "promptType": "define",
-  "hasOutputParser": true,
-  "schemaType": "manual",  // Required for nullable fields
-  "schema": { /* JSON Schema */ }
-}
-```
-
-Without these, AI outputs are unpredictable strings.
-
-## HTTP Request
-
-Include authentication method explicitly:
-
-```javascript
-{
-  "method": "POST",
-  "url": "https://api.example.com",
-  "authentication": "predefinedCredentialType",
-  "nodeCredentialType": "anthropicApi",
-  "sendBody": true,
-  "bodyParameters": { ... }
-}
-```
-
-## Switch vs If
-
-Always use Switch (not If):
-
-```javascript
-// Switch: named outputs, extensible
-{
-  "type": "n8n-nodes-base.switch",
-  "parameters": {
-    "rules": {
-      "rules": [
-        { "output": 0, "conditions": { ... } },
-        { "output": 1, "conditions": { ... } }
-      ]
-    }
-  }
-}
-```
-
-If node only has true/false outputs - Switch scales better.
-
-## Expression Patterns
-
-Always explicit references:
-
-```javascript
-// Good
-"={{ $('config').item.json.channel_id }}"
-
-// Bad - breaks on node reorder
-"={{ $json.channel_id }}"
-```
-
-Environment variables for secrets:
-
-```javascript
-"={{ $env.API_KEY }}"
-```
-
-## Error Handling
-
-Set `onError` for API nodes:
-
-```javascript
-{
-  "parameters": { ... },
-  "onError": "continueRegularOutput"  // or "continueErrorOutput"
-}
-```
-
-Options:
-- `stopWorkflow` - default, halts on error
-- `continueRegularOutput` - ignore errors, continue
-- `continueErrorOutput` - route errors to second output