Router MCP Server 🎯

The execution engine of GAFF - runs intent graphs with parallel execution, HITL support, and quality integration

Part of GAFF Framework - Open-source AI agent orchestration
Status: ✅ Production-Ready
Version: 1.0.3
Pipeline Position: Step 4 - Intent Graph Execution
Confluence: router Documentation

⭐ Recommended: Use gaff-gateway to access this and all other GAFF servers through a single connection.

The Router MCP Server is the execution engine of GAFF (Graphical Agentic Flow Framework). It takes intent graphs generated by the intent-graph-generator and executes them by orchestrating calls to agents, managing state, and coordinating Human-in-the-Loop (HITL) interactions.

📋 Table of Contents

• Overview
• Quick Start
• Features
• Tools
• Architecture
• Configuration
• Examples
• Integration
• Troubleshooting

Overview

The Router is responsible for:

1. Graph Validation - Ensures intent graphs are valid DAGs (Directed Acyclic Graphs)
2. Topological Execution - Determines optimal execution order
3. Agent Orchestration - Routes tool calls to appropriate agents
4. State Management - Persists execution state in Memory MCP server
5. Parallel Execution - Executes independent nodes concurrently
6. HITL Coordination - Pauses workflows for human approval
7. Error Handling - Automatic retries and graceful failure

Quick Start

See QUICKSTART.md for detailed getting started guide.

# Install
cd mcp/router
npm install
npm run build

# Test
node test-execution.js

Key Features

• ✅ Topological Execution - Determines optimal execution order via DAG analysis
• ✅ Parallel Processing - Executes independent nodes concurrently
• ✅ Human-in-the-Loop - Native support for pausing workflows for approval
• ✅ Quality Integration - Automatic coordination with quality-check for reruns
• ✅ State Management - Comprehensive execution tracking
• ✅ Error Handling - Automatic retries and graceful failure
• 🌐 Gateway Compatible - Accessible via gaff-gateway with router_* prefix

Memory-Backed State Management

All execution state can be stored in the Memory MCP server (future):

• Execution status and progress
• Node results and intermediate outputs
• Workflow context and variables
• Pause/resume state for HITL

✅ DAG Validation & Topological Sort

• Automatic cycle detection
• Dependency resolution
• Optimal execution ordering

✅ Parallel Execution

• Groups independent nodes into batches
• Configurable parallelism (max_parallel)
• Maintains dependency constraints

✅ Variable Resolution

Automatically resolves variable references in node inputs:

{
  "input": {
    "data": "${previous_node.result.data}",
    "user_id": "${context.user_id}"
  }
}

✅ Retry Logic

Per-node retry configuration with:

• Linear or exponential backoff
• Configurable max attempts
• Automatic delay calculation

✅ HITL (Human-in-the-Loop)

Automatically pauses execution at HITL nodes for human approval:

{
  "id": "approval_gate",
  "agent": "gaff-tools",
  "tool": "human_in_the_loop",
  "input": {
    "action_description": "Approve budget increase",
    "context": { "amount": 50000 }
  }
}

Tools

1. execute_graph

Execute a complete intent graph.

Input:

{
  "graph": { ... },           // Intent graph object
  "graph_memory_key": "...",  // OR retrieve from memory
  "execution_mode": "sync",   // "sync" or "async"
  "context": {                // Initial variables
    "user_id": "12345"
  },
  "config": {
    "max_parallel": 5,
    "timeout_ms": 300000,
    "enable_quality_check": false,
    "enable_hitl": true,
    "max_retries": 3,
    "store_state_in_memory": true
  }
}

Output:

{
  "execution_id": "exec_1696543210_abc123",
  "status": "completed",
  "results": {
    "node_1": { ... },
    "node_2": { ... }
  },
  "execution_time_ms": 1234,
  "nodes_executed": 5,
  "nodes_failed": []
}

2. route_to_agent

Route a single tool call to an agent.

Input:

{
  "agent_name": "data-processor",
  "tool_name": "transform_data",
  "input": {
    "data": [1, 2, 3]
  },
  "timeout_ms": 30000,
  "retry_config": {
    "max_attempts": 3,
    "backoff_strategy": "exponential"
  }
}

3. get_execution_status

Get current status of an execution from memory.

Input:

{
  "execution_id": "exec_1696543210_abc123"
}

Output:

{
  "execution_id": "exec_1696543210_abc123",
  "status": "running",
  "progress_percentage": 60.0,
  "nodes_completed": 3,
  "nodes_total": 5,
  "current_node": "node_4"
}

4. pause_execution

Manually pause a running execution.

Input:

{
  "execution_id": "exec_1696543210_abc123",
  "reason": "Manual review required"
}

