MCP CCPP Project Indexer

Name: MCP CCPP Project Indexer
Author: walti1972

ローカル

github.com/walti1972開発ツール104 週間前に更新

リポジトリ

MCP CCPP Project Indexer について

MCP CCPP Project Indexerは、大規模なC++プロジェクトのファイル、シンボル、ソース範囲、C++20モジュールを決定論的に索引化し、AIによるナビゲーションを支援します。コーディングエージェントに位置情報と確認可能なソースを提供し、意味解析は行いません。

主な機能

01シンボルと宣言の検索
02正確なソース範囲の読み取り
03C++20モジュールとパーティションのマッピング
04変更箇所とシンボルの対応付け
05インデックスの増分更新
06オプションのTUIコントロールセンター

活用シーン

01大規模なC++コードベースでシンボルを検索・確認
02C++20モジュール間のインポートとエクスポートを追跡
03索引化された宣言に基づく変更箇所のレビュー

MCP 対応

MCPサーバーとして動作し、MCPクライアントにインデックス検索と正確なソース範囲を提供します。クライアントはシンボル、ファイル、モジュール、変更範囲を特定し、該当するソースを取得できます。

#python-c-plus-plus-parsing-mcp-static-analysis-developer-tools-codex-ai-agents-cpp20-cpp20-modules-prompt-caching-token-reduction-context-window-cursor-ai-model-context-protocol-claude-code-context-ai

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

インストール方法は未掲載です

このサーバーのパッケージやリモートエンドポイントはまだ取得できていません。プロジェクトの README の手順に従ってください。

リポジトリ

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

mcp-cpp-project-indexer

mcp-cpp-project-indexer は、大規模でモジュールを多用するプロジェクトや、MCP ベースの AI コードナビゲーション向けの、決定論的な C++ ソース範囲インデクサーです。

コンパイラー、LSP の代替、リファクタリングエンジン、セマンティックアナライザー、呼び出しグラフビルダーではありません。

役割はシンプルです。

Find code. Read code. Do not guess code.

インデクサーは、C++ のシンボル、ファイル、C++20 モジュールを正確なソース範囲に対応付け、AI が必要なコードだけを読めるようにします。

プロジェクトや関連する AI オーケストレーションの取り組みについては、MEF Programming ホームページに記載されています。これには、MCP ツールの使用を支える、現在構築中のリレー／ガバナンスレイヤーも含まれます。

30 秒でわかる概要

mcp-cpp-project-indexer は、C++ ソースツリー上に軽量なルーティングインデックスを構築します。これにより、MCP クライアントは次のような決定論的な質問をできます。

この関数／クラス／データメンバーはどこにありますか？
読み取るべき正確なソース範囲はどれですか？
どのモジュールがこのパーティションをインポートまたはエクスポートしていますか？
どの変更ハンクが、どのインデックス済みシンボルまたはデータ範囲と交差していますか？

インデクサーが返すのは、メタデータと元のソース範囲です。プログラムを理解しているとは主張しません。AI は返されたソースを読み、その根拠に基づいて推論する必要があります。

最小限のワークフロー：

User asks about Widget::OnScroll
-> find_symbol("Widget::OnScroll")
-> read_symbol(symbolId)
-> AI explains only what was visible in that source range

これにより、正確なソースの根拠が必要になるまで、大規模な C++ プロジェクトをプロンプトに含めずに済みます。

5 分で始める

1. このリポジトリをクローンする

git clone https://github.com/walti1972/mcp-cpp-project-indexer.git
cd mcp-cpp-project-indexer

2. C++ プロジェクトのインデックスを構築する

python <indexer-root>\build_project_index.py `
  --root <project-root> `
  --output-root <project-root>\.mcp-cpp-project-indexer

生成されたインデックスは次の場所に書き込まれます。

<project-root>\.mcp-cpp-project-indexer

3. MCP サーバーを起動する

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer

複数の MCP クライアントで使用する場合や、長時間稼働する共有プロセスには、HTTP トランスポートを使用してください。

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --transport http `
  --http-host 127.0.0.1 `
  --http-port 8765

4. MCP クライアントにサーバーを追加する

LM Studio 形式の最小構成：

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "command": "python",
      "args": [
        "<indexer-root>\\code_index_mcp_server.py",
        "--project-root",
        "<project-root>",
        "--index-root",
        "<project-root>\\.mcp-cpp-project-indexer"
      ]
    }
  }
}

5. ファイル全体ではなく、正確なソースを指定して尋ねる

最初に試すとよいリクエスト：

Find the symbol Widget::OnScroll, read its implementation, and explain only
what is visible in the source range.

想定されるツールの流れ：

find_symbol -> read_symbol -> source-grounded answer

最良の結果を得るには、prompt_template.md にあるルールを AI に与えてください。要点は次のとおりです。

Use metadata to locate code. Read exact source ranges before explaining behavior.
Do not infer implementation behavior from metadata alone.

5 分で始める
本番規模とパフォーマンス
TUI コントロールセンター
リポジトリの構成
このツールを使う理由
使用前／使用後
仕組み
基本的なワークフロー
できること
ビルドと更新
プロジェクト検出の設定
コントロールセンター
MCP サーバーの起動
クライアントの設定
ワークフローの設定例
コマンドラインリファレンス
ツールの概要
AI の推奨使用ルール
ワークフローの例
設計ルール
開発の背景
スモークテスト
メンテナンスチェックリスト

リポジトリの構成

公開ルートの readme.md は、人間向けのプロジェクトドキュメントです。実際の Python 実装は src/ 以下にあります。

src/
  README.md
  indexer/
    build_project_index.py
    update_project_index.py
    cpp_project_index.py
  server/
    code_index_mcp_server.py
    server_ui/
  ui/
    indexer_tui.py
    indexer_control.py

build_project_index.py、code_index_mcp_server.py、indexer_tui.py、update_project_index.py など、ルートレベルのスクリプトは互換性を保つためのラッパーです。既存のコマンドラインや MCP クライアント設定を引き続き使用できるようにしながら、実行を実装パッケージへ振り分けます。

src/ 以下にあるフォルダー内の README は、project-indexer の形式に沿っています。そのため、公開ルートの README を機械専用のドキュメントに変えることなく、エージェントがどこから始めればよいかを把握できます。

🚀 本番規模とパフォーマンス

このプロジェクトは、単なるおもちゃの例ではなく、実際の C++ コードベースで使用されています。最近実施した 2 件の規模テストで、想定される対象範囲を確認できます。

プロジェクト	ファイル数	ソース行数	レクサートークン数	シンボル数	データ宣言数	C++20 モジュール数	全体ビルド
匿名化された商用 C++20 プロジェクト	7,046	979,658	4,682,882	97,924	36,551	3,754	19.5s
Chromium のチェックアウト	137,622	30,792,607	137,365,399	2,327,255	818,188	0	~24m 32s

これらの数値はマシンに依存します。Chromium の実行では、128 GB RAM とエンタープライズ NVMe SSD ストレージを備えた、コア数の多いワークステーション上で --jobs 60 を使用しました。非常に大規模な従来型のインクルードベース C++ コードベースを検証できるため、有用な公開ストレステストです。一方、匿名化された商用プロジェクトでは、密度の高い C++20 モジュールおよびパーティションのメタデータを検証できます。また、Chromium の実行では、データ／メンバーインデクサーの大規模な検証も行われました。ネストされたテンプレートにおける >> の深度処理を修正した後、公開ストレステストにより、追加で46,529件のデータ宣言と66,866件のデータ名エイリアスが見つかりました。

SQLite を使用したルックアップインデックスにより、Chromium 規模でもサーバーを実用的な時間で起動できます。MCP サーバーはすぐに起動し、起動後のメモリ使用量を約200 MBに抑えられます。これは、数百万件のシンボル／データ／名前エントリを Python オブジェクトに読み込む場合と比べて効率的です。

このツールは、Codex デスクトップアプリやその他の MCP クライアントを Visual Studio のナビゲーションと組み合わせ、必要に応じて IDA Pro などのツールからバイナリ／逆コンパイラーの証拠を参照するワークフロー向けに設計されています。

ある計測済みのワークフローでは、ソース範囲を正確にルーティングすることで、読み込んだソーステキストを約 2,000 行から 283 行に減らし、**86%**削減しました。

TUI コントロールセンター

日常的に使用できるよう、インデクサーにはマウス操作に対応したオプションの TUI が含まれています。プロジェクトインデックスを、小規模なローカルコントロールセンターに変えます。

1 か所から HTTP MCP サーバーとウォッチャーを起動する
全体ビルド、増分更新、高速更新、モジュールマップの再構築を実行する
サーバー、ウォッチャー、ロック、プロセス、トークン、インデックスの統計情報をリアルタイムで確認する
ツールを切り替えずにビルド／更新ログを確認する
必要に応じて、パーサーの証拠を詳しく調べるための診断用ファイルセクションを切り替える

TUI コントロールセンター

オプションの UI 依存関係をインストールし、プロジェクト／インデックスのパスを明示してコントロールセンターを起動します。

pip install -r <indexer-root>\requirements-ui.txt

python <indexer-root>\indexer_tui.py `
  --root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --jobs 20 `
  --http-url http://127.0.0.1:8765

UI はオプションです。コアインデクサーは引き続き依存関係が少なく、スクリプトまたは MCP クライアントだけで操作できます。セットアップとキーボードショートカットについては、コントロールセンターを参照してください。

💡 このツールが必要な理由

関数、クラス、インポート、宣言を 1 つ見つけるためだけにファイル全体を読み込むと、大規模な C++ プロジェクトを AI モデルに渡すコストが高くなります。C++20 モジュールでは、この問題がさらに複雑になります。多くの IDE／LSP スタイルのツールは、大規模なモジュールグラフ、パーティション、生成された SDK ヘッダー、ビルド固有の設定への対応に依然として苦労しています。

このインデクサーは、より限定的ながら非常に実用的な問題を解決します。AI に小規模で決定論的なルーティングマップを提供します。AI はまず、関連するシンボル、モジュール、ファイル、または変更されたハンクを特定し、その後、タスクに必要な正確な元のソース行だけを読み取れます。

実際のバグ発見ワークフローの例：

Whole file context:     ~2000 source lines
On-demand source reads:  ~283 source lines
--------------------------------------------
Reduction:               ~86% less source text

📊 導入前 / 導入後

