@pagelines/n8n-mcp 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.2.1] - 2025-01-13
+
+### Added
+- [Node Config Guide](docs/node-config.md) - Human-editable node settings (`__rl` resource locator, Set node JSON mode, AI structured output)
+
+### Changed
+- Sharpened documentation (31% line reduction, higher data-ink ratio)
+- README: Lead with differentiation, compact tool/validation tables
+- Best Practices: Quick reference at top, focused on MCP-validated patterns
+- Architecture: Technical reference, removed redundant philosophy sections
+
+## [0.2.0] - 2025-01-12
+
+### Added
+
+#### Version Control System
+- `version_list` - List saved versions of a workflow (stored locally in `~/.n8n-mcp/versions/`)
+- `version_get` - Get a specific saved version
+- `version_save` - Manually save a version snapshot
+- `version_rollback` - Restore a workflow to a previous version
+- `version_diff` - Compare two versions or current state vs a version
+- `version_stats` - Get version control statistics
+- Auto-save versions before workflow updates, rollbacks, and auto-fixes
+- Configurable via `N8N_MCP_VERSIONS` and `N8N_MCP_MAX_VERSIONS` env vars
+
+#### Auto-fix System
+- `workflow_autofix` - Auto-fix common validation issues:
+  - Convert names to snake_case
+  - Replace `$json` with explicit `$('node_name')` references
+  - Add AI structured output settings
+- `workflow_format` - Format workflows: sort nodes by position, clean up null values
+
+#### Expression Validation
+- Parse and validate n8n expressions in workflow parameters
+- Detect references to non-existent nodes
+- Check for syntax errors (unmatched parentheses, brackets)
+- Warn about deprecated patterns (`$node.` usage)
+- Detect circular references in expressions
+- Suggest optional chaining for deep property access
+
+### Changed
+- `workflow_validate` now includes expression validation and circular reference detection
+- `workflow_update` now auto-saves a version before applying changes
+
+## [0.1.0] - 2025-01-11
+
+### Added
+- Initial release
+- Workflow operations: list, get, create, update, delete, activate, deactivate, execute
+- Execution operations: list, get
+- Workflow validation with best practices enforcement:
+  - snake_case naming
+  - Explicit node references
+  - No hardcoded IDs or secrets
+  - Orphan node detection
+  - Code node usage detection
+  - AI node structured output settings
+  - In-memory storage detection
+- Patch-based workflow updates with parameter preservation warnings

package/README.md

@@ -1,47 +1,37 @@
-# pl-n8n-mcp
+# n8n MCP Server
 
