@pagelines/n8n-mcp 0.1.0 → 0.2.1

package/dist/validators.test.js

@@ -95,6 +95,89 @@ describe('validateWorkflow', () => {
             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', () => {

package/dist/versions.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Local version control for n8n workflows
+ * Stores workflow snapshots in ~/.n8n-mcp/versions/
+ */
+import type { N8nWorkflow } from './types.js';
+export interface WorkflowVersion {
+    id: string;
+    workflowId: string;
+    workflowName: string;
+    timestamp: string;
+    reason: string;
+    nodeCount: number;
+    hash: string;
+}
+export interface VersionConfig {
+    enabled: boolean;
+    maxVersions: number;
+    storageDir: string;
+}
+/**
+ * Initialize version control with custom config
+ */
+export declare function initVersionControl(customConfig?: Partial<VersionConfig>): void;
+/**
+ * Save a workflow version
+ */
+export declare function saveVersion(workflow: N8nWorkflow, reason?: string): Promise<WorkflowVersion | null>;
+/**
+ * List all versions for a workflow
+ */
+export declare function listVersions(workflowId: string): Promise<WorkflowVersion[]>;
+/**
+ * Get a specific version's full workflow data
+ */
+export declare function getVersion(workflowId: string, versionId: string): Promise<{
+    meta: WorkflowVersion;
+    workflow: N8nWorkflow;
+} | null>;
+/**
+ * Get the most recent version
+ */
+export declare function getLatestVersion(workflowId: string): Promise<{
+    meta: WorkflowVersion;
+    workflow: N8nWorkflow;
+} | null>;
+/**
+ * Compare two workflow versions
+ */
+export interface VersionDiff {
+    nodesAdded: string[];
+    nodesRemoved: string[];
+    nodesModified: string[];
+    connectionsChanged: boolean;
+    settingsChanged: boolean;
+    summary: string;
+}
+export declare function diffWorkflows(oldWorkflow: N8nWorkflow, newWorkflow: N8nWorkflow): VersionDiff;
+/**
+ * Delete all versions for a workflow
+ */
+export declare function deleteAllVersions(workflowId: string): Promise<number>;
+/**
+ * Get version control status/stats
+ */
+export declare function getVersionStats(): Promise<{
+    enabled: boolean;
+    storageDir: string;
+    maxVersions: number;
+    workflowCount: number;
+    totalVersions: number;
+}>;

package/dist/versions.js

@@ -0,0 +1,239 @@
+/**
+ * Local version control for n8n workflows
+ * Stores workflow snapshots in ~/.n8n-mcp/versions/
+ */
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const DEFAULT_CONFIG = {
+    enabled: true,
+    maxVersions: 20,
+    storageDir: path.join(os.homedir(), '.n8n-mcp', 'versions'),
+};
+let config = { ...DEFAULT_CONFIG };
+/**
+ * Initialize version control with custom config
+ */
+export function initVersionControl(customConfig = {}) {
+    config = { ...DEFAULT_CONFIG, ...customConfig };
+}
+/**
+ * Get the storage directory for a workflow
+ */
+function getWorkflowDir(workflowId) {
+    return path.join(config.storageDir, workflowId);
+}
+/**
+ * Generate a simple hash for workflow content
+ */
+function hashWorkflow(workflow) {
+    const content = JSON.stringify({
+        nodes: workflow.nodes,
+        connections: workflow.connections,
+        settings: workflow.settings,
+    });
+    // Simple hash - good enough for comparison
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        const char = content.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash).toString(16).padStart(8, '0');
+}
+/**
+ * Save a workflow version
+ */
+export async function saveVersion(workflow, reason = 'manual') {
+    if (!config.enabled)
+        return null;
+    const workflowDir = getWorkflowDir(workflow.id);
+    await fs.mkdir(workflowDir, { recursive: true });
+    const timestamp = new Date().toISOString();
+    const hash = hashWorkflow(workflow);
+    // Check if this exact version already exists (avoid duplicates)
+    const existing = await listVersions(workflow.id);
+    if (existing.length > 0 && existing[0].hash === hash) {
+        return null; // No changes, skip
+    }
+    const versionId = `${timestamp.replace(/[:.]/g, '-')}_${hash.slice(0, 6)}`;
+    const versionFile = path.join(workflowDir, `${versionId}.json`);
+    const versionMeta = {
+        id: versionId,
+        workflowId: workflow.id,
+        workflowName: workflow.name,
+        timestamp,
+        reason,
+        nodeCount: workflow.nodes.length,
+        hash,
+    };
+    const versionData = {
+        meta: versionMeta,
+        workflow,
+    };
+    await fs.writeFile(versionFile, JSON.stringify(versionData, null, 2));
+    // Prune old versions
+    await pruneVersions(workflow.id);
+    return versionMeta;
+}
+/**
+ * List all versions for a workflow
+ */
+export async function listVersions(workflowId) {
+    const workflowDir = getWorkflowDir(workflowId);
+    try {
+        const files = await fs.readdir(workflowDir);
+        const versions = [];
+        for (const file of files) {
+            if (!file.endsWith('.json'))
+                continue;
+            const filePath = path.join(workflowDir, file);
+            const content = await fs.readFile(filePath, 'utf-8');
+            const data = JSON.parse(content);
+            if (data.meta) {
+                versions.push(data.meta);
+            }
+        }
+        // Sort by timestamp descending (newest first)
+        return versions.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Get a specific version's full workflow data
+ */
+export async function getVersion(workflowId, versionId) {
+    const workflowDir = getWorkflowDir(workflowId);
+    const versionFile = path.join(workflowDir, `${versionId}.json`);
+    try {
+        const content = await fs.readFile(versionFile, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Get the most recent version
+ */
+export async function getLatestVersion(workflowId) {
+    const versions = await listVersions(workflowId);
+    if (versions.length === 0)
+        return null;
+    return getVersion(workflowId, versions[0].id);
+}
+/**
+ * Prune old versions beyond maxVersions
+ */
+async function pruneVersions(workflowId) {
+    const versions = await listVersions(workflowId);
+    if (versions.length <= config.maxVersions) {
+        return 0;
+    }
+    const toDelete = versions.slice(config.maxVersions);
+    const workflowDir = getWorkflowDir(workflowId);
+    for (const version of toDelete) {
+        const versionFile = path.join(workflowDir, `${version.id}.json`);
+        await fs.unlink(versionFile);
+    }
+    return toDelete.length;
+}
+export function diffWorkflows(oldWorkflow, newWorkflow) {
+    const oldNodes = new Map(oldWorkflow.nodes.map((n) => [n.name, n]));
+    const newNodes = new Map(newWorkflow.nodes.map((n) => [n.name, n]));
+    const nodesAdded = [];
+    const nodesRemoved = [];
+    const nodesModified = [];
+    // Find added and modified nodes
+    for (const [name, node] of newNodes) {
+        if (!oldNodes.has(name)) {
+            nodesAdded.push(name);
+        }
+        else {
+            const oldNode = oldNodes.get(name);
+            if (JSON.stringify(oldNode.parameters) !== JSON.stringify(node.parameters)) {
+                nodesModified.push(name);
+            }
+        }
+    }
+    // Find removed nodes
+    for (const name of oldNodes.keys()) {
+        if (!newNodes.has(name)) {
+            nodesRemoved.push(name);
+        }
+    }
+    const connectionsChanged = JSON.stringify(oldWorkflow.connections) !== JSON.stringify(newWorkflow.connections);
+    const settingsChanged = JSON.stringify(oldWorkflow.settings) !== JSON.stringify(newWorkflow.settings);
+    // Generate summary
+    const parts = [];
+    if (nodesAdded.length)
+        parts.push(`+${nodesAdded.length} nodes`);
+    if (nodesRemoved.length)
+        parts.push(`-${nodesRemoved.length} nodes`);
+    if (nodesModified.length)
+        parts.push(`~${nodesModified.length} modified`);
+    if (connectionsChanged)
+        parts.push('connections changed');
+    if (settingsChanged)
+        parts.push('settings changed');
+    return {
+        nodesAdded,
+        nodesRemoved,
+        nodesModified,
+        connectionsChanged,
+        settingsChanged,
+        summary: parts.length ? parts.join(', ') : 'no changes',
+    };
+}
+/**
+ * Delete all versions for a workflow
+ */
+export async function deleteAllVersions(workflowId) {
+    const versions = await listVersions(workflowId);
+    const workflowDir = getWorkflowDir(workflowId);
+    for (const version of versions) {
+        const versionFile = path.join(workflowDir, `${version.id}.json`);
+        await fs.unlink(versionFile);
+    }
+    // Remove the directory if empty
+    try {
+        await fs.rmdir(workflowDir);
+    }
+    catch {
+        // Ignore if not empty
+    }
+    return versions.length;
+}
+/**
+ * Get version control status/stats
+ */
+export async function getVersionStats() {
+    let workflowCount = 0;
+    let totalVersions = 0;
+    try {
+        const workflows = await fs.readdir(config.storageDir);
+        workflowCount = workflows.length;
+        for (const workflowId of workflows) {
+            const versions = await listVersions(workflowId);
+            totalVersions += versions.length;
+        }
+    }
+    catch {
+        // Storage dir doesn't exist yet
+    }
+    return {
+        enabled: config.enabled,
+        storageDir: config.storageDir,
+        maxVersions: config.maxVersions,
+        workflowCount,
+        totalVersions,
+    };
+}

package/docs/best-practices.md

@@ -0,0 +1,160 @@
+# n8n Best Practices
+
+## 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
+
+```
+Good: fetch_articles, check_approved, generate_content
+Bad:  FetchArticles, Check Approved, generate-content
+```
+
+Why: Consistency, readability, auto-fixable.
+
+### 2. Explicit References
+
+```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.
+
+### 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
+
+```javascript
+// Bad
+{ "apiKey": "sk_live_abc123" }
+
+// Good
+{{ $env.API_KEY }}
+```
+
+## 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
+
+Always set for predictable JSON:
+
+| 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 |
+| 5. Validate after | Catch issues immediately |
+
+## 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