bmalph-mcp-server

From idea to implemented code — without losing context.

A universal MCP Server that orchestrates BMAD-METHOD structured planning and bmalph/Ralph autonomous TDD execution in a single, installable package.

Built on the Model Context Protocol from Anthropic. Compatible with Claude Desktop, Claude Code, Cursor, OpenCode, Cline, Continue.dev, Google Antigravity, GPT-Codex, Gemini CLI, and VSCode.

The Problem This Solves

AI coding agents produce worse results the longer a session runs. Context accumulates, models lose track of the original plan, and code drifts from the intended architecture. The community calls it context drift.

The solution the vibe-coding community converged on:

1. Plan thoroughly before coding — BMAD-METHOD forces the AI to think before it builds: Brief → PRD → Architecture → Epics & Stories
2. Execute in isolated contexts — Ralph opens a fresh Claude Code instance per story, eliminating context drift
3. Bridge the gap automatically — bmalph-mcp-server handles the handoff between planning and execution, no manual copy-paste

Quick Start

Zero files to download. Zero config to write manually.

Step 1 — Initialize your project

Run this once in your project folder:

npx bmalph-mcp-server init

This will:

• Ask which MCP client you use (Claude Desktop, Cursor, OpenCode, etc.)
• Write the correct config file automatically
• Create _bmad-output/ folder structure
• Copy BMAD workflow files to _bmad/

Shorthand aliases — all three commands do the same thing:

npx bmalph-mcp-server init
npx vibe-flow init
npx bmalph-mcp init

Step 2 — Restart your MCP client

After init, restart your IDE or MCP client once. The server will appear automatically.

Step 3 — Start building

Tell your AI assistant what you want to build. The detect_intent tool will route you to the right workflow automatically.

Manual MCP config (if you prefer)

{
  "mcpServers": {
    "vibe-flow": {
      "command": "npx",
      "args": ["-y", "bmalph-mcp-server"]
    }
  }
}

| Client | Config file location | |--------|----------------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | Claude Code | .claude-code/config.json in project root | | Cursor | .cursor/mcp.json in project root | | OpenCode | .opencode/mcp.json in project root | | Cline | VSCode global storage cline_mcp_settings.json | | Continue.dev | ~/.continue/config.json | | Antigravity | .antigravity/mcp.json in project root | | GPT-Codex | ~/.config/codex/codex.json | | Gemini CLI | ~/.config/gemini/gemini.json |

Migrate artifacts (after version upgrade)

npx bmalph-mcp-server migrate          # migrate to current schema
npx bmalph-mcp-server migrate --dry-run  # preview without changes

Detects your MCP client and writes the correct config file automatically. Supports 9 clients.

Option 2 — Manual configuration

Add to your MCP client config:

{
  "mcpServers": {
    "vibe-flow": {
      "command": "npx",
      "args": ["-y", "bmalph-mcp-server"]
    }
  }
}

| Client | Config file location | |--------|----------------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | Claude Code | .claude-code/config.json in project root | | Cursor | .cursor/mcp.json in project root | | OpenCode | .opencode/mcp.json in project root | | Cline | VSCode global storage cline_mcp_settings.json | | Continue.dev | ~/.continue/config.json | | Antigravity | .antigravity/mcp.json in project root | | GPT-Codex | ~/.config/codex/codex.json | | Gemini CLI | ~/.config/gemini/gemini.json |

Option 3 — CLI migration

npx vibe-flow migrate        # migrate artifacts to current schema
npx vibe-flow migrate --dry-run  # preview without changes

Workflow

Idea → Brief → PRD → Architecture → Epics → IR Gate → Ralph → Done

Phase 1 — BMAD Planning

Use the bmad_principal_engineer prompt to activate the planning mode, then run tools in sequence:

create_product_brief  →  create_prd  →  create_architecture  →  create_epics_stories

Each step generates a markdown artifact in _bmad-output/planning-artifacts/.

Phase 2 — Implementation Readiness Gate

