import { spawn } from 'child_process';
import { readFileSync, writeFileSync } from 'fs';
import { join } from 'path';

interface MCPToolRequest {
  tool: string;
  params: Record<string, unknown>;
}

interface MCPToolResponse {
  success: boolean;
  output: string;
  diagnostics?: string[];
}

class WorkflowValidationEngine {
  private mcpProcess: ReturnType<typeof spawn>;

  constructor() {
    this.mcpProcess = spawn('npx', ['-y', '@automatelab/n8n-mcp'], {
      stdio: ['pipe', 'pipe', 'pipe'],
      env: { ...process.env, NODE_ENV: 'development' }
    });

    this.mcpProcess.stderr.on('data', (chunk: Buffer) => {
      console.error(`[MCP STDERR] ${chunk.toString().trim()}`);
    });
  }

  private async executeTool<T = unknown>(request: MCPToolRequest): Promise<MCPToolResponse> {
    return new Promise((resolve, reject) => {
      const payload = JSON.stringify(request) + '\n';
      
      this.mcpProcess.stdin.wr

ite(payload);

  let buffer = '';
  const onData = (chunk: Buffer) => {
    buffer += chunk.toString();
    if (buffer.includes('\n')) {
      try {
        const response = JSON.parse(buffer.trim());
        this.mcpProcess.stdout.off('data', onData);
        resolve({
          success: response.status === 'ok',
          output: response.result || '',
          diagnostics: response.warnings || []
        });
      } catch {
        // Continue buffering
      }
    }
  };
  
  this.mcpProcess.stdout.on('data', onData);
  
  setTimeout(() => {
    this.mcpProcess.stdout.off('data', onData);
    reject(new Error('MCP tool execution timed out'));
  }, 15000);
});

}

async scaffoldCustomNode(packageName: string, nodeType: string): Promise<string> { const response = await this.executeTool({ tool: 'n8n_scaffold_node', params: { targetPackage: packageName, nodeIdentifier: nodeType } });

if (!response.success) {
  throw new Error(`Scaffolding failed: ${response.output}`);
}

const outputPath = join(process.cwd(), 'packages', packageName);
writeFileSync(join(outputPath, 'node.ts'), response.output);
return outputPath;

}

async buildAndValidateWorkflow(description: string): Promise<Record<string, unknown>> { const generation = await this.executeTool({ tool: 'n8n_generate_workflow', params: { prompt: description, enforceTypedConnections: true } });

if (!generation.success) {
  throw new Error(`Generation failed: ${generation.output}`);
}

const workflowJson = JSON.parse(generation.output);

const lintResult = await this.executeTool({
  tool: 'n8n_lint_workflow',
  params: { workflowPayload: workflowJson }
});

if (lintResult.diagnostics && lintResult.diagnostics.length > 0) {
  console.warn('[VALIDATION] Linter warnings detected:');
  lintResult.diagnostics.forEach(w => console.warn(`  - ${w}`));
}

return workflowJson;

}

async diagnoseExecutionFailure(executionId: string): Promise<string> { const diagnosis = await this.executeTool({ tool: 'n8n_explain_execution', params: { executionIdentifier: executionId, includeZeroItemAnalysis: true } });

return diagnosis.output;

} }

// Usage example async function main() { const engine = new WorkflowValidationEngine();

try { const workflow = await engine.buildAndValidateWorkflow( 'Fetch user data from REST API, transform fields, and send to Slack channel' );

console.log('Workflow validated successfully. Ready for deployment.');
writeFileSync('validated-workflow.json', JSON.stringify(workflow, null, 2));

} catch (error) { console.error('Pipeline failed:', error); } finally { engine['mcpProcess'].kill(); } }

main();

**Why this architecture works:**
- The pipeline separates generation, validation, and deployment concerns.
- Typed connection enforcement happens at generation time, preventing topology failures.
- Linting runs immediately after generation, catching deprecated schemas and missing identifiers before deployment.
- The execution diagnostic tool integrates seamlessly into post-mortem analysis, reducing debugging cycles.

## Pitfall Guide

Even with robust tooling, workflow engineering introduces specific failure modes. Below are the most common mistakes observed in production environments, along with actionable fixes.

### 1. AI Node Connection Mismatch
**Explanation:** Developers allow LLMs to connect AI Agent sub-nodes using the default `main` output port. n8n's runtime ignores these connections, causing the AI branch to execute with empty context.
**Fix:** Always enforce typed connections (`ai_languageModel`, `ai_memory`, `ai_tool`). Use the linter to verify port mapping before deployment.

### 2. Deprecated Node Schema Drift
**Explanation:** Workflows reference retired nodes like `function` or `spreadsheetFile`. These import successfully but fail during node initialization, throwing cryptic runtime errors.
**Fix:** Run `n8n_lint_workflow` against all generated payloads. Replace deprecated nodes with their modern equivalents (`code`, `convertToFile`) before activation.

