Backlog Mcp

backlog-mcp

一个 MCP 服务，可为 AI Agent 提供对基于故事的项目待办事项列表的结构化读写权限。Agent 可以列出故事、读取内容、更新状态并添加备注 — 所有数据均存储在项目仓库中的纯 Markdown 文件内。

协作方式

这里没有共享服务。待办事项列表文件位于仓库的 requirements/ 目录中，并与代码一同提交和版本管理。Agent 之间，或 Agent 与人类之间的协作方式，与代码库其他部分完全相同：通过 git。如果两个 Agent 同时更新不同的故事，git 会合并更改。如果它们修改了同一行，则像处理其他合并冲突一样解决即可。

每个 Agent 都会为自己运行一个本地进程形式的 MCP 服务。它负责读写文件；其余工作由 git 处理。

---

安装

Homebrew（tap）

brew tap corbym/backlog-mcp
brew install backlog-mcp

也可以直接安装，无需显式执行 tap 步骤：

brew install corbym/backlog-mcp/backlog-mcp

二进制版本

从 Releases 页面下载适用于你平台的最新二进制文件，并将其放到 $PATH 中的某个位置。

Go 安装

如果已安装 Go：

go install github.com/corbym/backlog-mcp@latest

---

从源代码构建

go mod tidy
go build -o backlog-mcp .

---

设置

在项目根目录中初始化 requirements/ 文件夹：

./backlog-mcp init /path/to/your/project/requirements

这会创建：

requirements/
  requirements-index.md   # master index — source of truth for epics and story status
  backlog.md              # priority-ordered list of not-done stories
  epic-001-example/
    story-001.md          # example story file

将 requirements/ 文件夹提交到仓库。编辑其中的文件，添加自己的史诗和故事。

---

运行

./backlog-mcp

服务会从启动时的工作目录中查找 requirements/ 目录。Claude Code 会将工作目录设为项目根目录，因此无需配置。

创建计划文件

./backlog-mcp plan [name]

在 requirements/ 目录中创建新的计划模板。不指定名称时，文件名为 plan.md；指定名称时，文件名为 plan-<name>.md。如果文件已存在，则会添加数字后缀（plan-002.md 等）。打开文件，与 Agent 一起完善内容，然后再创建故事。

配置 MCP 客户端

建议使用提交到项目根目录的本地配置文件。这样服务的作用范围限定在当前项目，任何克隆仓库的 Agent 都能自动获得正确的设置。只有在希望 backlog-mcp 无需按项目配置即可在所有项目中使用时，才使用全局配置。

VS Code / GitHub Copilot — 在项目根目录添加 .vscode/mcp.json：

{
  "servers": {
    "backlog-mcp": {
      "command": "/path/to/backlog-mcp",
      "type": "stdio"
    }
  }
}

Claude Code — 在项目根目录添加 .claude/settings.json：

{
  "mcpServers": {
    "backlog-mcp": {
      "command": "/path/to/backlog-mcp"
    }
  }
}

如需使用全局备用配置（适用于所有项目），请将相同的配置放在 ~/.claude/settings.json（Claude Code）中，或将其添加到 VS Code 的用户 settings.json 文件中 mcp.servers 键下（GitHub Copilot）。始终优先使用项目本地配置文件。

---

工具

工具	描述
list_stories	列出故事，可按 epic_id、status 或 story_type 进行筛选
get_story	获取故事的完整 Markdown 内容和元数据，包括 story_type
get_index_summary	按状态汇总 Epic/故事数量
create_epic	创建新的 Epic — 分配下一个 EPIC-NNN ID、写入 Epic 文件并在索引中注册
create_story	在某个 Epic 下创建新故事 — 分配下一个 STORY-NNN ID，并在索引和待办列表中注册
set_epic_status	更新 Epic 生命周期状态，并执行完成和回退保护（见下文）
set_story_status	在索引和待办列表中更新故事状态（draft、in-progress、blocked、deferred）
set_acceptance_criteria	替换故事的验收标准部分（幂等）
check_acceptance_criterion	按索引或文本勾选单条验收标准 [x]
add_story_note	向故事文件追加带时间戳的备注
complete_story	将故事标记为已完成，并要求提供完成摘要和验收标准验证
groom_epic	根据故事文件和索引数据核对并同步 Epic 的 ## Stories 部分
bulk_update_acceptance_criteria	一次调用中更新一个故事的多项验收标准复选框状态
bulk_update_stories	一次调用中更新多个故事（状态、备注和/或验收标准补丁）
bulk_update_epics	一次调用中更新多个 Epic（状态和/或备注）

