VibeFlow Executor MCP Server

MCP server for workflow execution control, monitoring, and node registry.

Features

Tools (14 total)

Execution Control:

• execute_workflow - Execute a workflow
• execute_node - Execute a single node (testing)
• stop_execution - Stop running execution
• resume_execution - Resume paused execution (Wait nodes)

Monitoring:

• get_execution_status - Get current execution status
• get_execution_result - Get final execution result
• get_node_output - Get node output from execution
• list_executions - List recent executions
• get_execution_logs - Get execution logs

Testing & Validation:

• test_node_with_input - Test node with custom input
• dry_run_workflow - Validate without executing

Node Registry:

• list_available_nodes - List all available node types
• get_node_definition - Get node type definition
• search_nodes - Search nodes by query

Resources

• vibeflow://executions - Recent executions list
• vibeflow://execution/{id} - Specific execution details
• vibeflow://nodes - Available node types

Prompts (4 total)

• run_workflow - Execute and monitor workflow
• test_node - Test node with sample data
• debug_execution - Debug failed execution
• validate_workflow - Validate before running

Installation

cd /Users/ultra/xp/vibeflow/packages/mcp/executor
bun install
bun run build

Usage

As MCP Server (STDIO)

Development:

bun run dev

Production:

node build/index.js

Environment Variables

export CORE_API_URL=http://localhost:7576
export CONFIG_API_URL=http://localhost:7575

Claude Desktop Configuration

{
  "mcpServers": {
    "vibeflow-executor": {
      "command": "bun",
      "args": [
        "run",
        "/Users/ultra/xp/vibeflow/packages/mcp/executor/src/index.ts"
      ],
      "env": {
        "CORE_API_URL": "http://localhost:7576",
        "CONFIG_API_URL": "http://localhost:7575"
      }
    }
  }
}

Examples

Execute Workflow

// Start execution
const execution = await callTool('execute_workflow', {
  workflowId: 'workflow-123'
});
// Returns: { executionId: 'exec-456', status: 'running' }

// Monitor progress
const status = await callTool('get_execution_status', {
  executionId: 'exec-456'
});
// Returns: { status: 'running', progress: 50, currentNode: 'Code' }

// Get result when completed
const result = await callTool('get_execution_result', {
  executionId: 'exec-456'
});
// Returns: { result: [[{json: {...}}]], nodeStates: [...] }

Execute with Custom Input

await callTool('execute_workflow', {
  workflowId: 'workflow-123',
  startNodeId: 'webhook-node',
  inputData: {
    userId: 1,
    action: 'create'
  }
});

Test Node

const result = await callTool('test_node_with_input', {
  workflowId: 'workflow-123',
  nodeId: 'code-node',
  testInput: [{
    json: { value: 100 }
  }]
});
// Returns: { output: [...], duration: 45, error: undefined }

Validate Workflow

const validation = await callTool('dry_run_workflow', {
  workflowId: 'workflow-123',
  options: {
    checkConnections: true,
    validateNodes: true
  }
});
// Returns: {
//   plan: [
//     { nodeId: '...', nodeName: 'Start', nodeType: '...' },
//     { nodeId: '...', nodeName: 'Code', nodeType: '...' }
//   ],
//   validation: {
//     valid: true,
//     errors: []
//   }
// }

Stop/Resume Execution

// Stop
await callTool('stop_execution', {
  executionId: 'exec-456'
});

// Resume (for Wait nodes)
await callTool('resume_execution', {
  executionId: 'exec-456',
  waitNodeData: { approved: true }
});

List Executions

// All recent executions
const all = await callTool('list_executions', {});

// Filter by workflow
const workflowExecs = await callTool('list_executions', {
  workflowId: 'workflow-123',
  status: 'completed',
  limit: 10
});

Get Logs

// All execution logs
const logs = await callTool('get_execution_logs', {
  executionId: 'exec-456'
});

// Logs for specific node
const nodeLogs = await callTool('get_execution_logs', {
  executionId: 'exec-456',
  nodeId: 'code-node'
});

Node Registry

// List all nodes
const nodes = await callTool('list_available_nodes', {});

// Search for specific nodes
const httpNodes = await callTool('search_nodes', {
  query: 'http'
});

// Get node definition
const def = await callTool('get_node_definition', {
  nodeType: 'n8n-nodes-base.code'
});

Using Prompts

Run workflow:

