@pagelines/n8n-mcp 0.1.0

package/dist/tools.js

@@ -0,0 +1,260 @@
+/**
+ * MCP Tool Definitions
+ * Minimal, focused toolset for workflow management
+ */
+export const tools = [
+    // ─────────────────────────────────────────────────────────────
+    // Workflow Operations
+    // ─────────────────────────────────────────────────────────────
+    {
+        name: 'workflow_list',
+        description: 'List all workflows. Returns id, name, active status.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                active: {
+                    type: 'boolean',
+                    description: 'Filter by active status',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results (default 100)',
+                },
+            },
+        },
+    },
+    {
+        name: 'workflow_get',
+        description: 'Get a workflow by ID. Returns full workflow with nodes, connections, settings.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'workflow_create',
+        description: 'Create a new workflow. Returns the created workflow.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Workflow name (use snake_case)',
+                },
+                nodes: {
+                    type: 'array',
+                    description: 'Array of node definitions',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string' },
+                            type: { type: 'string' },
+                            typeVersion: { type: 'number' },
+                            position: {
+                                type: 'array',
+                                items: { type: 'number' },
+                                minItems: 2,
+                                maxItems: 2,
+                            },
+                            parameters: { type: 'object' },
+                            credentials: { type: 'object' },
+                        },
+                        required: ['name', 'type', 'typeVersion', 'position', 'parameters'],
+                    },
+                },
+                connections: {
+                    type: 'object',
+                    description: 'Connection map: { "NodeName": { "main": [[{ "node": "TargetNode", "type": "main", "index": 0 }]] } }',
+                },
+                settings: {
+                    type: 'object',
+                    description: 'Workflow settings',
+                },
+            },
+            required: ['name', 'nodes', 'connections'],
+        },
+    },
+    {
+        name: 'workflow_update',
+        description: `Update a workflow using patch operations. ALWAYS preserves existing data.
+
+Operations:
+- addNode: Add a new node
+- removeNode: Remove a node and its connections
+- updateNode: Update node properties (INCLUDE ALL existing parameters to preserve them)
+- addConnection: Connect two nodes
+- removeConnection: Disconnect two nodes
+- updateSettings: Update workflow settings
+- updateName: Rename the workflow
+
+Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "properties": { "parameters": { ...allExistingParams, "newParam": "value" } } }] }`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+                operations: {
+                    type: 'array',
+                    description: 'Array of patch operations',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            type: {
+                                type: 'string',
+                                enum: ['addNode', 'removeNode', 'updateNode', 'addConnection', 'removeConnection', 'updateSettings', 'updateName'],
+                            },
+                            // For addNode
+                            node: { type: 'object' },
+                            // For removeNode, updateNode
+                            nodeName: { type: 'string' },
+                            // For updateNode
+                            properties: { type: 'object' },
+                            // For connections
+                            from: { type: 'string' },
+                            to: { type: 'string' },
+                            fromOutput: { type: 'number' },
+                            toInput: { type: 'number' },
+                            outputType: { type: 'string' },
+                            inputType: { type: 'string' },
+                            // For updateSettings
+                            settings: { type: 'object' },
+                            // For updateName
+                            name: { type: 'string' },
+                        },
+                        required: ['type'],
+                    },
+                },
+            },
+            required: ['id', 'operations'],
+        },
+    },
+    {
+        name: 'workflow_delete',
+        description: 'Delete a workflow permanently.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'workflow_activate',
+        description: 'Activate a workflow (enable triggers).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'workflow_deactivate',
+        description: 'Deactivate a workflow (disable triggers).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'workflow_execute',
+        description: 'Execute a workflow via its webhook trigger. Workflow must have a webhook node.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID',
+                },
+                data: {
+                    type: 'object',
+                    description: 'Data to send to the webhook',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    // ─────────────────────────────────────────────────────────────
+    // Execution Operations
+    // ─────────────────────────────────────────────────────────────
+    {
+        name: 'execution_list',
+        description: 'List workflow executions. Filter by workflow or status.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workflowId: {
+                    type: 'string',
+                    description: 'Filter by workflow ID',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['success', 'error', 'waiting'],
+                    description: 'Filter by status',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results (default 20)',
+                },
+            },
+        },
+    },
+    {
+        name: 'execution_get',
+        description: 'Get execution details including run data and errors.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Execution ID',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    // ─────────────────────────────────────────────────────────────
+    // Validation
+    // ─────────────────────────────────────────────────────────────
+    {
+        name: 'workflow_validate',
+        description: `Validate a workflow against best practices:
+- snake_case naming
+- Explicit node references (no $json)
+- No hardcoded IDs
+- No hardcoded secrets
+- No orphan nodes`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'Workflow ID to validate',
+                },
+            },
+            required: ['id'],
+        },
+    },
+];

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+/**
+ * n8n API Types
+ * Minimal types for workflow management
+ */
+export interface N8nNode {
+    id: string;
+    name: string;
+    type: string;
+    typeVersion: number;
+    position: [number, number];
+    parameters: Record<string, unknown>;
+    credentials?: Record<string, {
+        id: string;
+        name: string;
+    }>;
+    disabled?: boolean;
+    notes?: string;
+    notesInFlow?: boolean;
+}
+export interface N8nConnection {
+    node: string;
+    type: string;
+    index: number;
+}
+export interface N8nConnections {
+    [nodeName: string]: {
+        [outputType: string]: N8nConnection[][];
+    };
+}
+export interface N8nWorkflow {
+    id: string;
+    name: string;
+    active: boolean;
+    nodes: N8nNode[];
+    connections: N8nConnections;
+    settings?: Record<string, unknown>;
+    staticData?: Record<string, unknown>;
+    tags?: {
+        id: string;
+        name: string;
+    }[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface N8nWorkflowListItem {
+    id: string;
+    name: string;
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+    tags?: {
+        id: string;
+        name: string;
+    }[];
+}
+export interface N8nExecution {
+    id: string;
+    workflowId: string;
+    finished: boolean;
+    mode: string;
+    startedAt: string;
+    stoppedAt?: string;
+    status: 'success' | 'error' | 'waiting' | 'running';
+    data?: {
+        resultData?: {
+            runData?: Record<string, unknown>;
+            error?: {
+                message: string;
+            };
+        };
+    };
+}
+export interface N8nExecutionListItem {
+    id: string;
+    workflowId: string;
+    status: string;
+    startedAt: string;
+    stoppedAt?: string;
+    mode: string;
+}
+export type PatchOperation = {
+    type: 'addNode';
+    node: Omit<N8nNode, 'id'> & {
+        id?: string;
+    };
+} | {
+    type: 'removeNode';
+    nodeName: string;
+} | {
+    type: 'updateNode';
+    nodeName: string;
+    properties: Partial<N8nNode>;
+} | {
+    type: 'addConnection';
+    from: string;
+    to: string;
+    fromOutput?: number;
+    toInput?: number;
+    outputType?: string;
+    inputType?: string;
+} | {
+    type: 'removeConnection';
+    from: string;
+    to: string;
+    fromOutput?: number;
+    toInput?: number;
+    outputType?: string;
+} | {
+    type: 'updateSettings';
+    settings: Record<string, unknown>;
+} | {
+    type: 'updateName';
+    name: string;
+} | {
+    type: 'activate';
+} | {
+    type: 'deactivate';
+};
+export interface ValidationWarning {
+    node?: string;
+    rule: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info';
+}
+export interface ValidationResult {
+    valid: boolean;
+    warnings: ValidationWarning[];
+}
+export interface N8nListResponse<T> {
+    data: T[];
+    nextCursor?: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * n8n API Types
+ * Minimal types for workflow management
+ */
+export {};

package/dist/validators.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Opinion-based workflow validation
+ * Enforces best practices from n8n-best-practices.md
+ */
+import type { N8nWorkflow, ValidationResult, ValidationWarning } from './types.js';
+export declare function validateWorkflow(workflow: N8nWorkflow): ValidationResult;
+/**
+ * Validate a partial update to ensure it won't cause issues
+ */
+export declare function validatePartialUpdate(currentWorkflow: N8nWorkflow, nodeName: string, newParameters: Record<string, unknown>): ValidationWarning[];

package/dist/validators.js

@@ -0,0 +1,171 @@
+/**
+ * Opinion-based workflow validation
+ * Enforces best practices from n8n-best-practices.md
+ */
+export function validateWorkflow(workflow) {
+    const warnings = [];
+    // Validate workflow name
+    validateSnakeCase(workflow.name, 'workflow', warnings);
+    // Validate each node
+    for (const node of workflow.nodes) {
+        validateNode(node, warnings);
+    }
+    // Check for orphan nodes (no connections)
+    validateConnections(workflow, warnings);
+    return {
+        valid: warnings.filter((w) => w.severity === 'error').length === 0,
+        warnings,
+    };
+}
+function validateNode(node, warnings) {
+    // Check node name is snake_case
+    validateSnakeCase(node.name, `node "${node.name}"`, warnings);
+    // Check for $json usage (should use explicit references)
+    checkForJsonUsage(node, warnings);
+    // Check for hardcoded IDs
+    checkForHardcodedIds(node, warnings);
+    // Check for hardcoded secrets
+    checkForHardcodedSecrets(node, warnings);
+}
+function validateSnakeCase(name, context, warnings) {
+    // Allow spaces for readability, but check the underlying format
+    const normalized = name.toLowerCase().replace(/\s+/g, '_');
+    // Check if it matches snake_case pattern (allowing numbers)
+    const isSnakeCase = /^[a-z][a-z0-9_]*$/.test(normalized);
+    // Also allow names that are already snake_case
+    const isAlreadySnake = /^[a-z][a-z0-9_]*$/.test(name);
+    if (!isSnakeCase && !isAlreadySnake) {
+        warnings.push({
+            rule: 'snake_case',
+            message: `${context} should use snake_case naming: "${name}" → "${normalized}"`,
+            severity: 'warning',
+        });
+    }
+}
+function checkForJsonUsage(node, warnings) {
+    const params = JSON.stringify(node.parameters);
+    // Detect $json without explicit node reference
+    // Bad: $json.field, {{ $json.field }}
+    // Good: $('node_name').item.json.field
+    const badPatterns = [
+        /\$json\./g,
+        /\{\{\s*\$json\./g,
+    ];
+    for (const pattern of badPatterns) {
+        if (pattern.test(params)) {
+            warnings.push({
+                node: node.name,
+                rule: 'explicit_reference',
+                message: `Node "${node.name}" uses $json - use explicit $('node_name').item.json.field instead`,
+                severity: 'warning',
+            });
+            break;
+        }
+    }
+}
+function checkForHardcodedIds(node, warnings) {
+    const params = JSON.stringify(node.parameters);
+    // Detect patterns that look like hardcoded IDs
+    const idPatterns = [
+        // Discord IDs (17-19 digit numbers)
+        /["']\d{17,19}["']/g,
+        // UUIDs
+        /["'][0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}["']/gi,
+        // MongoDB ObjectIds
+        /["'][0-9a-f]{24}["']/gi,
+    ];
+    for (const pattern of idPatterns) {
+        if (pattern.test(params)) {
+            warnings.push({
+                node: node.name,
+                rule: 'no_hardcoded_ids',
+                message: `Node "${node.name}" may contain hardcoded IDs - consider using config nodes or environment variables`,
+                severity: 'info',
+            });
+            break;
+        }
+    }
+}
+function checkForHardcodedSecrets(node, warnings) {
+    const params = JSON.stringify(node.parameters).toLowerCase();
+    // Check for common secret patterns
+    const secretPatterns = [
+        /api[_-]?key["']\s*:\s*["'][^"']+["']/i,
+        /secret["']\s*:\s*["'][^"']+["']/i,
+        /password["']\s*:\s*["'][^"']+["']/i,
+        /token["']\s*:\s*["'][a-z0-9]{20,}["']/i,
+    ];
+    for (const pattern of secretPatterns) {
+        if (pattern.test(params)) {
+            warnings.push({
+                node: node.name,
+                rule: 'no_hardcoded_secrets',
+                message: `Node "${node.name}" may contain hardcoded secrets - use $env.VAR_NAME instead`,
+                severity: 'error',
+            });
+            break;
+        }
+    }
+}
+function validateConnections(workflow, warnings) {
+    const connectedNodes = new Set();
+    // Collect all nodes that have connections (as source or target)
+    for (const [sourceName, outputs] of Object.entries(workflow.connections)) {
+        connectedNodes.add(sourceName);
+        for (const outputType of Object.values(outputs)) {
+            for (const connections of outputType) {
+                for (const conn of connections) {
+                    connectedNodes.add(conn.node);
+                }
+            }
+        }
+    }
+    // Check for orphan nodes (excluding trigger nodes which don't need incoming)
+    const triggerTypes = [
+        'n8n-nodes-base.webhook',
+        'n8n-nodes-base.scheduleTrigger',
+        'n8n-nodes-base.manualTrigger',
+        'n8n-nodes-base.emailTrigger',
+        '@n8n/n8n-nodes-langchain.chatTrigger',
+    ];
+    for (const node of workflow.nodes) {
+        const isTrigger = triggerTypes.some((t) => node.type.includes(t.split('.')[1]));
+        if (!isTrigger && !connectedNodes.has(node.name)) {
+            warnings.push({
+                node: node.name,
+                rule: 'orphan_node',
+                message: `Node "${node.name}" has no connections - may be orphaned`,
+                severity: 'warning',
+            });
+        }
+    }
+}
+/**
+ * Validate a partial update to ensure it won't cause issues
+ */
+export function validatePartialUpdate(currentWorkflow, nodeName, newParameters) {
+    const warnings = [];
+    const currentNode = currentWorkflow.nodes.find((n) => n.name === nodeName);
+    if (!currentNode) {
+        warnings.push({
+            node: nodeName,
+            rule: 'node_exists',
+            message: `Node "${nodeName}" not found in workflow`,
+            severity: 'error',
+        });
+        return warnings;
+    }
+    // Check for parameter loss
+    const currentKeys = Object.keys(currentNode.parameters);
+    const newKeys = Object.keys(newParameters);
+    const missingKeys = currentKeys.filter((k) => !newKeys.includes(k));
+    if (missingKeys.length > 0) {
+        warnings.push({
+            node: nodeName,
+            rule: 'parameter_preservation',
+            message: `Update will remove parameters: ${missingKeys.join(', ')}. Include all existing parameters to preserve them.`,
+            severity: 'error',
+        });
+    }
+    return warnings;
+}

package/dist/validators.test.d.ts

@@ -0,0 +1 @@
+export {};