5. resume_execution

Resume a paused execution.

Input:

{
  "execution_id": "exec_1696543210_abc123",
  "approval_decision": {
    "approved": true,
    "modified_context": {
      "budget_approved": 50000
    }
  }
}

6. cancel_execution

Cancel a running or paused execution.

Input:

{
  "execution_id": "exec_1696543210_abc123",
  "reason": "User requested cancellation"
}

Architecture

Components

router/
├── src/
│   ├── index.ts              # Main server
│   ├── types.ts              # Type definitions
│   └── utils/
│       ├── memory-client.ts  # Memory MCP client
│       ├── graph-executor.ts # Execution engine
│       └── agent-router.ts   # Agent routing
├── examples/
│   └── simple-graph.json     # Example graph
├── test-execution.js         # Test script
└── package.json

Execution Flow

1. Receive graph → Validate DAG structure
2. Topological sort → Determine execution order
3. Group nodes → Identify parallel execution opportunities
4. Initialize state → Store in Memory MCP server
5. Execute groups → For each node:
   • Resolve input variables
   • Check for HITL
   • Route to agent
   • Store result in memory
   • Update execution state
6. Return results → Complete or paused status

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | MEMORY_MCP_COMMAND | Memory server command | npx | | MEMORY_MCP_ARGS | Memory server args | -y,@modelcontextprotocol/server-memory |

Execution Config

{
  max_parallel?: number        // Max concurrent nodes (default: 5)
  timeout_ms?: number          // Overall timeout (default: 300000)
  enable_quality_check?: boolean  // Quality checking (default: false)
  enable_hitl?: boolean        // HITL support (default: true)
  max_retries?: number         // Node retries (default: 3)
  store_state_in_memory?: boolean  // Memory persistence (default: true)
}

Examples

See examples/simple-graph.json for a complete example.

Basic Sequential Workflow

{
  "graph_id": "example_001",
  "version": "1.0",
  "nodes": [
    {
      "id": "fetch",
      "agent": "data-agent",
      "tool": "fetch_data",
      "input": { "source": "api" },
      "dependencies": []
    },
    {
      "id": "process",
      "agent": "processor",
      "tool": "transform",
      "input": { "data": "${fetch.result}" },
      "dependencies": ["fetch"]
    }
  ],
  "edges": [
    { "from": "fetch", "to": "process" }
  ]
}

Integration

With GAFF Gateway

The GAFF Gateway automatically includes the router:

{
  "mcpServers": {
    "gaff": {
      "command": "node",
      "args": ["C:/path/to/gaff/mcp/gaff-gateway/build/index.js"]
    }
  }
}

Standalone

{
  "mcpServers": {
    "router": {
      "command": "node",
      "args": ["C:/path/to/gaff/mcp/router/build/index.js"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Troubleshooting

Memory Connection Failed

Problem: Failed to connect to memory server

Solution:

# Verify memory server works
npx -y @modelcontextprotocol/server-memory

# Check environment variables
echo $env:MEMORY_MCP_COMMAND
echo $env:MEMORY_MCP_ARGS

Graph Validation Failed

Problem: Cycle detected in graph

Solution:

• Review node dependencies
• Check for circular references
• Use topological sort tools to visualize

Node Execution Failed

Problem: Nodes fail with timeout/connection errors

Solution:

• Verify agent configuration in gaff.json
• Check agent endpoints are accessible
• Increase timeout: { "timeout_ms": 60000 }
• Add retries: { "max_retries": 5 }

HITL Not Pausing

Problem: HITL nodes execute without pausing

Solution:

// Ensure enable_hitl is true
{
  "config": {
    "enable_hitl": true
  }
}

// Verify node structure
{
  "agent": "gaff-tools",  // Must be exact
  "tool": "human_in_the_loop"  // Must be exact
}

Status

| Feature | Status | Notes | |---------|--------|-------| | Core execution engine | ✅ | Complete | | Memory integration | ✅ | Complete | | DAG validation | ✅ | Complete | | Topological sort | ✅ | Complete | | Parallel execution | ✅ | Complete | | Variable resolution | ✅ | Complete | | HITL support | ✅ | Pause/resume ready | | Error handling | ✅ | Complete | | Agent routing | ⚠️ | Placeholder (needs real clients) | | Quality-check integration | ⚠️ | Placeholder |

Next Steps

1. Agent Routing - Implement real MCP/HTTP clients in agent-router.ts
2. Quality Check - Integrate with quality-check MCP server
3. Resume Logic - Complete full execution resumption
4. Monitoring - Add execution metrics and observability

License

MIT

Author

Sean Poyner [email protected]

Part of GAFF (Graphical Agentic Flow Framework)