dev-loop-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dev-loop-mcp Add email validation to the signup form"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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"])
endFull 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:#fffPer-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)"| DPhase 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
buildCommandDEPLOY: Runs
deployCommand— skipped if not configuredINTEG_TEST: Runs
integTestCommand— skipped if not configuredINTEG_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-mcpOr use via npx:
npx dev-loop-mcpConfiguration
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 |
| Yes | Your Anthropic API key |
| No | Project root directory (defaults to |
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 failurecontext_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 toolsadvance_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Devopness MCP server for DevOps happiness! Empower AI Agents to deploy apps and infra, to any cloud.
Related MCP Servers
- AlicenseBqualityBmaintenanceMCP server that integrates DevFlow with AI code assistants to enforce structured development workflows including planning, task tracking, and code review gates.6533 npm1MIT
- AlicenseNot gradedqualityDmaintenanceAn autonomous MCP server for AI-assisted development with zero-API approach, auto-correction, inverted TDD, and native pipelines.MIT
- AlicenseAqualityBmaintenanceAn MCP server that brings senior-QA discipline to AI coding assistants, enabling test planning, TDD, mutation testing, and code review.50370 PyPI7Apache 2.0
- AlicenseNot gradedqualityCmaintenanceAn MCP server that adds engineering discipline to AI-assisted development, enforcing evidence-gated TDD, security review, backup strategy, and deployment generation to turn AI-generated code into production-ready software.11MIT