標準的な AI によるコードナビゲーション	mcp-cpp-project-indexer を使用
❌ AI がシンボルを探すためにファイル全体を読み込む	✅ AI は簡潔なメタデータを取得してから、該当するソース範囲だけを読み込む
❌ 関係のない宣言や実装でコンテキストが埋まる	✅ コンテキストを重要な行だけに絞れる
❌ C++20 モジュールの利用側やインポートをたどるのが難しい	✅ モジュールのインポート、再エクスポート、パーティション、利用側を直接確認できる
❌ レビューでは、まず変更されたファイルを手作業で確認する	✅ 変更箇所をインデックス化されたシンボルやデータの範囲に対応付ける
❌ ツールが、実際には持っていない意味的な確実性を示唆する場合がある	✅ インデクサーは、ナビゲーションに必要な事実と元のソース範囲だけを返す

これにより、トークン使用量とレイテンシーが減り、コンテキストの逸脱が抑えられ、ソースに根拠を置いた分析が可能になります。

仕組み

このインデクサーは、コンパイラーであるかのように振る舞うことを意図的に避けています。

高速なトークン／構造スキャン ソースファイルは軽量な Python レキサーと構造パーサーでスキャンされます。出力されるのは、ファイル、シンボル、データ宣言、字句レベルの #include ディレクティブ、ソース範囲、診断情報、モジュール情報を含む、決定論的な目次です。
C++20 モジュールマップ モジュールインターフェース、パーティション、インポート、export-import、利用側をインデックス化することで、AI は LSP にビルド全体の解析を任せることなく、モジュールを多用するコードをたどれます。
インクリメンタル更新とウォッチャー 更新処理ではコンテンツハッシュを追跡し、可能な場合は変更されたインデックスデータだけを書き換えます。オプションのウォッチャーを使うと、Visual Studio で作業している間、MCP サーバーのキャッシュを最新の状態に保てます。
簡潔な出力制御を備えた MCP ツール ツールはまず、ナビゲーションに必要な正確なメタデータを提供します。AI は必要な場合にのみ、簡潔なシンボル検索、ファイル／モジュール／変更の概要、正確な read_symbol または read_range、さらに詳細な再帰的ソース読み取りへと進みます。

インデクサーが提供するのは目次だけです。AI は、自身が明示的に読み込んだ元のソース行を基に、再帰的な調査とコードレビューを行います。

基本的なワークフロー

次の代わりに：

Read Renderer.cpp completely: ~2000 lines

こちらを使います：

find_symbol("Renderer::Paint")
read_symbol(symbolId)
inspect visible calls
read only relevant project callees

変更されたコードをレビューする場合：

list_changed_files
get_file_change_hunks(includeIndexedRangeSummary:true, includeSource:false)
get_file_change_hunks(symbolId/dataId, includeSource:true)
read_symbol/read_range only when current source behavior is needed

機能

スキャナーは、C++ ソースファイルからナビゲーションに必要な情報を抽出します。

ファイルと安定したファイル ID
C++20 モジュールとパーティション
字句レベルの #include ディレクティブ
インポートとエクスポート
名前空間
クラス／構造体／列挙型
関数／メソッド
コンストラクター／デストラクター／演算子
宣言とインライン定義
正確な startLine／endLine
構造上問題が疑われるファイルの診断情報

正規表現ベースではなく、ストリーム／トークンベースです。

対象外の機能

意図的に含めていない機能：

コンパイラーの精度でプログラム全体を対象とする呼び出しグラフ
find_references
型解決
テンプレートのインスタンス化の解決
コンパイラーの精度でのオーバーロード解決
マクロ展開
意味的な要約
バグ分析
analyze_symbol(symbolId)

AI はソース範囲を読み、元のコードに基づいて推論する必要があります。

出力レイアウト

既定の出力ディレクトリ：

<project-root>/.mcp-cpp-project-indexer/

生成されるファイル：

.mcp-cpp-project-indexer/
  manifest.json
  files/
    f_<pathHash>.json
  index.sqlite
  modules.json
  diagnostics.json
  update_state.json      # written by build/update; used for fast incremental updates
  module_map.json        # generated by build_module_map.py
  .watch_update_summary.json  # temporary watcher/update summary
  .update.lock           # process lock for index writers
  .watcher.lock          # process lock for one active watcher

グローバルなシンボルおよびデータのナビゲーションインデックスは index.sqlite に保存されます。ファイルごとの JSON インデックスは、正確なソース範囲とインクリメンタルな再構築における信頼できる情報源として維持されます。

オプションの JSONL エクスポート：

python <indexer-root>\export_index_jsonl.py --index-root <project-root>\.mcp-cpp-project-indexer --kind symbols --output symbols.jsonl
python <indexer-root>\export_index_jsonl.py --index-root <project-root>\.mcp-cpp-project-indexer --kind data --output data.jsonl

スキャナーの診断用ファイルインデックスフィールドは、--emit-diagnostics または --emit-diagnostic-file-indexes を指定した場合にのみ出力されます。

scopeIntervals
structuralEvents
functionBodyRanges

1 つのファイルをインデックス化する

任意のディレクトリから：

python <indexer-root>\build_file_index.py `
  --file <project-root>\path\to\file.ixx `
  --project-root <project-root> `
  --output <project-root>\.mcp-cpp-project-indexer\diagnostic_file.json

スキャナーの診断データを含める場合：

python <indexer-root>\build_file_index.py `
  --file <project-root>\path\to\file.ixx `
  --project-root <project-root> `
  --output <project-root>\.mcp-cpp-project-indexer\diagnostic_file.json `
  --emit-diagnostics

--project-root を省略すると、そのファイルの親ディレクトリが使用されます。

プロジェクトインデックスを構築する

C++ プロジェクトのルートから実行することをおすすめします。

cd <project-root>
python <indexer-root>\build_project_index.py

次の場所に書き込みます。

<project-root>/.mcp-cpp-project-indexer/

明示的な形式：

python <indexer-root>\build_project_index.py `
  --root <project-root> `
  --output-root <project-root>\.mcp-cpp-project-indexer

出力の概要例：

Built cpp.project_index.v1
Root: <project-root>
Output: <project-root>/.mcp-cpp-project-indexer
Files: 7076
Symbols: 97583
Names: 95674
Modules: 3774
Diagnostics: 7
Total code lines: 1750000
Total tokens: 14200000
SQLite index: <project-root>/.mcp-cpp-project-indexer/index.sqlite

Total tokens は、コメントを空白に置き換えた後、インデックス対象のソースに対してインデクサーが数えた字句解析トークン数です。これはプロジェクトの規模を示す指標であり、LLM の課金対象トークン数ではありません。

プロジェクトのルートが Git 作業ツリー内にあり、git が利用可能な場合、ファイルの検出では候補を git check-ignore --stdin でフィルタリングし、Git の無視ルールに従います。これにより、.gitignore、.git/info/exclude、またはユーザーのグローバル Git 無視ファイルに一致するパスが除外されます。Git を使用しないプロジェクトや Git がないシステムでは、組み込みの除外ディレクトリリストにフォールバックします。.git、.vs、.cache、.idea、.folder などのドットディレクトリは、デフォルトで除外されます。

プロジェクト検出設定

ソース構成が混在する大規模プロジェクトでは、プロジェクトルートまたは任意のサブディレクトリに indexer_config.json を配置します。設定ファイルはツリーの走査中に適用されます。ルートの設定が基本設定となり、サブディレクトリの設定で、そのサブツリーの設定を上書きまたは拡張できます。

例：

{
  "addExtensions": [".mm"],
  "addExcludeDirs": ["generated", "third_party"],
  "includeExtensionlessHeaders": true,
  "useGitIgnore": false
}

サポートされているフィールド：

{
  "extensions": [".cpp", ".cc", ".h"],
  "addExtensions": [".mm"],
  "removeExtensions": [".c"],
  "excludeDirs": ["out", "build"],
  "addExcludeDirs": ["generated"],
  "removeExcludeDirs": ["third_party"],
  "includeExtensionlessHeaders": true,
  "useGitIgnore": false
}

extensions と excludeDirs は、そのサブツリーの継承値を置き換えます。add* と remove* フィールドは、継承値を変更します。拡張子のないヘッダーの検出は保守的で、明示的な有効化が必要です。C/C++ ヘッダーらしい内容が先頭行にある、拡張子のないファイルのみが対象になります。 useGitIgnore:false を指定すると、Git の無視ルールによるフィルタリングのほうが明示的なインデクサー設定よりもコストが高い大規模リポジトリで、最後の git check-ignore --stdin による処理を無効にできます。

増分更新

インデックスを完全に構築した後、変更されたファイルを検出し、増分更新できます。

ドライラン：

python <indexer-root>\update_project_index.py `
  --root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --dry-run

すでにインデックス化されているファイルの高速更新：

python <indexer-root>\update_project_index.py `
  --root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --known-files-only

変更が判明しているファイルのウォッチャー形式の更新：

python <indexer-root>\update_project_index.py `
  --root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --known-files-only `
  --changed-file path\to\changed.cpp

--known-files-only は、新しいファイルを検出するための全体走査を省略します。保存や監視のループに最適です。 --changed-file は複数回指定でき、ウォッチャーが変更されていないファイルのハッシュ計算を省略できます。

インデックスへの書き込みは、インデックスルート内の排他的な .update.lock ファイルによって保護されます。これにより、完全ビルド、増分更新、モジュールマップの再構築が同じインデックスファイルへ同時に書き込むのを防ぎます。

プロジェクトインデックスを監視する

スタンドアロンのウォッチャーはソースファイルをポーリングし、変更をデバウンスして、増分更新を実行します。また、必要に応じて module_map.json を再構築します。

python <indexer-root>\watch_project_index.py `
  --root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --jobs 20

ファイルの変更のみの場合、ウォッチャーは次を呼び出します。

update_project_index.py --known-files-only --changed-file <path>

これにより、変更された候補ファイルのみがハッシュ計算されます。コンテンツハッシュに変化がなければ、ウォッチャーはモジュールマップの再構築と MCP キャッシュの再読み込みを省略します。

ウォッチャーは、オリエンテーション文書の変更も検出します。文書のみが変更された場合、C++ ファイルをスキャンせずに orientation.json とその SQLite ノードを更新します。C++ のみが変更された場合、更新処理は文書のスタンプを確認し、一致すれば既存のオリエンテーション結果を再利用します。ソースパスの追加や削除、および --force が指定された場合は、文書のリンクが変わる可能性があるため、オリエンテーションが再構築されます。

