BRD Graph Loop MCP Server

A specialized MCP (Model Context Protocol) server for graph-based task orchestration with automated validation and self-healing retry loops.

---

🎯 How It Works: High-Level Architecture

flowchart TD
    subgraph AI["🤖 AI Agent (Claude / Cursor / IDE)"]
        A1[1. Initialize Graph] --> A2[2. Query Ready Tasks]
        A2 --> A3[3. Start Task & Write Code]
        A3 --> A4[4. Call validate_task_loop]
    end

    subgraph MCP["⚙️ BRD Graph Loop MCP Server"]
        M1[(State Management: nodes, dependencies, status)]
        M2[Dependency Resolver & DAG Engine]
        M3[Command Executor & Output Capture]
        M4[Loop Controller: Retries, Max Attempts, Error Logging]
    end

    A1 -->|init_project_graph| M1
    A2 -->|get_ready_tasks| M2
    A3 -->|start_task| M1
    A4 -->|validate_task_loop| M3

    M3 -->|Pass: exitCode 0| M4
    M3 -->|Fail: exitCode != 0| M4
    M4 -->|Unlock Next Tasks| M2
    M4 -->|Return Error Context| AI

---

🔄 Node Lifecycle & State Transitions

Each task node moves through deterministic states based on its prerequisites and validation results:

stateDiagram-v2
    [*] --> PENDING : Initial state with unresolved dependencies
    PENDING --> READY : All 'depends_on' tasks reach COMPLETED
    READY --> IN_PROGRESS : AI calls 'start_task'
    
    state "Validation Loop" as Loop {
        IN_PROGRESS --> VALIDATING : AI calls 'validate_task_loop'
        VALIDATING --> RETRYING : Command fails (exitCode != 0 & attempts < max)
        RETRYING --> IN_PROGRESS : AI reads error logs and fixes code
    }

    VALIDATING --> COMPLETED : Command passes (exitCode 0)
    VALIDATING --> FAILED : Command fails & max_attempts exceeded
    
    COMPLETED --> [*] : Unlocks downstream PENDING nodes
    FAILED --> [*] : Can be reset with 'reset_task_node'

---

💡 Key Concepts

1. Directed Acyclic Graph (DAG)

Tasks have explicit dependencies (depends_on: ["task_a", "task_b"]). The server automatically ensures tasks only become READY when all their prerequisite tasks are COMPLETED.

2. The Iterative Validation Loop

Instead of hoping code works, each node specifies a validation_command (e.g., npm test, tsc --noEmit, pytest, eslint):

1. Pass (exitCode: 0): Loop status becomes PASSED, node becomes COMPLETED, and dependent nodes automatically switch to READY.
2. Fail (exitCode != 0): The server logs full stdout/stderr and exit codes in error_logs, increments current_attempt, and returns the error output to the AI.
3. Self-Correction: The AI analyzes the error, modifies code, and calls validate_task_loop again until it passes or hits max_attempts.

---

🛠️ Complete Step-by-Step Flow

Step 0: Scaffold Project Planning Docs (scaffold_project_docs)

Before initializing the graph, the AI agent can generate standard project documentation (Architecture, Phase-wise Tasks, and Test Cases) based on the user's requirements:

{
  "targetDirectory": "./",
  "architectureContent": "# Project Architecture\n...",
  "phaseTasks": [
    { "fileName": "PHASE_1.md", "content": "# Phase 1 Tasks\n..." }
  ],
  "testCasesContent": "# Integration Tests\n..."
}

---

Step 1: Initialize Workflow (init_project_graph)

The AI agent creates a task graph for a project:

{
  "projectName": "Auth Feature",
  "projectRoot": "/path/to/your/project/dir",
  "nodes": [
    {
      "id": "schema",
      "title": "Define User Database Schema",
      "description": "Create Prisma schema and migration scripts",
      "depends_on": [],
      "validation_command": "npx prisma validate",
      "max_attempts": 3
    },
    {
      "id": "jwt_service",
      "title": "Build JWT Token Service",
      "description": "Implement sign, verify, and refresh token functions",
      "depends_on": ["schema"],
      "validation_command": "npm run test -- jwt.test.ts",
      "max_attempts": 3
    },
    {
      "id": "login_route",
      "title": "Build API Login Endpoint",
      "description": "Express POST /api/login endpoint with validation",
      "depends_on": ["jwt_service"],
      "validation_command": "npm run test -- auth.test.ts",
      "max_attempts": 3
    }
  ]
}

---

Step 2: Fetch Ready Tasks (get_ready_tasks)

The agent asks what to work on next:

{
  "ready_count": 1,
  "ready_tasks": [
    {
      "id": "schema",
      "title": "Define User Database Schema",
      "status": "READY"
    }
  ]
}

(Notice jwt_service and login_route remain PENDING because their dependencies aren't done yet).

---

Step 3: Start the Task (start_task)

The agent claims the task:

{ "nodeId": "schema" }

Node status transitions to IN_PROGRESS.

---

Step 4: Validate the Code (validate_task_loop)

After the agent writes the schema files, it triggers the validation loop:

{ "nodeId": "schema" }

• If it passes:
  • schema status becomes COMPLETED.
  • jwt_service automatically becomes READY!
• If it fails:
  • MCP returns:

    {
      "validation_passed": false,
      "message": "Validation failed on attempt 1/3. Node 'schema' is in RETRYING status.",
      "result": {
        "exitCode": 1,
        "error": "Syntax error at line 14: invalid relation syntax"
      }
    }
    

  • The AI reviews the error, fixes line 14, and re-calls validate_task_loop.

---

📦 MCP Configuration

Add this to your MCP settings file (~/.cursor/mcp.json, Claude Desktop config, or .gemini/config/mcp_config.json):

{
  "mcpServers": {
    "brd-graph-loop": {
      "command": "node",
      "args": [
        "/Volumes/DATA/html work/mcp-graph-loop-server/build/index.js"
      ]
    }
  }
}