Codebase Cartographer

MCP-сервер, который строит граф символов локального Python-репозитория на основе AST и выполняет проверяемые многофайловые рефакторинги в нём.

Большинство агентов кодинга рефакторят, ища строку и переписывая найденное. Такой подход не отличает вызов compute() от локальной переменной, которая случайно называется compute, и понятия не имеет, какие двенадцать файлов сломаются при переименовании. Этот сервер даёт модели настоящий индекс вместо этого: разрешённые по областям видимости ссылки, граф импортов и двухфазный протокол редактирования, который отказывается записывать то, что не может проверить.

Что он делает

Строит карту. Обходит репозиторий (учитывая .gitignore), разбирает каждый модуль и строит таблицу символов: функции, классы, методы и переменные уровня модуля, а также граф импортов между модулями.

Разрешает ссылки. Находит ссылки с помощью настоящего анализа областей видимости — цепочки LEGB, объявлений global и nonlocal, областей видимости генераторов, привязок walrus и правила, что тела классов невидимы для вложенных функций. Локальная переменная, затеняющая символ уровня модуля, не является ссылкой на него, и инструмент знает разницу.

Рефакторит. Переименовывает, перемещает и удаляет символы во всех файлах, которые их затрагивают — переписывая from x import y, import x + доступ к атрибуту x.y, псевдонимы as и записи __all__. Ничего не записывается, пока вы не примените план, для которого видели diff.

Related MCP server: MCP Python Code Navigation Server

Модель безопасности

Рефакторинг двухфазный, и первая фаза никогда не касается диска.

1. plan_rename_symbol / plan_move_symbol / plan_delete_symbol возвращают идентификатор плана, unified diff и список предупреждений. Для каждого затронутого файла записывается хэш содержимого.

2. apply_plan повторно проверяет эти хэши (прерываясь, если что-то изменилось на диске с момента планирования), строит новое содержимое для каждого файла, повторно разбирает каждый из них и отказывается записывать, если какой-либо файл окажется неразбираемым. Оригиналы копируются в .cartographer-backups/<plan_id>/. При сбое в середине записи все файлы откатываются.

Дополнительные ограждения: пути за пределами корня карты отклоняются; переименование метода требует явного allow_heuristic=true, потому что сопоставление атрибутов не может быть разрешено без вывода типов; удаление символа, у которого всё ещё есть ссылки, отклоняется, если не принудительно.

Что он не может видеть

У статического анализа есть жёсткая граница, и инструмент создан так, чтобы указывать, где эта граница, а не притворяться, что её нет.

find_dynamic_references сообщает о строковых литералах, совпадающих с именем символа — getattr(mod, "compute"), реестрах плагинов, строковых настройках с точками, таблицах точек входа — и обнаруживает импорты нативных модулей с подчёркиванием в начале. Эти предупреждения прикрепляются к каждому плану рефакторинга.

Это имеет конкретное значение. Переименование JSONDecodeError в копии пакета json из стандартной библиотеки корректно переписывает все 19 ссылок на Python и всё равно ломает пакет, потому что C-ускоритель _json разрешает это имя во время выполнения через C API. Никакой чисто Python-анализ не может проследить это. Инструмент помечает импорт нативного ускорителя и говорит вам проверить вручную.

Также невидимы: реэкспорты from x import * (сообщается как предупреждение), динамическое monkey-patching и ссылки из других языков или конфигурационных файлов.

Инструменты

Установка

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