1 つのインデックスルートを所有するウォッチャーは 1 つだけにしてください。ウォッチャーは .watcher.lock を使用し、同じインデックスですでに別のウォッチャーが動作している場合は終了します。

診断は致命的なエラーではありません。個々のファイルに関する、ベストエフォートの構造上の警告を示します。

診断の概要を表示する：

python -c "import json; from collections import Counter; d=json.load(open(r'<project-root>\.mcp-cpp-project-indexer\diagnostics.json',encoding='utf-8')); print(len(d)); print(Counter(x.get('code') for x in d)); [print(x['relativePath'], x['code'], x['message'], x.get('range')) for x in d]"

モジュールマップを構築する

プロジェクトインデックスを構築した後：

python <indexer-root>\build_module_map.py `
  --index-root <project-root>\.mcp-cpp-project-indexer

出力：

<project-root>/.mcp-cpp-project-indexer/module_map.json

モジュールマップには、次の情報が含まれます。

モジュール名
プライマリモジュールとパーティション
各モジュールを定義するファイル
インポート
importedBy
モジュールツリー
解決できないインポート

これはメタデータのみです。実装の動作は分析しません。

コントロールセンター

コアインデクサーには、サードパーティーの実行時依存関係はありません。日常的な運用には、任意で使えるターミナルの操作画面が2つあります。

indexer_tui.py：マウス操作に対応した、洗練された Textual UI
indexer_control.py：依存関係のないコマンドラインの代替手段

任意の UI 依存関係をインストールします。

pip install -r <indexer-root>\requirements-ui.txt

Textual UI を起動します。

python <indexer-root>\indexer_tui.py `
  --root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --jobs 20 `
  --http-url http://127.0.0.1:8765

Textual UI は、ボタン、マウス操作、ステータスカード、HTTP /status のライブポーリング、アクティビティログ、ビルド／更新／監視／サーバー操作のプロセス制御を備えた、実際のターミナルインターフェースを提供します。

マウス入力への対応は、ターミナルエミュレーターによって異なります。Windows では、Windows Terminal またはマウスイベントをターミナルアプリケーションに転送できる、ほかの最新ターミナルを使用してください。キーボードショートカットは、Textual を実行できる環境であればどこでも使用できます。

UI の設定は、終了時および診断ファイルのセクションを切り替えたときに、<indexer-root>/.ui-settings/ に保存されます。各設定ファイルは、プロジェクト名とパスのハッシュをキーにするため、UI の設定がプロジェクトルートや生成されたインデックスディレクトリに書き込まれることはありません。保存される設定には、HTTP URL、ジョブ数、診断セクションの切り替え、管理 API の起動設定、アクティブな Textual テーマ、プロジェクトとインデックスのパスが含まれます。

外部 Relay UI の設定では、設定ファイルを直接編集することもできます。

{
  "httpUrl": "http://127.0.0.1:8765",
  "jobs": 20,
  "managementApiEnabled": true,
  "managementToken": "local-secret-token",
  "emitDiagnosticFileIndexes": true,
  "theme": "textual-dark"
}

Textual UI には、独立した Start HTTP + management アクションがあります。このアクションは、ウォッチャーと --enable-management-api を指定して HTTP MCP サーバーを起動し、設定されている場合は保存済みの managementToken を使用します。このアクションは意図的に TUI 内に限定されており、HTTP API の管理コマンドとしては公開されません。

代替のコントロールセンター：

python <indexer-root>\indexer_control.py `
  --root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --jobs 20 `
  --http-url http://127.0.0.1:8765

一般的なキー：

B  full build
U  incremental update
F  fast known-files update
M  rebuild module map
H  start HTTP server with watcher
G  start HTTP server with watcher and management API
W  start standalone watcher
S  toggle diagnostic file sections for launched commands
X  stop the currently running command
R  refresh
Q  quit

HTTP サーバーの実行中、どちらのコントロールセンターも /status をポーリングし、サーバー、ウォッチャー、ロック、インデックスの統計情報をリアルタイムで取得します。HTTP サーバーに接続できない場合は、ディスク上の manifest.json と module_map.json を読み取ります。

モジュールツリーをダンプする

テキストツリー：

python <indexer-root>\dump_module_tree.py `
  --index-root <project-root>\.mcp-cpp-project-indexer

ファイルに書き込みます。

python <indexer-root>\dump_module_tree.py `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --output <project-root>\.mcp-cpp-project-indexer\module-tree.txt

1つのモジュールのインポートツリー：

python <indexer-root>\dump_module_tree.py `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --imports Example.Module:Partition `
  --max-depth 5

MCP サーバーを起動する

サーバーは既存のインデックスを読み込みます。インデックスは再構築しません。

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer

サーバーは読み取り専用で、MCP stdio 経由でロケーター／読み取りツールを公開します。

編集中もサーバーのインメモリキャッシュを最新の状態に保つには、組み込みウォッチャーを指定して起動します。

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --watch-index `
  --watch-jobs 20

サーバーのウォッチャーはすべての進行状況を stderr に書き込むため、stdout は有効な MCP JSON-RPC のまま保たれます。実際にインデックスが変更されると、サーバーキャッシュは自動的に再読み込みされます。保存時に mtime のみが変わり、コンテンツハッシュが変わらない場合は、モジュールマップの再構築とキャッシュの再読み込みをスキップします。

別のウォッチャーが同じインデックスルートをすでに所有している場合、MCP サーバーは読み取り専用で動作し、独自のウォッチャーを起動しません。これにより、複数の MCP クライアントがそれぞれ別の stdio サーバーインスタンスを起動した際に、書き込みプロセスが同時に動作するのを防ぎます。

共有 HTTP トランスポート

複数の MCP クライアントがそれぞれ別の stdio サーバープロセスを起動する構成では、同じ JSON-RPC MCP インターフェースを HTTP 経由でも公開できます。

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --transport http `
  --http-host 127.0.0.1 `
  --http-port 8765 `
  --watch-index `
  --watch-jobs 20

HTTP エンドポイント：

POST http://127.0.0.1:8765/mcp

ステータスエンドポイント：

GET http://127.0.0.1:8765/health
GET http://127.0.0.1:8765/status

これにより、長時間実行するサーバープロセス、インメモリのインデックスキャッシュ、インデックスルート用のウォッチャーをそれぞれ1つに保てます。stdio のみをサポートするクライアントでは、引き続き stdio の設定、またはこの HTTP エンドポイントに接続する小規模なクライアント側ブリッジが必要です。

HTTP 管理 API

外部の制御 UI では、同じ HTTP サーバー上に小規模な管理機能を任意で有効にできます。ビルド／更新プロセスを起動する可能性があるため、デフォルトでは無効になっています。

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --transport http `
  --http-host 127.0.0.1 `
  --http-port 8765 `
  --enable-management-api `
  --management-token <token>

エンドポイント：

GET  /management/status
GET  /server/management/capabilities
POST /management/command
GET  /management/log?since=<eventId>&limit=<n>
GET  /management/log/stream
GET  /management/server-log?since=<eventId>&limit=<n>
GET  /management/server-log/stream

/server/management/capabilities は、外部のリレー／ガバナンスレイヤーで使用される、機械可読なインテント／カテゴリ／ツールの契約を返します。従来のエイリアス /management/capabilities も使用できます。

/management/status には、外部の制御センター向けに構成された dashboard オブジェクトが含まれます。TUI に表示される、同じ主要フィールドが含まれます。

dashboard.project.text
dashboard.index.text
dashboard.server.url / pid / ramText / cpuTimeText / cpuText / uptimeText
dashboard.watcher.runningText / lockText / last
dashboard.counts.filesText / symbolsText / dataText / modulesText / diagnosticsText
dashboard.stats.codeLinesText / tokensText / cpuTimeText / threadsText
dashboard.locks.updateFile / watcherFile
dashboard.mode.diagnosticFileSectionsText / jobsText / theme

サーバーが値を提供できる場合、フォーマット済みの *Text フィールドと並んで、生の数値も含まれます。dashboard.mode.theme は外部 UI 用に予約されています。HTTP サーバー自体はビジュアルテーマを管理しません。

汎用の server.process オブジェクトと management.runner.process オブジェクトにも、取得可能な場合は正規化された CPU フィールドが含まれます。

cpuUserSeconds
cpuSystemSeconds
cpuTimeSeconds
cpuTimeText
cpuCoresAverage
cpuPercentMachine
cpuText

設定されている場合、トークンは共有 HTTP MCP／ステータスのインターフェイスと管理エンドポイントの両方を保護します。次のいずれかの方法で指定してください。

Authorization: Bearer <token>
x-api-key: <token>

コマンドは単一の JSON オブジェクトです。

{ "command": "build", "jobs": 20 }
{ "command": "update", "jobs": 20 }
{ "command": "fast_update", "jobs": 20 }
{ "command": "module_map" }
{ "command": "reload_index" }
{ "command": "start_watcher", "jobs": 20 }
{ "command": "stop_watcher" }
{ "command": "stop_command", "wait": true }

/management/log は管理コマンドの出力を返します。/management/log/stream は対応する SSE ストリームです。ビルドと更新のサブプロセスの出力は非同期で読み取られるため、大規模なプロジェクトのインデックス作成中も、UI からステータスのポーリングとログのストリーミングを続けられます。

/management/server-log は、リクエスト／レスポンスのバイト数と、取得可能な場合は MCP メソッドの詳細を含む、最近の HTTP／MCP トラフィックログイベントを返します。/management/server-log/stream は、リアルタイムのリクエストアクティビティに対応する SSE ストリームです。MCP の tools/call イベントには、展開可能な UI の詳細情報として、toolName、argumentKeys、および上限付きの arguments を含む、簡潔な構造化 mcp オブジェクトも含まれます。JSON-RPC のレスポンスが判明すると、イベントには mcp.outcome（success または error）と mcp.errorCount が含まれるため、制御 UI はレスポンスペイロードを解析せずに、失敗したツール呼び出しを色分けできます。 HTTP のキープアライブリクエストでは、リクエストごとのログメタデータがリセットされるため、ステータスのポーリングで前回の MCP 呼び出しラベルが引き継がれることはありません。

HTTP セキュリティプロファイル

ローカル開発では、引き続きループバック HTTP を使用できます。

