Skip to main content
Glama

dev-loop-mcp

An MCP (Model Context Protocol) server that runs an AI-driven TDD development loop. It generalizes the dev-loop state machine to work with any project via a simple config file.

What it does

Two loop types are available — both share the same TDD pipeline; they differ only in how tasks are produced:

flowchart LR
    subgraph start_loop["start_loop (feature)"]
        direction LR
        A("description<br/>or tasks") --> B["DECOMPOSE<br/>AI breaks into tasks"]
        B --> C[/"tasks"/]
    end

    subgraph start_debug_loop["start_debug_loop (bug)"]
        direction LR
        D("symptom<br/>+ context files") --> E["DIAGNOSE<br/>AI ranks hypotheses"]
        E --> F[/"tasks"/]
    end

    C --> Pipeline["TDD pipeline"]
    F --> Pipeline

    subgraph Pipeline["Shared TDD pipeline"]
        direction LR
        I[INIT] --> T[TDD_LOOP<br/>per task]
        T --> Bu[BUILD]
        Bu --> De[DEPLOY<br/>optional]
        De --> It[INTEG_TEST<br/>optional]
        It -->|pass| Qr[QUALITY_REVIEW]
        It -->|fail| If[INTEG_FIX<br/>up to 5×]
        If --> Qr
        Qr --> Ct[CLEAN_TREE<br/>CHECK]
        Ct --> Pr[PUSH_AND_PR]
        Pr --> Done(["✓ DONE<br/>PR opened"])
    end

Full state machine

flowchart TD
    start_loop --> INIT
    start_debug_loop -->|"DIAGNOSE:<br/>ranked hypotheses → tasks"| INIT

    INIT -->|"pre-loaded tasks"| TDD_LOOP
    INIT -->|"description only"| DECOMPOSE
    DECOMPOSE -->|"AI → Task[]"| TDD_LOOP

    TDD_LOOP -->|"task done, more remain"| TDD_LOOP
    TDD_LOOP -->|"all tasks done"| BUILD
    TDD_LOOP -->|"task failed"| FAILED

    BUILD -->|pass| DEPLOY
    BUILD -->|fail| FAILED

    DEPLOY -->|"pass / skipped"| INTEG_TEST
    DEPLOY -->|fail| FAILED

    INTEG_TEST -->|"pass / skipped"| QUALITY_REVIEW
    INTEG_TEST -->|fail| INTEG_FIX

    INTEG_FIX -->|fixed| QUALITY_REVIEW
    INTEG_FIX -->|"still failing<br/>(retry, max 5)"| INTEG_FIX
    INTEG_FIX -->|"5 attempts exhausted"| FAILED

    QUALITY_REVIEW --> CLEAN_TREE_CHECK
    CLEAN_TREE_CHECK --> PUSH_AND_PR
    PUSH_AND_PR --> DONE

    DONE(["✓ DONE"])
    FAILED(["✗ FAILED"])

    style DONE fill:#22c55e,color:#fff
    style FAILED fill:#ef4444,color:#fff
    style start_loop fill:#6366f1,color:#fff
    style start_debug_loop fill:#f59e0b,color:#fff

Per-task TDD cycle

Each task in TDD_LOOP runs this inner cycle (up to 5 coding iterations):

flowchart LR
    A["Write scenarios<br/>scenarios/scenarios-*.md"] --> B["Write failing tests<br/>*.test.ts"]
    B --> C{"Tests<br/>fail?"}
    C -->|"no — tester error"| Z["✗ task failed"]
    C -->|yes| D["Implement"]
    D --> E{"Tests<br/>pass?"}
    E -->|yes| F["✓ commit & next task"]
    E -->|"no (retry)"| D

Phase reference:

  • INIT: Creates the git branch

  • DECOMPOSE: AI converts a description into a Task[]

  • DIAGNOSE: (debug loop only) AI reads symptom + context files and produces ranked root-cause hypotheses as a Task[]

  • TDD_LOOP: Per-task: scenarios → failing tests → implementation (up to 5 coding iterations per task)

  • BUILD: Runs buildCommand

  • DEPLOY: Runs deployCommand — skipped if not configured

  • INTEG_TEST: Runs integTestCommand — skipped if not configured

  • INTEG_FIX: AI diagnoses and fixes integration test failures (up to 5 attempts)

  • QUALITY_REVIEW: AI reviews the full branch diff and applies quality fixes

  • CLEAN_TREE_CHECK: Auto-commits any uncommitted files

  • PUSH_AND_PR: Pushes the branch and opens a GitHub PR

Related MCP server: Maestro

Installation

npm install -g dev-loop-mcp

