@pagelines/n8n-mcp 0.3.1 → 0.3.2

package/src/validators.ts

@@ -1,394 +0,0 @@
-/**
- * Opinion-based workflow validation
- * Enforces best practices from n8n-best-practices.md
- */
-
-import type {
-  N8nWorkflow,
-  N8nNode,
-  ValidationResult,
-  ValidationWarning,
-  NodeTypeValidationError,
-} from './types.js';
-
-export function validateWorkflow(workflow: N8nWorkflow): ValidationResult {
-  const warnings: ValidationWarning[] = [];
-
-  // 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: N8nNode, warnings: ValidationWarning[]): void {
-  // 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);
-
-  // Check for code node usage (should be last resort)
-  checkForCodeNodeUsage(node, warnings);
-
-  // Check for AI node structured output settings
-  checkForAIStructuredOutput(node, warnings);
-
-  // Check for in-memory storage (non-persistent)
-  checkForInMemoryStorage(node, warnings);
-}
-
-function validateSnakeCase(name: string, context: string, warnings: ValidationWarning[]): void {
-  // 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: N8nNode, warnings: ValidationWarning[]): void {
-  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: N8nNode, warnings: ValidationWarning[]): void {
-  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: N8nNode, warnings: ValidationWarning[]): void {
-  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 - consider using $env.VAR_NAME`,
-        severity: 'info',
-      });
-      break;
-    }
-  }
-}
-
-function checkForCodeNodeUsage(node: N8nNode, warnings: ValidationWarning[]): void {
-  // Detect code nodes - they should be last resort
-  const codeNodeTypes = [
-    'n8n-nodes-base.code',
-    'n8n-nodes-base.function',
-    'n8n-nodes-base.functionItem',
-  ];
-
-  if (codeNodeTypes.some((t) => node.type.includes(t))) {
-    warnings.push({
-      node: node.name,
-      rule: 'code_node_usage',
-      message: `Node "${node.name}" is a code node - ensure built-in nodes can't achieve this`,
-      severity: 'info',
-    });
-  }
-}
-
-function checkForAIStructuredOutput(node: N8nNode, warnings: ValidationWarning[]): void {
-  // Check AI/LLM nodes for structured output settings
-  const aiNodeTypes = [
-    'langchain.agent',
-    'langchain.chainLlm',
-    'langchain.lmChatOpenAi',
-    'langchain.lmChatAnthropic',
-    'langchain.lmChatGoogleGemini',
-  ];
-
-  const isAINode = aiNodeTypes.some((t) => node.type.toLowerCase().includes(t.toLowerCase()));
-  if (!isAINode) return;
-
-  // Check for structured output settings
-  const params = node.parameters as Record<string, unknown>;
-  const hasPromptType = params.promptType === 'define';
-  const hasOutputParser = params.hasOutputParser === true;
-
-  // Only warn if it looks like they want structured output but missed settings
-  if (params.outputParser || params.schemaType) {
-    if (!hasPromptType || !hasOutputParser) {
-      warnings.push({
-        node: node.name,
-        rule: 'ai_structured_output',
-        message: `Node "${node.name}" may need promptType: "define" and hasOutputParser: true for reliable structured output`,
-        severity: 'warning',
-      });
-    }
-  }
-}
-
-function checkForInMemoryStorage(node: N8nNode, warnings: ValidationWarning[]): void {
-  // Detect in-memory storage nodes that don't persist across restarts
-  const inMemoryTypes = [
-    'memoryBufferWindow',
-    'memoryVectorStore',
-    'vectorStoreInMemory',
-  ];
-
-  const isInMemory = inMemoryTypes.some((t) => node.type.toLowerCase().includes(t.toLowerCase()));
-  if (isInMemory) {
-    warnings.push({
-      node: node.name,
-      rule: 'in_memory_storage',
-      message: `Node "${node.name}" uses in-memory storage - consider Postgres for production persistence`,
-      severity: 'warning',
-    });
-  }
-}
-
-function validateConnections(workflow: N8nWorkflow, warnings: ValidationWarning[]): void {
-  const connectedNodes = new Set<string>();
-
-  // 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: N8nWorkflow,
-  nodeName: string,
-  newParameters: Record<string, unknown>
-): ValidationWarning[] {
-  const warnings: ValidationWarning[] = [];
-
-  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;
-}
-
-// ─────────────────────────────────────────────────────────────
-// 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];
-}

package/src/versions.ts

@@ -1,320 +0,0 @@
-/**
- * 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';
-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;
-}
-
-const DEFAULT_CONFIG: VersionConfig = {
-  enabled: true,
-  maxVersions: 20,
-  storageDir: path.join(os.homedir(), '.n8n-mcp', 'versions'),
-};
-
-let config: VersionConfig = { ...DEFAULT_CONFIG };
-
-/**
- * Initialize version control with custom config
- */
-export function initVersionControl(customConfig: Partial<VersionConfig> = {}): void {
-  config = { ...DEFAULT_CONFIG, ...customConfig };
-}
-
-/**
- * Get the storage directory for a workflow
- */
-function getWorkflowDir(workflowId: string): string {
-  return path.join(config.storageDir, workflowId);
-}
-
-/**
- * Generate a simple hash for workflow content
- */
-function hashWorkflow(workflow: N8nWorkflow): string {
-  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: N8nWorkflow,
-  reason: string = 'manual'
-): Promise<WorkflowVersion | null> {
-  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: WorkflowVersion = {
-    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: string): Promise<WorkflowVersion[]> {
-  const workflowDir = getWorkflowDir(workflowId);
-
-  try {
-    const files = await fs.readdir(workflowDir);
-    const versions: WorkflowVersion[] = [];
-
-    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 as NodeJS.ErrnoException).code === 'ENOENT') {
-      return [];
-    }
-    throw error;
-  }
-}
-
-/**
- * Get a specific version's full workflow data
- */
-export async function getVersion(
-  workflowId: string,
-  versionId: string
-): Promise<{ meta: WorkflowVersion; workflow: N8nWorkflow } | null> {
-  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 as NodeJS.ErrnoException).code === 'ENOENT') {
-      return null;
-    }
-    throw error;
-  }
-}
-
-/**
- * Get the most recent version
- */
-export async function getLatestVersion(
-  workflowId: string
-): Promise<{ meta: WorkflowVersion; workflow: N8nWorkflow } | null> {
-  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: string): Promise<number> {
-  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;
-}
-
-/**
- * Compare two workflow versions
- */
-export interface VersionDiff {
-  nodesAdded: string[];
-  nodesRemoved: string[];
-  nodesModified: string[];
-  connectionsChanged: boolean;
-  settingsChanged: boolean;
-  summary: string;
-}
-
-export function diffWorkflows(
-  oldWorkflow: N8nWorkflow,
-  newWorkflow: N8nWorkflow
-): VersionDiff {
-  const oldNodes = new Map(oldWorkflow.nodes.map((n) => [n.name, n]));
-  const newNodes = new Map(newWorkflow.nodes.map((n) => [n.name, n]));
-
-  const nodesAdded: string[] = [];
-  const nodesRemoved: string[] = [];
-  const nodesModified: string[] = [];
-
-  // 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: string[] = [];
-  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: string): Promise<number> {
-  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(): Promise<{
-  enabled: boolean;
-  storageDir: string;
-  maxVersions: number;
-  workflowCount: number;
-  totalVersions: number;
-}> {
-  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,
-  };
-}