--transport http --http-host 127.0.0.1 --http-port 8765

顧客環境または LAN へのデプロイでは、サーバーを暗号化されていない HTTP として公開しないでください。TLS と認証が有効になっていない場合、サーバーはループバック以外のバインドアドレスでの起動を拒否します。

セキュリティプロファイル：

プロファイル	想定用途	要件
`local-dev`	同一マシンでの開発	ループバック HTTP を許可
`trusted-lan`	Relay とインデクサーを異なる信頼済みホストで実行	TLS とトークン認証または mTLS
`production`	顧客環境へのデプロイ	TLS とトークン認証または mTLS

トークン認証付き TLS の例：

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --transport http `
  --http-host 10.0.0.20 `
  --http-port 8765 `
  --management-security-profile trusted-lan `
  --management-tls cert `
  --management-cert security\indexer-server.crt `
  --management-key security\indexer-server.key `
  --management-token <token> `
  --management-cors-origin https://relay.customer.internal `
  --management-allow-ip 10.0.0.12

mTLS の例：

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --transport http `
  --http-host 10.0.0.20 `
  --http-port 8765 `
  --management-security-profile production `
  --management-tls cert `
  --management-cert security\indexer-server.crt `
  --management-key security\indexer-server.key `
  --management-client-ca security\relay-clients-ca.crt `
  --management-require-client-cert `
  --management-cors-origin https://relay.customer.internal `
  --management-allow-ip 10.0.0.12

顧客証明書を使わずに暗号化されたローカルテストを行う場合、初回起動時に自己署名証明書を生成できます。

python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer `
  --transport http `
  --http-host 127.0.0.1 `
  --http-port 8765 `
  --management-tls self-signed `
  --management-auto-cert

生成されたファイルは次の場所に保存されます。

<index-root>\certs\management-cert.pem
<index-root>\certs\management-key.pem

自己署名 TLS は通信を暗号化しますが、ブラウザーやリモートクライアントから自動的に信頼されるわけではありません。顧客環境へのデプロイでは、顧客 CA、公開証明書、または明示的な mTLS 信頼情報を使用してください。

LM Studio MCP の設定

mcp.json の例：

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "command": "python",
      "args": [
        "<indexer-root>\\code_index_mcp_server.py",
        "--project-root",
        "<project-root>",
        "--index-root",
        "<project-root>\\.mcp-cpp-project-indexer"
      ]
    }
  }
}

トークン認証なしで共有 HTTP サーバーを使用する場合：

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

HTTP サーバーが --management-token <token> を指定して起動された場合、LM Studio はそのトークンをヘッダーとして送信する必要があります。

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

サーバーは X-API-Key も受け付けます。

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "X-API-Key": "<token>"
      }
    }
  }
}

インデックスまたはモジュールマップを再構築した後、MCP サーバー／LM Studio を再起動してください。

Codex の設定

Codex では、このリポジトリを MCP stdio サーバーとして設定し、Codex がプロジェクトの指示として読み込む場所にエージェントのルールを配置します。

MCP サーバーエントリの例：

[mcp_servers.mcp-cpp-project-indexer]
command = "python"

args = [
  "<indexer-root>\\code_index_mcp_server.py",
  "--project-root",
  "<project-root>",
  "--index-root",
  "<project-root>\\.mcp-cpp-project-indexer",
]

prompt_template.md のプロンプトルールを、Codex が開くプロジェクトルートの AGENTS.md ファイルにコピーします。例：

<project-root>\AGENTS.md

Codex は、現在の作業ツリーのリポジトリ／プロジェクトの指示として AGENTS.md を読み込みます。通常、C++ プロジェクトのルートではなく親ワークスペースから Codex を起動する場合は、そのワークスペースのルートにファイルを配置するか、Codex で C++ プロジェクトのルートを直接開き、指示が適用されるようにしてください。

MCP サーバーの設定とプロンプトルールは分けておきます。

MCP 設定はツールサーバーを起動し、生成されたインデックスを指定します。
AGENTS.md は、ツールを安全かつ簡潔に使用する方法をエージェントに伝えます。

MCP サーバーの設定を変更した後、またはインデックスを再構築した後は、更新されたツールスキーマが表示されるように、MCP サーバー／Codex セッションを再起動してください。

Claude のセットアップ

Claude Code と Claude Desktop では MCP の扱いが少し異なるため、クライアントごとにセットアップを分けてください。

Claude Code

Claude Code では、セットアップをリポジトリと一緒に持ち運べるようにする場合、プロジェクトルートにあるプロジェクト単位の .mcp.json ファイルに MCP サーバーの設定を記述します。

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "type": "stdio",
      "command": "python",
      "args": [
        "<indexer-root>\\code_index_mcp_server.py",
        "--project-root",
        "<project-root>",
        "--index-root",
        "<project-root>\\.mcp-cpp-project-indexer"
      ],
      "env": {}
    }
  }
}

同等の CLI セットアップ：

claude mcp add mcp-cpp-project-indexer --scope project -- `
  python <indexer-root>\code_index_mcp_server.py `
  --project-root <project-root> `
  --index-root <project-root>\.mcp-cpp-project-indexer

prompt_template.md のルールを Claude Code のプロジェクトメモリファイルにコピーします。

<project-root>\CLAUDE.md

Claude Code は .claude/CLAUDE.md にも対応しています。Claude 固有のファイルを .claude/ の下にまとめたい場合は、このパスを使用してください。重要なのは、Claude Code が開くプロジェクトルートにファイルを配置することです。そうしないと、ツール使用ルールが読み込まれない場合があります。

Claude Desktop

Claude Desktop は、アプリケーションの MCP 設定ファイルを使用します。Windows では通常、次の場所にあります。

%APPDATA%\Claude\claude_desktop_config.json

mcpServers の下にサーバーを追加します。

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "type": "stdio",
      "command": "python",
      "args": [
        "<indexer-root>\\code_index_mcp_server.py",
        "--project-root",
        "<project-root>",
        "--index-root",
        "<project-root>\\.mcp-cpp-project-indexer"
      ],
      "env": {}
    }
  }
}

Claude Desktop は、任意のチャットで CLAUDE.md などのリポジトリ指示ファイルを自動的には読み込みません。prompt_template.md の関連ルールを、Claude Desktop で使用するプロジェクト／チャットの指示に貼り付けるか、リポジトリ単位で永続する指示が必要な場合は Claude Code を使用してください。

.mcp.json、claude_desktop_config.json を変更した後、またはインデックスを再構築した後は、更新されたツールスキーマが表示されるように、Claude クライアントを再起動してください。

ワークフローの例

ソースに基づくバグの検出

実用的なレビューのワークフローとして、mcp-cpp-project-indexer を主なナビゲーションレイヤーとして使用し、AI には読み取った正確なソース範囲のみに基づいて推論させます。

一般的な流れ：

1. User asks:
     Review module X, file X, or function X for bugs.

2. AI uses mcp-cpp-project-indexer:
     find module/file/symbol
     read exact source ranges
     follow only relevant project-local calls
     avoid whole-file reads unless needed

3. AI reports findings:
     file path
     line range
     source-grounded explanation
     uncertainty where more context is needed

4. AI uses Visual Studio MCP only after analysis:
     open the file
     navigate to the exact finding location

これにより、モデルのコンテキストを整理できます。インデクサーが情報の振り分けとトークン削減を担い、AI は元のソース行から分析し、Visual Studio は開発者向けのエディターへの引き継ぎに使用します。

Visual Studio MCP を使用したツールの優先順位

C++20 のモジュールを多用するプロジェクトでは、Visual Studio／IntelliSense／clangd のようなツールで、AI のナビゲーションに十分な精度でモジュールシンボルを解決できない場合があります。

推奨される役割分担：

mcp-cpp-project-indexer
  Primary navigation layer.
  Use for symbols, files, modules, source ranges, imports, imported-by metadata.

Visual Studio MCP
  Editor and project-state layer.
  Use for opening files, jumping to locations, looking at build/output/editor state.
  Do not use as the primary C++20 module symbol resolver.

IDAPro MCP
  Binary/decompiler layer.
  Use only when source evidence is insufficient, or for ABI, crash, reverse
  engineering, decompiled code, imports/exports, or binary-behavior questions.

プロンプトルール：

Use mcp-cpp-project-indexer first for C++ source navigation.
Use Visual Studio MCP only when IDE/editor/build state is needed.
Use IDAPro MCP only when the question requires binary or decompiler evidence.

ドキュメント化されていない API に対するソースとバイナリの証拠

ドキュメント化されていない Windows コンポーネントとやり取りするコードでは、ソースの証拠だけでは不十分な場合があります。有用なセットアップとして、関連する DLL を IDAPro で読み込み、ソースレベルの証拠では挙動が明確にならない場合に限り、AI に逆コンパイル／逆アセンブルしたコードを調べさせます。

シナリオの例：

Project code uses wrappers around undocumented DirectUI behavior.
IDAPro has dui70.dll loaded.

1. AI uses mcp-cpp-project-indexer first:
     find the project wrapper/function
     read the exact source range
     follow only relevant local calls

2. If behavior is still unclear:
     use IDAPro MCP to inspect the corresponding function, import, export,
     vtable target, or decompiled implementation in dui70.dll

3. AI combines evidence:
     source callsite and wrapper behavior
     binary/decompiler evidence from the undocumented implementation
     final finding with source line ranges and binary evidence notes

4. AI uses Visual Studio MCP only for handoff:
     open the project source file
     navigate to the line that should be reviewed or changed

これにより、リバースエンジニアリングの作業を対象に絞れます。AI がバイナリを手当たり次第に調べるのではなく、ソースに基づく質問を持って IDAPro を使用します。これにより、無関係なコンテキストとトークン使用量を削減し、モデルがソースとバイナリの推論の流れを保ちやすくなります。

この設定が機能する理由

AI によるコードレビューでコストがかかるのは、多くの場合、推論ではなく、本当に重要な少量のソースを見つけることです。インデクサーは、ナビゲーションの問題をコンパクトなメタデータと正確なソース範囲に絞り込みます。そうすれば、ほかのツールは IDE との連携、ビルド状態、バイナリに関する情報など、それぞれの得意分野に集中できます。

コマンドラインリファレンス

`build_file_index.py`

ファイルごとのインデックス JSON を 1 つ作成します。