-> **@pagelines/n8n-mcp** - Opinionated MCP server for n8n workflow automation by [PageLines](https://github.com/pagelines)
+Workflow validation, version control, and patch-based updates for n8n.
 
-## Features
+## The Problem
 
-- **Minimal footprint** - ~1,200 lines total, no database, no bloat
-- **Patch-based updates** - Never lose parameters, always preserves existing data
-- **Built-in validation** - Enforces best practices automatically
-- **Safety warnings** - Alerts when updates might cause issues
+Other n8n MCPs replace entire nodes on update—losing parameters you didn't touch. No rollback. 70MB of SQLite for node docs you can Google.
 
-## Best Practices Enforced
+## This MCP
 
-- `snake_case` naming for workflows and nodes
-- Explicit node references (`$('node_name').item.json.field` not `$json`)
-- No hardcoded IDs or secrets
-- No orphan nodes
+| Feature | This | Others |
+|---------|------|--------|
+| Update approach | Patch (preserves params) | Replace (loses params) |
+| Version control | Auto-snapshot before mutations | Manual/none |
+| Validation | Expression syntax, circular refs, secrets | Basic |
+| Auto-fix | snake_case, $json→$('node'), AI settings | None |
+| Size | ~1,200 LOC, zero deps | 10k+ LOC, 70MB SQLite |
 
-## Installation
-
-```bash
-npm install @pagelines/n8n-mcp
-```
-
-Or run directly:
+## Install
 
 ```bash
 npx @pagelines/n8n-mcp
 ```
 
-## Configuration
-
-### Claude Code / Cursor
-
-Add to your MCP settings (`~/.claude/mcp.json` or IDE config):
+Add to `~/.claude/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "pl-n8n": {
+    "n8n": {
       "command": "npx",
       "args": ["-y", "@pagelines/n8n-mcp"],
       "env": {
-        "N8N_API_URL": "https://your-n8n-instance.com",
+        "N8N_API_URL": "https://your-n8n.com",
         "N8N_API_KEY": "your-api-key"
       }
     }
@@ -49,107 +39,42 @@ Add to your MCP settings (`~/.claude/mcp.json` or IDE config):
 }
 ```
 
-### Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `N8N_API_URL` | Your n8n instance URL |
-| `N8N_API_KEY` | API key from n8n settings |
-
 ## Tools
 
-### Workflow Operations
-
-| Tool | Description |
-|------|-------------|
-| `workflow_list` | List all workflows |
-| `workflow_get` | Get workflow by ID |
-| `workflow_create` | Create new workflow |
-| `workflow_update` | Update workflow with patch operations |
-| `workflow_delete` | Delete workflow |
-| `workflow_activate` | Enable triggers |
-| `workflow_deactivate` | Disable triggers |
-| `workflow_execute` | Execute via webhook |
-| `workflow_validate` | Validate against best practices |
-
-### Execution Operations
-
-| Tool | Description |
-|------|-------------|
-| `execution_list` | List executions |
-| `execution_get` | Get execution details |
-
-## Patch Operations
-
-The `workflow_update` tool uses patch operations to safely modify workflows:
-
-```javascript
-// Add a node
-{ "type": "addNode", "node": { "name": "my_node", "type": "n8n-nodes-base.set", ... } }
-
-// Update a node (INCLUDE ALL existing parameters)
-{ "type": "updateNode", "nodeName": "my_node", "properties": { "parameters": { ...existing, "newParam": "value" } } }
-
-// Remove a node
-{ "type": "removeNode", "nodeName": "my_node" }
-
-// Add connection
-{ "type": "addConnection", "from": "node_a", "to": "node_b" }
+| Category | Tools |
+|----------|-------|
+| Workflow | `list` `get` `create` `update` `delete` `activate` `deactivate` `execute` |
+| Execution | `list` `get` |
+| Validation | `validate` `autofix` `format` |
+| Versions | `list` `get` `save` `rollback` `diff` `stats` |
 
-// Remove connection
-{ "type": "removeConnection", "from": "node_a", "to": "node_b" }
+## Validation
 
-// Update settings
-{ "type": "updateSettings", "settings": { "executionOrder": "v1" } }
+| Rule | Severity | Auto-fix |
+|------|----------|----------|
+| snake_case naming | warning | Yes |
+| Explicit refs (`$('node')` not `$json`) | warning | Yes |
+| AI structured output | warning | Yes |
+| Hardcoded secrets | error | No |
+| Orphan nodes | warning | No |
+| Expression syntax | error | No |
+| Circular references | error | No |
 
-// Rename workflow
-{ "type": "updateName", "name": "new_name" }
-```
-
-## 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 |
-| `orphan_node` | warning | Node has no connections |
-| `parameter_preservation` | error | Update would remove parameters |
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Build
-npm run build
-
-# Watch mode
-npm run dev
-
-# Run tests
-npm test
-```
-
-## Deployment
-
-### npm
-
-Published automatically on push to `main` via GitHub Actions.
-
-Manual publish:
-```bash
-npm publish --access public
-```
+## Config
 
-### MCP Registry
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `N8N_API_URL` | required | n8n instance URL |
+| `N8N_API_KEY` | required | API key |
+| `N8N_MCP_VERSIONS` | `true` | Enable version control |
+| `N8N_MCP_MAX_VERSIONS` | `20` | Max snapshots per workflow |
 
-This server is registered at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) as `io.github.pagelines/n8n-mcp`.
+## Docs
 
-The `server.json` file contains the registry metadata.
+- [Best Practices](docs/best-practices.md) - Expression patterns, config nodes, AI settings
+- [Node Config](docs/node-config.md) - Human-editable node settings (`__rl`, Set node, etc.)
+- [Architecture](plans/architecture.md) - Technical reference
 
 ## License
 
-MIT
+MIT - [PageLines](https://github.com/pagelines)

package/dist/autofix.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Auto-fix common n8n workflow issues
+ * Transforms workflows to follow best practices
+ */
+import type { N8nWorkflow, ValidationWarning } from './types.js';
+export interface AutofixResult {
+    workflow: N8nWorkflow;
+    fixes: AutofixAction[];
+    unfixable: ValidationWarning[];
+}
+export interface AutofixAction {
+    type: string;
+    target: string;
+    description: string;
+    before?: string;
+    after?: string;
+}
+/**
+ * Auto-fix a workflow based on validation warnings
+ */
+export declare function autofixWorkflow(workflow: N8nWorkflow, warnings: ValidationWarning[]): AutofixResult;
+/**
+ * Format a workflow for consistency
+ * - Sorts nodes by position
+ * - Normalizes connection format
+ * - Removes empty/null values
+ */
+export declare function formatWorkflow(workflow: N8nWorkflow): N8nWorkflow;

package/dist/autofix.js

@@ -0,0 +1,222 @@
+/**
+ * Auto-fix common n8n workflow issues
+ * Transforms workflows to follow best practices
+ */
+/**
+ * Auto-fix a workflow based on validation warnings
+ */
+export function autofixWorkflow(workflow, warnings) {
+    // Deep clone to avoid mutation
+    const fixed = JSON.parse(JSON.stringify(workflow));
+    const fixes = [];
+    const unfixable = [];
+    for (const warning of warnings) {
+        const result = attemptFix(fixed, warning);
+        if (result) {
+            fixes.push(result);
+        }
+        else {
+            unfixable.push(warning);
+        }
+    }
+    return { workflow: fixed, fixes, unfixable };
+}
+function attemptFix(workflow, warning) {
+    switch (warning.rule) {
+        case 'snake_case':
+            return fixSnakeCase(workflow, warning);
+        case 'explicit_reference':
+            return fixExplicitReference(workflow, warning);
+        case 'ai_structured_output':
+            return fixAIStructuredOutput(workflow, warning);
+        default:
+            // Rules that can't be auto-fixed:
+            // - no_hardcoded_secrets (need manual review)
+            // - no_hardcoded_ids (need manual review)
+            // - orphan_node (need context to know what to connect)
+            // - code_node_usage (info only)
+            // - in_memory_storage (architectural decision)
+            return null;
+    }
+}
+/**
+ * Fix snake_case naming
+ */
+function fixSnakeCase(workflow, warning) {
+    const target = warning.node || 'workflow';
+    if (!warning.node) {
+        // Fix workflow name
+        const oldName = workflow.name;
+        const newName = toSnakeCase(oldName);
+        if (oldName === newName)
+            return null;
+        workflow.name = newName;
+        return {
+            type: 'rename',
+            target: 'workflow',
+            description: `Renamed workflow to snake_case`,
+            before: oldName,
+            after: newName,
+        };
+    }
+    // Fix node name
+    const node = workflow.nodes.find((n) => n.name === warning.node);
+    if (!node)
+        return null;
+    const oldName = node.name;
+    const newName = toSnakeCase(oldName);
+    if (oldName === newName)
+        return null;
+    // Update node name
+    node.name = newName;
+    // Update connections that reference this node
+    if (workflow.connections[oldName]) {
+        workflow.connections[newName] = workflow.connections[oldName];
+        delete workflow.connections[oldName];
+    }
+    // Update connections that target this node
+    for (const outputs of Object.values(workflow.connections)) {
+        for (const outputType of Object.values(outputs)) {
+            for (const connections of outputType) {
+                for (const conn of connections) {
+                    if (conn.node === oldName) {
+                        conn.node = newName;
+                    }
+                }
+            }
+        }
+    }
+    return {
+        type: 'rename',
+        target: `node:${oldName}`,
+        description: `Renamed node to snake_case`,
+        before: oldName,
+        after: newName,
+    };
+}
+/**
+ * Convert to snake_case
+ */
+function toSnakeCase(name) {
+    return name
+        .replace(/([A-Z])/g, '_$1')
+        .replace(/[-\s]+/g, '_')
+        .replace(/^_/, '')
+        .replace(/_+/g, '_')
+        .toLowerCase();
+}
+/**
+ * Fix $json to explicit references
+ * This is a best-effort fix - may need manual review
+ */
+function fixExplicitReference(workflow, warning) {
+    if (!warning.node)
+        return null;
+    const node = workflow.nodes.find((n) => n.name === warning.node);
+    if (!node)
+        return null;
+    // Find the previous node in the connection chain
+    const previousNode = findPreviousNode(workflow, node.name);
+    if (!previousNode) {
+        // Can't auto-fix without knowing the source
+        return null;
+    }
+    // Replace $json with explicit reference
+    const params = JSON.stringify(node.parameters);
+    const fixedParams = params
+        .replace(/\$json\./g, `$('${previousNode}').item.json.`)
+        .replace(/\{\{\s*\$json\./g, `{{ $('${previousNode}').item.json.`);
+    if (params === fixedParams)
+        return null;
+    node.parameters = JSON.parse(fixedParams);
+    return {
+        type: 'expression_fix',
+        target: `node:${node.name}`,
+        description: `Changed $json to explicit $('${previousNode}') reference`,
+        before: '$json.',
+        after: `$('${previousNode}').item.json.`,
+    };
+}
+/**
+ * Find the previous node in the connection chain
+ */
+function findPreviousNode(workflow, nodeName) {
+    for (const [sourceName, outputs] of Object.entries(workflow.connections)) {
+        for (const outputType of Object.values(outputs)) {
+            for (const connections of outputType) {
+                for (const conn of connections) {
+                    if (conn.node === nodeName) {
+                        return sourceName;
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Fix AI structured output settings
+ */
+function fixAIStructuredOutput(workflow, warning) {
+    if (!warning.node)
+        return null;
+    const node = workflow.nodes.find((n) => n.name === warning.node);
+    if (!node)
+        return null;
+    const params = node.parameters;
+    const changes = [];
+    if (params.promptType !== 'define') {
+        params.promptType = 'define';
+        changes.push('promptType: "define"');
+    }
+    if (params.hasOutputParser !== true) {
+        params.hasOutputParser = true;
+        changes.push('hasOutputParser: true');
+    }
+    if (changes.length === 0)
+        return null;
+    return {
+        type: 'parameter_fix',
+        target: `node:${node.name}`,
+        description: `Added AI structured output settings: ${changes.join(', ')}`,
+    };
+}
+/**
+ * Format a workflow for consistency
+ * - Sorts nodes by position
+ * - Normalizes connection format
+ * - Removes empty/null values
+ */
+export function formatWorkflow(workflow) {
+    const formatted = JSON.parse(JSON.stringify(workflow));
+    // Sort nodes by Y position, then X
+    formatted.nodes.sort((a, b) => {
+        const [ax, ay] = a.position;
+        const [bx, by] = b.position;
+        if (ay !== by)
+            return ay - by;
+        return ax - bx;
+    });
+    // Clean up parameters - remove undefined/null
+    for (const node of formatted.nodes) {
+        node.parameters = cleanObject(node.parameters);
+    }
+    return formatted;
+}
+/**
+ * Remove null/undefined values from object
+ */
+function cleanObject(obj) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === null || value === undefined)
+            continue;
+        if (typeof value === 'object' && !Array.isArray(value)) {
+            cleaned[key] = cleanObject(value);
+        }
+        else {
+            cleaned[key] = value;
+        }
+    }
+    return cleaned;
+}

package/dist/expressions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * n8n expression validation
+ * Parses and validates expressions in workflow parameters
+ */
+import type { N8nWorkflow } from './types.js';
+export interface ExpressionIssue {
+    node: string;
+    parameter: string;
+    expression: string;
+    issue: string;
+    severity: 'error' | 'warning' | 'info';
+    suggestion?: string;
+}
+/**
+ * Validate all expressions in a workflow
+ */
+export declare function validateExpressions(workflow: N8nWorkflow): ExpressionIssue[];
+/**
+ * Get all referenced nodes from expressions
+ */
+export declare function getReferencedNodes(workflow: N8nWorkflow): Map<string, string[]>;
+/**
+ * Check for circular references in expressions
+ */
+export declare function checkCircularReferences(workflow: N8nWorkflow): string[][];