Codebase Cartographer

Un servidor MCP que mapea un repositorio Python local en un grafo de símbolos basado en AST y realiza refactorizaciones multi-archivo verificadas sobre él.

La mayoría de los agentes de código refactorizan buscando una cadena y reescribiendo lo que encuentran. Ese enfoque no puede distinguir una llamada a compute() de una variable local que casualmente se llama compute, y no tiene idea de qué doce archivos se rompen cuando la renombras. Este servidor le da al modelo un índice real en su lugar: referencias resueltas por ámbito, un grafo de importaciones y un protocolo de edición en dos fases que se niega a escribir cualquier cosa que no pueda verificar.

Qué hace

Mapea. Recorre el repositorio (respetando .gitignore), analiza cada módulo y construye una tabla de símbolos de funciones, clases, métodos y variables a nivel de módulo, además del grafo de importaciones entre módulos.

Resuelve. Encuentra referencias usando análisis de ámbito real: la cadena LEGB, declaraciones global y nonlocal, ámbitos de comprensiones, vinculaciones walrus y la regla de que los cuerpos de clase son invisibles para funciones anidadas. Una variable local que sombrea un símbolo a nivel de módulo no es una referencia a él, y la herramienta conoce la diferencia.

Refactoriza. Renombra, mueve y elimina símbolos en todos los archivos que los tocan: reescribe from x import y, import x + acceso a atributo x.y, alias as y entradas __all__. Nada se escribe hasta que apliques un plan del que hayas visto el diff.

Related MCP server: MCP Python Code Navigation Server

Modelo de seguridad

La refactorización es en dos fases, y la primera fase nunca toca el disco.

1. plan_rename_symbol / plan_move_symbol / plan_delete_symbol devuelven un id de plan, un diff unificado y una lista de advertencias. Se registra el hash del contenido de cada archivo tocado.

2. apply_plan vuelve a comprobar esos hashes (abortando si algo cambió en disco desde la planificación), construye el nuevo contenido para cada archivo, re-analiza cada uno y se niega a escribir si algún archivo terminaría siendo no analizable. Los originales se copian a .cartographer-backups/<plan_id>/. Un fallo a mitad de escritura revierte todos los archivos.

Más salvaguardas: se rechazan rutas fuera de la raíz mapeada; renombrar un método requiere un allow_heuristic=true explícito porque la coincidencia de atributos no se puede resolver sin inferencia de tipos; eliminar un símbolo que aún tiene referencias se rechaza a menos que se fuerce.

Lo que no puede ver

El análisis estático tiene un límite duro, y la herramienta está construida para decir dónde está ese límite en lugar de fingir que no existe.

find_dynamic_references informa literales de cadena que coinciden con un nombre de símbolo — getattr(mod, "compute"), registros de plugins, cadenas de configuración con puntos, tablas de puntos de entrada — y detecta importaciones de módulos nativos con prefijo de subrayado. Esas advertencias se adjuntan a cada plan de refactorización.

Esto importa concretamente. Renombrar JSONDecodeError en una copia del paquete json de la biblioteca estándar reescribe correctamente las 19 referencias Python y aun así rompe el paquete, porque el acelerador C _json resuelve ese nombre en tiempo de ejecución a través de la API C. Ningún análisis Python puro puede seguir eso. La herramienta marca la importación del acelerador nativo y te dice que lo compruebes a mano.

También invisible: re-exportaciones from x import * (reportadas como advertencia), parcheo de monos en tiempo de ejecución y referencias desde otros lenguajes o archivos de configuración.

Herramientas

Instalación

pip install -e .

Regístralo con un cliente MCP:

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

CARTOGRAPHER_ROOT es solo el valor predeterminado para map_repository; la herramienta también acepta un argumento root explícito.

Una sesión típica

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/

Desarrollo

pip install -e ".[dev]"
pytest

65 pruebas cubren la resolución de ámbitos (sombreado, global, comprensiones, visibilidad de cuerpos de clase), la búsqueda de referencias en todos los estilos de importación, la corrección de renombrar/mover/eliminar, el estilo de importaciones generadas y las garantías de la fase de aplicación: detección de archivos obsoletos, validación de sintaxis y reversión.

La comprobación más fuerte de la suite es que la herramienta refactoriza su propio código fuente: renombra una función en la implementación y las pruebas, y mueve una entre módulos, después de lo cual la suite completa sigue pasando contra la copia reescrita.

Requisitos

Python 3.10+ (usa atributos de posición de ast.alias). Solo código fuente Python.

Licencia

MIT