backlog-mcp 是一个 MCP（Model Context Protocol）服务器，为 AI 智能体提供对基于故事的项目待办事项的结构化读写访问。智能体可以列出故事、读取内容、更新状态、追加备注，所有数据都保存在项目仓库内的纯 Markdown 文件中。
用途
该项目旨在让 AI 智能体能够像处理代码一样处理项目待办事项。待办事项文件存放在仓库的 requirements/ 目录下，与代码一起提交和版本控制。协作方式与代码库相同：通过 git。如果两个智能体并发更新不同的故事，git 会合并它们；如果它们修改同一行，则像处理其他合并冲突一样解决。没有共享服务器，MCP 服务器是每个智能体自己运行的本地进程，它读写文件，git 处理其余部分。
主要能力
- 列出故事、读取故事内容、更新故事状态、追加备注。
- 支持创建计划文件（plan file），在 requirements/ 目录中生成计划脚手架。
- 提供 set_epic_status 和 complete_story 等操作，并带有守卫条件（guards）以确保流程正确。
- 包含一个自动化 PR 待办事项智能体（GitHub Actions 工作流），在拉取请求打开或更新时自动更新故事状态并追加备注，无需 API 密钥，仅使用标准 GITHUB_TOKEN。
- 支持 VS Code / GitHub Copilot 和 Claude Code 等 MCP 客户端配置。
使用方式
- 安装：可以从 Releases 页面下载对应平台的二进制文件并放入 $PATH；如果安装了 Go，可以使用 go install github.com/corbym/backlog-mcp@latest 安装；也可以从源码构建。
- 初始化：在项目根目录创建 requirements/ 文件夹，并将其提交到仓库。编辑文件以添加自己的史诗（epic）和故事。
- 服务器会查找相对于启动时工作目录的 requirements/ 目录。Claude Code 将工作目录设置为项目根目录，因此无需配置。
- 配置 MCP 客户端：推荐使用提交到项目根目录的本地配置文件，例如 VS Code / GitHub Copilot 使用 .vscode/mcp.json，Claude Code 使用 .claude/settings.json。全局配置可作为后备。
- 使用 GitHub Copilot 智能体模式时，MCP 工具仅在 Agent 模式下可用，通过 Copilot Chat 的模式下拉菜单切换。配置后，Copilot 智能体可以在聊天会话中调用 list_stories、get_story、add_story_note 等所有待办事项工具。
适用场景
适用于希望将项目待办事项与代码仓库紧密集成、利用 git 进行协作和版本控制的团队或个人。特别适合使用 AI 智能体进行开发流程管理的场景，例如让智能体自动更新故事状态、根据 PR 更新待办事项等。
限制
- 文件写入是原子的（临时文件 + 重命名），崩溃不会损坏文件。
- 文件系统是唯一事实来源，MCP 服务器从不拥有数据。
- 设置史诗状态为 done 需要提供 summary（完成备注），并且所有故事必须已完成，否则调用失败并列出未完成的故事。只有在用户明确确认可以忽略未完成故事时，才可传递 override_incomplete=true。
- 状态回退（如 done → in-progress）会触发回归提示，智能体应建议创建新故事，只有在用户明确坚持跳过时才可传递 confirm_regression=true。blocked 和 deferred 是横向状态，可以自由设置。
- 完成故事前必须设置验收标准（非默认占位符），未勾选的验收标准会阻止完成，除非提供 incomplete_items 并为每个未勾选项提供解释。应通过 set_acceptance_criteria 先勾选已完成的标准，不要用 incomplete_items 确认实际已完成的工作。
- 故事类型：feature、bug、chore、spike。状态值：draft、in-progress、done、blocked、deferred。
- 故事文件位于 BACKLOG_ROOT 下的 epic-NNN-slug/story-NNN.md。
- 自动化 PR 工作流会扫描 PR 标题和分支名称中的 STORY-NNN ID，匹配后设置状态并追加备注，然后将更改提交回 PR 分支。
- 分支和 PR 命名需包含 STORY-NNN ID，具体约定见 CONTRIBUTING.md。
暂未提供的信息
关于收费、价格、平台支持的具体细节、效果数据等，资料中暂未提供。