set_epic_status 保护规则

将状态设为 done 需要满足：

1. summary — 完成备注，将作为带时间戳的条目追加到 Epic 文件中。
2. 所有故事均已完成 — 如果仍有未完成的故事，调用将失败并列出这些故事。仅在用户明确确认要有意省略未完成故事后，才传入 override_incomplete=true。

向后回退（例如，done → in-progress、in-progress → draft）会触发回退提示：Agent 应先提出创建新故事，然后再继续。仅当用户明确坚持跳过此步骤时，才传入 confirm_regression=true。blocked 和 deferred 属于横向状态，可自由设置。

complete_story 保护规则

完成故事前，必须先设置验收标准（不能使用默认占位内容）。未勾选的标准会阻止故事完成，除非为每项未勾选内容提供一条说明并传入 incomplete_items。先通过 set_acceptance_criteria 勾选已完成的标准 [x] — 不要使用 incomplete_items 来确认实际上已经完成的工作。

---

环境变量

变量	必需	默认值	描述
BACKLOG_ROOT	否	requirements	覆盖需求目录的路径

---

文件格式

requirements-index.md — 每个标题对应一个 Epic 部分，每个表格行对应一个故事：

## EPIC-001: Combat System — `draft`

| Story | Title | Status | Type |
|-------|-------|--------|------|
| [STORY-001](./epic-001-combat-system/story-001.md) | Basic combat | draft | feature |

backlog.md — 按优先级排序的编号列表：

1. **STORY-001** — Basic combat
2. **STORY-002** — Enemy AI *(in-progress)*

故事文件位于 BACKLOG_ROOT 下的 epic-NNN-slug/story-NNN.md。

故事类型： feature、bug、chore、spike

状态值： draft、in-progress、done、blocked、deferred

---

自动化 PR 待办列表 Agent

其中包含一个 GitHub Actions 工作流，可在拉取请求创建或更新时自动更新故事状态并追加备注。它不需要 API 密钥 — 只需标准的 GITHUB_TOKEN。

工作原理

每当发生 pull_request 事件（opened、synchronize）时，该工作流会：

1. 通过 go install github.com/corbym/backlog-mcp@latest 安装 backlog-mcp 二进制文件。
2. 扫描 PR 标题和分支名称，查找 STORY-NNN ID。
3. 对每个匹配的故事，将状态设为 in-progress（如果状态为 draft 且 PR 刚刚创建），并追加一条包含 PR 编号和标题的带时间戳备注。
4. 将 requirements/ 下任何已更改的文件提交回 PR 分支。

在仓库中设置

将以下三个文件复制到你的仓库中：

.github/
  actions/
    install/
      action.yml          # composite action — installs the binary via go install
  scripts/
    backlog_agent.py      # deterministic MCP client (Python 3, stdlib only)
  workflows/
    backlog-agent.yml     # the workflow

这些文件位于 corbym/backlog-mcp 仓库中。除了确保已有 requirements/ 文件夹外，无需任何密钥或额外配置。

分支和 PR 命名

Agent 根据 STORY-NNN ID 匹配故事。请在分支名称或 PR 标题中包含该 ID：

story-042-short-description          # branch
STORY-042: Short description         # PR title
STORY-042 STORY-043: Short desc      # multiple stories
chore: bump goreleaser to v2         # no story — agent skips cleanly

完整约定请参阅 CONTRIBUTING.md。

在 GitHub Copilot Agent 模式下使用 backlog-mcp

VS Code 中的 GitHub Copilot Agent 模式会从项目根目录下的 .vscode/mcp.json 读取 MCP 服务。请注意，键名是 "servers"，而不是 "mcpServers"（Claude Code 使用的约定）：

{
  "servers": {
    "backlog-mcp": {
      "command": "/path/to/backlog-mcp",
      "type": "stdio"
    }
  }
}

MCP 工具仅在 Agent 模式下可用——在 Copilot Chat 的模式下拉菜单中切换到该模式。完成配置后，Copilot Agent 可在聊天会话中调用 list_stories、get_story、add_story_note 以及所有其他 backlog 工具——这些工具与 GitHub Actions 工作流使用的相同。

---

备注

• 文件写入是原子操作（临时文件 + 重命名）——即使写入过程中崩溃，也不会损坏文件。
• 文件系统是事实来源。MCP 服务不会持有数据所有权。