ChangeAtlas

ChangeAtlas

ChangeAtlas 展示 Git 变更可能影响的本地文件和测试。它会追踪静态导入，并返回每个链接背后的文件路径，方便你自行检查依据。它在你的计算机上运行，读取你的代码库，不会将其中的内容发送到任何服务。

如果你修改了某个模块，并希望在提交前快速获得一份有依据的检查清单，它会很有用。它不会判断变更是否安全，也不会判断测试是否覆盖某种行为。

安装

需要 Python 3.11 或更高版本，以及 Git。

pip install mcp-changeatlas

将其指向 Git 代码库的确切根目录：

mcp-changeatlas --root /path/to/repo overview
mcp-changeatlas --root /path/to/repo changes --base HEAD
mcp-changeatlas --root /path/to/repo trace src/app/core.py
mcp-changeatlas --root /path/to/repo tests src/app/core.py

对于 MCP 客户端，请配置一个 stdio 服务，命令为 mcp-changeatlas，参数为 --root、代码库路径和 serve。例如：

{
  "mcpServers": {
    "changeatlas": {
      "command": "mcp-changeatlas",
      "args": ["--root", "/path/to/repo", "serve"]
    }
  }
}

四个工具分别是 repository_overview、analyze_changes、trace_file 和 find_tests。根目录由运行服务的人员设置，工具调用无法更改它。

Docker 镜像用于目录构建检查和独立演示。它会分析镜像内的代码库快照。若要分析自己的工作，请在本地安装此软件包，并将 --root 设为你的代码库路径。

工作原理

ChangeAtlas 会读取受 Git 跟踪的 Python、JavaScript 和 TypeScript 文件，并构建本地导入图。Python 导入通过标准库 AST 解析。JS/TS 相对导入、导出和 require 链接则通过静态分析发现。它会沿着指向变更文件的反向链接，按所选深度追踪附近的模块和测试。结果包含指向每条建议的文件链。

analyze_changes 会将工作树（包括已暂存的变更）与某个 Git 提交进行比较。include_untracked 会添加未跟踪文件的名称。它绝不会运行项目代码、测试命令、软件包管理器或 Git 钩子。它会解析路径，并拒绝指向已配置代码库之外的文件。文件数量和结果数量均有固定上限。

此首个版本可以解析本地 Python 导入和相对 JS/TS 导入。它无法追踪运行时导入、软件包别名、单体仓库路径映射或非代码依赖项。已删除和不受支持的文件会列在 unindexed_changes 下；结果不完整时会明确标记。建议的测试是导入路径上的测试，而非覆盖情况的保证。

开发

python -m venv .venv
python -m pip install -e ".[dev]"
pytest
ruff check .
mypy
python -m build

发布

软件包名称和 MCP Registry 名称设置在 pyproject.toml、README.md 和 server.json 中。首次发布到 PyPI 前，为 robyroro/mcp-changeatlas 创建一个待处理的可信发布者，工作流设为 release.yml，环境设为 pypi。然后创建一个带有匹配软件包版本标签的 GitHub Release。发布工作流会运行测试，并通过 PyPI 的可信发布流程发布 wheel 和源代码归档。

确认 PyPI 上显示了确切版本后，运行 GitHub Actions 工作流 Publish to MCP Registry。该工作流会验证 server.json，并使用 GitHub OIDC 发布，具体遵循 Registry 发布者指南。Registry 发布是一个独立步骤。仅发布代码库或 PyPI 软件包，都不会创建 Registry 条目。

许可证

MIT