🚀 Phases MCP

A spec-driven, context-engineered development methodology as an MCP server.

Stop vibecoding. Start shipping phase by phase.

Phases turns your AI coding assistant into a structured development partner. Clarify intent, define specs, plan in phases, execute with atomic commits, and verify with real automated tests.

⚡ Quick Setup

Install & Build

git clone https://github.com/tankuday21/phases-mcp.git
cd phases-mcp
npm install
npm run build

Add to Your MCP Client

Add this to your MCP configuration:

{
  "mcpServers": {
    "phases": {
      "command": "node",
      "args": ["/path/to/phases-mcp/dist/index.js"],
      "transportType": "stdio"
    }
  }
}

Restart your IDE/client and all 19 phases_* tools will be available.

🎮 Available Tools (19)

🔴 Clarify First

| Tool | Purpose | |------|---------| | phases_clarify | Ask smart questions to understand user intent before starting |

🔵 Core Workflow

| Tool | Purpose | |------|---------| | phases_init | Initialize project with SPEC + ROADMAP | | phases_refine | Split large phases into smaller sub-phases | | phases_plan | Create XML-structured execution plans | | phases_execute | Record task completion + atomic git commit | | phases_verify | Auto-run test commands with real evidence | | phases_debug | Systematic debugging with 3-strike rule | | phases_rollback | Revert a phase that went wrong | | phases_map | Analyze codebase → ARCHITECTURE.md |

🟢 Navigation & State

| Tool | Purpose | |------|---------| | phases_progress | Show current position in roadmap | | phases_pause | Save session state for handoff | | phases_resume | Restore context from last session |

🟠 Phase Management

| Tool | Purpose | |------|---------| | phases_add_phase | Add a phase to the roadmap | | phases_remove_phase | Remove a phase (with safety checks) | | phases_discuss_phase | Clarify scope before planning | | phases_milestone | Create a new milestone with phases |

🟣 Utilities

| Tool | Purpose | |------|---------| | phases_add_todo | Quick capture an idea or task | | phases_check_todos | List all pending TODO items | | phases_help | Show all tools and workflow |

🔄 Enhanced Workflow

phases_clarify → phases_init → phases_refine → phases_plan → phases_execute → phases_verify → (phases_rollback if needed)

1. phases_clarify — Ask smart questions to understand what the user really wants
2. phases_init — Define your project vision, goals, and development phases
3. phases_refine — Split any large phases into smaller, manageable sub-phases
4. phases_plan — Create XML-structured plans with tasks, verification commands, and acceptance criteria
5. phases_execute — Complete tasks one-by-one, each with an atomic git commit
6. phases_verify — Auto-run test commands and capture real evidence (exit code 0 = PASS)
7. phases_rollback — If something goes wrong, revert the phase and try again

📁 Project Structure Created

.gsd/
├── SPEC.md          ← Finalized project specification
├── ROADMAP.md       ← Phases and progress tracking
├── STATE.md         ← Session memory and current position
├── ARCHITECTURE.md  ← System design (from phases_map)
├── DECISIONS.md     ← Architecture Decision Records
├── JOURNAL.md       ← Session log
├── TODO.md          ← Quick capture
└── phases/
    ├── 1/
    │   ├── 1-PLAN.md
    │   ├── 1-SUMMARY.md
    │   ├── VERIFICATION.md
    │   └── TEST-RESULTS.md   ← Auto-generated test output
    └── 2/
        └── ...

🧠 Philosophy

• Clarify before code — Ask questions first, don't assume
• Spec before code — SPEC.md matters more than you think
• Small phases — Break work into the smallest achievable phases
• Phase-driven development — Break work into achievable phases
• Fresh context > polluted context — State dumps prevent hallucinations
• Proof over trust — Auto-run real tests, don't self-report
• Aggressive atomicity — 2-3 tasks per plan, atomic commits
• 3-strike debugging — After 3 failures, dump context and start fresh
• Safe rollbacks — If a phase goes wrong, revert and try again

🛠 Tech Stack

• TypeScript — Type-safe implementation
• MCP SDK — @modelcontextprotocol/sdk for server framework
• Zod — Schema validation for all tool inputs
• stdio transport — Local process communication

License

MIT