code-atlas

code-atlas

多言語対応のコードインテリジェンス MCP サーバー — Claude Code（およびあらゆる MCP クライアント）に、コードベースの生テキストではなく、構造化されたビューを提供します。シンボル検索、ファイルの概要、AST パターンクエリ、ファイル間参照、呼び出し／型階層、インポートグラフ、影響を受けるテストの検出を含む変更影響分析、Web フレームワークのルートマップ（Express/NestJS/Fastify/FastAPI/Flask/Django）、Mermaid 図、LSP による正確な回答、ローカル埋め込みによるセマンティック検索、ゲームエンジンのアセット理解（Godot、Unity、Unreal）に対応しています。25 言語をインデックス化します。

grep してファイル全体を読む代わりに、モデルは 「このリポジトリのマップを作って」、「このファイルの概要を教えて」、「parseConfig を呼び出しているのは誰？」、「リクエストハンドラーはどのように DB レイヤーに到達する？」、「このファイルが変更されるたびに何が変わる？」 といった質問をし、永続的な tree-sitter インデックスに基づいた、簡潔でトークン効率の高い回答を得られます。

すべての回答には予算が設定されます。ツールには max_tokens 上限があり、上限に達した回答にはカーソルが返されます。そのカーソルを渡して続きを取得できるため、より大きな予算で再度質問する必要はありません。

ステータス：リリース済み（npm @lusiem/code-atlas、MCP レジストリ io.github.lusiem/code-atlas）。25 言語、32 ツール、構造的な最低限の情報を備えた LSP による正確な回答、エンジンアダプター、そしてトークン効率を重視して構築されたエージェントワークフローレイヤー（repo_map、context_pack、verify_changes）に対応しています。19k ファイル／6.3M LOC で検証済みです。

仕組み

your repo ──scan (gitignore-aware)──> tree-sitter parse ──> SQLite index (symbols, imports,
                                                             occurrences, call/type edges, FTS5)
                                                                   │
Claude Code ◄──────────── MCP tools over stdio ────────────────────┘

• 永続インデックスは <repo>/.code-atlas/index.db に保存されます（Git の対象から自動的に除外されます）。コンテンツハッシュに基づいて段階的に更新されます。
• リアルタイム — gitignore に対応したファイルウォッチャーが、デバウンス間隔の後に保存内容を再インデックス化し、影響を受けたファイルのみを再解決します（無効にするには --no-watch または "watch": false を指定します）。
• 設定不要 — リポジトリのルートを指定するだけで動作します。必要に応じて code-atlas.json で対象の追加や除外を調整できます。
• すべてローカル — コードがマシンの外部に送信されることはありません。

Claude Code へのインストールと使用

claude mcp add code-atlas -- npx -y @lusiem/code-atlas serve

または、クローンから使用します。

git clone https://github.com/lusiem/code-atlas && cd code-atlas
npm install && npm run build
claude mcp add code-atlas -- node /path/to/code-atlas/dist/index.js serve

サーバーは現在の作業ディレクトリをインデックス化します。変更するには --root <path> を渡してください。

CLI

node dist/index.js index [--root <path>]              # one-shot index build (debugging / warm-up)
node dist/index.js serve [--root <path>] [--no-watch] [--no-lsp] [--no-embeddings] [--no-download]
                                                      # MCP server on stdio

ツール

出力例付きの完全なリファレンス：docs/tools.md。

