MCP Repo Mapper

mcp-repo-mapper

mcp-repo-mapper は、リポジトリ構造を決定論的にマッピングする FastMCP サーバーです。ローカルのコードベースをスキャンし、ファイル構造、言語別の件数、Python のインポート依存関係、循環依存の検出、フレームワークの検出、エントリーポイント候補、およびキャッシュされたリポジトリ構造リソースを公開します。

このサーバーは LLM を呼び出さず、ユーザーコードも実行しません。wayfinder のようなコードベースのオンボーディングエージェント向けに、根拠に基づく構造解析ツールとして設計されています。

コードベースのオンボーディングスタック

mcp-repo-mapper は、コードベースのオンボーディングエージェントである Project 6 wayfinder 向けの、3 つの MCP ツールサーバースタックにおける構造レイヤーです。

• mcp-repo-mapper は、リポジトリの構造、言語、エントリーポイント、フレームワークの根拠、および Python の依存関係エッジをマッピングします。
• mcp-ast-explorer は、シンボルに基づく Python の定義、シグネチャ、参照、呼び出しチェーン、およびクラス階層の検索を提供します。
• mcp-test-runner は、ローカルの pytest/Jest チェックとカバレッジの概要を実行し、エージェントの主張を実行結果と照合して検証できるようにします。

wayfinder では、このサーバーがアーキテクチャのマッピング段階に情報を提供し、その後に意味的な説明やテストによる検証が始まります。

機能

• scan_repo(path) は、ファイル、言語の内訳、エントリーポイント、Python の依存関係グラフ、および検出されたフレームワークを含む、型付けされたリポジトリスキャン結果を返します。
• find_circular_deps(path) は、静的な依存関係グラフから循環依存を返します。
• language_breakdown(path) は、ファイル数とバイト数に基づく言語別の件数を返します。
• detect_framework(path) は、レジストリベースのマーカーを使用して FastAPI、Flask、Django、Express、Spring を検出します。
• find_entry_points(path) は、Python の main、FastAPI アプリ、パッケージの start スクリプト、Dockerfile、Node のインデックスなど、ランク付けされたエントリーポイント候補を返します。
• repo-structure://{url_hash} は、ツール呼び出しによってキャッシュに登録された後、キャッシュ済みの JSON スキャン結果を返します。

インストール

uv sync --extra dev

サーバーをローカルで実行します：

uv run mcp-repo-mapper

開発

uv run ruff check .
uv run mypy
uv run pytest

リソースのフロー

リソースの読み取りでは、ツール呼び出しによって登録されたキャッシュを使用します：

1. scan_repo(path) または別のスキャンベースのツールを呼び出します。
2. 同じパスを使ってリポジトリハッシュを計算します。
3. repo-structure://{url_hash} を読み取ります。

URL スキームにはアンダースコアを含められないため、公開リソースには repo-structure://... を使用します。

対象範囲と制限事項

• 依存関係グラフのサポートは現在 Python のみで、静的な ast 解析に基づいています。
• インポートグラフの解決では、スキャン対象のリポジトリ内に存在するモジュールのみを記録します。
• フレームワークの検出は、完全なビルドシステム解析ではなく、ヒューリスティックなマーカー照合です。
• リソースキャッシュはメモリ内にあり、プロセスごとに分離されています。
• サーバーはローカルファイルシステムのパスのみをスキャンします。

ライセンス

MIT