@huhai0403/bmad-workflow-mcp

v0.5.0

Published

9 days ago

BMAD automated development workflow as an MCP server

0High
0Medium
0Low

huhai0403

mcp bmad workflow cursor

@huhai0403/bmad-workflow-mcp

BMAD 自动化开发工作流 MCP Server — 可在 Cursor、OpenCode 等 MCP 客户端中直接调用，无需安装 BMAD 本体或 Skill 文件。

相对原版 BMAD 的差异：双工作流模式（planning 全流程 / pipeline 增量批处理）、v0.3.0 新增 chain_to_pipeline 默认开启（一次工具调用跑完 planning + pipeline）、v0.5.0 重新引入 use_llm + 新增 requirement_file（让 MCP 端能直接读 650 行 PRD 并调 LLM 产出高质量规划产物）、AI 代码审查走 host 端 /bmad-code-review skill（不内置 LLM 调用）、原生 MCP 协议、状态持久化与断点续传。

功能

双工作流模式
- planning：PRD → 用户故事 → AC → 架构 → 任务 → 代码生成 → 代码审查 → 审计
- pipeline：Story Discovery → Dev → Test → Review → Status → Checkpoint → Audit
planning 阶段 LLM 增强（v0.5.0）：use_llm=true（默认）且 OPENAI_API_KEY / LLM_API_KEY 存在时，planning 7 步产物由 OpenAI 兼容 LLM 解析 PRD 后生成；无 key 或调用失败时自动 fallback 到模板
PRD 文件直读（v0.5.0）：requirement_file: "docs/prd.md" 让 MCP 端直接读文件，无需把 650 行塞进 MCP 参数
batch / epic / story 粒度控制（pipeline 模式；留空则全量运行）
精简入参：project_root 可省略（默认 MCP 启动 cwd），start_bmad_workflow 只剩 workflow_type / output_dir / requirement_description 等核心参数；其他参数有合理默认值
AI 代码审查：MCP 端产出 lint-only 初始 fingerprint，由 host 端 /bmad-code-review skill 覆盖为 source=llm 才可 APPROVE
4-checkpoint 完成审计：每个 story 必须同时具备 Test Output、Lint Output、Code Review Summary、Definition of Done 四项证据，缺一即重排队为 in-progress 并返回 workflow 失败
状态持久化、dry-run、断点续传、审计日志
Token 估算：优先 tiktoken（可选依赖），否则字符数 ÷ 4

环境要求

Node.js >= 18（见 package.json 的 engines 字段）
支持 MCP 协议的客户端：Cursor / OpenCode / Claude Desktop / 其他 MCP Host

安装

全局安装（推荐，使用已发布版本）：

npm install -g @huhai0403/bmad-workflow-mcp

本地开发（克隆仓库后）：

npm install
npm run build

配置

Cursor 配置

编辑 ~/.cursor/mcp.json：

本地构建版本（路径请替换为你的实际位置）：

{
  "mcpServers": {
    "bmad-workflow": {
      "command": "node",
      "args": ["D:/auto-dev-workflow/dist/index.js"]
    }
  }
}

npm 全局安装版本：

{
  "mcpServers": {
    "bmad-workflow": {
      "command": "npx",
      "args": ["-y", "@huhai0403/bmad-workflow-mcp"]
    }
  }
}

Windows 路径建议统一使用正斜杠 /，避免 JSON 转义问题。

OpenCode 配置

OpenCode 的 MCP 配置位于 mcp 字段。

项目级（<project>/opencode.json，仅当前项目生效）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bmad-workflow": {
      "type": "local",
      "command": ["node", "D:/auto-dev-workflow/dist/index.js"]
    }
  }
}

全局（~/.config/opencode/opencode.json，所有项目共享，推荐使用 npx）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bmad-workflow": {
      "type": "local",
      "command": ["npx", "-y", "@huhai0403/bmad-workflow-mcp"]
    }
  }
}

macOS / Linux 路径示例：

{
  "mcp": {
    "bmad-workflow": {
      "type": "local",
      "command": ["node", "/Users/you/projects/auto-dev-workflow/dist/index.js"]
    }
  }
}

也可通过 OpenCode CLI 临时注册（仅当前会话）：

opencode mcp add bmad-workflow -- node /path/to/auto-dev-workflow/dist/index.js

配置完成后重启 Cursor / OpenCode 使 MCP Server 生效。具体字段以 OpenCode 官方文档为准。

快速开始

在 Cursor / OpenCode 中对模型说任意一句描述意图的话（例如 "用 bmad-workflow 帮我规划一个 TODO 列表 Web 应用"）。模型会读取工具 description 里的推荐选项，把以下预设之一呈现给用户选择：

| 选项 | 适用场景 | 关键参数 | |------|---------|---------| | 1. Planning（新建项目） | 从 0 开始一个新项目 | workflow_type=planning, output_dir=.bmad-output, requirement_file=docs/prd.md（推荐）或 requirement_description=… | | 2. Planning dry-run | 先看产物结构、不落盘 | mode=dry-run, include_codegen=false | | 3. Pipeline（继续既有 batch） | 在已有 batch 上继续开发 | workflow_type=pipeline, batch=<name>, epic=<n>?, story=<n>-<m>? | | 4. List batches | 先看看有哪些 batch | 调用 list_bmad_batches(output_dir=".bmad-output") |

project_root 可省略——不传时默认使用 MCP server 启动时的当前目录（通常是 Cursor/OpenCode 的工作区根）。

use_llm 默认 true——若 MCP 进程环境里有 OPENAI_API_KEY（或 LLM_API_KEY），planning 7 步产物由 OpenAI 兼容 LLM 生成高质量内容；无 key 或调用失败时自动 fallback 到模板。无 key 时可显式 use_llm=false 跳过判断以提速。

用户选定一个选项后，模型再调 start_bmad_workflow。比如选 1，对应参数（PRD 写在文件里）：

{
  "output_dir": ".bmad-output",
  "workflow_type": "planning",
  "requirement_file": "docs/prd.md"
}

或内联简述（仍由 LLM 解析）：

{
  "output_dir": ".bmad-output",
  "workflow_type": "planning",
  "requirement_description": "实现一个 TODO 列表的 Web 应用"
}

v0.3.0 行为变更：chain_to_pipeline 默认 true。一次 start_bmad_workflow 跑完 planning 后，会在同一次工具调用内自动扫描 planning-artifacts/ 推断 batch 并跑完 pipeline。Host 端 LLM 不必再发起第二次调用。要保持 v0.2.x 行为请显式传 chain_to_pipeline: false。

使用流程

全新项目（从 0 开始）

| # | 用户对模型说 | 关键参数 | |---|---|---| | 1 | "用 bmad-workflow 跑一次 planning dry-run，需求：XXX" | 选选项 2：mode: dry-run, include_codegen: false, chain_to_pipeline: false | | 2 | "刚才那条改成正常模式" | 去掉 mode: dry-run，开启 chain_to_pipeline: true（默认即开） | | 3 | 读 outputDir/planning-artifacts/{slug}/01-prd.md ~ 04-architecture.md；偏差大就："用 bmad-workflow 取消 workflow_id=xxx" | cancel_workflow | | 4 | "再跑一次完整链（planning + pipeline）" | chain_to_pipeline: true（默认即开） | | 5 | 后续特性切 pipeline："用 bmad-workflow 跑 pipeline，batch=todo-v1，先 dry-run" | 选选项 3 + mode: dry-run |

v0.5.0 输出结构变化：planning 7 步产物（01-prd.md ~ 07-code-review.md）现写到 output_dir/planning-artifacts/{slug}/ 下（与原 Skill 的 _bmad-output/planning-artifacts/{batch}/ 对齐），便于 chain_to_pipeline 推断 batch。final-report.md 与 audit-log.json 仍在 output_dir/ 顶层。

既有项目（增量迭代）