--file PATH                    C++ source/module file to index. Required.
--project-root PATH            Root used for normalized relative paths.
--output PATH                  Output JSON path.
--output-root PATH             Directory used when --output is omitted.
--case-insensitive-paths / --no-case-insensitive-paths
                               Case-fold relative paths before hashing. Default: true.
--blank-comments / --no-blank-comments
                               Blank comments before scanning while preserving lines.
--emit-diagnostics / --no-emit-diagnostics
                               Include scanner diagnostic data.
--print-summary-json           Print summary JSON.

`build_project_index.py`

プロジェクト全体のインデックスを作成します。

--root PATH                    Project/source root. Default: current directory.
--output-root PATH             Index output root. Default: <root>/.mcp-cpp-project-indexer.
--extensions EXT [EXT ...]     Source extensions, e.g. .cpp .cc .mm .h .ixx or cpp,h,ixx.
--include-extensionless-headers / --no-include-extensionless-headers
                               Also discover extensionless files that look like
                               C/C++ headers. Uses a conservative first-lines
                               heuristic. Default: false.
--git-ignore / --no-git-ignore Filter discovered files through git check-ignore
                               when available. Default: true.
--exclude-dir NAME             Extra excluded directory name. Repeatable or comma-separated.
--case-insensitive-paths / --no-case-insensitive-paths
                               Case-fold relative paths before hashing. Default: true.
--blank-comments / --no-blank-comments
                               Blank comments before scanning. Default: true.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Include scanner diagnostic fields in files/<fileId>.json.
                               Compatibility alias: --emit-debug-file-indexes.
                               Default: false.
--print-summary-json           Print summary JSON.
--list-defaults                Print default extensions and excluded directories.
--jobs N                       Worker processes. 1 = sequential, 0 = conservative auto.
--progress / --no-progress     Show progress on stderr. Default: true.

`update_project_index.py`

既存のプロジェクトインデックスを段階的に更新します。

--root PATH                    Project/source root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--extensions EXT [EXT ...]     Source extensions for discovery.
--include-extensionless-headers / --no-include-extensionless-headers
                               Also discover extensionless files that look like
                               C/C++ headers. Uses a conservative first-lines
                               heuristic. Default: false.
--git-ignore / --no-git-ignore Filter discovered files through git check-ignore
                               when available. Default: true.
--exclude-dir NAME             Extra excluded directory name. Repeatable or comma-separated.
--case-insensitive-paths / --no-case-insensitive-paths
                               Case-fold relative path keys. Default: true.
--blank-comments / --no-blank-comments
                               Blank comments before scanning changed files. Default: true.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Include scanner diagnostic fields in updated file indexes.
                               Compatibility alias: --emit-debug-file-indexes.
                               Default: false.
--dry-run                      Show added/modified/deleted files without writing.
--jobs N                       Worker processes for added/modified files.
--force                        Reindex all current files.
--known-files-only             Only consider files already present in manifest.json.
--changed-file PATH            Known changed file. Repeatable. Used by watchers to avoid
                               hashing unchanged files.
--progress / --no-progress     Show progress on stderr. Default: true.
--print-summary-json           Print summary JSON.
--summary-json-file PATH       Write summary JSON while keeping normal console output.

`watch_project_index.py`

ソースファイルを監視し、変更が落ち着いた後に段階的な更新を実行します。

--root PATH                    Project/source root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--indexer-root PATH            Directory containing the indexer scripts.
--extensions EXT [EXT ...]     Source extensions for snapshot scanning.
--include-extensionless-headers / --no-include-extensionless-headers
                               Also discover extensionless files that look like
                               C/C++ headers. Uses a conservative first-lines
                               heuristic. Default: false.
--git-ignore / --no-git-ignore Filter discovered files through git check-ignore
                               when available. Default: true.
--exclude-dir NAME             Extra excluded directory name. Repeatable or comma-separated.
--case-insensitive-paths / --no-case-insensitive-paths
                               Case-fold relative path keys. Default: true.
--jobs N                       Worker process count for update actions.
--poll-interval SECONDS        Poll interval. Default: 1.0.
--debounce SECONDS             Wait for changes to settle. Default: 1.5.
--module-map / --no-module-map Rebuild module_map.json after real index changes. Default: true.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Pass diagnostic emission to watcher-triggered updates.
                               Compatibility alias: --emit-debug-file-indexes.
                               Default: false.

`build_module_map.py`

プロジェクトインデックスからモジュール間の関係を示すメタデータを作成します。

--index-root PATH              Project index root. Default: ./.mcp-cpp-project-indexer.
--output PATH                  Output JSON path. Default: <index-root>/module_map.json.
--print-summary-json           Print compact summary JSON.

`dump_module_tree.py`

読みやすいモジュールツリーとインポートの情報を出力します。

--index-root PATH              Project index root. Default: ./.mcp-cpp-project-indexer.
--imports MODULE               Dump import tree for one C++20 module name.
--max-depth N                  Maximum tree depth. For --imports, default is 4.
--max-files N                  Maximum file paths per module leaf. Default: 1.
--output PATH                  Optional output text file.

`code_index_mcp_server.py`

MCP stdio サーバーを起動します。

--project-root PATH            Project root used for read_range/read_symbol.
--index-root PATH              Directory containing the generated index.
--watch-index / --no-watch-index
                               Start server-managed background watcher. Default: false.
--watch-poll-interval SECONDS  Watcher poll interval. Default: 1.0.
--watch-debounce SECONDS       Watcher debounce delay. Default: 1.5.
--watch-jobs N                 Worker process count for watcher update actions.
--watch-module-map / --no-watch-module-map
                               Rebuild module_map.json after watcher updates. Default: true.
--watch-emit-diagnostic-file-indexes / --no-watch-emit-diagnostic-file-indexes
                               Pass diagnostic emission to server watcher updates.
                               Compatibility alias: --watch-emit-debug-file-indexes.
                               Default: false.
--watch-include-extensionless-headers / --no-watch-include-extensionless-headers
                               Let the server watcher discover extensionless files
                               that look like C/C++ headers. Default: false.
--watch-git-ignore / --no-watch-git-ignore
                               Filter watcher discovery through git check-ignore
                               when available. Default: true.
--transport stdio|http         Transport mode. Default: stdio.
--http-host HOST               HTTP bind host for --transport http. Default: 127.0.0.1.
--http-port PORT               HTTP bind port for --transport http. Default: 8765.

`indexer_control.py`

ビルド／更新／監視／サーバーの各ワークフローを制御するターミナルコントロールセンターです。

--root PATH                    C++ project root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--indexer-root PATH            Directory containing indexer scripts.
--jobs N                       Worker process count for launched commands.
--http-url URL                 HTTP server base URL for live status.
                               Default: http://127.0.0.1:8765.
--enable-management-api / --no-enable-management-api
                               Enable the TUI's HTTP + management launch mode.
--management-token TOKEN       Management API token used when launching
                               HTTP + management.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Initial diagnostic file section setting.

`indexer_tui.py`

マウス操作とライブステータスパネルに対応した、オプションの Textual ターミナル UI です。pip install -r requirements-ui.txt が必要です。

--root PATH                    C++ project root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--indexer-root PATH            Directory containing indexer scripts.
--jobs N                       Worker process count for launched commands.
--http-url URL                 HTTP server base URL for live status.
                               Default: http://127.0.0.1:8765.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Initial diagnostic file section setting.

`indexer_menu.py`

旧式の対話型メニューおよび非対話型コマンドラッパーです。通常の操作には indexer_control.py を使用してください。

--root PATH                    C++ project root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--indexer-root PATH            Directory containing the indexer scripts.
--jobs N                       Worker process count for build/update actions.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Initial menu switch state for scanner diagnostic file sections.
                               Compatibility alias: --emit-debug-file-indexes.
                               Default: false.
--action NAME                  Run one action without the menu.

サポートされている --action の値：

build-index
build-module-map
build-all
update-dry-run
update-known-dry-run
update-index
update-known
update-all
update-known-all
watch
summary
diagnostics
dump-module-tree
lmstudio-config
server
server-watch
server-http-watch

ツールの概要

プロジェクトの概要

get_project_summary
get_index_fingerprint
get_file_fingerprint(file)
get_symbol_fingerprint(symbolId)
get_data_fingerprint(dataId)
validate_fingerprints(items)

サーバーは、現在のインデックス成果物（manifest.json、index.sqlite、モジュール／診断／更新ファイル）を対象とする、サーバー側で低コストに計算できるフィンガープリント stateFingerprint を公開します。読み込まれたインデックスの状態が変わると値も変わるため、再ビルド、更新、またはキャッシュの再読み込み後に、リレー／オーケストレーター層が古いツールの情報を無効として扱えるようになります。

すべての MCP ツールの結果には、結果の _meta にフィンガープリントが含まれます：

{
  "_meta": {
    "stateFingerprint": "..."
  }
}

同じ値は get_project_summary.stateFingerprint と、index.stateFingerprint の下にある HTTP ステータスエンドポイントからも取得できます。

細かな粒度で情報を再利用するには、フィンガープリントツールを使用してください。グローバルインデックスフィンガープリントは警告シグナルとしてのみ使用します。ファイル、シンボル、データのフィンガープリントを使えば、更新のたびに証拠キャッシュ全体を破棄せずに、リレーで有効な情報を検証できます：

fileFingerprint =
  hash(fileId + relativePath + contentHash + line/token counts)

symbol/data fingerprint =
  hash(id + fileFingerprint + startLine + endLine + signature)

validate_fingerprints は、リレー／オーケストレーター層向けの一括処理のエントリーポイントです。最大 500 件のファイル／シンボル／データ項目を受け付け、有効性とフィンガープリントのメタデータのみをコンパクトに返します。これらの呼び出しでは、ソーステキストの読み取りや返却は行いません。

変更追跡ツール

これらのツールは、git.exe が利用可能で、project-root がワークツリー内にある場合にのみ公開されます。読み取り専用であり、汎用のコマンド実行機能は公開しません。

list_changed_files
list_recent_revisions
get_revision_summary
get_file_change_hunks
resolve_hunk_to_indexed_range

現在の変更、最近のリビジョン、ハンクの確認、変更されたファイルのレビュー、コミットメッセージの提案に使用します。

