Backlog Mcp

backlog-mcp

ストーリー形式のプロジェクトバックログに対して、AI エージェントが構造化された読み書きを行える MCP サーバーです。エージェントは、ストーリーの一覧表示、内容の読み取り、ステータスの更新、メモの追記を行えます。これらはすべて、プロジェクトリポジトリ内にあるプレーンな Markdown ファイルによって管理されます。

コラボレーションの仕組み

共有サーバーはありません。バックログファイルはリポジトリ内の requirements/ に置かれ、コードと一緒にコミットされ、バージョン管理されます。エージェント同士、またはエージェントと人間のコラボレーションは、コードベースの他の部分と同じように git を通じて行います。2 つのエージェントが別々のストーリーを同時に更新した場合、git がマージします。同じ行を変更した場合は、通常のマージコンフリクトと同じように解決します。

MCP サーバーは、各エージェントが個別に実行するローカルプロセスです。ファイルの読み書きを行い、それ以外は git が処理します。

---

インストール

Homebrew（tap）

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

明示的な tap の手順を省略して、直接インストールすることもできます。

brew install corbym/backlog-mcp/backlog-mcp

バイナリリリース

Releases ページからお使いのプラットフォーム向けの最新のバイナリをダウンロードし、$PATH 上の任意の場所に配置してください。

Go install

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 など）。ファイルを開き、エージェントと一緒に内容を記入してからストーリーを作成してください。

MCP クライアントの設定

プロジェクトのルートにコミットするローカル設定ファイルを推奨します。これによりサーバーの適用範囲がプロジェクトに限定され、リポジトリをクローンしたエージェントは誰でも自動的に適切なセットアップを利用できます。プロジェクトごとの設定をせずに、すべてのプロジェクトで 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	story_typeを含む、ストーリーの完全なMarkdownコンテンツとメタデータを取得します
get_index_summary	ステータス別のエピック／ストーリー数の概要を取得します
create_epic	新しいエピックを作成します — 次のEPIC-NNN IDを割り当て、エピックファイルを作成し、インデックスに登録します
create_story	エピック配下に新しいストーリーを作成します — 次のSTORY-NNN IDを割り当て、インデックスとバックログに登録します
set_epic_status	完了および後退を防ぐガード付きで、エピックのライフサイクルステータスを更新します（以下を参照）
set_story_status	インデックスとバックログのストーリーステータス（draft、in-progress、blocked、deferred）を更新します
set_acceptance_criteria	ストーリーの受け入れ条件セクションを置き換えます（冪等）
check_acceptance_criterion	インデックスまたはテキストを指定して、単一の受け入れ条件にチェック [x] を付けます
add_story_note	タイムスタンプ付きのメモをストーリーファイルに追加します
complete_story	必須の完了サマリーと受け入れ条件の検証を伴って、ストーリーを完了済みにします
groom_epic	エピックの## Storiesセクションをストーリーファイルおよびインデックスのデータと照合して整理します
bulk_update_acceptance_criteria	1回の呼び出しで、1つのストーリーに対する複数の受け入れ条件チェックボックスの状態を更新します
bulk_update_stories	1回の呼び出しで複数のストーリーを更新します（ステータス、メモ、受け入れ条件のパッチのいずれか、または複数）
bulk_update_epics	1回の呼び出しで複数のエピックを更新します（ステータス、メモのいずれか、または両方）

set_epic_statusのガード

ステータスをdoneに設定するには、次の条件を満たす必要があります。

1. summary — エピックファイルにタイムスタンプ付きのエントリーとして追加される完了メモです。
2. すべてのストーリーが完了済み — 未完了のストーリーが残っている場合、呼び出しは失敗し、そのストーリーを一覧表示します。未完了のストーリーを意図的に除外することをユーザーが明示的に確認した後に限り、override_incomplete=trueを指定してください。

ステータスを後退させる場合（例：done → in-progress、in-progress → draft）、後退の確認が求められます。エージェントは、続行する前に新しいストーリーの作成を提案してください。この手順を省略することをユーザーが明示的に強く求める場合に限り、confirm_regression=trueを指定してください。blockedとdeferredは同じ段階のステータスであり、自由に設定できます。

complete_storyのガード

ストーリーを完了する前に、受け入れ条件を設定する必要があります（デフォルトのプレースホルダーは不可）。チェックされていない条件がある場合、未チェックの各項目に対する説明をincomplete_itemsに指定しない限り、完了できません。完了した条件には、まずset_acceptance_criteriaでチェック [x] を付けてください — 実際に完了している作業の確認にincomplete_itemsを使わないでください。

---

環境変数

変数	必須	デフォルト	説明
BACKLOG_ROOT	いいえ	requirements	requirementsディレクトリのパスを上書きします

---

ファイル形式

requirements-index.md — 見出しごとに1つのエピックセクション、テーブル行ごとに1つのストーリー：

## 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バックログエージェント

プルリクエストがオープンまたは更新されたときに、ストーリーのステータスを自動更新し、メモを追加する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. 一致した各ストーリーについて、（PRが新規オープンされ、ステータスがdraftの場合は）ステータスをin-progressに設定し、PR番号とタイトルを含むタイムスタンプ付きのメモを追加します。
4. requirements/配下で変更されたファイルをPRブランチにコミットします。

リポジトリでの設定

次の3つのファイルをリポジトリにコピーします。

.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の命名

エージェントは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のエージェントモードでbacklog-mcpを使用する

VS CodeのGitHub Copilotのエージェントモードは、プロジェクトのルートにある.vscode/mcp.jsonからMCP サーバーを読み込みます。キーは"mcpServers"（Claude Codeの規則）ではなく、"servers"であることに注意してください。

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

MCP ツールはエージェントモードでのみ使用できます。Copilot Chatのモードドロップダウンから切り替えてください。設定すると、Copilotエージェントはチャットセッション中にlist_stories、get_story、add_story_noteなど、その他すべてのバックログツールを呼び出せます。GitHub Actionsのワークフローが使用するツールと同じです。

---

注記

• ファイルへの書き込みはアトミックです（一時ファイルを作成してから名前を変更します）。書き込み中にクラッシュしても、ファイルが破損することはありません。
• ファイルシステムが信頼できる唯一の情報源です。MCP サーバーがデータを所有することはありません。