Codebase Cartographer

一个 MCP 服务器，可将本地 Python 仓库映射为基于 AST 的符号图，并对其执行经过验证的多文件重构。

大多数编码代理通过搜索字符串并重写找到的内容来进行重构。这种方法无法区分对 compute() 的调用与恰好名为 compute 的局部变量，也不知道重命名它时会破坏哪十二个文件。该服务器为模型提供了一个真正的索引：作用域解析的引用、导入图，以及一个两阶段编辑协议，该协议拒绝写入任何无法验证的内容。

功能

映射。 遍历仓库（遵循 .gitignore），解析每个模块，并构建函数、类、方法和模块级变量的符号表，以及模块之间的导入图。

解析。 使用真实的作用域分析查找引用——LEGB 链、global 和 nonlocal 声明、推导式作用域、海象运算符绑定，以及类体对嵌套函数不可见的规则。遮蔽模块级符号的局部变量不是对该符号的引用，该工具能区分这一点。

重构。 在所有涉及符号的文件中重命名、移动和删除符号——重写 from x import y、import x + x.y 属性访问、as 别名和 __all__ 条目。在您查看差异并应用计划之前，不会写入任何内容。

Related MCP server: MCP Python Code Navigation Server

安全模型

重构是两阶段的，第一阶段从不触碰磁盘。

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")、插件注册表、点分设置字符串、入口点表——并检测下划线前缀的原生模块导入。这些警告会附加到每个重构计划上。

这一点有具体的影响。在标准库 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