@pagelines/n8n-mcp 0.1.0 → 0.2.0

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,241 @@
+# n8n Best Practices
+
+> Enforced by `@pagelines/n8n-mcp`
+
+## Guiding Principle
+
+**What is most stable and easiest to maintain?**
+
+| 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 |
+
+---
+
+## Naming Convention
+
+**snake_case everywhere**
+
+```
+Workflows: content_factory, publish_linkedin, upload_image
+Nodes: trigger_webhook, fetch_articles, check_approved
+```
+
+Never `NodeName`. Always `node_name`.
+
+---
+
+## Expression References
+
+**NEVER use `$json`. Always explicit node references.**
+
+```javascript
+// Bad - breaks when flow changes
+{{ $json.field }}
+
+// Good - traceable and debuggable
+{{ $('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 }}
+```
+
+---
+
+## Secrets and Configuration
+
+**Secrets in environment variables. Always.**
+
+```javascript
+// Bad
+{ "apiKey": "sk_live_abc123" }
+
+// Good
+{{ $env.API_KEY }}
+```
+
+**For workflow-specific settings, use a config node:**
+
+```
+[trigger] → [config] → [rest of workflow]
+```
+
+Config node uses JSON output mode:
+```javascript
+={
+  "channel_id": "{{ $json.body.channelId || '1234567890' }}",
+  "max_items": 10,
+  "ai_model": "gpt-4.1-mini"
+}
+```
+
+Then reference: `{{ $('config').item.json.channel_id }}`
+
+---
+
+## Workflow Editing Safety
+
+### The Golden Rule
+
+**Never edit a workflow without explicit confirmation and backup.**
+
+### Pre-Edit Checklist
+
+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
+
+### Parameter Preservation
+
+**CRITICAL:** Partial updates REPLACE the entire `parameters` object.
+
+```javascript
+// Bad: Only updates messageId, loses operation and labelIds
+{
+  "type": "updateNode",
+  "nodeName": "archive_email",
+  "properties": {
+    "parameters": {
+      "messageId": "={{ $json.message_id }}"
+    }
+  }
+}
+
+// Good: Include ALL required parameters
+{
+  "type": "updateNode",
+  "nodeName": "archive_email",
+  "properties": {
+    "parameters": {
+      "operation": "addLabels",
+      "messageId": "={{ $json.message_id }}",
+      "labelIds": ["Label_123", "Label_456"]
+    }
+  }
+}
+```
+
+---
+
+## Code Nodes
+
+**Code nodes are a last resort.** Exhaust built-in options first:
+
+| 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') }}` |
+
+**When code IS necessary:**
+- Re-establishing `pairedItem` after chain breaks
+- Complex conditional logic
+- API response parsing expressions can't handle
+
+**Code node rules:**
+- Single responsibility (one clear purpose)
+- Name it for what it does: `merge_context`, `parse_response`
+- No side effects - pure data transformation
+
+---
+
+## 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:**
+
+| 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
+
+---
+
+## 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
+
+```javascript
+// Explicit reference
+{{ $('node_name').item.json.field }}
+
+// Environment variable
+{{ $env.VAR_NAME }}
+
+// Config node reference
+{{ $('config').item.json.setting }}
+
+// Parallel branch query
+{{ $('lookup').all().some(i => i.json.id === $json.id) }}
+
+// Date formatting
+{{ $now.format('yyyy-MM-dd') }}
+
+// Fallback
+{{ $json.text || $json.description || 'default' }}
+```

package/package.json

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

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.pagelines/n8n-mcp",
   "displayName": "pl-n8n-mcp",
   "description": "Opinionated MCP server for n8n workflow automation with built-in validation and safety features",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": {
     "name": "PageLines",
     "url": "https://github.com/pagelines"
@@ -46,8 +46,16 @@
     "workflow_deactivate",
     "workflow_execute",
     "workflow_validate",
+    "workflow_autofix",
+    "workflow_format",
     "execution_list",
-    "execution_get"
+    "execution_get",
+    "version_list",
+    "version_get",
+    "version_save",
+    "version_rollback",
+    "version_diff",
+    "version_stats"
   ],
   "keywords": [
     "n8n",