Use the "run_workflow" prompt to execute workflow "abc123" and monitor it

Test node:

Use the "test_node" prompt to test the Code node in workflow "abc123"

Debug:

Use the "debug_execution" prompt to analyze what went wrong in execution "exec-456"

Architecture

Executor MCP Server
└── ExecutionManager
    ├── Execution Control (execute, stop, resume)
    ├── Monitoring (status, result, logs)
    ├── Testing (test node, dry run)
    └── Node Registry (list, search, get definition)

Testing

# Run all tests
bun test

# Run with watch mode
bun test --watch

Test Coverage

• ✅ ExecutionManager: 17 tests
  • execute workflow/node
  • stop/resume execution
  • get status/result/output
  • list executions
  • get logs
  • test node with input
  • dry run validation
  • node registry (list, search, get definition)

Total: 17 tests, all passing ✅

Common Patterns

1. Execute and Wait for Result

// Start
const { executionId } = await execute_workflow({ workflowId });

// Poll until complete
let status;
do {
  await new Promise(resolve => setTimeout(resolve, 1000)); // Wait 1s
  status = await get_execution_status({ executionId });
} while (status.status === 'running');

// Get result
if (status.status === 'completed') {
  const result = await get_execution_result({ executionId });
  console.log('Success:', result);
} else {
  const logs = await get_execution_logs({ executionId });
  console.error('Failed:', logs);
}

2. Test Node Before Deployment

// Create test data
const testData = [{
  json: {
    email: '[email protected]',
    name: 'Test User'
  }
}];

// Test node
const result = await test_node_with_input({
  workflowId,
  nodeId: 'email-node',
  testInput: testData
});

console.log(`Execution took ${result.duration}ms`);
if (result.error) {
  console.error('Error:', result.error);
} else {
  console.log('Success:', result.output);
}

3. Validate Before Executing

// Validate
const validation = await dry_run_workflow({
  workflowId,
  options: { checkConnections: true, validateNodes: true }
});

if (!validation.validation.valid) {
  console.error('Validation failed:', validation.validation.errors);
  return;
}

// Show execution plan
console.log('Execution plan:');
validation.plan.forEach((step, i) => {
  console.log(`${i + 1}. ${step.nodeName} (${step.nodeType})`);
});

// Execute if valid
const { executionId } = await execute_workflow({ workflowId });

4. Debug Failed Execution

// Get result
const result = await get_execution_result({ executionId });

// Find failed nodes
const failed = result.nodeStates.filter(s => s.status === 'error');

for (const node of failed) {
  console.log(`Failed node: ${node.node_name}`);
  console.log(`Error: ${node.error_message}`);

  // Get logs for this node
  const logs = await get_execution_logs({ executionId, nodeId: node.node_id });
  console.log('Logs:', logs.logs.join('\n'));
}

Best Practices

Execution

1. Always validate first - Use dry_run_workflow before executing in production
2. Monitor progress - Poll get_execution_status for long-running workflows
3. Handle errors - Check status and get logs if execution fails
4. Use timeouts - Don't poll indefinitely, set max wait time

Testing

1. Test nodes individually - Use test_node_with_input before full workflow test
2. Use realistic data - Test with data similar to production
3. Check performance - Monitor duration in test results
4. Validate output - Ensure output format matches expectations

Monitoring

1. Check logs regularly - Use get_execution_logs to understand behavior
2. Track execution history - Use list_executions to see patterns
3. Get node outputs - Use get_node_output to debug intermediate steps
4. Monitor status - Use get_execution_status for real-time updates

Troubleshooting

"Execution failed to start"

• Check if Config server is running (http://localhost:7575)
• Verify workflow exists in config
• Check for validation errors

"Node execution timeout"

• Increase timeout in node parameters
• Check if external APIs are responding
• Review node code for infinite loops

"Cannot stop execution"

• Execution may have already completed
• Check execution status first
• Some operations cannot be stopped mid-execution

"Missing node output"

• Node may not have been executed yet
• Check if node completed successfully
• Verify nodeId is correct

Roadmap

• [ ] Real-time WebSocket updates for execution progress
• [ ] Execution replay (re-run failed executions)
• [ ] Parallel execution optimization
• [ ] Execution scheduling and cron jobs
• [ ] Performance profiling and metrics

See Also

• FlowEditor MCP
• NodeEditor MCP
• Main MCP Documentation
• VibeFlow Core