Bmad MCP Server

🚀 BMAD-MCP

BMAD-MCP 是一款遵循 MCP（模型上下文協議）的服務器，作為具備商業思維的敏捷開發（Business-Minded Agile Development）工作流編排器。它涵蓋了完整的敏捷開發工作流：產品負責人（PO）→ 架構師 → Scrum 主管（SM）→ 開發人員 → 代碼審查員 → 質量保證人員（QA）。

其具備以下特性：

• 交互式需求收集：通過詢問澄清問題，確保需求完整。
• 動態引擎選擇：默認使用 Claude，必要時採用雙引擎。
• 內容引用系統：通過文件引用高效使用令牌。
• 易讀的任務名稱：按任務名稱而非 UUID 進行組織。

🚀 快速開始

安裝（3 步）

# 步驟 1：從 npm 全局安裝
npm install -g bmad-mcp

# 步驟 2：添加到 Claude Code
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

# 步驟 3：驗證安裝
bmad-mcp
# 預期輸出："BMAD MCP Server running on stdio"

完成以上步驟後，重啟 Claude Code 即可開始使用 BMAD 工作流。

使用示例

只需告知 Claude Code 使用 BMAD：

用戶：使用 bmad-task 創建一個用戶認證系統

Claude Code 將執行以下操作：
1. 啟動 BMAD 工作流（產品負責人階段）
2. 生成產品需求文檔（通過交互式問答）
3. 生成系統架構（通過交互式問答）
4. 創建 Sprint 計劃
5. 實現代碼（使用 Codex）
6. 進行代碼審查
7. 運行質量保證測試

所有工件將保存到：.claude/specs/user-authentication-system/

配置位置

MCP 配置會自動添加到 ~/.claude/config.json：

{
  "mcpServers": {
    "bmad": {
      "type": "stdio",
      "command": "bmad-mcp"
    }
  }
}

✨ 主要特性

• 管理工作流狀態：明確當前所處階段以及下一步需求。
• 分發角色提示：為每個角色提供詳細提示。
• 保存工件：保存產品需求文檔（PRD）、架構、代碼、報告等。
• 不調用大語言模型（LLMs）：調用 LLMs 是 Claude Code 的任務。

📦 安裝指南

高級安裝選項

選項 1：通過 NPM 安裝（推薦）

npm install -g bmad-mcp
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

選項 2：從源代碼構建

git clone https://github.com/cexll/bmad-mcp-server
cd bmad-mcp-server
npm install
npm run build
npm link  # 使 bmad-mcp 全局可用

# 添加到 Claude Code
claude mcp add-json --scope user bmad '{"type":"stdio","command":"bmad-mcp"}'

驗證安裝

# 檢查二進制文件是否可用
which bmad-mcp
# 輸出：/usr/local/bin/bmad-mcp（或類似路徑）

# 直接測試服務器
bmad-mcp
# 預期輸出："BMAD MCP Server running on stdio"
# 按 Ctrl+C 退出

# 重啟 Claude Code 以加載配置

卸載

# 從 Claude Code 中移除
claude mcp remove bmad

# 卸載 npm 包
npm uninstall -g bmad-mcp

💻 使用示例

基礎用法

// 1. 啟動工作流
const startResult = await callTool("bmad-task", {
  action: "start",
  cwd: "/path/to/your/project",
  objective: "Implement user login system"
});

const { session_id, task_name, role_prompt, engines } = JSON.parse(startResult.content[0].text);

// 2. 使用引擎執行
if (engines.includes("claude")) {
  const claudeResult = await callClaude(role_prompt);
}
if (engines.includes("codex")) {
  const codexResult = await callCodexMCP(role_prompt);
}

// 3. 提交結果
await callTool("bmad-task", {
  action: "submit",
  session_id: session_id,
  stage: "po",
  claude_result: claudeResult,
  codex_result: codexResult
});

