@pagelines/n8n-mcp 0.2.1 → 0.3.0

package/src/tools.ts

@@ -29,7 +29,7 @@ export const tools: Tool[] = [
 
   {
     name: 'workflow_get',
-    description: 'Get a workflow by ID. Returns full workflow with nodes, connections, settings.',
+    description: 'Get a workflow by ID. Use format=summary for minimal response, compact (default) for nodes without parameters, full for everything.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -37,6 +37,11 @@ export const tools: Tool[] = [
           type: 'string',
           description: 'Workflow ID',
         },
+        format: {
+          type: 'string',
+          enum: ['summary', 'compact', 'full'],
+          description: 'Response detail level. summary=minimal, compact=nodes without params (default), full=everything',
+        },
       },
       required: ['id'],
     },
@@ -44,7 +49,7 @@ export const tools: Tool[] = [
 
   {
     name: 'workflow_create',
-    description: 'Create a new workflow. Returns the created workflow.',
+    description: 'Create a new workflow. Returns the created workflow with validation.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -81,6 +86,11 @@ export const tools: Tool[] = [
           type: 'object',
           description: 'Workflow settings',
         },
+        format: {
+          type: 'string',
+          enum: ['summary', 'compact', 'full'],
+          description: 'Response detail level (default: compact)',
+        },
       },
       required: ['name', 'nodes', 'connections'],
     },
@@ -138,6 +148,11 @@ Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "proper
             required: ['type'],
           },
         },
+        format: {
+          type: 'string',
+          enum: ['summary', 'compact', 'full'],
+          description: 'Response detail level (default: compact)',
+        },
       },
       required: ['id', 'operations'],
     },
@@ -229,13 +244,18 @@ Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "proper
           type: 'number',
           description: 'Max results (default 20)',
         },
+        format: {
+          type: 'string',
+          enum: ['summary', 'compact', 'full'],
+          description: 'Response detail level (default: compact)',
+        },
       },
     },
   },
 
   {
     name: 'execution_get',
-    description: 'Get execution details including run data and errors.',
+    description: 'Get execution details. Use format=summary for status only, compact (default) omits runData, full for everything including runData.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -243,6 +263,11 @@ Example: { "operations": [{ "type": "updateNode", "nodeName": "my_node", "proper
           type: 'string',
           description: 'Execution ID',
         },
+        format: {
+          type: 'string',
+          enum: ['summary', 'compact', 'full'],
+          description: 'Response detail level. summary=status only, compact=no runData (default), full=everything',
+        },
       },
       required: ['id'],
     },
@@ -315,6 +340,36 @@ Returns the fixed workflow and list of changes made.`,
     },
   },
 
+  // ─────────────────────────────────────────────────────────────
+  // Node Discovery
+  // ─────────────────────────────────────────────────────────────
+  {
+    name: 'node_types_list',
+    description: `List available n8n node types. Use this to discover valid node types BEFORE creating workflows.
+
+Returns: type name, display name, description, category, and version for each node.
+Use the search parameter to filter by keyword (searches type name, display name, and description).
+
+IMPORTANT: Always check node types exist before using them in workflow_create or workflow_update.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        search: {
+          type: 'string',
+          description: 'Filter nodes by keyword (searches name, type, description)',
+        },
+        category: {
+          type: 'string',
+          description: 'Filter by category (e.g., "Core Nodes", "Flow", "AI")',
+        },
+        limit: {
+          type: 'number',
+          description: 'Max results (default 50)',
+        },
+      },
+    },
+  },
+
   // ─────────────────────────────────────────────────────────────
   // Version Control
   // ─────────────────────────────────────────────────────────────
@@ -347,6 +402,11 @@ Returns the fixed workflow and list of changes made.`,
           type: 'string',
           description: 'Version ID (from version_list)',
         },
+        format: {
+          type: 'string',
+          enum: ['summary', 'compact', 'full'],
+          description: 'Response detail level (default: compact)',
+        },
       },
       required: ['workflowId', 'versionId'],
     },
@@ -385,6 +445,11 @@ Returns the fixed workflow and list of changes made.`,
           type: 'string',
           description: 'Version ID to restore',
         },
+        format: {
+          type: 'string',
+          enum: ['summary', 'compact', 'full'],
+          description: 'Response detail level (default: compact)',
+        },
       },
       required: ['workflowId', 'versionId'],
     },

package/src/types.ts

@@ -105,3 +105,36 @@ export interface N8nListResponse<T> {
   data: T[];
   nextCursor?: string;
 }