check_implementation_readiness

Returns GO or NO-GO with specific gaps. Implementation is blocked until the gate passes. This prevents the most common failure mode: implementing before the plan is complete.

Phase 3 — Ralph Execution

Use the ralph_senior_engineer prompt, then:

bmalph_bridge_implement  →  spawn_ralph_worker (per story)

Ralph opens an isolated Claude Code instance for each story — fresh context, no drift.

Anytime — Course Correction

correct_course  →  apply_course_correction

Scope changed mid-sprint? correct_course analyzes impact on PRD, Architecture, and Stories before touching anything.

Session End — Wrap Up

wrap_up

Commits pending changes with semantic messages, fixes file naming, persists session learnings to CLAUDE.md, and optionally generates community insight drafts.

MCP Tools Reference

Planning Tools

| Tool | Description | |------|-------------| | create_product_brief | Create a Product Brief from a natural language idea. First step in BMAD. | | create_prd | Generate a PRD with Functional Requirements, NFRs, and scope from a Brief. | | create_architecture | Document technical decisions, patterns, and components from the PRD. | | create_epics_stories | Break down PRD + Architecture into Epics and Stories with BDD acceptance criteria. | | detect_intent | Detect which workflow to start from natural language. Falls back to explicit menu. | | elicitation_mode | Apply Advanced Elicitation [A] or Party Mode [P] to any workflow step. |

Quality Gates

| Tool | Description | |------|-------------| | check_implementation_readiness | Validate PRD, Architecture, and Epics alignment. Returns GO/NO-GO. Persists to state. |

Sprint & Story Management

| Tool | Description | |------|-------------| | sprint_planning | Generate ordered sprint plan from epics.md. | | create_story | Prepare individual story with isolated, self-contained context for Ralph. | | get_status | Current project status + next recommended step. | | list_workflows | List all available BMAD workflows with commands and phases. |

Execution Bridge

| Tool | Description | |------|-------------| | bmalph_bridge_implement | Convert planning artifacts to Ralph task format. Creates .ralph/@fix_plan.md. | | spawn_ralph_worker | Spawn isolated Claude Code subprocess for a task. Fresh context per story. | | get_worker_status | Check status of a running Ralph worker by task_id. | | circuit_breaker_rollback | Git-based safety rollback when Ralph generates broken code. | | generate_bmad_artifacts | Save BMAD planning documents to disk (briefing, prd, architecture, epics). |

Course Correction

| Tool | Description | |------|-------------| | correct_course | Analyze impact of scope change on all artifacts. Read-only. | | apply_course_correction | Apply correction: update artifacts + append to append-only history log. |

Session Learning Loop

| Tool | Description | |------|-------------| | wrap_up | Ship It: auto-commit with Conventional Commits. Remember It: persist learnings to CLAUDE.md and .claude/rules/. Review & Apply: generate [RULE] entries for recurring errors. Publish It: draft community insights to _bmad-output/publish-drafts/. |

MCP Resources

| Resource | URI | Description | |----------|-----|-------------| | Architecture | bmad://architecture | Live architecture document | | PRD | bmad://prd | Product requirements document | | Briefing | bmad://briefing | Project briefing | | Task Queue | ralph://task_queue | Current Ralph tasks with status | | Ralph Status | ralph://status | Ralph loop runtime status |

MCP Prompts

bmad_principal_engineer

Activates BMAD planning mode. Guides the AI through Analysis → Planning → Solutioning, enforcing "think before build". References generate_bmad_artifacts and bmalph_bridge_implement.

ralph_senior_engineer

Activates Ralph autonomous execution mode. Enforces TDD-first, one-task-per-loop, and status reporting via RALPH_STATUS blocks. References circuit_breaker_rollback for safety.

Architecture