// 4. 確認並繼續（統一操作：保存並進入下一階段）
await callTool("bmad-task", {
  action: "confirm",
  session_id: session_id,
  confirmed: true
});

高級用法

start - 啟動新工作流

{
  "action": "start",
  "cwd": "/path/to/project",
  "objective": "Project description"
}

返回結果：

{
  "session_id": "uuid",
  "task_name": "project-description",
  "stage": "po",
  "state": "generating",
  "stage_description": "Product Owner - Requirements Analysis",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "📋 **BMAD 工作流已啟動**...",
  "role_prompt": "<complete prompt>",
  "engines": ["claude"],
  "context": {...},
  "pending_user_actions": ["review_and_confirm_generation"]
}

submit - 提交階段結果

{
  "action": "submit",
  "session_id": "uuid",
  "stage": "po",
  "claude_result": "...",
  "codex_result": "..."
}

當分數 ≥ 90 時的返回結果：

{
  "session_id": "uuid",
  "stage": "po",
  "state": "awaiting_confirmation",
  "score": 92,
  "requires_user_confirmation": true,
  "interaction_type": "user_decision",
  "user_message": "✅ **PRD生成完成**\n質量評分：92/100...",
  "final_draft_summary": "...",
  "final_draft_file": ".bmad-task/temp/uuid/po_final_result_xxx.md",
  "pending_user_actions": ["confirm", "reject_and_refine"]
}

當分數 < 90 且有澄清問題時的返回結果：

{
  "session_id": "uuid",
  "stage": "po",
  "state": "clarifying",
  "current_score": 75,
  "requires_user_confirmation": true,
  "interaction_type": "user_decision",
  "user_message": "⚠️ **需求澄清...**",
  "gaps": ["Target user group unclear", "..."],
  "questions": [{"id": "q1", "question": "...", "context": "..."}],
  "pending_user_actions": ["answer_questions"]
}

confirm - 確認並保存（統一操作）

{
  "action": "confirm",
  "session_id": "uuid",
  "confirmed": true
}

返回結果（保存工件並進入下一階段）：

{
  "session_id": "uuid",
  "stage": "architect",
  "state": "generating",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "💾 **文檔已保存，並已進入下一階段**...",
  "role_prompt": "<architect prompt>",
  "engines": ["claude"],
  "previous_artifact": ".claude/specs/task-name/01-product-requirements.md",
  "pending_user_actions": ["review_and_confirm_generation"]
}

answer - 回答澄清問題

{
  "action": "answer",
  "session_id": "uuid",
  "answers": {
    "q1": "Target users are enterprise B2B customers",
    "q2": "Expected 10k concurrent users with <200ms response time"
  }
}

返回結果：

{
  "session_id": "uuid",
  "stage": "po",
  "state": "refining",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_regeneration",
  "user_message": "📝 **已收到你的回答**...",
  "role_prompt": "<updated prompt with user answers>",
  "engines": ["claude"],
  "pending_user_actions": ["regenerate_with_answers"]
}

approve - 批准當前階段（僅適用於 Scrum 主管階段）

{
  "action": "approve",
  "session_id": "uuid",
  "approved": true
}

進入開發階段時的返回結果：

{
  "session_id": "uuid",
  "stage": "dev",
  "state": "generating",
  "requires_user_confirmation": true,
  "interaction_type": "awaiting_generation",
  "user_message": "✅ **Sprint Plan 已批准**\n\n正在進入下一階段：Developer - Implementation\n\nSprint Plan 包含 3 個 Sprint：\n1. Sprint 1: 基礎架構\n2. Sprint 2: 核心功能\n3. Sprint 3: 優化和完善\n\n⚠️ 重要：請明確指示開發範圍...",
  "role_prompt": "<dev prompt>",
  "engines": ["codex"],
  "pending_user_actions": ["specify_sprint_scope_then_generate"]
}

重要 - 開發階段說明：

• 批准 Sprint 計劃後，工作流進入開發階段，但不會自動開始開發。
• 用戶必須明確指定開發範圍：
  • “開始開發” / “start development” → 實現所有 Sprint（默認）
  • “開發 Sprint 1” / “implement sprint 1” → 僅實現 Sprint 1
• 這樣可確保用戶完全控制開發內容和時間。

status - 查詢工作流狀態

{
  "action": "status",
  "session_id": "uuid"
}

返回結果：

{
  "session_id": "uuid",
  "current_stage": "dev",
  "current_state": "generating",
  "stages": {...},
  "artifacts": [...]
}

📚 詳細文檔

架構

用戶 → Claude Code → bmad-mcp 工具
                       ↓
            返回結果: {
              stage: "po",
              role_prompt: "<完整的產品負責人提示>",
              engines: ["claude", "codex"],
              context: {...}
            }
                       ↓
Claude Code 執行操作:
  - 調用 Claude（使用角色提示）
  - 調用 Codex MCP（使用角色提示）
                       ↓
Claude Code 提交結果 → bmad-mcp
                       ↓
bmad-mcp: 合併、評分、保存結果，並進入下一階段

工作流階段

文件結構

項目結構

your-project/
├── .bmad-task/
│   ├── session-abc-123.json          # 工作流狀態（包含內容引用）
│   ├── task-mapping.json             # 將 session_id 映射到任務名稱
│   └── temp/
│       └── abc-123/                  # 臨時內容文件
│           ├── po_claude_result_xxx.md
│           ├── po_codex_result_xxx.md
│           └── po_final_result_xxx.md
├── .claude/
│   └── specs/
│       └── implement-user-login/     # 任務名稱（易讀的短名稱）
│           ├── 01-product-requirements.md
│           ├── 02-system-architecture.md
│           ├── 03-sprint-plan.md
│           ├── 04-dev-reviewed.md
│           └── 05-qa-report.md
└── src/

會話狀態文件

{
  "session_id": "abc-123",
  "task_name": "implement-user-login",
  "cwd": "/path/to/project",
  "objective": "Implement user login",
  "current_stage": "dev",
  "current_state": "generating",
  "stages": {
    "po": {
      "status": "completed",
      "claude_result_ref": {
        "summary": "前 300 個字符...",
        "file_path": ".bmad-task/temp/abc-123/po_claude_result_xxx.md",
        "size": 12450,
        "last_updated": "2025-01-15T10:30:00Z"
      },
      "final_result_ref": {...},
      "score": 92,
      "approved": true
    },
    ...
  },
  "artifacts": [".claude/specs/implement-user-login/01-product-requirements.md", ...]
}

引擎配置

產品負責人和架構師階段（動態引擎選擇）

• 默認情況：僅使用 Claude（單引擎）。
• 雙引擎情況：當目標中包含 “codex” 或 “使用 codex” 時啟用。
• 若啟用雙引擎：
  • 同時調用 Claude 和 Codex。
  • 每個引擎生成獨立的解決方案。
  • BMAD-MCP 合併結果：
    • 若兩者分數均 ≥ 90：選擇分數較高的結果。
    • 若其中一個分數 ≥ 90：選擇該結果。
    • 若兩者分數均 < 90：選擇分數較高的結果並進行優化。
• 交互式澄清：
  • 第一輪迭代：識別差距，生成 3 - 5 個澄清問題。
  • 用戶回答問題。
  • 根據回答重新生成內容。
  • 迭代直至分數 ≥ 90。

Scrum 主管階段（僅使用 Claude）

僅調用 Claude，因為 Scrum 計劃不需要 Codex。

開發/審查/質量保證階段（僅使用 Codex）

• 僅調用 Codex MCP。
• 代碼任務使用 GPT - 5。
• 重要：使用 model: "gpt-5"（而非 “gpt - 5 - codex”）。
• 參數：
  • model: "gpt-5"
  • sandbox: "danger-full-access"
  • approval-policy: "on-failure"

