関連 issue: #85（クローズ・失敗）
作成日: 2026-09-09
アーカイブ日: 2026-09-12
ステータス: 終了（失敗）。CodeRabbit CLI のローカル cr review は組織の Custom MCP Connection を
利用しないことが確定し、本文書が前提としていた「MCP 経由で Gitea Issue をレビュー文脈として
読ませる」方式は成立しないため、Issue #85 を失敗としてクローズした。検証の詳細は Gitea Issue #85
の該当コメントを正本とする。実装（butler/coderabbit_mcp.py 等）・VPS 配備・関連ドキュメント記述は
撤去済み。.coderabbit.yaml の path_instructions による repo 内仕様レビュー（段階 A 相当）のみ
運用を継続している。本文書は当時の検討過程の記録として docs/archive/ に保管する。
検討用（補助資料）。Issue #85 本体の「CodeRabbit 専用 read-only Butler MCP を提供し、
Gitea Issue をレビュー文脈として読めるようにする」という目的を含みつつ、その前後に必要な
CodeRabbit 導入と常用運用までを扱う。
本書の主題は MCP サーバーの実装そのものではない。CodeRabbit を現在の Claude Code / Codex / Butler
による共同開発体制へレビュー担当として加え、Claude Code と Codex が相互レビューに使っている
負荷と利用枠を減らすための全体作業案である。
現在の butler2 開発では、Claude Code と Codex が設計・実装だけでなく、相互のコードレビューも
担当している。一つの変更に対して、実装担当とは別の Brain が差分・仕様・Issue を読み直すため、
両者の利用枠を大きく消費する。利用制限に達すると、一方または両方が使えなくなり、実装・確認・
引き継ぎを継続できない時間が発生する。
レビューを省略して負荷を下げるのではなく、日常的な一次レビューを別サービスへ移管し、Claude Code
と Codex の利用枠を設計・実装・重要な判断に優先配分する必要がある。
実装を担当した Brain とは別のレビュー主体として CodeRabbit を導入し、未コミットのコード差分を
次の 2 種類の根拠と照合できるようにする。
これにより、テストだけでは検出しにくい「実装は動くが仕様と違う」「Issue の要求を一部実装し
忘れている」といった不一致を work_record / work_publish による作業確定前に発見する。
| 担当 | 主な役割 |
|---|---|
| Claude Code / Codex | 要件理解、設計、実装、CodeRabbit 指摘の妥当性判断、必要な修正 |
| CodeRabbit | 未コミット差分の一次レビュー、バグ・セキュリティ・仕様乖離の検出 |
| Butler | Gitea Issue の提供、作業状態の管理、作業記録・公開 |
| 人間 | 方針決定、重大な指摘の裁定、最終判断 |
CodeRabbit は正否を自動決定する品質ゲートではなく、実装後・作業記録前に呼び出す第二レビュー担当とする。
別 Brain による追加レビューは、後述する条件に該当する重要変更や CodeRabbit が扱えない場合に限定する。
work_record の前に CodeRabbit で未コミット差分をレビューするwork_record / work_publish する| 段階 | 移管するレビュー | Butler MCP | 前提 |
|---|---|---|---|
| A | 一般的な不具合・セキュリティ・repo 内仕様との不一致 | 不要 | Essentials、IDE/CLI クライアント導入 |
| B | Gitea Issue の目的・受け入れ条件・議論経過との不一致 | 必要 | Gate 0 通過（Issue #85） |
| C | Claude Code / Codex のどちらからも安定して呼べるチーム共通運用 | 必要 | A / B の効果確認 |
段階 A で日常的な一次レビューの移管を始め、段階 B で Issue 固有要件のレビューまで移管する。
段階 B は単なる追加候補ではなく、本書と Issue #85 の達成対象である。ただし、Gate 0 で CodeRabbit
IDE/CLI が組織 MCP を利用できないと判明した場合は、技術的な代替経路を別途検討する。
CodeRabbit の導入自体を完了扱いにせず、試行期間中の作業ごとに次の代理指標を記録する。
少なくとも複数の代表的な変更で試行し、通常変更では CodeRabbit が別 Brain の全差分レビューを
代替できること、重要変更では必要な追加レビューへ正しく切り替えられることを確認する。
第三者（生成 AI と推定）から「自作 Butler MCP を CodeRabbit に接続して Gitea Issue を
読み取らせる手順」として受領した手順書の正否確認から検討を開始した。受領手順書の全文は
本書末尾「付録 A」に収録する。要旨は次の 4 ステップである。
@modelcontextprotocol/sdk（TypeScript）の SSEServerTransport でラップする。ngrok / Cloudflare Tunnel で一時的なパブリック HTTPS URL を発行する。.../sse）・User Guidance を登録する。.coderabbit.yaml に knowledge_base.mcp.usage: "enabled" を書く。事実確認の結果:
@modelcontextprotocol/sdk のtransport="streamable-http" をネイティブサポートする。gitea_get_issue は Worker MCP、issue_read は Brain 向け MCP に存在し、同一の MCP.coderabbit.yaml の knowledge_base.mcp.usage は実在し、auto（public リポジトリで無効）enabled / disabled を取る。論点の展開:
docs/）にある。CodeRabbit はリポジトリを直接読めるため、.coderabbit.yaml だけで大半が実現でき、MCP はreviews.path_instructions でknowledge_base.code_guidelines.filePatterns にbutler/wiki_* ↔docs/capabilities/wiki/仕様書.md）。usage: enabled でも毎回の呼び出しは保証されない。coderabbit review --uncommitted --agent 等）でdocs/。AIエージェント作業規約.md は repo 外（../）にありcoderabbit review --uncommitted --agent が動作するか確認する。.coderabbit.yaml をリポジトリルートに作成たたき台（対応表は A-3 で確定させる）:
# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
language: "ja"
reviews:
profile: "assertive" # ノイズが多ければ "chill" に落とす
path_instructions:
- path: "butler/issue_backend.py"
instructions: |
Gitea Issue 操作の仕様は docs/capabilities/gitea/仕様書.md を正本とする。
実装がフロー・エラー処理・戻り値契約と食い違う場合は指摘する。
- path: "butler/maids/gitea_issue_worker.py"
instructions: "docs/capabilities/gitea/仕様書.md を根拠に突き合わせる。"
- path: "butler/handover_backend.py"
instructions: "docs/capabilities/handover/仕様書.md を正本として突き合わせる。"
- path: "butler/implement.py"
instructions: |
docs/capabilities/implement/仕様書.md と
docs/capabilities/implement/implement_maid仕様.md を根拠とする。
- path: "butler/maids/implement_maid.py"
instructions: "docs/capabilities/implement/implement_maid仕様.md を根拠とする。"
- path: "butler/maids/implement_common.py"
instructions: "docs/capabilities/implement/仕様書.md を根拠とする。"
- path: "butler/registry.py"
instructions: "Maid 登録・ルーティングの仕様は docs/capabilities/maid/仕様書_v3.md を正本とする。"
- path: "butler/router.py"
instructions: "docs/capabilities/maid/仕様書_v3.md を根拠とする。"
- path: "butler/maids/session_log_worker.py"
instructions: "docs/capabilities/session_log/仕様書.md を根拠とする。"
- path: "butler/maids/session_log_summary_worker.py"
instructions: "docs/capabilities/session_log/要約転記仕様書.md を根拠とする。"
- path: "butler/version_backend.py"
instructions: "docs/capabilities/version/仕様書.md を根拠とする。"
- path: "butler/wiki_doc_summarizer.py"
instructions: "docs/capabilities/wiki/仕様書.md を根拠とする。"
- path: "butler/maids/wiki_worker.py"
instructions: "docs/capabilities/wiki/仕様書.md を根拠とする。"
- path: "butler/work_record_backend.py"
instructions: |
docs/capabilities/work_record/仕様書.md と
docs/capabilities/work_record/実装手順書.md を根拠とする。
- path: "butler/track_backend.py"
instructions: |
docs/Track_Ledger運用マニュアル.md と
docs/capabilities/work_record/仕様書.md の現行契約を根拠とする。
knowledge_base:
code_guidelines:
enabled: true
filePatterns:
- "docs/マスタードキュメント.md"
- "docs/黒執事アーキテクチャ_v2.md"
- "docs/ドキュメント構成.md"
learnings:
scope: "auto"
# 段階 B で追加:
# mcp:
# usage: "enabled"
2 段構えの意図:
code_guidelines.filePatterns … 設計原則・責務境界・配置ルールを 全レビュー共通で常時ロード。path_instructions … 触ったコードに対応する 機能仕様書だけをピンポイントで突き合わせさせる。下表はファイル名から推測したたたき台。段階 A で実際の仕様書内容を確認しながら
1 エントリずつ確定する。
| コード | 根拠仕様（候補） |
|---|---|
butler/issue_backend.py, butler/maids/gitea_issue_worker.py |
docs/capabilities/gitea/仕様書.md |
butler/handover_backend.py |
docs/capabilities/handover/仕様書.md |
butler/implement.py, butler/maids/implement_maid.py, butler/maids/implement_common.py |
docs/capabilities/implement/仕様書.md、docs/capabilities/implement/implement_maid仕様.md |
butler/maids/gemini_cli_implement_maid.py |
docs/capabilities/implement/仕様書.md。legacy 固有契約が不足する場合は正本へ昇格してから追加 |
butler/registry.py, butler/router.py, butler/maids/base.py |
docs/capabilities/maid/仕様書_v3.md |
butler/maids/session_log_worker.py |
docs/capabilities/session_log/仕様書.md |
butler/maids/session_log_summary_worker.py |
docs/capabilities/session_log/要約転記仕様書.md |
butler/version_backend.py |
docs/capabilities/version/仕様書.md |
butler/wiki_doc_summarizer.py, butler/maids/wiki_worker.py, butler/wiki_project_registry.py |
docs/capabilities/wiki/仕様書.md |
butler/work_record_backend.py |
docs/capabilities/work_record/仕様書.md、docs/capabilities/work_record/実装手順書.md |
butler/track_backend.py |
docs/Track_Ledger運用マニュアル.md、docs/capabilities/work_record/仕様書.md |
butler/agy_runtime.py, butler/agy_toolless.py, butler/agy_auth.py |
現行契約を docs/capabilities/ 配下へ昇格してから追加（docs/検討用/ は直接の正本にしない） |
butler/maids/agy_review_maid.py, butler/maids/gemini_cli_review_maid.py |
review capability の現行契約を正本化してから追加 |
butler/mcp_facade.py |
docs/黒執事アーキテクチャ_v2.md、docs/Butler利用ガイド.md |
code_guidelines.filePatterns）docs/マスタードキュメント.mddocs/黒執事アーキテクチャ_v2.mddocs/ドキュメント構成.mdcapability 個別仕様は path_instructions で名指しするため filePatterns には含めない
（全レビューに全 capability 仕様を積むとコンテキストが膨らみ、精度が落ちる）。
段階 A の完了条件:
CodeRabbit CLI v0.7.6 と、仕様確認済みの 4 ファイルに限定した .coderabbit.yaml を導入し、
version capability の意図的な仕様違反で最小 probe を行った。詳細な実行記録は
Issue #85 コメント #6162 を正本とする。
.coderabbit.yaml の path_instructions が参照されることを確認したcode_guidelines.filePatterns に登録した常時参照文書の実利用と、通常変更で別 Brain のgit config core.quotepath false が有効だった。恒久要件とはせず、CLI 更新時に再確認するこの結果は段階 A の成立可能性を示すが、段階 A の完了を意味しない。次は設定対象の網羅ではなく、
現在の 4 ファイルを対象に実作業で負荷軽減効果と見逃し・誤検出を測る。
AIエージェント作業規約.md が repo 外 → 文書全体を複製せず、CodeRabbit のレビュー判断に必要な.coderabbit.yaml の instructions としてdocs/検討用/ には probe ログ・旧版が混在する → filePatterns でディレクトリ一括指定しない。docs/capabilities/ 等の正本へ昇格する。Issue #85 の採用方針に従う。要点のみ再掲する。
butler2-mcp / butler2-worker-mcp に HTTP フラグを足す構成は採らない。butler2-coderabbit-mcp）。/mcp。認証必須。work_session_start や module-level active session に.env / プロセス環境およびGITEA_TOKEN_DEFAULT → GITEA_TOKEN_AI の選択規則で管理・利用する。.env / プロセス環境には検証用のCODERABBIT_MCP_API_TOKEN_SHA256（64桁hex）だけを保存する。Connections → Custom → MCP。Streamable HTTP、https://<公開ホスト>/mcp、Authentication API token、Auth headerAuthorization として登録した。Bearer <生token> を設定する必要があった。Discover tools で、専用サーバーが公開する gitea_get_issue だけが表示された。CallToolRequest を確認し、監査ログにもtool=gitea_get_issue, issue_id=85, repository=akira/butler2, outcome=success が以上により Gate 0 は通過とする。次は固定 HTTPS URL と自動再起動を備えた段階 C の運用構成へ進む。
段階 B の .coderabbit.yaml 追記:
knowledge_base:
mcp:
usage: enabled
加えてダッシュボードで MCP サーバーを登録し、User Guidance を記載する（Issue #85 のたたき台）。
段階 B の完了条件:
Additional context used または利用面に応じた同等の証跡で確認できるhttps://coderabbit-mcp.keinafarm.net/mcp とした。restart: unless-stopped で常時起動する。ホストへ 8848 番ポートは公開しない。Discover tools でgitea_get_issue だけが表示されることを確認済み。更新直後の最終レビューは CodeRabbit CLIWebSocket closed で開始前に失敗したため、固定 URL での tool call 監査証跡は再確認待ち。docs/Butler利用ガイド.md に追記する。work_record 前に CodeRabbit を呼ぶ共通ルールを設定する。次の場合は CodeRabbit だけで完了とせず、Claude Code / Codex のうち実装担当ではない Brain、
または人間へ追加レビューを依頼する。
gitea_get_issue(85) が成功した監査証跡を初期基準とする。Gate 0 が不通過の場合も、段階 A による一般レビューの負荷移管は継続する。Issue 固有要件の
レビューについては、対応 Git 基盤への mirror、Issue 内容の一時的な review context 化などの
代替案を別 Issue で検討する。
AIエージェント作業規約.md から抽出するレビュー向け恒久ルールと、その正本の配置先。butler/mcp_facade.py, butler/worker_mcp.pydocs/Butler利用ガイド.md, docs/マスタードキュメント.md, docs/ドキュメント構成.md出所: 第三者提供（生成 AI と推定。文中の [cite: NN] は原文のまま。信憑性は本書「背景」で
検証済み）。本書の検証・結論はこの原文を対象にしている。
トライアルが Essentials プランの状態で、自作の**「Butler MCP」を CodeRabbit に接続して
Gitea の Issue を読み取らせる**ための具体的な設定手順を解説します [cite: 74, 136, 628]。CodeRabbit はクラウド上の SaaS（クライアント）として動作するため、ローカルの MCP サーバーに
セキュアに接続する設定が必要になります [cite: 1, 629]。以下の 4 つのステップで設定を
進めていきましょう。¶ STEP 1：Butler MCP サーバーを「SSE 形式」で起動する（技術的な前提）
MCP（Model Context Protocol）は、ローカル環境（VS Code や Cursor など）では通常
「stdio（標準入出力）」で通信しますが、CodeRabbit などのクラウドサービスと通信する場合は、
**「SSE（Server-Sent Events）プロトコル」**を介して HTTPS でやり取りする必要があります。
- Butler の SSE 対応を確認： Butler が SSE（HTTP サーバーとして起動し、特定のポートで
リクエストを待機するモード）をサポートしているか確認してください。
- ※もし現状 stdio 形式のみの場合は、SDK のラッパー（例：TypeScript 用の
@modelcontextprotocol/sdkに含まれるSSEServerTransportなど）を使って、
HTTP の SSE エンドポイントとして公開するように Butler を起動します。- ローカルで起動： 例えば、ローカルのポート
3000番で Butler MCP サーバー（SSE）を
起動しておきます。¶ STEP 2：セキュアトンネルでインターネットに公開する
クラウドにある CodeRabbit（SaaS）が、ユーザー様のローカル PC で動いている Butler に
アクセスできるようにするため、ngrokやCloudflare Tunnelを使って一時的にパブリックな
HTTPS URL を発行します。ターミナルで以下を実行します（例：ngrok を使用する場合）：
ngrok http 3000起動すると、以下のような公開 URL が発行されます。
https://xxxx-xxxx.ngrok-free.appこの URL が、CodeRabbit から Butler へ接続するためのベース URL になります。
¶ STEP 3：CodeRabbit ダッシュボードで MCP サーバーを登録する
CodeRabbit の管理画面から、公開した Butler を「ナレッジソース」として登録します
[cite: 122, 514]。
- CodeRabbit ダッシュボード（Web） にログインします [cite: 10, 225]。
- 設定メニューから、「Organization Settings」➔ 「Integrations」 ➔ 「MCP Servers」 を
開きます [cite: 122, 514]。- 「Add MCP Server」 ボタンをクリックします。
- 以下の接続情報を設定します：
- Label（名前）:
gitea-butler（分かりやすい名前で OK です） [cite: 254, 598]- URL: ngrok で発行された公開 URL（SSE エンドポイント）を指定します。
（例：https://xxxx-xxxx.ngrok-free.app/sse）- User Guidance（ユーザーガイダンス：超重要！）: CodeRabbit の AI に対して、
**「この MCP サーバーが何であり、いつどのツールをどう使うべきか」**を日本語で詳しく
記述します [cite: 282, 629]。💡 記述例：
このMCPサーバーは、私たちのGitea Issue情報と仕様書を管理する「Butler」です。 コードレビューを生成する前に、必ずこのサーバーから関連するコンテキストを取得してください。 【利用可能なツール】 - `issue_read`: 実装すべきビジネスロジックや要件定義を読み取ります。 - `gitea_get_issue`: 低レベルなチケットの詳細情報を取得します。 【指示】 コードレビューを開始する前に、まず変更内容やブランチ名から関連するGiteaのIssue番号を特定し、`issue_read` ツールを使ってその要件・仕様・受け入れ基準を取得してください。 コードの実装が、取得したGitea Issueの仕様に100%適合しているかを厳格に突き合わせて確認し、要件漏れや仕様の不一致がある場合は必ずエラーとして指摘してください。¶ STEP 4：リポジトリの
.coderabbit.yamlで MCP を有効化するCodeRabbit がレビューを実行する際に、先ほどダッシュボードで登録した MCP サーバーを
自律的に呼び出せるように、リポジトリの設定ファイルに記述します [cite: 11, 235]。リポジトリルートにある
.coderabbit.yamlを以下のように更新してコミット・ステージします
[cite: 64, 86]：# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json language: "ja" reviews: profile: "assertive" # 仕様適合のチェック漏れを防ぐためにassertive推奨 knowledge_base: mcp: usage: "enabled" # MCPサーバーの利用を有効化します¶ 🚀 動作検証
- わざと「Gitea の特定の Issue に書かれた仕様（例：『ID を UUID にする』など）」に
違反するコードを手元で書きます。- 変更をステージ（
git add .）します [cite: 4, 37]。- VS Code の CodeRabbit 拡張で 「Review Changes」 ボタンを押すか、ターミナルで
coderabbit review --prompt-only --type uncommittedを実行します [cite: 37, 51]。- CodeRabbit の AI エンジンが動き出すと、裏で ngrok を経由してローカルの Butler に
issue_readリクエストが飛びます。- CodeRabbit から、「Gitea の Issue #XX（仕様書）に記載されている『〇〇』の要件が
実装コードで満たされていません」 というレビューコメントが返ってくれば成功です。
| 原文の主張 | 判定 | 補足 |
|---|---|---|
| CodeRabbit は SaaS 側が MCP クライアントとして動く | ○ | 現行 UI の Connections → Custom → MCP で登録 |
SSE（/sse）で公開する必要がある |
△（古い） | Streamable HTTP と SSE 両対応。現行は Streamable HTTP /mcp 推奨 |
| stdio のみなら TypeScript SDK でラップ | ✗ | Butler は Python + FastMCP。transport="streamable-http" をネイティブサポート |
ngrok / Cloudflare Tunnel で HTTPS 公開 |
○（probe 用） | 常用には不向き。固定 URL・常時到達・自動再起動が必要（段階 C） |
| ダッシュボード「Organization Settings → Integrations → MCP Servers」 | △（旧 UI） | 現行 UI は Connections → Add connection → Custom → MCP |
| User Guidance フィールド | ○ | 現行 UI では Prompt Guidance。何のサーバーか・いつ使うかを記述する |
ツール名 issue_read |
○（偶然一致） | Butler に実在 |
ツール名 gitea_get_issue |
○（別公開面） | Worker MCP に実在する。issue_read は Brain 向け MCP にあり、同一サーバーではない |
.coderabbit.yaml の knowledge_base.mcp.usage: "enabled" |
○ | schema v2 に実在（auto / enabled / disabled） |
coderabbit review --prompt-only --type uncommitted |
△（古い構文） | CLI v0.7.6 に --prompt-only / --type は無い。現行は coderabbit review --uncommitted --agent（agent 向け構造化出力）または coderabbit review --uncommitted（プレーン、既定） |
| （原文に記載なし）MCP 連携のプラン要件 | 補足 | Essentials 以上。Essentials は接続 5 件まで |
| （原文に記載なし）Gitea は CodeRabbit 公式非対応 | 補足 | PR bot 不可。IDE/CLI レビュー前提 |
| （原文の前提）User Guidance を書けば毎回 MCP が呼ばれる | ✗ | MCP 呼び出しは AI の自律判断。Additional context used で実利用を確認する必要がある |