primer-mcp

primer-mcp

ベータ版 — コアのワークフローは安定しており、テスト済みですが、このツールは新しいものです。まだ不完全な点があることをご了承ください。

AI 支援開発の計画優先ワークフローをガイドする、Jira の簡易版 MCP サーバーです。チケットは Markdown ファイルとして保存され、AI エージェントがインターフェースになります。

効果はあるのでしょうか？ 108 回の実行評価では、機能開発と自由形式のリクエストにおいて、コーディング前の計画実施率が 0/15 から 15/15 に向上しました。ただし、CLAUDE.md に 1 行追加しただけでも計画が保存されたため、primer-mcp が加える価値は記録の構造化にあります。詳細はこちら。

理由

AI コーディングエージェントから本当の価値を引き出すには、プロンプトを工夫するだけでは不十分です。エージェントが何を作るかを形作り、その周りのワークフローを設計し、実践で通用するものをデプロイする必要があります。

エージェントに任せきりにすると、すぐに実装へ取りかかります。Primer-mcp は、まず計画を立てるようにします。

• 作業が重要な理由を明確にする
• 判断を記録し、トレードオフを検討する
• 作業をストーリーとタスクに分割する
• コーディングの前に、あなたと計画を確認する
• それぞれを完了し、検証する

チケットは YAML フロントマター付きのプレーンな Markdown で、コードと一緒にコミットされます。外部サービスもデータベースもありません。すべてリポジトリ内で確認でき、Obsidian などのツールで簡単に閲覧できます。

primer-mcp は、個人開発者や小規模プロジェクト向けに設計されています。1 人（とその AI エージェント）でバックログに取り組む想定です。担当割り当て、通知、複数ユーザー間の調整機能はありません。これは意図的な設計であり、Jira の代替ではなく、AI ワークフローを軽量に補完するものです。

クイックスタート

Python 3.12 以降と uv が必要です。

MCP クライアントの設定に追加します（例：Claude Code の settings.json、Claude Desktop の claude_desktop_config.json）。

{
  "mcpServers": {
    "primer-mcp": {
      "command": "uvx",
      "args": ["primer-mcp"]
    }
  }
}

これだけです。MCP クライアントが primer-mcp を自動でダウンロードし、実行します。手動でインストールする必要はありません。

作りたいものを AI エージェントに伝えれば、あとはエージェントが処理します。サーバーは、作業が重要な理由、判断、ストーリー、タスク、完了までの計画優先ワークフローをエージェントに案内します。次に何をすべきかわからない場合は、エージェントに尋ねてください。現在の状態を読み取り、次に何をすべきか把握します。

手動インストール（任意）

list-actionable CLI コマンドを使う場合など、primer-mcp をスタンドアロンツールとしてインストールしたい場合：

uv tool install primer-mcp

# Update to latest
uv tool upgrade primer-mcp

# Uninstall
uv tool uninstall primer-mcp

使用イメージ

一般的なセッションの流れです。作業内容を説明すると、エージェントが計画を進めます。

You:  I want to add user authentication.

Agent: You have EP-001: "Launch the app" — auth fits under that.
       Or I can create a separate epic if this is a bigger initiative.

You:  EP-001 is fine.

Agent: Before we build, we should decide on the auth approach.
       A few common options:

         1. JWT with refresh tokens — stateless, good for mobile/SPAs
         2. Server-side sessions — simple, but needs sticky storage
         3. OAuth2 only — delegates to a provider, less to maintain
            ...

You:  Option 1 — we need mobile support.

Agent: I'll record that decision so we don't revisit it later.
       → Recorded ADR-003: "Use JWT with refresh tokens"
         Rejected: server-side sessions (no mobile support),
                   OAuth2 only (need local accounts too)

       Breaking this into stories.
       → Created ST-005: "Login and registration endpoints"
       → Created ST-006: "Token refresh and revocation"

       And tasks for the first story:
       → Created TK-010: "Add /register endpoint with validation"
       → Created TK-011: "Add /login endpoint returning JWT pair"
       → Created TK-012: "Write integration tests for auth flow"

You:  Let's start with TK-010.

Agent: → Started TK-010

       [implements the register endpoint]

       Done — added POST /register with email/password validation,
       password hashing, and duplicate-email check.
       → Completed TK-010

You:  Looks good, verify it.

Agent: → Verified TK-010 (evidence: "all tests pass — a1b2c3d")

       TK-011 is next. Want me to continue?

すべてのチケットは primer/ 内の Markdown ファイルで、コードと一緒にコミットされます。export_graph ツールで、チケットのつながりを可視化できます。

リポジトリをクローンして assets/demo-graph.html を開くと、インタラクティブ版を利用できます。任意のノードをクリックすると、チケットの全内容が表示されます。

チケットはウィキリンク付きのプレーンな Markdown なので、primer/ を Obsidian の保管庫として開くこともできます。チケットの変更に応じてライブグラフが更新されるため、エクスポートし直す必要はありません。

ツール

AI エージェントはこれらのツールを自動的に呼び出すため、直接実行する必要はありません。必要に応じて、特定のツールを呼び出すようエージェントに依頼することもできます。

セットアップ

ツール	機能
init_project	primer/ チケットストアを作成し、ワークフローのセクションを CLAUDE.md に追加します

計画

ツール	内容
plan_epic	エピックを作成します。エピックは、一連の作業をまとめる最上位のコンテナです
record_adr	アーキテクチャ上の決定を記録します。コンテキスト、決定、却下した代替案、影響を記録します
create_story	エピックの下にストーリーを作成します。ストーリーは、受け入れ条件を持つ成果物です
create_task	ストーリーの下にタスクを作成します。タスクは、テスト可能な結果を伴う具体的な作業単位です
create_spike	スパイクを作成します。質問への回答を得るための、期間を限定した調査です

