dev-loop-mcp

Un servidor MCP (Model Context Protocol) que ejecuta un bucle de desarrollo TDD impulsado por IA. Generaliza la máquina de estados del bucle de desarrollo para trabajar con cualquier proyecto mediante un archivo de configuración simple.

Qué hace

Hay dos tipos de bucles disponibles; ambos comparten la misma canalización TDD; solo difieren en cómo se producen las tareas:

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

Máquina de estados completa

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

Ciclo TDD por tarea

Cada tarea en TDD_LOOP ejecuta este ciclo interno (hasta 5 iteraciones de codificación):

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

Referencia de fases:

INIT: Crea la rama de git
DECOMPOSE: La IA convierte una descripción en una Task[]
DIAGNOSE: (solo bucle de depuración) La IA lee los síntomas + archivos de contexto y produce hipótesis de causa raíz clasificadas como una Task[]
TDD_LOOP: Por tarea: escenarios → pruebas fallidas → implementación (hasta 5 iteraciones de codificación por tarea)
BUILD: Ejecuta buildCommand
DEPLOY: Ejecuta deployCommand — se omite si no está configurado
INTEG_TEST: Ejecuta integTestCommand — se omite si no está configurado
INTEG_FIX: La IA diagnostica y corrige fallos en las pruebas de integración (hasta 5 intentos)
QUALITY_REVIEW: La IA revisa la diferencia completa de la rama y aplica correcciones de calidad
CLEAN_TREE_CHECK: Confirma automáticamente cualquier archivo no confirmado
PUSH_AND_PR: Envía la rama y abre una PR de GitHub

Instalación

npm install -g dev-loop-mcp

O úsalo mediante npx:

npx dev-loop-mcp

Configuración

Crea dev-loop.config.json en la raíz de tu proyecto:

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

Todos los campos son opcionales. Valores predeterminados:

buildCommand: "npm run build"
testCommand: "npm test"
deployCommand: ausente (fase DEPLOY omitida)
integTestCommand: ausente (fase INTEG_TEST omitida)
branchPrefix: "claude/"
model: "claude-sonnet-4-6"

Variables de entorno

Variable	Requerido	Descripción
`ANTHROPIC_API_KEY`	Sí	Tu clave de API de Anthropic
`DEV_LOOP_ROOT`	No	Directorio raíz del proyecto (por defecto `cwd`)

Configuración de MCP

Añádelo a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json de Claude Desktop):

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

Herramientas disponibles

`start_debug_loop`

Inicia un bucle de depuración a partir de una descripción de síntoma. La IA diagnostica las causas raíz como tareas TDD clasificadas, luego ejecuta la canalización TDD estándar por hipótesis y abre una PR con un informe de diagnóstico completo.

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

Parámetros:

symptom (requerido) — descripción en lenguaje natural del error o fallo observado
context_files (opcional) — rutas relativas a los archivos fuente que la IA debe leer mientras diagnostica

El paso DIAGNOSE se ejecuta antes de la canalización TDD estándar (ver la máquina de estados arriba). El cuerpo de la PR incluye el síntoma, las causas raíz identificadas y lo que se corrigió.

La rama se nombra <branchPrefix>debug/<symptom-slug>.

`start_loop`

Inicia un nuevo bucle de desarrollo.

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

O con tareas pre-descompuestas:

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

Reanuda un bucle interrumpido:

{}

`loop_status`

Comprueba el estado actual del bucle:

{}

Uso como biblioteca

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,
});

dev-loop-mcp

dev-loop-mcp

Qué hace

Máquina de estados completa

Ciclo TDD por tarea

Instalación

Configuración

Variables de entorno

Configuración de MCP

Herramientas disponibles

`start_debug_loop`

`start_loop`

`resume_loop`

`loop_status`

Uso como biblioteca

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API