Or use via npx:

npx dev-loop-mcp

Configuration

Create dev-loop.config.json in your project root:

{
  "buildCommand": "npm run build",
  "testCommand": "npm test",
  "deployCommand": "npm run deploy",
  "integTestCommand": "npm run test:integ",
  "branchPrefix": "claude/",
  "model": "claude-sonnet-4-6"
}

All fields are optional. Defaults:

  • buildCommand: "npm run build"

  • testCommand: "npm test"

  • deployCommand: absent (DEPLOY phase skipped)

  • integTestCommand: absent (INTEG_TEST phase skipped)

  • branchPrefix: "claude/"

  • model: "claude-sonnet-4-6"

Environment variables

Variable

Required

Description

ANTHROPIC_API_KEY

Yes

Your Anthropic API key

DEV_LOOP_ROOT

No

Project root directory (defaults to cwd)

MCP setup

Add to your MCP client configuration (e.g., Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "dev-loop": {
      "command": "dev-loop-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "DEV_LOOP_ROOT": "/path/to/your/project"
      }
    }
  }
}

Available tools

start_debug_loop

Start a debug loop from a symptom description. The AI diagnoses root causes as ranked TDD tasks, then runs the standard TDD pipeline per hypothesis, and opens a PR with a full diagnosis writeup.

{
  "symptom": "read_website returns failure on most real URLs",
  "context_files": ["src/tools/read-website.ts", "src/http/client.ts"]
}

Parameters:

  • symptom (required) — natural-language description of the observed bug or failure

  • context_files (optional) — relative paths to source files the AI should read while diagnosing

The DIAGNOSE step runs before the standard TDD pipeline (see state machine above). The PR body includes the symptom, root causes identified, and what was fixed.

The branch is named <branchPrefix>debug/<symptom-slug>.

start_loop

Start a new development loop.

{
  "description": "Add email validation to the user registration flow",
  "branch": "claude/email-validation"
}

Or with pre-decomposed tasks:

{
  "tasks": [
    {
      "id": 1,
      "title": "Add email validator function",
      "scope": "src/utils/email.ts",
      "acceptance": "validateEmail returns true for valid emails and false for invalid ones"
    }
  ],
  "branch": "claude/email-validation"
}

resume_loop

Resume an interrupted loop:

{}

loop_status

Check the current loop status:

{}

Using as a library

import { runLoop, loadConfig, RealShellAdapter, AnthropicDevWorker } from "dev-loop-mcp";
import Anthropic from "@anthropic-ai/sdk";

const config = await loadConfig("/path/to/project");
const client = new Anthropic();
const shell = new RealShellAdapter();
const aiWorker = new AnthropicDevWorker(client, config.model, shell);

const finalState = await runLoop(initialState, {
  shell,
  aiWorker,
  stateFilePath: "/path/to/project/.loop-state.json",
  repoRoot: "/path/to/project",
  config,
});

Available Tools

4 tools
advance_loopA

Report the outcome of the last instruction and get the next one. Call this after completing each phase step. The loop persists state between calls.

Inputs: event (required), tasks, failureReason, stderr, +2 more.

loop_statusB

Get the current status of the loop: phase, branch, task list, failure reason, or PR URL.

Inputs: no named parameters.

start_debug_loopC

Start a debug loop from a symptom description. Returns an instruction telling you to diagnose root causes as ranked TDD tasks, then proceeds through the standard TDD pipeline. The PR body will include a diagnosis writeup.

Inputs: symptom (required).

start_loopA

Start a new TDD development loop. Returns an instruction telling you what to do first. Keep calling advance_loop after each step until the loop reaches DONE or FAILED. Phases: INIT → DECOMPOSE → TDD_LOOP → BUILD → DEPLOY → INTEG_TEST → INTEG_FIX → QUALITY_REVIEW → CLEAN_TREE_CHECK → PUSH_AND_PR.

Inputs: description, tasks, branch.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: advance_loop progresses the loop, loop_status checks current state, start_debug_loop initiates debugging, and start_loop initiates standard development. The descriptions make it impossible to confuse their functions.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case throughout: advance_loop, loop_status, start_debug_loop, and start_loop. The naming is predictable and readable across the set.

    Tool Count5/5

    Four tools is well-scoped for a development loop server, covering initiation (start_loop, start_debug_loop), progression (advance_loop), and status checking (loop_status). Each tool earns its place without bloat or gaps.

    Completeness5/5

    The tool set provides complete lifecycle coverage for TDD development loops: starting loops (standard and debug), advancing through phases, and checking status. No obvious gaps exist for the stated purpose, enabling agents to manage loops end-to-end.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers