Codebase Cartographer

Ein MCP-Server, der ein lokales Python-Repository in einen AST-gestützten Symbolgraphen abbildet und verifizierte Multi-Datei-Refactorings darauf durchführt.

Die meisten Coding-Agenten refaktorieren, indem sie nach einem String greppen und das Gefundene neu schreiben. Dieser Ansatz kann einen Aufruf von compute() nicht von einer lokalen Variablen unterscheiden, die zufällig compute heißt, und er hat keine Ahnung, welche zwölf Dateien brechen, wenn man sie umbenennt. Dieser Server gibt dem Modell stattdessen einen echten Index: scope-aufgelöste Referenzen, einen Importgraphen und ein zweiphasiges Bearbeitungsprotokoll, das sich weigert, etwas zu schreiben, das es nicht verifizieren kann.

Was er tut

Kartiert. Geht das Repository durch (unter Beachtung von .gitignore), parst jedes Modul und erstellt eine Symboltabelle für Funktionen, Klassen, Methoden und Modulebene-Variablen sowie den Importgraphen zwischen den Modulen.

Löst auf. Findet Referenzen mithilfe echter Scope-Analyse – die LEGB-Kette, global- und nonlocal-Deklarationen, Comprehension-Scopes, Walrus-Bindungen und die Regel, dass Klassenkörper für verschachtelte Funktionen unsichtbar sind. Eine lokale Variable, die ein Symbol auf Modulebene überschattet, ist keine Referenz darauf, und das Tool kennt den Unterschied.

Refaktoriert. Benennt, verschiebt und löscht Symbole in allen Dateien, die sie betreffen – schreibt from x import y, import x + x.y-Attributzugriffe, as-Aliase und __all__-Einträge um. Nichts wird geschrieben, bis du einen Plan anwendest, dessen Diff du gesehen hast.

Related MCP server: MCP Python Code Navigation Server

Sicherheitsmodell

Refactoring ist zweiphasig, und die erste Phase berührt niemals die Festplatte.

1. plan_rename_symbol / plan_move_symbol / plan_delete_symbol geben eine Plan-ID, einen Unified-Diff und eine Liste von Warnungen zurück. Der Inhalts-Hash jeder berührten Datei wird aufgezeichnet.

2. apply_plan überprüft diese Hashes erneut (bricht ab, wenn sich seit der Planung etwas auf der Festplatte geändert hat), erstellt den neuen Inhalt für jede Datei, parst jede erneut und weigert sich zu schreiben, wenn eine Datei unparsbar enden würde. Originale werden nach .cartographer-backups/<plan_id>/ kopiert. Ein Fehler mitten im Schreiben rollt jede Datei zurück.

Weitere Schutzmaßnahmen: Pfade außerhalb des abgebildeten Wurzelverzeichnisses werden abgelehnt; das Umbenennen einer Methode erfordert ein explizites allow_heuristic=true, da Attributabgleich ohne Typinferenz nicht aufgelöst werden kann; das Löschen eines Symbols, das noch Referenzen hat, wird verweigert, es sei denn, es wird erzwungen.

Was es nicht sehen kann

Statische Analyse hat eine harte Grenze, und das Tool ist darauf ausgelegt, zu sagen, wo diese Grenze liegt, anstatt so zu tun, als gäbe es sie nicht.

find_dynamic_references meldet String-Literale, die mit einem Symbolnamen übereinstimmen – getattr(mod, "compute"), Plugin-Registries, gepunktete Einstellungs-Strings, Entry-Point-Tabellen – und erkennt Importe von unterstrichen-präfixierten nativen Modulen. Diese Warnungen werden jedem Refactoring-Plan beigefügt.

Das ist konkret von Bedeutung. Das Umbenennen von JSONDecodeError in einer Kopie des Stdlib-Pakets json schreibt alle 19 Python-Referenzen korrekt um und bricht das Paket trotzdem, weil der _json-C-Beschleuniger diesen Namen zur Laufzeit über die C-API auflöst. Keine reine Python-Analyse kann dem folgen. Das Tool kennzeichnet den nativen Beschleuniger-Import und sagt dir, dass du manuell prüfen sollst.

Auch unsichtbar: from x import *-Re-Exporte (als Warnung gemeldet), Runtime-Monkey-Patching und Referenzen aus anderen Sprachen oder Konfigurationsdateien.

Werkzeuge

Installation

pip install -e .

Registriere es bei einem MCP-Client:

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

CARTOGRAPHER_ROOT ist nur der Standard für map_repository; das Tool akzeptiert auch ein explizites root-Argument.

Eine typische Sitzung

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/

Entwicklung

pip install -e ".[dev]"
pytest

65 Tests decken Scope-Auflösung (Schattenbildung, global, Comprehensions, Sichtbarkeit von Klassenkörpern), Referenzfindung über alle Importstile, Korrektheit von Umbenennen/Verschieben/Löschen, generierten Importstil und die Garantien der Anwendungsphase ab: Erkennung veralteter Dateien, Syntaxvalidierung und Rollback.

Die stärkste Prüfung der Suite ist, dass das Tool seinen eigenen Quellcode refaktoriert – eine Funktion über die Implementierung und die Tests hinweg umbenennt und eine zwischen Modulen verschiebt – wonach die gesamte Suite weiterhin gegen die umgeschriebene Kopie besteht.

Anforderungen

Python 3.10+ (verwendet ast.alias-Positionsattribute). Nur Python-Quellcode.

Lizenz

MIT