BMAD MCP Server 🚀

一个全面的模型上下文协议（MCP）服务器，实现了**BMAD（业务建模与开发）**方法论。通过MCP协议提供智能任务管理、多代理工作流以及跨IDE项目管理。

✨ 特性

🤖 6个专业AI代理

• 📊 分析师：业务分析、市场研究、需求收集
• 🏗️ 架构师：系统设计、架构规划、技术栈选择
• 💻 开发者：代码实现、调试、技术开发
• 📋 项目经理：任务协调、时间线管理、资源规划
• 🔍 质量保证：质量保证、测试策略、代码审查
• 🔍 编码代理：高级语义代码分析和编辑能力 ⭐ 新增！

📋 高级任务管理

• 实时进度跟踪：实时更新和通知
• 智能调度：自动分配并管理容量
• 后续任务生成：自动工作流程推进
• Notion集成：双向同步Notion数据库
• TodoWrite桥接：无缝Claude集成

⏱️ 时间和成本追踪 ⭐ 新增！

• 精确时间追踪：每个项目花费的确切时间及会话管理
• AI成本计算：自动计算每个项目的AI模型成本
• 项目计费：全面的计费报告用于客户发票
• 多种格式导出：JSON、CSV和发票样式计费报告
• 成本优化：跟踪并优化跨项目的AI模型使用
• 会话管理：自动结束过期会话并跟踪工作模式

🎨 模板系统及标准化项目结构 ⭐ 新增！

• 6个项目模板：标准、web-app、api、移动、数据科学、基础设施
• 自动结构创建：统一的.bmad-core/目录
• 自动发现：自动识别新的BMAD项目
• 迁移工具：将现有项目迁移到BMAD v2.0标准
• 零配置：新项目立即可用，带有完整的配置

🔄 增强功能

• BMAD-METHOD工作流系统：完全实现并具有智能编排 ⭐ 新增！
• 质量门（@qa命令）：6个全面的质量保证命令 ⭐ 新增！
• 高级语义代码分析：通过编码代理的专业代码智能 ⭐ 新增！
• 基于时间的监控：计划提醒和进度检查
• 工作日模拟：演示模式和现实进度测试
• 实时控制台输出：漂亮的格式化状态显示
• 项目上下文集成：支持多个项目并具有全局注册表
• 性能指标：详细的跟踪和报告

🌐 通用IDE访问

兼容任何支持MCP的IDE：

• Claude Code ✅
• VS Code ✅
• Cursor ✅
• 任何支持MCP的IDE ✅

🚀 快速开始

预备条件

• Python 3.8+
• OpenRouter API密钥（用于AI模型路由）
• Notion API令牌（可选，用于数据库同步）

安装

# 1. 克隆仓库
git clone https://github.com/yourusername/bmad-mcp-server.git
cd bmad-mcp-server

# 2. 安装依赖
pip install -r requirements.txt

# 3. 设置环境变量
cp .env.example .env
# 使用您的API密钥编辑.env文件

配置

添加到IDE的MCP配置：

Claude Code (claude_desktop_config.json)

{
  "mcpServers": {
    "bmad": {
      "command": "python",
      "args": ["-m", "src.bmad_mcp.server"],
      "cwd": "/path/to/bmad-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/bmad-mcp-server",
        "OPENROUTER_API_KEY": "your_openrouter_api_key",
        "NOTION_TOKEN": "your_notion_token"
      }
    }
  }
}

VS Code / Cursor

{
  "mcp.servers": {
    "bmad": {
      "command": "python",
      "args": ["-m", "src.bmad_mcp.server"],
      "cwd": "/path/to/bmad-mcp-server",
      "env": {
        "PYTHONPATH": "/path/to/bmad-mcp-server",
        "OPENROUTER_API_KEY": "your_openrouter_api_key"
      }
    }
  }
}

🛠️ 可用的MCP工具

🤖 代理管理

工具	描述	示例
bmad_list_agents	列出所有可用的代理	显示5个专业代理
bmad_activate_agent	切换到特定代理	agent: "dev"
bmad_get_agent_help	获取代理特定指导	上下文感知帮助

📋 任务管理

工具	描述	示例
bmad_get_task_summary	综合任务概览	进度、指标、状态
bmad_create_task	创建新任务并自动调度	task_id, name, hours
bmad_update_task_progress	更新进度并实时同步	task_id, hours_completed
bmad_get_today_tasks	今天的预定任务	每天的工作负载视图
bmad_get_agent_tasks	代理特定的任务列表	按代理过滤

⏱️ 时间和成本追踪 ⭐ 新增！

