# 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

```mermaid
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:

```mermaid
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:

```json
{
  "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:

```json
{
  "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:
```json
{
  "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:
```json
{ "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:
```json
{ "nodeId": "schema" }
```

- **If it passes**:
  - `schema` status becomes `COMPLETED`.
  - `jwt_service` automatically becomes `READY`!
- **If it fails**:
  - MCP returns:
    ```json
    {
      "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`):

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