| # | 用户对模型说 | 关键参数 | |---|---|---| | 1 | "用 bmad-workflow 列出当前项目的所有 batch" | list_bmad_batches(output_dir=".bmad-output") | | 2 | "用 bmad-workflow 跑 pipeline，batch=xxx，epic=1，story=1-2" | 选选项 3 + epic: "1", story: "1-2" | | 3 | 中断时："用 bmad-workflow 续 workflow_id=xxx" | resume_bmad_workflow | | 4 | 纯实现时："include_code_review 改 false 再跑一次" | include_code_review: false | | 5 | 读 audit-log.json，对 skipped/failed 项针对性补 | — |

反模式

planning 一次性开 include_codegen=true 跑全量 — 中间决策被跳过
pipeline 不带 epic/story 一次全跑 — 失败要重跑整批
改完代码不复跑 — audit-log 与实际代码脱节

MCP 工具

| 工具 | 说明 | |------|------| | start_bmad_workflow | 启动工作流 | | resume_bmad_workflow | 断点续传（按 workflow_id 恢复） | | get_workflow_status | 查询进度 | | cancel_workflow | 软取消（保留已生成产物） | | list_bmad_batches | 列出可用 batch |

start_bmad_workflow

启动一次工作流。所有工具的 project_root 均为可选——省略时使用 MCP server 启动时的工作目录（通常是 Cursor / OpenCode 的工作区根）。

核心参数：

| 参数 | 必填 | 默认 | 说明 | |------|------|------|------| | project_root | | MCP 启动 cwd | 项目根目录（绝对路径）。省略时使用 MCP server 启动时的工作目录 | | output_dir | ✅ | | 产物根目录（相对 project_root，如 .bmad-output 或 _bmad-output） | | workflow_type | | planning | planning 或 pipeline | | requirement_description | planning 必填* | | 内联需求描述文本（pipeline 模式可选） | | requirement_file | planning 必填* | | (v0.5.0) 相对 project_root 的 PRD 文件路径（如 docs/prd.md）。与 requirement_description 二选一；都传时 requirement_file 优先。推荐用于 > 50 行的 PRD——避免把 650 行塞进 MCP 参数 | | use_llm | | true (v0.5.0) | (planning only) 启用 LLM 增强。需要环境变量 OPENAI_API_KEY（或 LLM_API_KEY）；可用 OPENAI_BASE_URL / OPENAI_MODEL 覆盖。无 key 或调用失败时自动 fallback 到模板 | | mode | | normal | dry-run 仅预览不落盘 | | include_codegen | | true | 启用代码生成步骤；纯文档场景可设 false 提速 | | include_code_review | | true | 启用代码审查（尝试 npm run lint，MCP 端只能产出 lint-only fingerprint） | | batch | pipeline 推荐 | | batch 名称（pipeline 模式；留空全量） | | epic | | | epic 过滤（如 "1"） | | story | | | story 过滤（如 "1-3"） | | chain_to_pipeline | | true (v0.3.0 改默认值) | planning 跑完后在同一次工具调用内自动跑 pipeline（按 planning-artifacts/{slug}/ 推断 batch）。false 退回 v0.2.x 行为 |

调用示例（最小化入参）：

{
  "output_dir": ".bmad-output",
  "requirement_description": "实现一个 TODO 列表的 Web 应用"
}

resume_bmad_workflow

从 .bmad-workflow-state.json 续跑（断点续传）。

| 参数 | 必填 | 默认 | 说明 | |------|------|------|------| | project_root | | MCP 启动 cwd | 项目根目录（绝对路径）。省略时使用 MCP server 启动时的工作目录 |

续跑依据的是 project_root 下持久化的 state 文件，无需传 workflow_id——启动时返回的 ID 已写入 .bmad-workflow-state.json。

get_workflow_status

查询工作流进度，返回 workflowId / type / status / 进度百分比 / 当前步骤 / 输出目录 / 最后错误。

| 参数 | 必填 | 默认 | 说明 | |------|------|------|------| | project_root | | MCP 启动 cwd | 项目根目录（绝对路径）。省略时使用 MCP server 启动时的工作目录 |

cancel_workflow

软取消运行中的工作流（保留已生成产物）。

| 参数 | 必填 | 默认 | 说明 | |------|------|------|------| | project_root | | MCP 启动 cwd | 项目根目录（绝对路径）。省略时使用 MCP server 启动时的工作目录 |

list_bmad_batches

