ContextBridge

ContextBridge

ContextBridge を使う理由

CB がない場合、AI コーディングエージェントは関連するファイルを推測するか、ソースファイル全体をチャットに貼り付けることになり、不要なコードに何千もの入力トークンを費やしてしまいます。

CB を使えば、AI は 1 つの MCP ツールを呼び出すだけで、簡潔で順位付けされた結果を取得できます。結果には、オーナーファイル、関連ファイル、主要なシンボル、依存関係の概要が含まれます。生のソースコードを何万行も渡す代わりに、通常は数百トークンで済みます。

これはバグの調査に限りません。同じツールで、既存の機能やワークフローがどのように実装されているかについての一般的な質問にも答えられます。

CB がない場合	CB を使う場合
生のファイルを 10～50 個コンテキストに貼り付ける	CB が実際に重要な 3～5 個のファイルを返す
AI が関連するコードを推測する	実際のコードベース構造に基づいた結果が得られる
トークンコストが高く、コンテキストにノイズが多い	トークンコストが低く、コンテキストが絞り込まれる
ファイルパスやメソッド名を幻覚する	正確なファイルパス、シンボル、行のヒントが得られる

オプションのローカル AI 分析ステージでは、クラウド AI に結果を渡す前にさらに圧縮するため、コストを一段と抑えられます。

対象範囲に関する注記： ContextBridge はコードベースのルーティングおよび検索ツールであり、推論エンジンではありません。適切なファイル、シンボル、関連性は見つけますが、因果関係を証明したり、修正方法を選んだりはしません。境界の詳細については、対象範囲を参照してください。

---

💡 初めての方へ： すべてを読む必要はありません。AI アシスタント（Claude、ChatGPT、Gemini など）に docs/ フォルダーを読ませて、お使いの OS とプロジェクトに合わせたセットアップを案内してもらいましょう。

AI コーディングエージェント向けの、ローカルファーストなコード検索レイヤーです。ContextBridge は（Graphify の出力を使用して）コードベースをインデックス化し、どの AI クライアント（Claude Code、Codex、Cursor、Antigravity、…）からも呼び出せる MCP ツールを公開します。これにより、順位付けされたファイル、シンボル、依存関係の連鎖を取得できます。必要に応じて、回答をクラウド AI に渡す前にローカル LLM で検証し、再順位付けすることもできます。

Your prompt ─► ContextBridge (keyword + vector retrieval)
            ─► Local AI (optional: validates, re-ranks, fills gaps)
            ─► Your AI agent (implements, grounded in real files)

エンジンは汎用です。プロジェクト固有の順位付けはすべて交換可能なプロファイルプラグインに実装されているため、同じツールをあらゆるコードベースで使用できます。

---

アーキテクチャ

コードが ContextBridge を経由して AI エージェントに届くまでの流れ：

---

ダッシュボード

ContextBridge には、検索品質、インデックスの健全性、設定を監視するローカルダッシュボードが付属しています。クラウドへの依存はありません。

概要 — 検索品質、トークンの節約量、検索モードの内訳

設定 — パイプラインモード、RAG の重み、モデル設定をリアルタイムで調整

トークンの節約量 — クエリごとに、CB が返した内容とファイル全体を渡した場合のコストを比較

---

📖 始める前に — ドキュメントをお読みください。 docs/ フォルダーには、セットアップ、設定、パイプライン、プロファイル作成に必要な情報がすべて含まれています。すべてのドキュメントを案内するインデックスとして、docs/0. README.md から始めてください。

---

クイックスタート

:: 1. Install deps + build the index + scaffold config files
context_bridge\setup\windows\setup_context_bridge.bat

:: 2. Point the config at YOUR source folders
::    edit config.hybrid.json  ->  settings.discovery.*  (replace your_backend / your_frontend)

:: 3. Re-run setup to index your code
context_bridge\setup\windows\setup_context_bridge.bat

:: 4. Start the server + dashboard (pick Hybrid / Semantic / Keyword)
context_bridge\setup\windows\1.  start_Context_Bridge.bat

Mac/Linux： context_bridge/setup/mac/ または context_bridge/setup/linux/ に相当するものを使用してください。

セットアップは何度でも安全に実行できます。*.example テンプレートから設定ファイルと起動ファイルを、存在しない場合にのみ作成し（編集内容が上書きされることはありません）、実行するたびにインデックスを再構築します。設定をテンプレートの内容に戻すには、setup_context_bridge.bat --force を実行してください。