+
+// Node type information from n8n API (GET /api/v1/nodes)
+export interface N8nNodeType {
+  name: string;           // e.g., "n8n-nodes-base.webhook"
+  displayName: string;    // e.g., "Webhook"
+  description: string;
+  group: string[];        // e.g., ["trigger"]
+  version: number;
+  defaults?: {
+    name: string;
+  };
+  codex?: {
+    categories?: string[];
+    alias?: string[];
+  };
+}
+
+// Simplified node type for tool responses (reduced tokens)
+export interface N8nNodeTypeSummary {
+  type: string;           // Full type name
+  name: string;           // Display name
+  description: string;
+  category: string;
+  version: number;
+}
+
+// Node type validation error
+export interface NodeTypeValidationError {
+  nodeType: string;
+  nodeName: string;
+  message: string;
+  suggestions?: string[];
+}

package/src/validators.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { validateWorkflow, validatePartialUpdate } from './validators.js';
+import { validateWorkflow, validatePartialUpdate, validateNodeTypes } from './validators.js';
 import type { N8nWorkflow } from './types.js';
 
 const createWorkflow = (overrides: Partial<N8nWorkflow> = {}): N8nWorkflow => ({
@@ -68,7 +68,7 @@ describe('validateWorkflow', () => {
     );
   });
 
-  it('errors on hardcoded secrets', () => {
+  it('warns on hardcoded secrets', () => {
     const workflow = createWorkflow({
       nodes: [
         {
@@ -83,11 +83,10 @@ describe('validateWorkflow', () => {
     });
 
     const result = validateWorkflow(workflow);
-    expect(result.valid).toBe(false);
     expect(result.warnings).toContainEqual(
       expect.objectContaining({
         rule: 'no_hardcoded_secrets',
-        severity: 'error',
+        severity: 'info',
       })
     );
   });
@@ -275,3 +274,101 @@ describe('validatePartialUpdate', () => {
     expect(warnings).toHaveLength(0);
   });
 });
+
+describe('validateNodeTypes', () => {
+  const availableTypes = new Set([
+    'n8n-nodes-base.webhook',
+    'n8n-nodes-base.set',
+    'n8n-nodes-base.code',
+    'n8n-nodes-base.httpRequest',
+    '@n8n/n8n-nodes-langchain.agent',
+    '@n8n/n8n-nodes-langchain.chatTrigger',
+  ]);
+
+  it('passes when all node types are valid', () => {
+    const nodes = [
+      { name: 'webhook_trigger', type: 'n8n-nodes-base.webhook' },
+      { name: 'set_data', type: 'n8n-nodes-base.set' },
+      { name: 'ai_agent', type: '@n8n/n8n-nodes-langchain.agent' },
+    ];
+
+    const errors = validateNodeTypes(nodes, availableTypes);
+    expect(errors).toHaveLength(0);
+  });
+
+  it('returns error for invalid node type', () => {
+    const nodes = [
+      { name: 'my_node', type: 'n8n-nodes-base.nonexistent' },
+    ];
+
+    const errors = validateNodeTypes(nodes, availableTypes);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toEqual(
+      expect.objectContaining({
+        nodeType: 'n8n-nodes-base.nonexistent',
+        nodeName: 'my_node',
+      })
+    );
+  });
+
+  it('returns errors for multiple invalid node types', () => {
+    const nodes = [
+      { name: 'valid_node', type: 'n8n-nodes-base.webhook' },
+      { name: 'invalid_one', type: 'n8n-nodes-base.fake' },
+      { name: 'invalid_two', type: 'n8n-nodes-base.bogus' },
+    ];
+
+    const errors = validateNodeTypes(nodes, availableTypes);
+    expect(errors).toHaveLength(2);
+    expect(errors.map((e) => e.nodeName)).toEqual(['invalid_one', 'invalid_two']);
+  });
+
+  it('provides suggestions for typos', () => {
+    const nodes = [
+      { name: 'trigger', type: 'n8n-nodes-base.webhok' }, // typo: webhok
+    ];
+
+    const errors = validateNodeTypes(nodes, availableTypes);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].suggestions).toContain('n8n-nodes-base.webhook');
+  });
+
+  it('provides suggestions for partial matches', () => {
+    const nodes = [
+      { name: 'code_node', type: 'n8n-nodes-base.cod' }, // partial: cod
+    ];
+
+    const errors = validateNodeTypes(nodes, availableTypes);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].suggestions).toContain('n8n-nodes-base.code');
+  });
+
+  it('returns empty suggestions when no matches found', () => {
+    const nodes = [
+      { name: 'xyz_node', type: 'n8n-nodes-base.xyz123completely_random' },
+    ];
+
+    const errors = validateNodeTypes(nodes, availableTypes);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].suggestions).toHaveLength(0);
+  });
+
+  it('limits suggestions to 3', () => {
+    // Create a set with many similar types
+    const manyTypes = new Set([
+      'n8n-nodes-base.httpRequest',
+      'n8n-nodes-base.httpRequestTool',
+      'n8n-nodes-base.httpRequestV1',
+      'n8n-nodes-base.httpRequestV2',
+      'n8n-nodes-base.httpRequestV3',
+    ]);
+
+    const nodes = [
+      { name: 'http', type: 'n8n-nodes-base.http' }, // should match multiple
+    ];
+
+    const errors = validateNodeTypes(nodes, manyTypes);
+    expect(errors).toHaveLength(1);
+    expect(errors[0].suggestions!.length).toBeLessThanOrEqual(3);
+  });
+});