工具	描述	示例
bmad_start_timer	开始任务的时间追踪	task_id, agent, session_type
bmad_stop_timer	停止计时器并计算成本	task_id, ai_model, tokens
bmad_get_active_timers	列出所有当前运行的计时器	当前会话概览
bmad_get_task_time_summary	任务的时间追踪摘要	小时数、成本、会话
bmad_get_daily_time_report	每天的时间追踪报告	项目分解、小时数
bmad_get_project_billing	生成项目计费报告	JSON、CSV、发票格式
bmad_auto_end_stale_sessions	结束运行时间过长的会话	清理过期计时器
bmad_update_model_costs	更新AI模型定价	配置每令牌的成本
bmad_get_model_costs	获取当前模型成本	查看定价配置

⚡ 增强功能

工具	描述	示例
bmad_start_realtime_mode	启用实时任务监控	后台更新
bmad_start_work_session	跟踪任务的工作会话	时间追踪
bmad_simulate_work_day	演示现实的工作进展	测试和演示
bmad_get_project_status	综合项目概述	多项目支持
bmad_sync_notion_tasks	与Notion数据库同步	双向同步

🔧 项目管理

工具	描述	示例
bmad_detect_project	扫描BMAD配置	自动发现
bmad_register_project	将项目添加到全局注册表	跨IDE访问
bmad_execute_task	运行BMAD方法论任务	模板执行
bmad_create_document	从模板生成文档	自动化文档
bmad_run_checklist	质量保证检查清单	QA工作流

🚀 BMAD-METHOD工作流系统 ⭐ 新增！

工具	描述	示例
bmad_workflow_start_project	启动BMAD-METHOD项目工作流	全部/规划/开发模式
bmad_workflow_advance	将工作流推进到下一个状态	项目/故事状态转换
bmad_workflow_start_story	在开发周期中创建故事	故事创建和规划
bmad_workflow_run_qa	执行质量门（@qa命令）	*风险, *设计, *跟踪, *非功能要求, *审查, *门
bmad_workflow_execute_command	智能路由代理命令	上下文感知代理路由
bmad_workflow_get_status	获取综合工作流状态	实时进度监控
bmad_workflow_generate_report	生成详细的工作流报告	分析和建议

🔍 语义代码分析 ⭐ 新增！

工具	描述	示例
bmad_coder_activate_project	激活项目进行分析	语义代码智能
bmad_coder_find_symbol	语义查找代码符号	函数、类、变量
bmad_coder_get_symbols_overview	获取文件符号概览	代码结构分析
bmad_coder_find_referencing_symbols	查找符号引用	跨引用跟踪
bmad_coder_insert_after_symbol	在符号后插入代码	精确代码插入
bmad_coder_replace_symbol_body	替换符号实现	代码修改
bmad_coder_execute_shell_command	执行shell命令	测试、构建、自动化
bmad_coder_search_for_pattern	高级模式搜索	智能代码搜索
bmad_coder_write_memory	存储项目知识	持久见解
bmad_coder_read_memory	加载存储的知识	访问项目记忆

🎨 模板系统 ⭐ 新增！

工具	描述	示例
bmad_create_project	使用标准化结构创建项目	path, template
bmad_list_project_templates	显示所有可用模板	6个模板可用
bmad_get_project_template_info	详细模板信息	功能、结构
bmad_migrate_project_to_standard	迁移现有项目	自动备份、结构

📊 使用示例

基本任务管理

# 列出可用代理
bmad_list_agents()

# 激活开发者代理
bmad_activate_agent(agent="dev")

# 创建新任务
bmad_create_task(
    task_id="feature-implementation",
    name="实现用户认证",
    allocated_hours=8.0,
    agent="dev"
)

# 更新进度
bmad_update_task_progress(
    task_id="feature-implementation", 
    hours_completed=2.5
)

# 获取每日概览
bmad_get_today_tasks()

实时监控

# 启动实时监控
bmad_start_realtime_mode()

# 开始工作会话
bmad_start_work_session(task_id="feature-implementation")

# 工作在任务上...

# 结束会话并自动记录进度
bmad_end_work_session(
    task_id="feature-implementation",
    hours_worked=2.0
)

# 获取综合状态
bmad_get_realtime_status()

时间和成本追踪 ⭐ 新增！

# 开始任务的时间追踪
bmad_start_timer(
    task_id="feature-implementation",
    agent="dev",
    session_type="development",
    description="实现用户认证系统"
)

# 停止计时器并计算AI成本
bmad_stop_timer(
    task_id="feature-implementation",
    ai_model_used="claude-sonnet-4",
    tokens_input=1500,
    tokens_output=800,
    mark_completed=False
)