ツール	回答できること
repo_map	このリポジトリは何で、どこから始めればよいですか？ import の流入・流出を示す注釈付きディレクトリツリー（レイヤー構造をひと目で把握）、エントリーポイント、重要度順に並べた主要シンボルとそれぞれの順位の理由、サードパーティ依存関係の一覧を、grep で一通り検索する代わりに、予算内の 1 回の呼び出しで確認できます。path_prefix／depth で範囲を絞れます。
project_overview	手軽に確認できる概要です。言語、サイズ、構成、インデックスの鮮度を確認できます。
search_symbols	X はどこで定義されていますか？ 名前とドキュメントコメントを対象に、FTS とファジー検索を行います。種類、言語、パスで絞り込めます。
search_content	この テキスト はどこにありますか？ 文字列リテラル、エラーメッセージ、環境変数、設定キー、TODO などを検索します。また、コード以外のファイル（md/json/yaml/toml/sql/Dockerfile/CI）を検索できる唯一のツールです。インデックスで候補を提示し、ディスク上で照合するため、検索結果が古くなることはありません。
semantic_search	「リトライのバックオフはどこに実装されていますか？」 — キーワードと埋め込みを組み合わせて順位付けする、完全ローカルの自然言語検索です。
get_file_outline	このファイルには何がありますか？ ソースを読まずに、階層化されたシグネチャを確認できます。予算を超える場合は末尾の行ではなくネストの深さを減らすため、トップレベルのシンボルはすべて残ります。ディレクトリを渡すと、パッケージの公開 API 全体を 1 回の呼び出しで確認できます。
get_symbol_info	ID、位置、名前のいずれかで指定したシンボルに関するすべての情報（ドキュメントとソースを含む）を取得します。
context_pack	シンボルに関する情報を、トークン予算内で 1 回の呼び出しにまとめて取得します。ソース、概要、呼び出し元／呼び出し先、型、ルート、関連テストを、個別に 6 回検索せずに確認できます。予算に収まらないセクションは名前が示されます。
batch_symbols	最大 50 個の #id を、1 回の呼び出しで簡潔な 1 行形式に解決します。
ast_query	生の tree-sitter S 式クエリを実行します。構造検索は正規表現では行えません。
find_references	このシンボルを使っているのはどこですか？ 利用可能な場合は LSP による正確な検索を行い、それ以外の場合は解決済みの使用箇所を先に、名前の一致箇所を候補として返します。
go_to_definition	指定位置にある識別子の定義を取得します。LSP による正確な検索を行い、インデックスでフォールバックします。
call_hierarchy	このシンボルを呼び出すもの／このシンボルが呼び出すものをツリー形式で確認できます。言語サーバーの実行中は、エッジに [lsp 1.00] と表示されます。
type_hierarchy	extends／implements のエッジをたどって、上位型と下位型を確認できます。
get_dependencies	ファイルの import グラフを、両方向（import／import 元）で取得します。
trace_path	2 つのシンボル間の最短呼び出しチェーンを取得します。
change_impact	変更の影響範囲を分析します。呼び出し元を再帰的にたどり、import の到達可能性も調べ、影響を受けるテストファイルを優先して表示します。シンボル、ファイルのリスト、または何も指定しない方法で対象を設定できます。引数を指定しない場合は、未コミットの git diff を分析します（ハンク単位で、実際に変更したシンボルだけをたどり始めます）。影響を受けるルートハンドラーには [ROUTE GET /users/:id] のタグが付きます。
verify_changes	git HEAD と比較して、編集後の構造を検証します。解決できなくなった import、他のファイルから参照されている削除済み export、呼び出し元が残っているシグネチャの変更を確認します。change_impact が予測し、こちらが検証します。
tests_for_symbol	このシンボルをテストしているテストはどれですか？ 逆方向にグラフをたどってテストファイルを探し、テストケース名も表示します。import チェーンのみで見つかったものは、より弱い手がかりとして報告されます。
find_similar_code	「このヘルパーはすでにありますか？」 — ローカルの埋め込みベクトルを使って類似コードを検索します。カバレッジの構築中は、テキスト類似度によるフォールバックを利用します。
find_dead_code	エントリーポイント／ルート／ライフサイクルを除外したうえで、参照が 0 件のシンボルを検出します。確度を考慮し、同名の使用箇所がどこかにある場合は possibly dead と表示します。未使用の export は別途一覧表示されます。
hotspots	キャッシュされたコミット履歴から、変更頻度 × サイズに基づいてリスク順に順位付けします。
change_coupling	このファイルと過去に一緒に変更されたファイルを確認できます。構造インデックスでは見つけられない結合（設定、フィクスチャ、ドキュメント、文字列キーによるディスパッチ）を調べます。方向性を示す確度を表示し、import エッジのないファイルにはその旨を示します。
symbol_history	なぜこのような実装になっているのか、誰に尋ねればよいのかを確認できます。シンボルの行範囲を対象に git log -L を実行し、sha、日付、作成者、件名を表示します。
list_routes	ワークスペース全体の Web フレームワークのルートを一覧表示します。Express、Fastify、NestJS、FastAPI、Flask、Django に加え、Next.js、SvelteKit、Nuxt、Remix のファイルベースルーティングにも対応しています。それぞれのルートはハンドラーシンボルにリンクされています。
find_route	「GET /api/users/7 を処理するコードはどれですか？」 — 具体的な URL をインデックス済みのルートパターンと照合します（:id、{id}、<int:pk> はワイルドカードです）。ハンドラーを返します。
generate_diagram	上記のグラフを Mermaid 図として生成します。import グラフ（ファイルまたはディレクトリ単位）、シンボル周辺の呼び出しグラフ、型階層、呼び出しパスを、GitHub の Markdown やドキュメントにそのまま貼り付けられます。
get_scene_structure	Godot のシーンノードツリーを、アタッチされたスクリプト、インスタンス化されたサブシーン、シグナル接続（ハンドラーはシンボルに解決）とともに取得します。
find_asset_references	このスクリプト、アセット、ハンドラーを使用しているシーン／プレハブ／Blueprint を検索します。Godot の res:// パス、Unity の GUID（.meta 経由）、Unreal のモジュールと /Game/ Blueprint パスを対象に逆引きします。
search_reflection	すべての UPROPERTY(Replicated)、[SerializeField]、@export 変数、シグナルなど、ワークスペース全体のエンジンのリフレクションマーカーを検索します。
index_status / reindex	インデックスの状態確認と手動更新を行います。
ファイル横断の回答はLSP を優先しつつ、構造解析を最低限の基盤とします。言語サーバーが利用可能な場合（PATH 上で見つかった場合、またはユーザーごとのキャッシュに自動取得された場合）、参照／定義／ホバー／呼び出し階層は正確で、lsp とタグ付けされます。それ以外の場合は、インポート名やシンボル名のヒューリスティックな解決に基づき、エッジごとの信頼度スコアを付けて回答します。対応サーバー：typescript-language-server と pyright（npm）、gopls（go install）、rust-analyzer と clangd（バージョン固定、SHA-256 検証済みのリリースバイナリ）、Java 用の Eclipse JDT LS（Java 21 以上のランタイムが必要。PATH／JAVA_HOME から検出）、kotlin-language-server（任意の JRE が必要）、C# 用の csharp-ls（.NET SDK が必要。dotnet tool としてインストール。ライセンスが VS 専用の Microsoft 製 Roslyn LSP は意図的に採用していません）。GDScript は、エディターでプロジェクトを開いている間、Godot エディター内蔵の言語サーバー（TCP 127.0.0.1:6005、CODE_ATLAS_GODOT_LSP_PORT で変更可能）に接続します。エディターを閉じると回答は構造解析にフォールバックし、再び開くと次のクエリで再接続します。ランタイムがない言語は構造解析にフォールバックし、その状況は index_status に正確に報告されます。初回の取得（ダウンロード＋起動）でクエリがブロックされることはありません。ツールは最大 8 秒待機し、その後はサーバーの起動完了を待つ間、構造解析で回答します。--no-lsp で無効化できます。--no-download で自動ダウンロードを無効化できます。