package/src/validators.ts

@@ -3,7 +3,13 @@
  * Enforces best practices from n8n-best-practices.md
  */
 
-import type { N8nWorkflow, N8nNode, ValidationResult, ValidationWarning } from './types.js';
+import type {
+  N8nWorkflow,
+  N8nNode,
+  ValidationResult,
+  ValidationWarning,
+  NodeTypeValidationError,
+} from './types.js';
 
 export function validateWorkflow(workflow: N8nWorkflow): ValidationResult {
   const warnings: ValidationWarning[] = [];
@@ -133,8 +139,8 @@ function checkForHardcodedSecrets(node: N8nNode, warnings: ValidationWarning[]):
       warnings.push({
         node: node.name,
         rule: 'no_hardcoded_secrets',
-        message: `Node "${node.name}" may contain hardcoded secrets - use $env.VAR_NAME instead`,
-        severity: 'error',
+        message: `Node "${node.name}" may contain hardcoded secrets - consider using $env.VAR_NAME`,
+        severity: 'info',
       });
       break;
     }
@@ -283,3 +289,106 @@ export function validatePartialUpdate(
 
   return warnings;
 }
+
+// ─────────────────────────────────────────────────────────────
+// Node Type Validation
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate that all node types in an array exist in the available types
+ * Returns errors for any invalid node types with suggestions
+ */
+export function validateNodeTypes(
+  nodes: Array<{ name: string; type: string }>,
+  availableTypes: Set<string>
+): NodeTypeValidationError[] {
+  const errors: NodeTypeValidationError[] = [];
+
+  for (const node of nodes) {
+    if (!availableTypes.has(node.type)) {
+      errors.push({
+        nodeType: node.type,
+        nodeName: node.name,
+        message: `Invalid node type "${node.type}" for node "${node.name}"`,
+        suggestions: findSimilarTypes(node.type, availableTypes),
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Find similar node types for suggestions (fuzzy matching)
+ * Returns up to 3 suggestions
+ */
+function findSimilarTypes(invalidType: string, availableTypes: Set<string>): string[] {
+  const suggestions: string[] = [];
+  const searchTerm = invalidType.toLowerCase();
+
+  // Extract the last part after the dot (e.g., "webhook" from "n8n-nodes-base.webhook")
+  const typeParts = searchTerm.split('.');
+  const shortName = typeParts[typeParts.length - 1];
+
+  for (const validType of availableTypes) {
+    const validLower = validType.toLowerCase();
+    const validShortName = validLower.split('.').pop() || '';
+
+    // Check for partial matches (substring)
+    if (
+      validLower.includes(shortName) ||
+      shortName.includes(validShortName) ||
+      validShortName.includes(shortName)
+    ) {
+      suggestions.push(validType);
+      if (suggestions.length >= 3) break;
+      continue;
+    }
+
+    // Check for typos using Levenshtein distance
+    const distance = levenshteinDistance(shortName, validShortName);
+    const maxLen = Math.max(shortName.length, validShortName.length);
+    // Allow up to 2 character differences for short names, or 20% of length for longer ones
+    const threshold = Math.max(2, Math.floor(maxLen * 0.2));
+    if (distance <= threshold) {
+      suggestions.push(validType);
+      if (suggestions.length >= 3) break;
+    }
+  }
+
+  return suggestions;
+}
+
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(a: string, b: string): number {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  const matrix: number[][] = [];
+
+  // Initialize first column
+  for (let i = 0; i <= a.length; i++) {
+    matrix[i] = [i];
+  }
+
+  // Initialize first row
+  for (let j = 0; j <= b.length; j++) {
+    matrix[0][j] = j;
+  }
+
+  // Fill in the rest of the matrix
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,      // deletion
+        matrix[i][j - 1] + 1,      // insertion
+        matrix[i - 1][j - 1] + cost // substitution
+      );
+    }
+  }
+
+  return matrix[a.length][b.length];
+}