### 3. Silent Zero-Item Handoffs
**Explanation:** An upstream node returns an empty array. n8n skips downstream execution without logging an error. Engineers assume the pipeline failed, when it actually executed correctly with no data.
**Fix:** Use `n8n_explain_execution` to trace item counts across nodes. Add explicit validation nodes that check for empty arrays and route to error handling branches.

### 4. Missing Webhook Identifiers
**Explanation:** Webhook nodes lack a `webhookId` field. The workflow imports, but external triggers fail to route correctly, resulting in 404 responses or silent drops.
**Fix:** Ensure all webhook nodes include a deterministic `webhookId`. The linter will flag missing identifiers. Generate IDs using a consistent hashing strategy for reproducibility.

### 5. IF Node Version Confusion
**Explanation:** Mixing IF-v1 and IF-v2 schemas in the same workflow causes conditional routing failures. v2 uses a different condition structure and evaluation engine.
**Fix:** Standardize on IF-v2 across all workflows. The linter detects v1 schemas and recommends migration paths. Avoid mixing versions within a single execution graph.

### 6. Assuming Stateless Tools Require Credentials
**Explanation:** Engineers configure API keys unnecessarily for linting and generation tools, increasing attack surface and configuration complexity.
**Fix:** Reserve `N8N_API_URL` and `N8N_API_KEY` for live-instance tools only. Stateless utilities operate entirely on local JSON payloads and require no network access.

### 7. Ignoring Linter Warnings as "Non-Critical"
**Explanation:** Teams treat linter output as advisory rather than mandatory. Warnings about deprecated nodes or missing identifiers accumulate, leading to runtime instability.
**Fix:** Integrate linting into CI/CD pipelines as a blocking step. Treat warnings as errors until resolved. Maintain a workflow schema registry that enforces current n8n standards.

## Production Bundle

### Action Checklist
- [ ] Verify Node.js 20+ runtime: MCP server requires modern ESM support and stable stdio handling
- [ ] Configure host environment: Apply MCP JSON block to Cursor, Claude Desktop, Cline, or Windsurf
- [ ] Separate credential scopes: Use API keys only for live-instance tools; keep stateless tools offline
- [ ] Enforce lint-before-import policy: Run `n8n_lint_workflow` on all generated payloads before deployment
- [ ] Validate AI topology: Confirm typed connections for all AI Agent sub-nodes before activation
- [ ] Monitor zero-item drops: Implement execution tracing for pipelines with conditional routing
- [ ] Standardize node versions: Migrate all workflows to IF-v2, `code`, and `convertToFile` schemas
- [ ] Version control workflows: Store validated JSON in Git with automated lint checks on pull requests

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Rapid prototyping | Stateless generation + local linting | No API keys required; fast iteration; safe sandbox | Zero infrastructure cost |
| Production deployment | Live-instance tools + CI/CD gating | Ensures topology correctness; prevents broken workflows in prod | Moderate CI/CD setup time |
| Legacy workflow migration | Linter diagnostics + scaffold replacement | Identifies deprecated nodes; generates modern equivalents | High initial effort, low long-term maintenance |
| AI Agent pipeline debugging | Execution explain tool + zero-item tracing | Pinpoints silent data loss; reduces MTTR by 70%+ | Minimal tooling overhead |
| Multi-agent orchestration | Stateless generation + manual review | Prevents topology conflicts; ensures deterministic routing | Higher review overhead, lower failure rate |

### Configuration Template

```json
{
  "mcpServers": {
    "n8n-workflow-engine": {
      "command": "npx",
      "args": ["-y", "@automatelab/n8n-mcp"],
      "env": {
        "N8N_API_URL": "https://<your-instance>.n8n.cloud",
        "N8N_API_KEY": "n8n_<your-api-key>",
        "MCP_LOG_LEVEL": "warn",
        "NODE_OPTIONS": "--max-old-space-size=4096"
      },
      "disabled": false,
      "autoApprove": ["n8n_lint_workflow", "n8n_generate_workflow", "n8n_explain_execution"]
    }
  }
}

Notes:

• autoApprove reduces friction for stateless tools that don't modify live instances.
• NODE_OPTIONS prevents memory pressure during large workflow generation.
• Keep API keys in environment variables or secret managers; never commit to version control.

Quick Start Guide

1. Install the MCP server globally: Run npm install -g @automatelab/n8n-mcp and verify Node 20+ is active.
2. Configure your AI host: Paste the configuration template into your MCP client settings. Omit API keys if you only need stateless tools.
3. Generate and validate a workflow: Prompt your AI agent to describe a pipeline. The server will generate JSON, run automatic linting, and flag topology issues before you attempt deployment.
4. Deploy to live instance: Use the live-instance tools to create, activate, and monitor workflows. Run n8n_list_executions to verify first-run success.
5. Iterate with diagnostics: If execution fails, pass the execution ID to n8n_explain_execution to receive node-level breakdowns and zero-item analysis. Apply fixes and redeploy.

By treating n8n workflows as compiled artifacts rather than ad-hoc JSON payloads, engineering teams can achieve deterministic automation delivery. The MCP validation layer closes the gap between AI generation and runtime execution, transforming workflow development from a debugging-heavy process into a reliable, repeatable engineering practice.