# 获取任务时间摘要
bmad_get_task_time_summary(task_id="feature-implementation")

# 生成项目计费报告
bmad_get_project_billing(
    project_id="my-project-id",
    start_date="2025-01-01",
    end_date="2025-01-31",
    export_format="invoice"  # json, csv, 或发票
)

# 获取每日追踪报告
bmad_get_daily_time_report(date="2025-01-20")

# 自动结束过期会话（运行>8小时）
bmad_auto_end_stale_sessions(max_hours=8)

项目上下文

# 检测BMAD项目
bmad_detect_project(path="./my-project")

# 注册到全局注册表
bmad_register_project(
    project_path="./my-project",
    project_name="我的精彩项目"
)

# 获取项目概述
bmad_get_project_status()

模板系统使用 ⭐ 新增！

# 列出可用模板
bmad_list_project_templates()

# 获取模板详情
bmad_get_project_template_info(template_name="web-app")

# 使用模板创建新项目
bmad_create_project(
    project_path="./my-web-app",
    template="web-app",
    name="我的Web应用",
    description="现代基于React的Web应用"
)

# 迁移现有项目
bmad_migrate_project_to_standard(
    project_path="./legacy-project",
    backup=True
)

可用模板

• 标准：基本BMAD项目，带有完整结构
• web-app：前端/后端，支持React/Vue/Angular
• api：REST/GraphQL API，带OpenAPI文档
• 移动：React Native/Flutter跨平台应用
• 数据科学：ML/Jupyter，带笔记本和数据管道
• 基础设施：Docker/Terraform/Kubernetes部署

模拟与测试

# 模拟完整工作日
bmad_simulate_work_day(speed_factor=10.0)

# 测试特定代理工作流
bmad_simulate_agent_workday(agent="qa", hours=6.0)

# 模拟危机场景
bmad_simulate_crisis_scenario(crisis_type="blocked_task")

高级时间追踪工作流 ⭐ 新增！

# 开始综合工作会话
bmad_start_timer(
    task_id="user-auth-system",
    agent="dev",
    session_type="development",
    description="实现OAuth2集成"
)

# 使用AI辅助完成任务
# ... 开发工作，使用AI模型 ...

# 停止计时器并详细跟踪AI成本
bmad_stop_timer(
    task_id="user-auth-system",
    ai_model_used="claude-sonnet-4",
    tokens_input=2500,
    tokens_output=1200,
    mark_completed=True
)

# 生成综合项目计费
billing_report = bmad_get_project_billing(
    project_id="client-project-2025",
    start_date="2025-01-01",
    end_date="2025-01-31",
    export_format="invoice"
)

# 监控日常生产力
daily_report = bmad_get_daily_time_report("2025-01-20")
print(f"今天: {daily_report['total_hours']:.2f}h, ${daily_report['total_cost_usd']:.2f}")

# 自动会话管理
bmad_auto_end_stale_sessions(max_hours=6)  # 结束超过6小时的会话

🏗️ 架构

bmad-mcp-server/
├── src/
│   └── bmad_mcp/
│       ├── core/                    # 核心功能
│       │   ├── task_tracker.py      # 高级任务管理
│       │   ├── time_cost_tracker.py # 时间和成本追踪 ⭐ 新增！
│       │   ├── console_formatter.py # 实时输出格式化  
│       │   ├── realtime_updater.py  # 实时监控
│       │   ├── time_monitor.py      # 计划监控
│       │   ├── simulator.py         # 演示和测试
│       │   ├── notion_sync.py       # Notion集成
│       │   └── global_registry.py   # 跨IDE项目
│       ├── agents/                  # 代理定义
│       │   ├── analyst.py           # 业务分析
│       │   ├── architect.py         # 系统设计
│       │   ├── developer.py         # 代码实现
│       │   ├── project_manager.py   # 项目协调
│       │   ├── qa.py               # 质量保证
│       │   └── coder.py           # 高级语义代码分析和编辑
│       ├── workflows/              # BMAD-METHOD工作流系统
│       │   ├── workflow_engine.py  # 中央工作流编排
│       │   ├── orchestrator_agent.py # 项目/故事生命周期管理
│       │   ├── quality_gates.py    # 质量保证（@qa命令）
│       │   └── workflow_states.py  # 状态机定义
│       ├── tools/                   # MCP工具实现
│       ├── routing/                 # OpenRouter集成
│       └── server.py               # MCP服务器
├── config/                         # 配置模板
├── docs/                          # 文档
├── examples/                      # 使用示例
└── tests/                        # 测试套件

🔧 配置

环