MCP サーバーはデフォルトで SSE を使用して http://127.0.0.1:8755/sse で実行されます。AI クライアントの接続先に指定してください。SSE に対応していないクライアント向けに、stdio トランスポートもサポートしています（起動前に CONTEXT_BRIDGE_TRANSPORT=stdio を設定してください）。複数の AI クライアントで、それぞれ個別のプロセスを起動せずに実行中のサーバーを共有できるため、SSE の使用を推奨します。 ダッシュボード：http://127.0.0.1:8795。ライブ統計は最新のアクティビティより最大約 15 秒遅れることがあります。また、履歴一覧（最近のイベント、未検出のファイル、失敗したクエリ）には全期間のログではなく、直近 1000 件が表示されます。どちらも意図的なパフォーマンス上のトレードオフであり、データの損失ではありません。

---

検索モード

起動時に選択されます（起動スクリプトが対応する設定ファイルを選択します）。

モード	設定	機能
ハイブリッド	config.hybrid.json	キーワード優先＋制御されたベクトル検索による補助（推奨）
セマンティック	config.semantic.json	ベクトル検索のみ（sentence-transformers が必要）
キーワード	config.json	ベクトル検索なしの純粋なキーワード検索

---

MCP ツール

ツール	用途
search_context_hybrid()	主要 — ファイルとコンテキストを幅広く検索（分析を自動実行）
find_code_locations()	メソッドまたはクラスの正確な所有ファイル／シンボル／行を特定
get_module_summary()	モジュール／サービスの概要
get_graphify_pack()	機能パック内のすべてのファイル
record_outcome()	検索結果が役立ったかどうかを記録
health_check()、get_usage_summary()、search_context()、find_related_files()	ユーティリティ

利用可能なツールは設定で制御されます。ツールが登録されている場合は、安全に呼び出せます。

---

独自のプロファイルの作成

汎用エンジンは各ステップでプロファイルに問い合わせ、プロジェクト固有のランキングを行います。 プロファイルがない場合（project_profile: "default"）、汎用的なスコアリングのみが行われます。

1. rules/projects/example_profile.py を rules/projects/<yourapp>_profile.py にコピーします
2. 必要なフックを実装します（すべてのフックは任意です。省略したフックは何もしない処理にフォールバックします）
3. 有効にします。起動スクリプトで CONTEXT_BRIDGE_PROFILE=<yourapp> を設定するか、設定ファイルで project_profile: "<yourapp>" を指定してください

プロファイルフック（すべて任意）

フック	目的
expand_query_tokens(query, tokens)	検索トークンを追加
module_intent_tokens()	モジュール名 → 語彙の対応付け
pinned_owner_files(query_tokens)	特定のファイルを上位に固定
adjust_document_score(...)	候補ドキュメントのスコアを加算／減算
adjust_owner_score(...)	名前を指定して所有ファイルのスコアを加算／減算
adjust_primary_owner_score(...)	単一の主要な所有ファイルのスコアを調整
adjust_scoped_score(...)	優勢なモジュール／パック内のファイルを優先
extra_owner_file_patterns()	優先度の高いファイル名パターンを追加
infer_module_from_path(path)	パス → モジュール名（統合時のスコープ設定）
low_signal_terms()	重要度の低い語として扱うモジュール／ドメイン用語
noise_files()	優先度を下げるファイル名（ui/support/root）
gap_queries()	トリガー語 → 整理された再検索クエリ
analysis_prompt_override()	ローカル AI 用のシステムプロンプト全体
pack_files_for_intents(...)	インテント → Graphify パックファイルの対応付け（上級者向け）

セットアップ、パイプライン、プロファイル作成、デバッグコマンドについて詳しくは、docs/ を参照してください。

インデックス作成

ContextBridge がインデックスを作成するのは、Graphify の出力（graph.json、GRAPH_REPORT.md、 source-files.txt、scope-summary.md、manifest.json）と /behavior/ ドキュメントであり、未加工の ソースではありません。プロジェクト用に Graphify を生成し、settings.discovery.* をそれらのフォルダーに 設定して、セットアップを実行してください。インデックスを更新するには、Graphify を更新するたびにセットアップを再実行してください。

---

ローカル AI（任意）

pipeline.analysis_stage でローカルモデルを設定してください（デフォルトのプロバイダーは ollama、 または anthropic／openai／openrouter）。有効にすると、CB の結果を検証して再ランク付けし、複数のトピックを含む プロンプトを分解して、ギャップを補うための再検索を実行します。その後、簡潔で根拠に基づいた結果をクラウド AI に渡します。 model のみを変更してモデルを切り替えられます。プロンプトはモデルに依存しません。

---

ライセンス

Copyright 2026 Tiju Thomas

Apache License, Version 2.0 に基づいてライセンスされています。