セマンティック検索では、コード向けに調整されたローカルモデル（jinaai/jina-embeddings-v2-base-code、量子化済み ONNX）を使ってすべての関数／クラス（シグネチャ＋ドキュメント＋本体）を埋め込み、コサイン類似度と BM25 のキーワード順位を統合します。すべての処理はお使いのマシン内で完結します。ONNX ランタイム（約 220 MB）とモデル（約 150 MB）はこのパッケージには含まれません。semantic_search を初めて呼び出したときにユーザーごとのキャッシュへダウンロードされ、インストール時にダウンロードされることはありません。また、構造解析ツールがこれらのダウンロードを待つこともありません。カバレッジが完了するまでは、キーワードの重みを高めた結果が返され、その旨が示されます。シンボル数 60,000 のリポジトリの埋め込みには、バックグラウンドで約 15 分かかりますが、実行は一度だけです。その後は編集されたシンボルのみ再埋め込みされます。"embeddings": {"model": "fast"} で 4 倍高速な汎用モデルに切り替えられます。--no-embeddings でこのレイヤーを無効化できます。

言語

現在のインデックス対応（25）： TypeScript、TSX、JavaScript、Python、C、C++、Rust、Go、Java、Kotlin、C#、 GDScript、PHP、Ruby、Lua、Solidity、Zig、Nix、Swift、Scala、Dart、Terraform/HCL、Pascal/Delphi、 Vue、Svelte。

