ModAST-MCP

C++20/23 プロジェクト向けのモジュール対応 AST MCP サーバー。通常の AST/LSP 操作には永続的な clangd プロセスを使用し、clangd 22 がシンボルとして公開しないエンティティ（module、export module、インポートエッジ）についてはソースレベルでモジュールインデックスを維持します。

実行

npm install
npm run build
node dist/index.js

このサーバーは MCP stdio トランスポートを使用します。Codex/Claude Desktop では、node dist/index.js をコマンドとして指定してください。

Related MCP server: clangd-mcp-server

Windows + Arch WSL

{
  "mcpServers": {
    "modast": {
      "command": "node",
      "args": ["D:/runtime/mcp/ModAST-MCP/dist/index.js"]
    }
  }
}

最初にワークスペースを開いてください：

{
  "root": "E:/github/cnetmod",
  "buildDirectory": "E:/github/cnetmod/cmake-build-release-wsl",
  "transport": "wsl",
  "wslDistro": "Arch",
  "experimentalModules": false
}

mode は auto、cpp、modules のいずれかを受け付け、デフォルトは auto です。auto モードではモジュール拡張子とコンパイラフラグ（-x c++-module、-fmodule-output、/interface、/ifcOutput など）をチェックします。純粋な cpp モードでは PCM/modmap の検出をスキップし、clangd の実験的モジュールサポートを有効にしません。

workspace_open は、オペレーティングシステムの一時ディレクトリ配下に、ワークスペースパスとビルドパスのハッシュで分離された拡張コンパイルデータベースを作成します。CMake/Ninja が生成した .modmap ファイルがあればそれを再利用します。生成されたマップがない翻訳単位については、既存の PCM ファイルに対してソースレベルのインポートを解決し、既知の推移的 PCM マッピングをすべて含むキャッシュ済みレスポンスファイルを作成します。この高速パスでは experimentalModules はオフのままにしてください。必要な PCM ファイルが存在しない場合にのみ有効にしてください。

workspace_warm はノンブロッキングです。永続的な clangd バックグラウンドインデックスを構築している間は workspace_status を呼び出してください。ファイルを開いた後、クエリは同じ clangd セッションから処理されます。

開発時の更新とディスク書き込み

このワークスペースは、compile_commands.json に存在するファイルと、既知の .pcm および .modmap アーティファクトのみを監視します。リポジトリ内のすべてのファイルを再帰的に監視したり再スキャンしたりすることはありません。

• 監視対象のソースを編集すると、メモリ内のモジュールグラフが更新されます。開いているドキュメントは textDocument/didChange を通じて clangd に送信されます。ModAST キャッシュファイルは書き込まれません。

• モジュールインターフェースを編集すると、そのモジュールは「stale（古い）」とマークされます。対応する PCM が再ビルドされるまで、AST、定義、参照、診断のレスポンスには警告が含まれます。

• PCM、modmap、コンパイルデータベースの変更は、1 回のワークスペースリフレッシュにまとめられます（デバウンス）。これにより、通常の「編集 → Ninja/CMake ビルド → クエリ」のループが処理されます。

• 新しい翻訳単位は、ビルドシステムが compile_commands.json を更新した後、workspace_refresh によって検出されます。

• 生成されたコンパイルデータベースとレスポンスファイルは内容比較を使用します。同一の内容は決して書き換えられません。workspace_status.compileDatabase は、最新の準備における diskWrites と cacheFilesReused を報告します。

• 一時ワークスペースキャッシュは、オープン時に 14 日間の TTL、20 個の非アクティブワークスペース上限、512 MB の非アクティブキャッシュ上限で整理されます。アクティブなワークスペースは保持され、クリーンアップ結果は workspace_status.cacheCleanup として公開されます。

• セマンティッククエリは進行中のリフレッシュを待機するため、停止したクライアントではなく、置き換え後の clangd プロセスに対して実行されます。

workspace_status は sourceChanges、lastChangeAt、watchedFiles、staleModules、refreshes も報告するため、エージェントはクロスモジュールデータが最新かどうかを判断できます。

長時間実行されるツールと workspace_open はどちらも、クライアントが進行トークンを送信した場合に MCP notifications/progress を発行します。遅い clangd リクエストは 5 秒ごとにハートビートを発行します。workspace_status はポーリングしても安全です。phase、progressCompleted、progressTotal、elapsedMs、および最新 20 件の人間が読める events が含まれます。

ツール

• workspace_open、workspace_status、workspace_refresh、workspace_warm

• module_search、module_graph

• module_quality、format

• ast、document_symbols、workspace_symbols

• definition、references、diagnostics

行と文字の引数は 1 始まりです。エージェントが使用する場合は、definition と references は needle と occurrence を受け付けるため、手動で位置を計算する必要はありません。

format は clangd/clang-format に委譲し、プロジェクトの .clang-format を尊重します。デフォルトではプレビューのみで、フォーマット後のテキストと LSP の編集内容を返します。apply=true を指定するとソースへの書き込みが必要です。適用前に、サーバーはファイルが clangd のスナップショットと一致することを検証します。同時進行のエディタ変更があると、上書きされる代わりに競合エラーが発生します。書き込みが成功した場合は、同じディレクトリ内の一時ファイルとアトミックな名前変更を使用し、その後、永続的な clangd ドキュメントを同期します。

module_quality はソース正規表現ではなく clangd の AST ノードを使用します。モジュールインターフェースユニット内の実質的な関数本体を報告し、テンプレートと constexpr/consteval 定義は無視します。また、名前付きモジュールに .cpp、.cc、.cxx の実装ファイルやパーティション実装ユニットがない場合に警告します。2 つ目の非エクスポート .cppm ファイルがあっても、このアーキテクチャチェックは満たされません。しきい値とスキャンの並行度は設定可能です。

設計上の注意

• clangd の textDocument/ast は clangdAst の下で変更されずに返されます。

• 合成された moduleContext がモジュールユニットとインポートを追加します。これは、clangd 22 が export module ... に対して AST ノードを返さず、モジュール名をワークスペースシンボルとしてインデックス化しないためです。

• モジュール解析は意図的にソースベースであり、コンパイラベンダーに依存しません。clangd プロセスは C++ 宣言のセマンティックな権威であり続けます。

• transport が wsl の場合、Windows のワークスペースパスはプロセス境界でのみ /mnt/<drive>/... に変換され、MCP レスポンスは Windows パスにマッピングし直されます。

• MCP stdio を閉じる、stdin を終了する、または SIGINT/SIGTERM を送信すると、ファイルウォッチャーが閉じられ、clangd はグレースフルにシャットダウンされます。

検証

npm test はユニットテストとライフサイクルテストを実行します。MODAST_INTEGRATION=1 を設定すると、実際の clangd を使用したライブテストが追加されます。このテストは Windows では Arch WSL、Linux ではネイティブの clangd を使用します。GitHub Actions は Windows と Linux で Node.js 20 および 24 をテストし、Linux でのライブ clangd テストを実行し、高 severity の本番依存関係に関するアドバイザリを拒否します。