工作流流程

graph TD
    A[開始] --> B[產品負責人階段：生成]
    B --> C{是否有問題?}
    C -->|是| D[澄清階段：用戶回答]
    D --> E[優化階段：重新生成]
    E --> F{分數 ≥ 90?}
    C -->|否| F
    F -->|否| C
    F -->|是| G[等待確認]
    G -->|確認| H[保存並進入架構師階段]
    H --> I{是否有問題?}
    I -->|是| J[澄清階段：用戶回答]
    J --> K[優化階段：重新生成]
    K --> L{分數 ≥ 90?}
    I -->|否| L
    L -->|否| I
    L -->|是| M[等待確認]
    M -->|確認| N[保存並進入 Scrum 主管階段]
    N -->|批准| O[開發階段]
    O --> P[審查階段]
    P --> Q[質量保證階段]
    Q --> R[完成]

🔧 技術細節

項目結構

bmad-mcp/
├── src/
│   ├── index.ts              # 主 MCP 服務器
│   └── master-prompt.ts      # 所有角色提示
├── dist/                     # 編譯輸出
├── package.json
├── tsconfig.json
└── README.md

構建

npm run build

開發模式

npm run dev  # 監聽模式

本地測試

npm run build
node dist/index.js

主編排器設計

所有角色提示都嵌入在單個 master-prompt.ts 文件中：

• 集中管理：所有角色提示集中在一處。
• 工作流定義：明確階段順序。
• 引擎配置：指定每個階段使用的引擎。
• 質量關卡：設定分數閾值和批准點。

與 Codex MCP 集成

在開發/審查/質量保證階段調用 Codex 時：

// Claude Code 調用 Codex MCP
await callTool("codex", {
  prompt: role_prompt,  // 來自 bmad-task
  model: "gpt-5",  // 重要：使用 "gpt-5"，而非 "gpt-5-codex"
  sandbox: "danger-full-access",
  "approval-policy": "on-failure"
});

配置

質量閾值

在 master-prompt.ts 中定義：

quality_gates: {
  po: { min_score: 90, approval_required: true },
  architect: { min_score: 90, approval_required: true },
  sm: { approval_required: true },
  dev: {},
  review: {},
  qa: {}
}

工件文件名

artifacts: {
  po: "01-product-requirements.md",
  architect: "02-system-architecture.md",
  sm: "03-sprint-plan.md",
  dev: "code-implementation",
  review: "04-dev-reviewed.md",
  qa: "05-qa-report.md"
}

🔍 故障排除

服務器無法啟動

# 檢查安裝情況
which bmad-mcp

# 直接測試
bmad-mcp

工具名稱錯誤

• 重要：工具名稱是 bmad-task，而非 bmad。
• 在代碼中使用 callTool("bmad-task", {...})。
• Claude Code 配置應使用 bmad-task 作為工具名稱。

會話未找到

• 確保 .bmad-task/ 目錄具有寫入權限。
• 檢查 session_id 是否正確。
• 驗證 cwd 路徑是否為絕對路徑。

分數未檢測到

• 確保生成的內容包含：Quality Score: X/100 或 JSON 中的 "quality_score": 92。
• 檢查分數格式是否符合模式（0 - 100）。
• 產品負責人/架構師階段需要分數 ≥ 90 才能進入下一階段。

澄清工作流問題

• 若看到 state: "clarifying"，用戶必須通過 answer 操作回答問題。
• 不要自動生成答案，等待用戶的真實輸入。
• 在繼續操作前，檢查 requires_user_confirmation: true。

📄 許可證

本項目採用 MIT 許可證。

🙋 支持

• 文檔：本 README 文件。
• 問題反饋：GitHub 問題。
• 參考資料：https://github.com/cexll/myclaude

使用 BMAD 變革你的開發流程 —— 一套工作流，涵蓋完整敏捷過程，確保開發質量。