Vue と Svelte の単一ファイルコンポーネントでは、<script> ブロック（<script setup> を含むすべて）が実際のファイル行番号でインデックス化されます。コンポーネントのインポートも解決されるため、.vue/.svelte の依存関係グラフは get_dependencies と change_impact で機能します。Terraform ではブロックをシンボルに対応付けます（resource "aws_s3_bucket" "logs" はどちらのラベルでも検索できます）。また、ローカルの module ソースをインポートとして解決します。LSP 対応の中核範囲外の言語も、ほかの言語と同じ契約に基づき、信頼度スコア付きのエッジを使って構造的に回答します。

テストファイルの認識： インデックス化されるすべてのファイルは、言語ごとのパス規約（*.test.ts、test_*.py、*_test.go、src/test/、*_spec.rb、Foundry の .t.sol など）に基づいて分類されます。これにより、change_impact で影響を受けるテストを報告できます。インラインテストブロック（Rust の #[cfg(test)]、Zig の test）はパスで分類できないため、仕様として対象外です。

ゲームエンジン： エンジンのアセットもコードと併せてインデックス化されます。Godot の .tscn/.tres シーン（ノードツリー、スクリプトのアタッチ、シグナル接続、自動読み込み。res:// は project.godot に基づいて解決され、複数のプロジェクトを含むモノレポにも対応）、Unity の .unity/.prefab/.asset と .meta GUID マップ（MonoBehaviour → C# クラスのリンク、シリアル化された参照）、Unreal の .uproject/.uplugin/Build.cs モジュールグラフに加え、インデックス化されたリフレクションマクロに対応します。UCLASS/USTRUCT/UFUNCTION/UPROPERTY の指定子は注釈対象のシンボルに紐付き（検索可能で、get_symbol_info に表示）、dllexport マクロ（class MYGAME_API AMyActor）によって C++ クラスの抽出が妨げられることもなくなりました。

Unreal Blueprints（.uasset/.umap）： バイナリのエディターパッケージをネイティブに解析します（パッケージの概要、名前／インポート／エクスポートテーブル、アセットレジストリタグ、範囲を限定したタグ付きプロパティの読み取りに対応。Unreal のインストールは不要です）。Blueprint の関数、イベントディスパッチャー、メンバー変数は検索可能なシンボルとして公開され（search_symbols kind:event_dispatcher、lang:uasset）、アセットごとの get_file_outline、全文検索でのグラフノードのコメント、さらに find_asset_references でのアセット／/Game/ パス＋親クラス＋呼び出し先関数への参照にも対応します（handles_event を使った「ReceiveBeginPlay を処理するのはどれか」の検索を含む）。Blueprint から C++ へのリンク（Unreal の A/U/F 命名規則に基づく親クラス、呼び出された UFUNCTIONs）は、信頼度スコア付きの provenance: engine エッジとして生成され、type_hierarchy、call_hierarchy、change_impact に反映されます。対象は未調理（エディター）アセットです。実際の UE 5.6 プロジェクトで検証済みで（1,763/1,764 個のアセットを解析。UE 4.25 から 5.6 までの保存バージョンに対応）、調理済み／マーケットプレイスのパッケージは検出され、理由を記録したうえでスキップされます。バイナリアセットは maxAssetFileBytes（既定値 64 MB）でサイズが制限され、サイズ＋mtime によって変更の有無を判定するため、ウォームスイープで再読み込みされることはありません。Godot のバイナリ .scn は対象外です。

ロードマップ

