MCP AST Explorer

mcp-ast-explorer

決定論的な Python コードベースのシンボル探索を行う MCP サーバーです。

mcp-ast-explorer は LibCST を使って Python ソースファイルをインデックス化し、コードベースの把握に役立つ特化型の MCP ツールを提供します。定義の検索、関数シグネチャ、ローカル参照、直接的な呼び出しチェーン、シンプルなクラス階層クエリを利用できます。

コードベース把握スタック

mcp-ast-explorer は、コードベース把握エージェントである Project 6 wayfinder 向けの 3 サーバー構成の MCP ツールスタックにおいて、セマンティックなシンボルレイヤーを担います。

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

wayfinder では、このサーバーがエントリーポイントとシンボルの説明を支援し、存在しないシンボルを捏造することはありません。

ステータス

これは Python のみを対象とする v1 です。TypeScript は未対応のバックエンドのプレースホルダーとして登録されており、サーバーには明示的な拡張ポイントがありますが、TypeScript の解析はまだ実装されていません。

このサーバーはシンボル検索に LLM を使用しません。要求されたシンボルまたはクラスが解析済みのインデックスに存在しない場合、ツールは回答を捏造せず、構造化された未検出結果を返します。

ツール

ツール	用途
health()	スモークチェックに対して ok を返します。
find_definition(path, symbol, language="python")	モジュール、クラス、関数、またはメソッドの定義を検索します。
function_signature(path, symbol, language="python")	関数またはメソッドのシグネチャを返します。
find_references(path, symbol, language="python")	既存のシンボルについて、同一モジュール内の CST 名参照を返します。
call_chain(path, from_symbol, depth=2, language="python")	ローカル参照から検出された直接の呼び出し元を返します。
class_hierarchy(path, class_name, language="python")	シンプルな基底クラス名から検出された直接のサブクラスを返します。

対応範囲

• LibCST で解析される Python ファイル。
• シンボルの種類：モジュール、クラス、関数、メソッド。
• シンプルな名前を対象とする同一モジュール内の参照検索。
• 関数またはメソッドのコンテナから直接の呼び出し元を検出します。
• class Child(Base): のような単純な継承における直接のサブクラスの検出。
• 未対応言語および未検出のシンボルに対する構造化エラーレスポンス。

現在の制限事項

• ファイル間のインポートとパッケージ全体の解決は v1 の対象外です。
• エイリアス、スターインポート、動的な属性アクセス、修飾参照は解決されません。
• call_chain が現在返すのは直接の呼び出し元のみです。複数ホップの再帰的な展開は実装されていません。
• class_hierarchy が現在返すのは直接のサブクラスのみで、シンプルな基底クラス名を扱います。
• TypeScript は v1 では意図的に未対応です。

ローカル開発

依存関係をインストールします：

uv sync --extra dev

MCP サーバーを実行します：

uv run mcp-ast-explorer

検証を実行します：

uv run ruff check .
uv run mypy
uv run pytest

ライセンス

MIT