┌────────────────────────────────────────────────────────────────┐
│                        IDE / MCP Client                        │
│         (Claude Desktop, Claude Code, Cursor, OpenCode…)       │
└─────────────────────────┬──────────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌────────────────────────────────────────────────────────────────┐
│                   bmalph-mcp-server                            │
│                                                                │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ Workflow    │  │ IR Gate      │  │ Session Learning     │  │
│  │ Engine      │  │ (GO/NO-GO)   │  │ Loop (/wrap-up)      │  │
│  └─────────────┘  └──────────────┘  └──────────────────────┘  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ NLP Intent  │  │ Elicitation  │  │ Course Correction    │  │
│  │ Classifier  │  │ & Party Mode │  │ & History            │  │
│  └─────────────┘  └──────────────┘  └──────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Ralph Bridge + Circuit Breaker             │   │
│  └─────────────────────────────────────────────────────────┘   │
└──────────┬─────────────────────────────────┬───────────────────┘
           │                                 │
           ▼                                 ▼
┌─────────────────────┐          ┌─────────────────────────────┐
│  _bmad-output/      │          │  Ralph Workers              │
│  planning-artifacts │          │  (isolated Claude Code      │
│  implementation-    │          │   subprocess per story)     │
│  artifacts          │          └─────────────────────────────┘
└─────────────────────┘

Key design decisions:

• Filesystem sandbox — all file I/O is validated via assertSafePath(). The server never reads or writes outside _bmad-output/, .ralph/, .vibe-flow/, .claude/, and a few config files.
• IR Gate — bmalph_bridge_implement is blocked until check_implementation_readiness returns GO. You cannot accidentally start implementing an incomplete plan.
• Fresh context per story — spawn_ralph_worker creates a new, isolated Claude Code process for each story. Context from story N never bleeds into story N+1.
• State persistence — session state lives in .vibe-flow/state.json. Restarting the MCP client never loses planning progress.
• Backward compatibility — artifact schema changes only happen on major versions. v1.x artifacts work with any v1.y server.

Generated File Structure

_bmad-output/
  planning-artifacts/
    product-brief-<project>-<date>.md   # Brief
    prd.md                               # Product Requirements Document
    architecture.md                     # Architecture decisions
    epics.md                             # Epics + Stories with BDD ACs
    sprint-plan.md                       # Ordered sprint plan
    course-corrections.md                # Append-only correction history
    publish-drafts/                      # Community insight drafts (wrap-up)
  implementation-artifacts/
    sprint-status.yaml                   # Story/epic status tracking
    stories/
      1-1-<story-name>.md               # Individual story contexts

_bmad/
  config.yaml                            # BMAD configuration
  bmm/workflows/                         # BMAD workflow definitions

.vibe-flow/
  state.json                             # Session state (IR gate, artifacts, lastWrapUp)

.claude/
  rules/                                 # Folder-scoped rules (generated by wrap-up)

CLAUDE.md                                # Global project rules (generated by wrap-up)
CLAUDE.local.md                          # Local unfinished context (generated by wrap-up)

Development

git clone https://github.com/your-org/bmalph-mcp-server
cd bmalph-mcp-server
npm install
npm run build

# Run tests
npm test

# Run preflight (build + test + typecheck)
npm run preflight

# Watch mode
npm run dev

Credits

This project stands on the shoulders of two exceptional frameworks from the vibe-coding community:

BMAD-METHOD

github.com/bmad-method/BMAD-METHOD

The planning methodology powering this server. BMAD forces AI agents to think structurally before writing code: Brief → PRD → Architecture → Epics & Stories → Implementation Readiness Gate. Created to solve the most common AI coding failure: building the wrong thing well.

"Think before you build."

bmalph / Ralph

github.com/ralphf/ralph

The autonomous TDD execution loop. Ralph implements stories one at a time, each in a fresh Claude Code instance with isolated context. The bmalph bridge connects BMAD planning artifacts to Ralph's task format — eliminating the manual handoff that previously required copying specifications between tools.

"One story. One context. No drift."

License

MIT

Built with the belief that context is the most valuable resource in AI-assisted development — and that protecting it is an engineering problem worth solving.