1. 構造解析の中核：スキャナー、SQLite+FTS5 インデックス、TS/JS/Python 抽出器、最初の 6 つのツール ✅
2. 11 言語すべての抽出器、ファイル間のインポート解決、呼び出しグラフ（find_references、call_hierarchy、trace_path） ✅
3. ファイルウォッチャー＋差分再インデックス（対象を絞った再解決、スキーマ移行） ✅
4. LSP レイヤー（ts-ls/pyright/gopls を自動取得、チェックサム固定の rust-analyzer/clangd バイナリ、JRE/.NET 検出に対応した JDT LS/kotlin-language-server/csharp-ls、フォールバック機能付きの正確な参照／定義／ホバー／呼び出し階層） ✅
5. ローカル埋め込みによるセマンティック検索（semantic_search、BM25＋ベクトルの逆順位融合によるハイブリッド検索、モデルの遅延ダウンロード、差分再埋め込み） ✅
6. ゲームエンジンアダプター：GDScript 文法（同梱 wasm ビルド）、Godot シーン／オートロード、Unity プレハブ／GUID、Unreal モジュールグラフ＋リフレクション検索、Godot エディターへの LSP 接続（TCP 6005、実際のエディターでナイトリーテスト済み） ✅
7. ドキュメント、CI でのベンチマーク（コールドインデックス作成：157k LOC で約 5 秒、ウォームクエリ p95 < 10 ms）、クロスプラットフォーム CI、npm pack のスモークテスト ✅ — npm 公開＋MCP レジストリへの登録は保留中
8. 競争力強化：change_impact（影響範囲＋影響を受けるテスト、git-diff モード）、Web フレームワークのルートインデックス作成（list_routes／find_route）、Vue/Svelte SFC を含む 13 言語を追加 ✅
9. エージェントワークフロー向けリリース（0.4.0）：context_pack（トークン予算に応じた 1 回の呼び出しによる概要）、verify_changes（編集後に git HEAD と照合）、tests_for_symbol、find_similar_code、find_dead_code＋hotspots、batch_symbols、リスト形式のすべてのツールに max_tokens を追加、ファイルベースのルーティング（Next.js/SvelteKit/Nuxt/Remix）、PHP PSR-4／C# 名前空間／Swift SPM のインポート解決、オプトイン式の LSP エッジ昇格、sqlite-vec vec0 KNN ✅
10. オリエンテーション向けリリース（0.5.0）：repo_map（注釈付きアーキテクチャマップ、重要度ランキング、エントリーポイント、依存関係一覧）、再開可能なカーソル＋再調整されたトークン推定器、深さを折りたたむアウトラインとディレクトリアウトライン、永続化されたコミットキャッシュに基づく change_coupling＋symbol_history、シンボルが数百万件あるリポジトリ向けのストリーミング解決 ✅
11. トークン精度とテキスト対応のリリース（0.6.0）：エントロピーの高い出力を過少に見積もらない推定器（base64 のコストが実際の 4 分の 1 と見積もられ、max_tokens を超えることがあった問題を修正）、各行ではなく回答ごとに 1 回だけ出典を表示、コンテンツを格納しない FTS インデックス上の search_content とディスク上での検証、コード以外のファイル（md/json/yaml/Dockerfile/CI）を初めてインデックス化 ✅

パフォーマンス（vuejs/core、157k LOC、536 ファイル、.vue SFC を含む）：コールドインデックス作成 3.8 秒、ウォーム時のツール呼び出しは MCP の往復全体で p95 ≤ 6 ms。CI では scripts/bench.mjs を実行します。

スケール（Unreal Engine Engine/Source/Runtime、19,097 ファイル、6.3M LOC、622k シンボル、502k エッジ）： コールドインデックス作成は 413 秒、ウォーム時の構造クエリは p95 ≤ 18 ms、repo_map は 2,500 トークンの予算内で p95 126 ms でアーキテクチャ全体を返します。19k ファイルすべてに対するテキスト検索は p50 69 ms で、コンテンツインデックスは 45.6 MB（データベースの 4%） です。ファイルテキストは保存せず、候補を提示してディスク上で検証するためです。

開発

npm install        # also copies grammar wasm files into grammars/
npm test           # vitest: extractor golden tests, store, scanner, MCP end-to-end
npm run lint
npm run dev serve  # run from source via tsx

位置の規約：行番号は 1 始まり、列番号は 0 始まり、パスはルート相対でスラッシュを使用します。 言語、サーバー、文法の追加方法については、CONTRIBUTING.md を参照してください。

ライセンス

MIT