実行

ツール	内容
start_task	タスクを進行中にします
complete_task	実施内容のメモを添えて、タスクを完了としてマークします
verify_task	証拠（コミットを示すもの）を添えて、完了したタスクを検証します
complete_spike	調査結果を記録してスパイクを終了します

クエリ

ツール	内容
list_actionable	エピックのコンテキストと推奨事項を含め、今すぐ着手できる項目を一覧表示します
get_ticket	IDでチケットを取得し、本文全体を読みます
list_tickets	タイプまたはステータスで絞り込んでチケットを一覧表示します
update_ticket	チケットのステータス、依存関係、本文セクション、外部参照を更新します

エクスポート

ツール	内容
export_graph	プロジェクトをインタラクティブなグラフとして可視化する、自己完結型の HTML ファイルを生成します

プロンプト

プロンプト	内容
plan_story	ストーリーを作成する前に、計画についての会話を順を追って進めます
export_jira	Jira MCP サーバー経由で primer-mcp のチケットを Jira にエクスポートします
import_jira	Jira のエピックとその階層を primer-mcp にインポートします

エージェントへの指示

プロジェクトを初期化すると（初回使用時に自動で行われるか、init_project を使用）、エージェントをガイドするため、このセクションがエージェントの設定ファイル（CLAUDE.md、AGENTS.md）に追加されます。手動で追加する場合は、次のようにします。

## primer-mcp

This project uses primer-mcp for planning-first development.
Tickets are markdown files under `primer/` — they are yours to read and edit. 
Prefer the tools for creating and updating them: they allocate IDs, follow the templates
and guide the workflow. Hand-edit where the tools fall short.

- Plan before code. Recommended flow: Epic -> ADR -> Story -> Task,
  suggest rather than enforce — skip steps when it makes sense.
- Unsure what to do next? Call `list_actionable`.
- Completion is two-phase: `complete_task` with notes, then `verify_task`
  with evidence (point at the commit, not the output). Both are
  recommended — the tools will nudge you if you skip a step.
- After tickets creation or changes, offer to regenerate the project graph with `export_graph`.
- Before committing, check that completion notes on finished tickets
  still reflect the actual work — update both the frontmatter
  `completed_notes` and the `## Completion Notes` section if needed.
- Before implementing new work, propose a ticket and parent. Small fixes (1–2
  tasks) go under the standing bug-fix story; larger efforts get their
  own story. The user can decline.

Jira への移行（実験的）

primer-mcp のチケットは Jira の概念（Epic、Story、Task、ADR）に直接対応します。プロジェクトがローカルの Markdown ファイルでは収まらなくなった場合：

• export_jira は、任意の Jira MCP サーバーを通じてチケットを Jira に送信します。各チケットの external_ref フィールドで Jira のキーを追跡するため、再エクスポート時には重複して作成せず、既存の課題を更新します。
• import_jira は逆方向にインポートします。

どちらのプロンプトも実験的で、エンドツーエンドのテストは行われていません。

効果はありますか？

primer-mcp-eval は、primer-mcp によって AI コーディングエージェントの動作が変わるかをテストします。ヘッドレスの Claude Code に同じ12件の変更依頼を、次の3つの方法で与えます。

• 何も追加しない
• primer-mcp を使う
• コーディング前に docs/ へ計画を保存するよう CLAUDE.md に1行追加する

合計108回の独立した実行を行い、LLM の評価者を使わず、トランスクリプトから採点しました。

わかったこと：

• primer-mcp を使うと、コーディング前に計画を文書化した実行は、機能追加や自由度の高い依頼で0回中0回から15回中15回になりました。バグ修正やリファクタリングでは、ガイダンスによってエージェントが計画を省略できるため、ほとんど変化はありませんでした。
• 1行の指示では、36回すべての実行で計画が保存されました。コスト増加は primer-mcp の50％に対して約7％でした。
• 成果： 3つの方法のいずれも、測定可能な違いをもたらしませんでした。

つまり、計画を文書化するために primer-mcp は必要ありません。primer-mcp が追加するのは、計画ファイルにはなかった記録の構造です。

• 目標と実装手順を分けて記録する
• 却下した選択肢を含めて決定を記録する
• 作業の各項目にステータスを付ける

この構造が後続のセッションで役立つかどうかは、まだ検証されていません。

オーバーヘッド。 エージェントが primer-mcp を使って計画した場合、追加で約15～25ターンかかりました。この増加はコード変更の規模ではなく、作成したチケットの数に応じて大きくなるため、大規模な作業では全体に占める割合が小さくなるはずです（未検証）。

方法論と完全な結果は、同リポジトリにあります。

このリポジトリは自分自身を使っています

このリポジトリの primer/ ディレクトリは、src/ のツールを使って作成し、意図的にコミットしたプロジェクト独自のバックログです。チケットストアをコミットするよう促すツールなら、自分自身のチケットストアもコミットすべきです。インストールする前に、GitHub で参照して実際のストアがどのようなものか確認できます。

• primer/adrs/ — 却下した代替案とその理由を含む設計上の決定事項
• primer/stories/ と primer/tasks/ — 完了したこと、次に行うこと、検証の証拠

これはプロジェクト管理用であり、パッケージの一部ではありません。 wheel に含まれるのは src/primer_mcp のみで、primer/ は配布物から除外されます。計画を始めると、独自の primer/ が自動的に作成されます。

開発

DEVELOPMENT.md では、チェックアウトのセットアップ方法、チェックの実行方法、未リリースのコードを MCP クライアントから参照する方法、そして MCP 経由でツール呼び出しが届いてからチケットファイルが書き込まれるまでのコードの仕組みを説明しています。

ライセンス

MIT