ハンクのメタデータに変更後の行範囲が含まれていて、ソースを読み取る前にリレーに有効な symbolId／dataId のルーティング先が必要な場合は、resolve_hunk_to_indexed_range(file, line|startLine/endLine) を使用してください。変更範囲を包含、重複、または最も近い位置にある、インデックス済みのシンボル／データ範囲を返します。これはメタデータのみを扱うもので、差分を解釈したり、正しさを保証したりするものではありません。

ユーザーが修正、変更、保存、更新、コミットしたと述べた場合や、現在の作業のレビューを求めた場合、エージェントは通常のソースナビゲーションを行う前にこれらのツールを確認してください。ウォッチャーを使用する構成では、インデックスがすでに最新の場合があり、変更追跡ツールを使うことで、影響を受けるファイル／シンボル範囲に最小限のコストでたどり着けます。

get_file_change_hunks には、変更されたハンクの行範囲と、インデックス済みのシンボル／データ範囲との交差部分を示す indexedRanges が含まれることがあります。これらはルーティングのヒントにすぎません。実装について述べる前に、read_symbol または read_range で関連するソースを読んでください。

トークン使用量を抑えたレビューのルーティングでは、get_file_change_hunks を includeIndexedRangeSummary:true、includeIndexedRanges:false、includeSource:false を指定して呼び出してください。返される summaryByIndexedRange は、ハンクごとの交差情報をすべて繰り返すことなく、影響を受けるインデックス済みのシンボル／データ範囲ごとに変更されたハンクをまとめます。

影響を受ける範囲を選択した後、symbolId または dataId を get_file_change_hunks に渡すと、そのシンボル／データ範囲と交差するハンクのみが返されます。これは引き続き行範囲によるフィルタリングであり、意味解析ではありません。

シンボルとソースのツール

find_symbol(query)
find_declaration(query)
find_symbols_glob(pattern)
read_symbol(symbolId)
read_range(file, startLine, endLine)
read_range(file, line, beforeLines, afterLines)
get_nearest_symbol_for_line(file, line)
list_file_symbols(file)

get_nearest_symbol_for_line は、診断、変更箇所、ビルド出力、Visual Studio、または IDA のメモに含まれるファイル／行を、該当する、または最も近いインデックス済みシンボル／データ範囲に対応付けます。このツールが返すのはメタデータのみです。動作について述べる前に、選択されたソース範囲を読み取ってください。

read_symbol では、オプションの startOffset／endOffset または絶対位置の startLine／endLine を指定して、大きなシンボル本体の一部分だけを読み取れます。

read_range では、明示的な startLine／endLine、または line、beforeLines、afterLines を使った対象行の前後を指定する形式を使用できます。対象行の前後を指定する形式は、呼び出し元が関連するソース行を 1 行把握している診断、変更箇所、検索一致、Visual Studio からの引き継ぎ、IDA のメモを想定しています。

find_symbol はシンボルのメタデータのみを検索します。

完全一致の shortName
完全一致の qualifiedName／エイリアス
shortName、qualifiedName、signature に対する部分文字列検索（フォールバック）

オプションのルーティング制御：

compact：コンパクトなルーティングフィールドのみを返します
responseFormat：メタデータのレスポンス形式を pretty または minified の JSON にします
omitNulls：メタデータのレスポンスから null フィールドを省略します
omitEmpty：メタデータのレスポンスから空の配列／オブジェクトを省略します
symbolTypes：インデックス済みシンボルの種類で絞り込みます（例：method、function、type_alias）
container：クラス／構造体／名前空間の名前または接尾辞に含まれるシンボルに絞り込みます
file：1 つの fileId またはプロジェクト相対パスに絞り込みます
filePattern：プロジェクト相対パスの glob パターンで絞り込みます
exactOnly：大文字・小文字を区別しない完全一致を含め、完全一致の short name または qualified name のみを返します
hideNamespaces：ナビゲーション結果から名前空間の再オープンを表すシンボルを除外します

container は、シンボルが宣言されている実際の字句スコープ／インデックス上のコンテナーにのみ使用してください。そのクラスから呼び出されるというだけの理由で、ヘルパーのフリー関数にクラスのコンテナーを指定しないでください。container を指定した find_symbol クエリで結果が返らない場合は、search_source にフォールバックする前に、container を付けずにシンボル名を完全一致で再試行してください。

各結果には、なぜ一致したかを示す matchKind が含まれます。exact_qualified_name や exact_short_name などの強い一致は、通常、ルーティングに最適です。部分文字列、シグネチャ、メタデータによる一致は候補としてより弱いため、ソースを読む前に候補を絞り込んでください。

file と filePattern は同時に指定しないでください。これらは位置を絞り込むフィルターであり、ソースコードを読み取ったり、オーバーロードを意味的に解決したりするものではありません。

レスポンスのパッキングオプションは、メタデータ／ルーティング用ツールでのみ使用できます。ソース用ツールの行番号付きソース出力は変更されません。

ファイルがすでに特定されている場合、list_file_symbols を使って、より小さなファイル単位のシンボル候補リストを取得することもできます。

compact：コンパクトなルーティングフィールドのみを返します
symbolTypes：インデックス済みシンボルの種類で絞り込みます
container：クラス／構造体／名前空間の名前または接尾辞に含まれるシンボルに絞り込みます
hideNamespaces：名前空間の再オープンを表すシンボルを除外します
limit：結果のサイズを制限します

これは位置を絞り込むフィルターにすぎません。継承、オーバーロード、型の意味を解決するものではありません。

ファイルがすでに特定されており、クラスメンバーとローカルヘルパー関数の両方が関係する可能性がある場合は、container フィルターを推測する前に list_file_symbols(file, compact:true, hideNamespaces:true) を優先してください。無名名前空間のヘルパーも通常のインデックス済み関数です。呼び出し元のクラスではなく、周囲の名前付き名前空間がコンテナーになっている場合があります。

search_source では symbolId を指定して、1 つのインデックス済みシンボル範囲内だけを検索できます。位置が特定済みの関数またはメソッド内で字句的な確認を行う場合は、この方法が推奨されます。ただし、これはソースの字句検索であり、呼び出しや参照を意味的に解決するものではありません。

標準の引数：

{ "query": "Editor::_OnScroll" }

互換性のために name が受け付けられる場合もありますが、標準は query です。

ファイルツール

find_files(pattern)
list_file_includes(file)
get_file_structure(file)

プロジェクト相対パスのみを対象に glob 検索します。ソースコードの grep ではありません。

list_file_includes は、1 つのファイルの字句上の #include ディレクティブを返します。 Chromium のような、従来型の include ベースの C++ コードベースを対象としています。

{
  "file": "chrome/app/chrome_main.cc",
  "compact": true,
  "includeResolved": true
}

include メタデータは、ルーティングの根拠としてのみ使用してください。インデクサーは、ソース行、ターゲットテキスト、include の種類（quote、angle、macro）、およびインクルードされたファイルが直接確認できる場合の、可能な範囲でのプロジェクト相対パスへの解決結果を記録します。#if／#ifdef、コンパイラーの include ディレクトリ、生成されたヘッダー、マクロ展開は評価しません。

get_file_structure は、1 つのファイルのメタデータのみの目次を返します。大きなファイルでは、まず includeOutline:false を指定してください。include メタデータが必要な場合は、includeIncludes:true を使用してください。応答を小さく保つには、symbolTypes、dataKinds、hideNamespaces、outlineLimit、compactOutline:true を使用してください。関連するアウトライン項目を特定したら、実装に関する主張をする前に、read_symbol または read_range でソースを読み取ってください。

--emit-diagnostic-file-indexes を指定してファイルインデックスが構築されている場合、get_file_structure には任意のパーサー／インデクサー診断セクションも含められます。

{
  "file": "...",
  "includeOutline": false,
  "includeIndexerDiagnostics": true,
  "diagnosticKinds": ["structuralEvents", "scopeIntervals", "functionBodyRanges"],
  "diagnosticStartLine": 120,
  "diagnosticEndLine": 180,
  "compactDiagnostics": true,
  "diagnosticLimit": 100
}

これは、パーサー診断、見つからないシンボル、疑わしいソース範囲、予期しないスコープ／関数本体の検出を調査する場合にのみ使用してください。インデクサーの診断出力はスキャナーの根拠であり、実装の動作を示すものではありません。

ここでは、プロンプトの表現が重要です。「デバッグ情報」という表現は多くの AI エージェントにとって範囲が広すぎ、DEBUG、_DEBUG、#ifdef DEBUG、Visual Studio のデバッグ、ログ出力の分岐などの C++ のデバッグビルドコードと混同される可能性があります。インデクサーのスキャナーデータについて尋ねる場合は、インデクサー／パーサーの診断を明示してください。

概要把握ツール

get_project_orientation()
list_orientation_nodes()
get_orientation_node(path)
search_orientation(query)

プロジェクト内に標準の概要ブロックを含むフォルダーレベルの README.md／readme.md ファイル、またはファイル名に topology を含む Markdown ファイルがある場合、インデクサーはそれらを任意の概要メタデータとして記録します。これにより、AI エージェントは実装ソースを読む前に、手軽にプロジェクトの全体像を把握できます。フォルダーの README は kind: "folder_orientation"、トポロジー文書は kind: "topology" を使用します。

これらのツールは動的に公開されます。読み込まれたインデックスに概要／トポロジーノードがない場合、tools/list と管理機能のメタデータから概要ツールが除外されます。

概要レイヤーが構造化フィールドを抽出するのは、プロジェクトインデクサーで定義された概要 README の見出しのみです。

Purpose:
Use this folder when the question is about:
Do not use this folder first when the question is about:
## Map
## Start Here
## Boundaries

Responsibilities、Non-responsibilities、Use when、Current layout、Responsibility Boundaries などの旧形式の見出しは、通常の Markdown テキストとしてのみ扱われます。これらは構造化された概要フィールドには反映されません。## Map の項目は、項目名と説明の間に 2 つ以上のスペースがあるフェンス付き text ブロックから解析されます。解決された項目には targetRootRelativePath と pathStatus が含まれます。

search_orientation は BM25 によるルーティング検索を使用し、schema: "cpp.project_orientation.search.v2.1"、algorithm: "bm25"、クエリ語の診断情報、スコア、マッチしたフィールド、アンチマッチ語を返します。結果はルーティングのヒントとしてのみ使用してください。

アーキテクチャやナビゲーションに関する質問には、このツールを使用してください。

{
  "query": "MCP dispatch",
  "limit": 10
}

