@pagelines/n8n-mcp 0.1.0

package/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm test -- --run
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - run: npm run build
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        continue-on-error: true # Won't fail if version already exists

package/README.md

@@ -0,0 +1,155 @@
+# pl-n8n-mcp
+
+> **@pagelines/n8n-mcp** - Opinionated MCP server for n8n workflow automation by [PageLines](https://github.com/pagelines)
+
+## Features
+
+- **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
+
+## Best Practices Enforced
+
+- `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
+
+## Installation
+
+```bash
+npm install @pagelines/n8n-mcp
+```
+
+Or run directly:
+
+```bash
+npx @pagelines/n8n-mcp
+```
+
+## Configuration
+
+### Claude Code / Cursor
+
+Add to your MCP settings (`~/.claude/mcp.json` or IDE config):
+
+```json
+{
+  "mcpServers": {
+    "pl-n8n": {
+      "command": "npx",
+      "args": ["-y", "@pagelines/n8n-mcp"],
+      "env": {
+        "N8N_API_URL": "https://your-n8n-instance.com",
+        "N8N_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### 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" }
+
+// Remove connection
+{ "type": "removeConnection", "from": "node_a", "to": "node_b" }
+
+// Update settings
+{ "type": "updateSettings", "settings": { "executionOrder": "v1" } }
+
+// 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
+```
+
+### MCP Registry
+
+This server is registered at [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) as `io.github.pagelines/n8n-mcp`.
+
+The `server.json` file contains the registry metadata.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * @pagelines/n8n-mcp
+ * Opinionated MCP server for n8n workflow automation
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * @pagelines/n8n-mcp
+ * Opinionated MCP server for n8n workflow automation
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { N8nClient } from './n8n-client.js';
+import { tools } from './tools.js';
+import { validateWorkflow } from './validators.js';
+// ─────────────────────────────────────────────────────────────
+// Configuration
+// ─────────────────────────────────────────────────────────────
+const N8N_API_URL = process.env.N8N_API_URL || process.env.N8N_HOST || '';
+const N8N_API_KEY = process.env.N8N_API_KEY || '';
+if (!N8N_API_URL || !N8N_API_KEY) {
+    console.error('Error: N8N_API_URL and N8N_API_KEY environment variables are required');
+    console.error('Set them in your MCP server configuration or environment');
+    process.exit(1);
+}
+const client = new N8nClient({
+    apiUrl: N8N_API_URL,
+    apiKey: N8N_API_KEY,
+});
+// ─────────────────────────────────────────────────────────────
+// MCP Server
+// ─────────────────────────────────────────────────────────────
+const server = new Server({
+    name: '@pagelines/n8n-mcp',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools,
+}));
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const result = await handleTool(name, args || {});
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ─────────────────────────────────────────────────────────────
+// Tool Handlers
+// ─────────────────────────────────────────────────────────────
+async function handleTool(name, args) {
+    switch (name) {
+        // Workflow operations
+        case 'workflow_list': {
+            const response = await client.listWorkflows({
+                active: args.active,
+                limit: args.limit || 100,
+            });
+            return {
+                workflows: response.data.map((w) => ({
+                    id: w.id,
+                    name: w.name,
+                    active: w.active,
+                    updatedAt: w.updatedAt,
+                })),
+                total: response.data.length,
+            };
+        }
+        case 'workflow_get': {
+            const workflow = await client.getWorkflow(args.id);
+            return workflow;
+        }
+        case 'workflow_create': {
+            const nodes = args.nodes.map((n, i) => ({
+                id: crypto.randomUUID(),
+                name: n.name,
+                type: n.type,
+                typeVersion: n.typeVersion,
+                position: n.position || [250, 250 + i * 100],
+                parameters: n.parameters || {},
+                ...(n.credentials && { credentials: n.credentials }),
+            }));
+            const workflow = await client.createWorkflow({
+                name: args.name,
+                nodes,
+                connections: args.connections || {},
+                settings: args.settings,
+            });
+            // Validate the new workflow
+            const validation = validateWorkflow(workflow);
+            return {
+                workflow,
+                validation,
+            };
+        }
+        case 'workflow_update': {
+            const operations = args.operations;
+            const { workflow, warnings } = await client.patchWorkflow(args.id, operations);
+            // Also run validation
+            const validation = validateWorkflow(workflow);
+            return {
+                workflow,
+                patchWarnings: warnings,
+                validation,
+            };
+        }
+        case 'workflow_delete': {
+            await client.deleteWorkflow(args.id);
+            return { success: true, message: `Workflow ${args.id} deleted` };
+        }
+        case 'workflow_activate': {
+            const workflow = await client.activateWorkflow(args.id);
+            return {
+                id: workflow.id,
+                name: workflow.name,
+                active: workflow.active,
+            };
+        }
+        case 'workflow_deactivate': {
+            const workflow = await client.deactivateWorkflow(args.id);
+            return {
+                id: workflow.id,
+                name: workflow.name,
+                active: workflow.active,
+            };
+        }
+        case 'workflow_execute': {
+            const result = await client.executeWorkflow(args.id, args.data);
+            return result;
+        }
+        // Execution operations
+        case 'execution_list': {
+            const response = await client.listExecutions({
+                workflowId: args.workflowId,
+                status: args.status,
+                limit: args.limit || 20,
+            });
+            return {
+                executions: response.data,
+                total: response.data.length,
+            };
+        }
+        case 'execution_get': {
+            const execution = await client.getExecution(args.id);
+            return execution;
+        }
+        // Validation
+        case 'workflow_validate': {
+            const workflow = await client.getWorkflow(args.id);
+            const validation = validateWorkflow(workflow);
+            return {
+                workflowId: workflow.id,
+                workflowName: workflow.name,
+                ...validation,
+            };
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+// ─────────────────────────────────────────────────────────────
+// Start Server
+// ─────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('@pagelines/n8n-mcp server started');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/n8n-client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * n8n REST API Client
+ * Clean, minimal implementation with built-in safety checks
+ */
+import type { N8nWorkflow, N8nWorkflowListItem, N8nExecution, N8nExecutionListItem, N8nListResponse, N8nNode, PatchOperation } from './types.js';
+export interface N8nClientConfig {
+    apiUrl: string;
+    apiKey: string;
+}
+export declare class N8nClient {
+    private baseUrl;
+    private headers;
+    constructor(config: N8nClientConfig);
+    private request;
+    listWorkflows(options?: {
+        limit?: number;
+        cursor?: string;
+        active?: boolean;
+        tags?: string[];
+    }): Promise<N8nListResponse<N8nWorkflowListItem>>;
+    getWorkflow(id: string): Promise<N8nWorkflow>;
+    createWorkflow(workflow: {
+        name: string;
+        nodes: N8nNode[];
+        connections: N8nWorkflow['connections'];
+        settings?: Record<string, unknown>;
+    }): Promise<N8nWorkflow>;
+    updateWorkflow(id: string, workflow: Partial<Omit<N8nWorkflow, 'id' | 'createdAt' | 'updatedAt'>>): Promise<N8nWorkflow>;
+    deleteWorkflow(id: string): Promise<void>;
+    activateWorkflow(id: string): Promise<N8nWorkflow>;
+    deactivateWorkflow(id: string): Promise<N8nWorkflow>;
+    patchWorkflow(id: string, operations: PatchOperation[]): Promise<{
+        workflow: N8nWorkflow;
+        warnings: string[];
+    }>;
+    private applyOperations;
+    listExecutions(options?: {
+        workflowId?: string;
+        status?: 'success' | 'error' | 'waiting';
+        limit?: number;
+        cursor?: string;
+    }): Promise<N8nListResponse<N8nExecutionListItem>>;
+    getExecution(id: string): Promise<N8nExecution>;
+    deleteExecution(id: string): Promise<void>;
+    executeWorkflow(id: string, data?: Record<string, unknown>): Promise<{
+        executionId?: string;
+        data?: unknown;
+    }>;
+    healthCheck(): Promise<{
+        healthy: boolean;
+        version?: string;
+        error?: string;
+    }>;
+}