列出 output_dir/planning-artifacts/ 下所有 batch。

| 参数 | 必填 | 默认 | 说明 | |------|------|------|------| | project_root | | MCP 启动 cwd | 项目根目录（绝对路径）。省略时使用 MCP server 启动时的工作目录 | | output_dir | ✅ | | 产物根目录（相对 project_root，与 start_bmad_workflow.output_dir 一致） |

输出结构

假设 project_root=D:/demo，output_dir=.bmad-output：

planning 模式（v0.5.0）

D:/demo/.bmad-output/
├── planning-artifacts/{slug}/       # slug 来自 requirement_description
│   ├── 01-prd.md
│   ├── 02-user-stories.md
│   ├── 03-acceptance-criteria.md
│   ├── 04-architecture.md
│   ├── 05-tasks.md
│   ├── 06-code-skeleton/
│   ├── 07-code-review.md
│   └── chain-summary-{workflow_id}.md  # 仅 chain 模式
├── final-report.md
└── audit-log.json

D:/demo/.bmad-workflow-state.json

v0.4 及之前版本把 7 步产物写在 output_dir/ 顶层；v0.5.0 起按 batch 子目录组织，与原 Skill _bmad-output/planning-artifacts/{batch}/ 对齐。chain_to_pipeline=true 时，子目录的 01-prd.md 会被 inferBatchFromPlanningArtifacts 识别为 batch 入口，pipeline 阶段自动消费。

pipeline 模式

D:/demo/.bmad-output/
├── planning-artifacts/{batch}/
└── implementation-artifacts/{batch}/mcp-workflow-run/
    ├── 01-story-discovery.md
    ├── 02-dev.md
    ├── 03-test.md
    ├── 04-review.md
    ├── 05-status.md
    ├── 06-checkpoint.md
    ├── 07-audit.md
    ├── 08-completion-audit.md
    └── audit-log.json

常见问题

Q: 如何从中断处继续？ A: 调用 resume_bmad_workflow 并传入 workflow_id（启动时返回，也写入项目根的 .bmad-workflow-state.json）。

Q: Windows 路径在 MCP 配置中报"找不到文件"？ A: 统一使用正斜杠（D:/auto-dev-workflow/dist/index.js），避免反斜杠在 JSON 中需双重转义。也可改用 npx -y @huhai0403/bmad-workflow-mcp 免维护路径。

Q: pipeline 模式只想跑某一个 story？ A: 设置 epic="1" story="1-3"，会跳过其它 story；batch 留空则全量。

Q: dry-run 模式产物会落盘吗？ A: 不会。mode: "dry-run" 仅生成预览文本到响应中，便于审阅工作流结构。

Q: Cursor / OpenCode 启动后看不到工具？ A: 检查客户端日志中 MCP Server 是否成功注册；本地构建版本需先 npm run build，路径指向 dist/index.js（不是 src/）。

Q: v0.5.0 怎么又把 use_llm 加回来了？v0.4 不是删了吗？ A: v0.4 删除 use_llm 时把 planning 阶段唯一能产出高质量内容的能力一并砍掉，事后发现当 PRD 超过 50 行、含具体 Epic/Story/技术栈约束时，模板填充（enhancePlanningContent 退化为 no-op）产出的 01-prd.md / 02-user-stories.md / 04-architecture.md 与实际需求严重脱节（如 8 Epic 120 Story 的 PRD 变成 3 个通用 Story）。v0.5.0 重新引入 LlmProvider（OpenAI 兼容 API）+ enhancePlanningContent 的真 LLM 路径，use_llm=true（默认）且环境里有 OPENAI_API_KEY 时由 LLM 解析 PRD；无 key 或失败时 fallback 到模板，行为不破坏。AI 代码审查这一步仍走 host 端 /bmad-code-review skill，不在 MCP 端调 LLM（防绕过 + 简化权限模型）。

Q: v0.5.0 的 requirement_file 怎么用？ A: requirement_file: "docs/prd.md" 是相对 project_root 的路径。MCP 端启动时直接 fs.readFile 读这个文件，把内容当 requirement 喂给 planning 7 步。强烈推荐用于超过 50 行的 PRD——避免把 650 行塞进 MCP 参数导致 token 暴涨或截断。requirement_file 与 requirement_description 二选一；都传时 requirement_file 优先。

