Codebase Cartographer

ローカルなPythonリポジトリをASTベースのシンボルグラフにマッピングし、検証済みのマルチファイルリファクタリングを実行するMCPサーバーです。

ほとんどのコーディングエージェントは、文字列をgrepして見つけたものを書き換えることでリファクタリングを行います。そのアプローチでは、compute()の呼び出しと、たまたまcomputeという名前のローカル変数を区別できず、名前を変更したときにどの12のファイルが壊れるかもわかりません。このサーバーは、代わりにモデルに実際のインデックスを提供します。スコープ解決済みの参照、インポートグラフ、そして検証できないものは何も書き込まないことを拒否する2フェーズの編集プロトコルです。

機能

マッピング。 リポジトリを（.gitignoreを尊重して）走査し、すべてのモジュールを解析し、関数、クラス、メソッド、モジュールレベルの変数のシンボルテーブルと、モジュール間のインポートグラフを構築します。

解決。 実際のスコープ分析（LEGBチェーン、globalおよびnonlocal宣言、内包表記のスコープ、セイウチ演算子の束縛、そしてクラス本体がネストされた関数から見えないという規則）を使用して参照を見つけます。モジュールレベルのシンボルを隠すローカル変数は、それへの参照ではありません。ツールはその違いを認識しています。

リファクタリング。 シンボルに触れるすべてのファイルにわたって、シンボルの名前変更、移動、削除を行います。from x import y、import x + x.y属性アクセス、asエイリアス、__all__エントリを書き換えます。差分を見たプランを適用するまで、何も書き込まれません。

Related MCP server: MCP Python Code Navigation Server

安全性モデル

リファクタリングは2フェーズで行われ、最初のフェーズはディスクに触れることはありません。

1. plan_rename_symbol / plan_move_symbol / plan_delete_symbolは、プランID、統合差分、警告のリストを返します。触れたすべてのファイルのコンテンツハッシュが記録されます。

2. apply_planはそれらのハッシュを再確認し（プラン作成以降にディスク上で何か変更された場合は中止）、すべてのファイルの新しいコンテンツを構築し、それぞれを再解析し、解析不能になるファイルがある場合は書き込みを拒否します。オリジナルは.cartographer-backups/<plan_id>/にコピーされます。書き込み途中の失敗はすべてのファイルをロールバックします。

さらなるガードレール：マッピングされたルート外のパスは拒否されます。メソッドの名前変更には、型推論なしでは属性マッチングを解決できないため、明示的なallow_heuristic=trueが必要です。まだ参照があるシンボルの削除は、強制されない限り拒否されます。

見えないもの

静的解析には限界があり、ツールはその限界がどこにあるかを示すように作られており、そこにないふりをするわけではありません。

find_dynamic_referencesは、シンボル名に一致する文字列リテラル（getattr(mod, "compute")、プラグインレジストリ、ドット区切りの設定文字列、エントリポイントテーブル）を報告し、アンダースコアで始まるネイティブモジュールのインポートを検出します。これらの警告はすべてのリファクタリングプランに添付されます。

これは具体的に重要です。stdlibのjsonパッケージのコピーでJSONDecodeErrorの名前を変更すると、19個のPython参照はすべて正しく書き換えられますが、それでもパッケージは壊れます。なぜなら_json CアクセラレータがC APIを通じて実行時にその名前を解決するからです。純粋なPython解析ではそれを追跡できません。ツールはネイティブアクセラレータのインポートにフラグを立て、手動で確認するよう指示します。

また見えないもの：from x import *の再エクスポート（警告として報告）、ランタイムのモンキーパッチ、他の言語や設定ファイルからの参照。

ツール

インストール

pip install -e .

MCPクライアントに登録します：

{
  "mcpServers": {
    "codebase-cartographer": {
      "command": "python",
      "args": ["-m", "cartographer"],
      "env": { "CARTOGRAPHER_ROOT": "/path/to/your/repo" }
    }
  }
}

CARTOGRAPHER_ROOTはmap_repositoryのデフォルトにすぎません。ツールは明示的なroot引数も受け取ります。

典型的なセッション

map_repository(root="~/work/service")
  -> 412 files, 1 import cycle, 38k LOC

impact_of_change(module="service.auth.tokens")
  -> 23 transitive dependents

find_references(qualname="service.auth.tokens.decode_jwt")
  -> 31 references across 12 files

find_dynamic_references(name="decode_jwt")
  -> 1 string literal in service/registry.py:44   <- read this before proceeding

plan_rename_symbol(qualname="service.auth.tokens.decode_jwt", new_name="decode_access_token")
  -> plan 9f2a1c: 31 edits across 12 files, with diff

apply_plan(plan_id="9f2a1c")
  -> written, backed up to .cartographer-backups/9f2a1c/

開発

pip install -e ".[dev]"
pytest

65のテストが、スコープ解決（シャドーイング、global、内包表記、クラス本体の可視性）、すべてのインポートスタイルにわたる参照検出、名前変更/移動/削除の正確性、生成されたインポートスタイル、そして適用フェーズの保証（古いファイルの検出、構文検証、ロールバック）をカバーしています。

スイートの最も強力なチェックは、ツールが自身のソースをリファクタリングすることです。実装とテストにわたって関数の名前を変更し、モジュール間で関数を移動します。その後、書き換えられたコピーに対して完全なスイートがまだ合格します。

要件

Python 3.10以上（ast.aliasの位置属性を使用）。Pythonソースのみ。

ライセンス

MIT