次に、選択した概要ノードを読み取ります。

{
  "path": "src/server/core/mcp"
}

概要メタデータは、実装の根拠ではありません。次のことに答えるためのものです。

Where should I start?
Which subsystem owns this responsibility?
Which folder should I not inspect first?

関数の動作、コードの正しさ、実行時の動作が保証されるかどうかには答えられません。そのような主張をする場合は、find_symbol、list_file_symbols、read_symbol、または read_range でソースを特定して読み取ってください。

良いプロンプトの例：

Show me which indexer diagnostics are present.
Show me the parser/indexer diagnostics from the index.
Show me indexerDiagnostics.diagnostics from get_file_structure(includeIndexerDiagnostics:true) for file X.
Which indexerDiagnostics.diagnostics are available in the index for file X?
Show me the source location for this indexer diagnostic.

次のような曖昧なプロンプトは避けてください。

Show me debug information.
Find the debug code.
Where is DEBUG used?

想定されるワークフローは次のとおりです。

get_file_structure(includeIndexerDiagnostics:true, compactDiagnostics:true)
-> inspect indexerDiagnostics.diagnostics first
-> read_range around the reported line
-> optionally get_nearest_symbol_for_line for the containing symbol

例：

*Editor*
*/TextEditor/*.ixx
*/Shell/Browser/*

モジュールツール

find_module(moduleName)
list_module_files(moduleName)
search_modules(pattern)
get_module_map_summary
get_module_info(moduleName)
list_module_imports(moduleName)
list_module_imported_by(moduleName)
get_module_tree(maxDepth)

C++20 のモジュール構文を使用してください。

Example.Module:Partition
uiframework.Elements:ElementImpl

モジュールツールに C++ の名前空間構文を渡さないでください。

Example::Namespace
UIFramework::Elements

名前空間、クラス、関数には、find_symbol または find_symbols_glob を使用してください。

方向が重要です。

What does module X import?       -> list_module_imports(X) or get_module_info(X)
Who imports/consumes module X?   -> list_module_imported_by(X) or get_module_info(X)

逆方向のインポートに関する質問に答える際、まずソーステキストを検索しないでください。モジュールマップには importedBy メタデータがすでに保存されています。呼び出し元が実際のインポート行の確認を求めている場合、またはメタデータが不審な場合にのみ、ソースを読み取ってください。

モジュールメタデータツールでは、必要に応じて compact:true を指定できます。

find_module / list_module_files：モジュール／ファイルの簡潔なルーティングフィールド
get_module_info：ファイル、インポート、インポート元メタデータの簡潔な情報
list_module_imports：簡潔な出力インポートレコード
list_module_imported_by：簡潔なインポート元モジュールレコード

データ／メンバーツール

find_data(query)
list_type_members(container)
read_data(dataId)
resolve_code_entity(query, file?, line?, container?)

フィールド、グローバル変数、名前空間定数、列挙値、変数テンプレート、コンセプトには find_data を使用してください。包含する型または名前空間がすでに分かっている場合は、list_type_members を使用してください。どちらのツールもメタデータのみを対象としており、出力を簡潔にするには compact:true を指定できます。

ソース範囲に識別子が含まれており、次にどの読み取りツールを選ぶかを決める前に、それがおそらくフィールド／データ宣言、呼び出し可能なシンボル、型シンボル、または曖昧な候補のいずれかを判断する必要がある場合は、resolve_code_entity を使用してください。任意のファイル、行、コンテナーのコンテキストを指定でき、ランク付けされたメタデータ候補と、read_data や read_symbol などの推奨される次のツールを返します。

resolve_code_entity はあくまで概要把握用です。コンパイラによる名前検索、オーバーロード解決、マクロ展開、C++ の型解決、意味的な参照解決は行いません。ソースレベルの主張には、引き続き read_data、read_symbol、または read_range が必要です。

typeText は、宣言の型を示す元のソーステキストです。コンパイラで解決された型ではありません。意味上の型の同一性を示す証拠ではなく、シンボルやソースをさらに検索するための手がかりとして扱ってください。

関数グラフツール

get_function_body_graph(symbolId, mode?)
get_call_xrefs_from(symbolId)
get_call_xrefs_to(symbolId)
get_symbol_neighborhood(symbolId)

呼び出し可能なシンボルを特定した後、その関数本体からソース構造上の直接的なエッジ（プロジェクト内の呼び出し候補、未解決／外部の呼び出し、データ／メンバーへのアクセス、制御フローマーカー）が必要な場合は、get_function_body_graph を使用してください。このツールはオンデマンドで、キャッシュを認識します。通常のインデックス構築経路は変更しません。

有用なモード：

compute_if_missing：互換性のあるキャッシュ済みグラフを再利用するか、グラフを計算します。
cache_only：互換性のあるキャッシュ済みグラフデータのみを返します。
refresh：そのシンボルのグラフを再計算し、保存済みのエッジを置き換えます。

xref ツールと近傍ツールは、保存済みのグラフエッジのみを読み取ります。

get_call_xrefs_from：関数からの保存済み呼び出しエッジ。
get_call_xrefs_to：関数への保存済み呼び出しエッジ。
get_symbol_neighborhood：対象／呼び出し元／呼び出し先の簡潔な近傍情報。

xref の完全性を前提とする前に、関連する呼び出し元に対して get_function_body_graph を計算または更新してください。関数グラフの出力は、構造上のナビゲーションの証拠に限られます。claimStrength=source_structure_allowed、behaviorClaimsAllowed=false です。動作分析、外部 API の意味、動的ディスパッチの証明、コンパイラ精度のオーバーロード解決を示すものではありません。

詳しくは、Function Graph MCP Tools を参照してください。

AI の推奨使用ルール

モデルは次のルールに従ってください。

Use mcp-cpp-project-indexer as a deterministic source-range locator.
Read source before making implementation claims.
Use query as the canonical argument for symbol lookup tools.
Do not ask for analyze_symbol.
Use function graph tools only as structural navigation evidence.
Do not treat module metadata as implementation behavior.

ツール公開に関する注意

大規模な MCP ツールセットは、クライアントが現在のタスクに関連するツールを有効にしておくと、最も効果的に動作します。すべてのリクエストであらゆるツールを公開していると、モデルによっては調査しすぎたり、似たようなクエリを繰り返したり、必要以上に広範なツールを選択したりすることがあります。これは汎用モデルの通常の動作であり、インデックスデータに問題があることを示すものではありません。

通常の使用では、まず簡潔なメタデータクエリを実行し、実装の証拠が必要な場合にのみソース範囲を読み取ってください。

正しい呼び出し：

find_symbol({"query": "Editor::_OnScroll"})
find_declaration({"query": "OnNotifyReflect"})

避けるべき例：

find_symbol({"name": "Editor::_OnScroll"})

システムプロンプトの完全なテンプレートは、prompt_template.md で確認できます。

ワークフローの例

宣言と定義を検索する

ユーザー：

Find the declaration and definition of OnNotifyReflect.

AI ワークフロー：

find_symbol({"query": "OnNotifyReflect"})
read_symbol(symbolId for declaration)
read_symbol(symbolId for definition)

必要に応じて関数を分析する

ユーザー：

Show me Editor::_OnScroll.

AI ワークフロー：

find_symbol({"query": "Editor::_OnScroll"})
read_symbol(symbolId)

次に、AI は関連するプロジェクト内の呼び出しのみを追跡します：

GetHWND -> find_symbol/read_symbol
SendMessageW -> external Win32 API, do not query project index
MAKEWPARAM -> external Win32 macro, do not query project index

インポートしたモジュールの使用方法

ワークフロー：

1. get_module_info or list_module_imports/list_module_imported_by
2. use relativePath and sourceLine from import metadata
3. list_file_symbols(relativePath)
4. choose the likely entry point from symbol names/signatures
5. read_symbol(candidate)
6. inspect visible source usage
7. follow more project symbols only if needed

ソースコード内の使用箇所の検索の代わりに find_symbols_glob を使わないでください。これは呼び出し箇所ではなく、シンボルのメタデータを検索します。

設計ルール

正確な行番号がシステムの要です

symbolId -> fileId -> startLine/endLine -> original source

実行時データを小さく保つ

実行時インデックスにはルーティングに必要な情報を保存します。スキャナーの診断データは --emit-diagnostics または --emit-diagnostic-file-indexes を指定した場合にのみ出力されます。

検索と閲覧を分離する

index.sqlite               -> symbol/data search
module_map.json            -> module browsing
manifest.json              -> file browsing

診断情報を隠さない

診断をゼロにするためだけに、実際のパーサーやソースコードの問題を隠さないでください。

意味的なスコープを拡大しない

呼び出しグラフは作りません。参照グラフも作りません。マクロ展開も行いません。解析ツールも作りません。AI が必要に応じてソースコードを再帰的に調べます。

再構築の手順

cd <project-root>

python <indexer-root>\build_project_index.py

python <indexer-root>\build_module_map.py `
  --index-root .\.mcp-cpp-project-indexer

その後、MCP サーバー／LM Studio を再起動します。

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。

SPDX-License-Identifier: Apache-2.0

Apache-2.0 ライセンスの全文を、リポジトリ内に次の名前で追加してください：

LICENSE

ソースファイルへのヘッダー追加（任意）：

# SPDX-License-Identifier: Apache-2.0

著作権

Copyright (c) 2026 Mike Walter

プロジェクト名：

mcp-cpp-project-indexer

🤖 開発の経緯

このプロジェクトは、ChatGPT、Gemini、DeepSeek を活用した複数モデルによる AI 支援開発ワークフローを通じて形作られました。目的は、1 つのモデルに広範なツールを盲目的に作らせることではなく、複数のモデルと実際の本番環境でのフィードバックを使って、スコープ、制約、ワークフロー上の摩擦について議論することでした。

アーキテクチャとスコープに関する議論 ChatGPT と Gemini を使い、ツールが何をすべきか、何を避けるべきか、そしてコンパイラーや clangd の代替ではなく、軽量なルーティングインデックスに留めるべき理由について議論しました。
段階的な実装 AI コーディングエージェントを使ってコードベースを段階的に実装し、各機能変更を、C++20 のモジュールを多用する実際のプロジェクトでテストしました。
ワークフロー構造の分析とレビュー 7,000 ファイルのコードベースでの本番利用において、DeepSeek を専任のワークフロー分析パートナーとして活用しました。ツール呼び出しの順序、パラメーターの選択、出力サイズ、ランキングの品質、ナビゲーション上の摩擦、コンテキストの整理状態を評価し、呼び出し回数の削減とトークン効率の向上につながる具体的な変更を提案しました。
反復的な改善 これらのセッションから得たフィードバックをもとに、出力の簡潔化、シンボル／ファイル／コンテナーのフィルター、変更差分のルーティング、ウォッチャーによる再読み込み、指定行周辺の読み取り、プロンプトルールの厳格化など、的を絞った改善を行いました。

その結果、AI 支援によるコードナビゲーションのために AI を活用して構築されたツールが完成しました。厳格な原則は 1 つです。インデクサーの出力を正確かつ小さく保ち、AI の推論は明示的に読み取ったソース範囲だけに基づかせます。

スモークテスト

MCP との統合後、次のテストを実行してください：

get_project_summary
Example.Core.Direct2D の下にあるすべてのモジュールを表示してください。
Example.Shell.Browser:Impl をインポートしているモジュールはどれですか？
ExampleClass::OnEvent の宣言と定義を検索してください。
GetHandler のすべてのオーバーロードを読み取ってください。
Example.Elements:ElementImpl を定義しているファイルはどれですか？
ExampleClass::operator= の定義を検索してください。
Example/Core/Renderer.cpp 内のすべてのシンボルを一覧表示してください。
Example.UI:ToggleSwitch がインポートしているモジュールはどれですか？
Example.Core のモジュールツリーを表示してください（最大深度 3）。
ExampleDialog* に一致するすべてのファイルを検索してください。
Example/Core/Main.ixx の先頭 20 行を読み取ってください。
ExampleClass::ExampleClass の宣言を検索してください（コンストラクター）。
Example/Core/Renderer.cpp 内で Paint に一致するすべてのシンボルを検索してください。
Example.Shell:Impl がインポートしているモジュールを表示してください。
モジュールマップの概要を取得してください。
ExampleClass::OnKeyDown の定義を検索してください。
ExampleClass::OnPaint の範囲（150～200 行目）を読み取ってください。
Example.UI:Controls モジュール内のすべてのファイルを検索してください。
Example.UI:ToggleSwitch のインポートツリーを表示してください。
ExampleNamespace::ExampleClass::Method シンボルを検索してください。
Example.Core.Service をインポートしているすべてのモジュールを一覧表示してください。
テンプレート関数 ExampleClass::Create の宣言を検索してください。
ExampleClass::OnNotify のシンボルを読み取ってください。
Example/UI/Controls/ 以下のすべてのファイルを検索してください。
Example.Core.Direct2D.Renderer のモジュール情報を表示してください。
ExampleClass::Initialize の定義を検索してください。
Example/Core/Service.cpp 内の関数であるすべてのシンボルを一覧表示してください。
Example.UI に属するモジュールはどれですか？
ExampleClass::HandleInput のソース（50～120 行目）を読み取ってください。
Example.Core:ModuleImpl を定義しているファイルを検索してください。
Example.UI:Controls.Button のすべてのインポートを表示してください。
enum ExampleClass::State の宣言を検索してください。
ExampleClass::GetSize のシンボルを読み取ってください。
Example/ 以下にある .ixx 拡張子のすべてのファイルを検索してください。
Example.Shell のモジュールツリーを表示してください（最大深度 2）。
ExampleClass::_UpdateLayout の定義を検索してください。
Example/Core/Utils.cpp 内のすべてのシンボルを一覧表示してください。
Example.UI:Controls をインポートしているモジュールはどれですか？
ExampleClass::Paint の範囲（200～250 行目）を読み取ってください。
ExampleClass::~ExampleClass の宣言を検索してください（デストラクター）。
Example.Shell.Browser:Impl のモジュール情報を表示してください。
Example/Core/ 内で Handler に一致するすべてのシンボルを検索してください。
ExampleClass::OnMouseMove のシンボルを読み取ってください。
Example.UI:Controls.Button を定義しているファイルを検索してください。
Example.Core.Direct2D がインポートしているすべてのモジュールを一覧表示してください。
ExampleClass::SetValue の定義を検索してください。
Example.UI のモジュールツリーを表示してください（最大深度 4）。
Example/Shell/Browser/ 以下のすべてのファイルを検索してください。
Example/Core/Service.ixx の先頭 30 行を読み取ってください。
ExampleClass::GetAccessibleImpl の宣言を検索してください。
Example/UI/Controls/Button.cpp 内のすべてのシンボルを一覧表示してください。
Example.Shell.Browser:Impl がインポートしているモジュールを検索してください。
Example.Elements:ElementImpl のモジュール情報を表示してください。
ExampleClass::OnPropertyChanged の定義を検索してください。
ExampleClass::GetState のシンボルを読み取ってください。
Example/Core/ 以下で Service に一致するすべてのファイルを検索してください。
Example.Elements のモジュールツリーを表示してください（最大深度 3）。
ExampleClass::Register の宣言を検索してください。
Example/Shell/Browser/Impl.cpp 内のすべてのシンボルを一覧表示してください。
Example.Core.Direct2D.Renderer をインポートしているモジュールはどれですか？
ExampleClass::OnInput の範囲（100～150 行目）を読み取ってください。
ExampleClass::_SelfLayoutDoLayout の定義を検索してください。
Example.UI:Controls.Dialog のモジュール情報を表示してください。
Example/Core/ 内で Layout に一致するすべてのシンボルを検索してください。
ExampleClass::GetSliderSize のシンボルを読み取ってください。
Example.Shell:Impl を定義しているファイルを検索してください。
Example.Core に属するすべてのモジュールを一覧表示してください。
ExampleClass::DefaultAction の宣言を検索してください。
Example/UI/Controls/Dialog.ixx の先頭 40 行を読み取ってください。
ExampleClass::_FireClickEvent の定義を検索してください。
Example.Core.Direct2D のモジュールツリーを表示してください（最大深度 5）。
Example/Elements/ 以下のすべてのファイルを検索してください。
ExampleClass::GetCaptured のシンボルを読み取ってください。
Example.Private.Helper をインポートしているモジュールはどれですか？
Example.UI:Controls.Dialog のモジュール情報を表示してください。
ExampleClass::SetCaptured の宣言を検索してください。
Example/Elements/ElementImpl.cpp 内のすべてのシンボルを一覧表示してください。
ExampleClass::OnInput の定義を検索してください。
ExampleClass::_UpdateLabel の範囲（170～180 行目）を読み取ってください。
Example/Elements/ 以下で Element に一致するすべてのファイルを検索してください。
Example.Private のモジュールツリーを表示してください（最大深度 2）。
ExampleClass::GetPressed の宣言を検索してください。
ExampleClass::SetPressed のシンボルを読み取ってください。
Example.Elements:ElementImpl をインポートしているモジュールはどれですか？
Example.Private.Helper のモジュール情報を表示してください。
ExampleClass::OnPropertyChanged の定義を検索してください。
Example/Core/Direct2D/Renderer.cpp 内のすべてのシンボルを一覧表示してください。
Example/UI/ 以下にある .cpp 拡張子のすべてのファイルを検索してください。
ExampleClass::GetSliderBorderStrokeWidth のシンボルを読み取ってください。
ExampleClass::SliderBackgroundColorProp の宣言を検索してください。
Example のモジュールツリーを表示してください（最大深度 1）。
Example.UI で始まるすべてのモジュールを検索してください。
ExampleClass::_SelfLayoutUpdateDesiredSize の範囲（200～220 行目）を読み取ってください。
ExampleClass::SliderBorderColorProp の定義を検索してください。
Example/Private/Helper.cpp 内のすべてのシンボルを一覧表示してください。
Example.UI:Controls.Dialog をインポートしているモジュールはどれですか？
Example.Elements:ElementWithTooltip のモジュール情報を表示してください。
ExampleClass::SliderForegroundColorProp の宣言を検索してください。
ExampleClass::SliderSizeProp のシンボルを読み取ってください。
Example/Private/ 以下のすべてのファイルを検索してください。
ExampleClass::StateProp の定義を検索してください。
Example/Core/Service.cpp 内のすべてのシンボルを一覧表示してください。
Example.Elements:ElementImpl がインポートしているモジュールを検索してください。
Example.UI.Controls のモジュールツリーを表示してください（最大深度 3）。
ExampleClass::CapturedProp の宣言を検索してください。
ExampleClass::PressedProp のシンボルを読み取ってください。
Example/Private/ 以下で Helper に一致するすべてのファイルを検索してください。
ExampleClass::ClassInfoI::GetClassInfoPtr の定義を検索してください。
Example/UI/Controls/Dialog.cpp 内のすべてのシンボルを一覧表示してください。
Example.Private.TreeHelper をインポートしているモジュールはどれですか？
Example.UI:Controls.Button のモジュール情報を表示してください。
ExampleClass::ElementWithPromptValueI::ElementWithPromptValueProperties の宣言を検索してください。
ExampleClass::Initialize のシンボルを読み取ってください（3 つのパラメーターを持つオーバーロード）。
Example/Core/Direct2D/ 以下のすべてのファイルを検索してください。
ExampleClass::_Initialize の定義を検索してください。
Example/Elements/ElementWithTooltip.cpp 内のすべてのシンボルを一覧表示してください。
Example.Private.ValueHelper をインポートしているモジュールはどれですか？
Example.Shell.Browser のモジュールツリーを表示してください（最大深度 4）。
ExampleClass::Register の宣言を検索してください。
ExampleClass::ToggleSwitch のシンボルを読み取ってください（コンストラクター）。
Example/Core/Direct2D/ 以下で Renderer に一致するすべてのファイルを検索してください。期待される動作：
モデルがツールを使用する
ファイル全体を読み取らない
名前空間とモジュールを混同しない
シンボルのメタデータを検索した後にのみ read_symbol を呼び出す
必要な場合にのみ、プロジェクト内の呼び出しを再帰的にたどる

メンテナンスチェックリスト

ツールの動作、コマンドラインスイッチ、プロンプト、またはドキュメントを変更した後は、 MAINTENANCE_CHECKLIST.md を確認してください。通常確認する同期ポイントとして、ツールの説明、プロンプトのルール、README、メニュー／CLI フラグ、インデックスデータの互換性、スモークテスト、リレーの前提条件、コミットの準備を扱っています。

Markdown 対応

ログインしてコメント

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。