Q: use_llm=false 和无 API key 的区别？ A: use_llm=false 完全跳过 LLM 判断（提速）；use_llm=true 但无 key 时静默 fallback 到模板。两种结果一致——产物都是模板填充——但 use_llm=false 少一次环境检查。如果只想"无 key 时跑模板"，保持默认 use_llm=true 即可。

Q: v0.3.0 的 chain_to_pipeline 是什么？为什么默认开了？ A: v0.3.0 之前，planning 跑完后用户/host 必须再调一次 start_bmad_workflow(workflow_type=pipeline)。这导致 Cursor/OpenCode 在关键节点"停下来问"。v0.3.0 起，planning 跑完后引擎在同一次工具调用内自动从 .bmad-output/planning-artifacts/ 推断 batch 并跑完 pipeline，host 不必再发第二次调用。完整两阶段汇总写入 .bmad-output/chain-summary-<workflow_id>.md，响应体超过 200 行会自动截短到前 30 行并提示文件路径。

Q: 如何回到 v0.2.x 行为（两次独立调用）？ A: 显式传 chain_to_pipeline: false 即可。

Q: chain 模式下 planning 失败了会跑 pipeline 吗？ A: 不会。planning 失败会立刻中止链，pipeline 不启动。resume_bmad_workflow 会从当前失败的 phase 续跑。

Q: chain 响应体太大被 host 截断了怎么办？ A: 完整汇总在 outputDir/planning-artifacts/{slug}/chain-summary-{workflow_id}.md（v0.5.0 起子目录化），响应消息底部会显示路径。structuredContent 里的 chainPhases 数组也只包含每阶段的 workflowType/status/completedSteps，不含审计细节。

Q: v0.5.0 升级后，旧的 output_dir/01-prd.md 还在吗？ A: planning 重新跑时产物会写到 output_dir/planning-artifacts/{slug}/ 下。旧路径下 v0.4 留下的 01-prd.md 等文件不会自动迁移（属于产物目录结构变更）。如需保留历史，手动把 v0.4 时代的 output_dir/01-prd.md 移入子目录 planning-artifacts/{slug}/ 即可。list_bmad_batches 仍按 planning-artifacts/ 扫描，对迁移后的产物无感。

开发调试

npm run build            # 编译 TypeScript
npm run dev              # tsx 直接跑源码（开发热试）
npm run inspector        # 启动 MCP Inspector，可视化调试所有工具
npm run test:unit        # Vitest 单元测试（139 用例，含 LLM Provider / AI 审查 / 4-checkpoint 审计 / chain 模式）
npm run test:unit:coverage  # 单元测试 + v8 coverage
npm run test:smoke       # 冒烟测试
npm run test:interactive # 交互式测试（28 用例，含 4-checkpoint 失败重排队）
npm run test:stability   # 稳定性测试（2 小时长跑）
npm run test:all         # 跑完 unit + smoke + interactive + stability 四套

调试步骤：先 npm run build && node dist/index.js 确认进程能起，再回到客户端检查 MCP 注册。

AI 代码审查（含防绕过）

code_review / code_review_pipeline 步骤会自动：

收集 git 变更文件（git diff 暂存 + 工作区 + 未跟踪，跳过 node_modules / 锁文件 / 二进制 / 超过 60KB 的文件，最多 25 个）
调 lint（npm run lint 存在时执行）
渲染为 07-code-review.md / 05-code-review.md，写入 step 产物与故事文件（带 sentinel）。MCP 端不内置 LLM 调用——初始 fingerprint 始终是 source=lint / source=no_lint_script / source=no_changes，verdict 必为 CHANGES_REQUESTED
真正拿到 APPROVE 的方式：host 端跑 /bmad-code-review skill（或同等的人工/AI 审查），重写 Code Review Summary 段里的 bmad-fingerprint 块为 source=llm + 新的 review_hash

Verdict 与 source 强约束（防虚假跳过）：

| reviewSource | 来源 | 能否给出 APPROVE | 原因 | |--------------|------|------------------|------| | llm | host /bmad-code-review skill 覆盖 | ✅ | 真实评审 | | lint | 仅 lint 输出 | ❌ 必为 changes_requested | LLM 未执行 | | no_changes | git 无变更 | ❌ 必为 changes_requested | 无对象可评审 | | no_lint_script | lint 脚本缺失 | ❌ 必为 changes_requested | LLM 未执行 |

Fingerprint：每次审查都会写入 bmad-fingerprint: 块（source / review_hash / model / reviewed_at / lint_executed / file_count），审计以此判断审查是否真发生。

BLOCKED：verdict 为 BLOCKED 时，pipeline code_review_pipeline 步直接返回 success: false，workflow 整体失败（不再等审计）。

4-Checkpoint 完成审计（含防绕过）

pipeline 模式 completion_audit 步强制每个 story 满足 BMAD ANTI-SKIP GUARDRAIL 全部 4 项证据。

4 项证据

| 证据 | 解析方式 | 缺失后果 | |------|---------|---------| | Test Output | 故事文件存在 ## Test Output 段 + 内容非占位符 + MCP sentinel | 重排队 | | Lint Output | 存在 ## Lint Output 段 + 非空 + MCP sentinel | 重排队 | | Code Review Summary | 存在 ## Code Review Summary 段 + 包含 verdict + MCP sentinel + bmad-fingerprint 块 + source 必须为 llm | 重排队 | | Definition of Done | 存在 ## Definition of Done 段，所有 - [ ] 已勾选；或 ## Acceptance Criteria 段全部勾选 | 重排队 |

防绕过机制（5 个攻击路径被封堵）

用户手写 4 段假内容 — 每段必须含  sentinel；缺失即拒
从其他 workflow 复制 sentinel — 审计传入 workflowId，sentinel 的 workflow 必须匹配
claim 是 LLM 但实际 fingerprint 缺失 — ## Code Review Summary 段必须含 bmad-fingerprint: source=llm 行
用户手写一个假 LLM fingerprint — 故事文件内容与 step artifact 04-testing.md / 05-code-review.md 用 60 字符探针字符串交叉对照，不匹配即拒
复制 code_review_summary 段但没改 fingerprint — 同上，探针不匹配即拒

onRequeue 把失败 story 状态改回 in-progress，并把 state.lastError 与 state.status = "failed" 写回。审计报告 (08-completion-audit.md) 列出每项证据的 PASS/FAIL、sentinel 来源、cross-reference 结果。

Sentinel 格式

kind: test / lint / review
stepId: 写入该段的 MCP 步骤 ID（testing / code_review_pipeline 等）
at: ISO 8601 时间戳
workflow: 当前 workflow run ID（bmad-YYYYMMDD-{uuid8}）

用户/agent 手工添加的段不携带这个 sentinel，因此会被识别为非 MCP 写入并被审计拒绝。

Fingerprint 格式

bmad-fingerprint: source={llm|lint|no_changes|no_lint_script}
bmad-fingerprint: review_hash={sha256-prefix-16}
bmad-fingerprint: model={openai-model-name}    # 仅 LLM 路径（host skill 注入）
bmad-fingerprint: reviewed_at={ISO8601}
bmad-fingerprint: lint_executed={true|false}
bmad-fingerprint: file_count={n}

review_hash 是 review 输出内容的 SHA-256 截断，跨文件交叉对照时使用。

文档

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@huhai0403/bmad-workflow-mcp

目录

功能

环境要求

安装

配置

Cursor 配置

OpenCode 配置

快速开始

使用流程

全新项目（从 0 开始）

既有项目（增量迭代）

反模式

MCP 工具

start_bmad_workflow

resume_bmad_workflow

get_workflow_status

cancel_workflow

list_bmad_batches

输出结构

planning 模式（v0.5.0）

pipeline 模式

常见问题

开发调试

AI 代码审查（含防绕过）

4-Checkpoint 完成审计（含防绕过）

4 项证据

防绕过机制（5 个攻击路径被封堵）

Sentinel 格式

Fingerprint 格式

文档

License