ChangeAtlas

ChangeAtlas

ChangeAtlas shows which local files and tests may be affected by a Git change. It follows static imports and returns the file path behind every link, so you can inspect the evidence yourself. It runs on your machine, reads your repository, and does not send its contents to a service.

It is useful when you have changed a module and want a short, grounded list of places to check before committing. It does not decide whether a change is safe or whether a test covers a behavior.

Install

Requires Python 3.11 or newer and Git.

pip install mcp-changeatlas

Point it at the exact root of a Git repository:

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

For an MCP client, configure a stdio server with command mcp-changeatlas and arguments --root, the repository path, and serve. For example:

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

The four tools are repository_overview, analyze_changes, trace_file, and find_tests. The root is set by the person running the server and cannot be changed by a tool call.

The Docker image is for directory build checks and a self-contained demo. It analyzes the repository snapshot inside the image. To analyze your own work, install the package locally and set --root to your repository.

How it works

ChangeAtlas reads tracked Python, JavaScript, and TypeScript files and builds a local import graph. Python imports are parsed with the standard library AST. JS/TS relative import, export, and require links are found statically. It follows reverse links from a changed file to nearby modules and tests, up to a chosen depth. Results include the file chain that led to each suggestion.

analyze_changes compares the working tree, including staged changes, with a Git commit. include_untracked adds untracked file names. It never runs project code, test commands, package managers, or Git hooks. It resolves paths and rejects files that point outside the configured repository. File and result counts have fixed limits.

This first release resolves local Python imports and relative JS/TS imports. It cannot follow runtime imports, package aliases, monorepo path mappings, or non-code dependencies. Deleted and unsupported files are shown under unindexed_changes; an incomplete result is marked as such. A suggested test is a path through imports, not a coverage claim.

Development

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

Publishing

The package name and MCP Registry name are set in pyproject.toml, README.md, and server.json. Before the first PyPI release, create a pending trusted publisher for robyroro/mcp-changeatlas, workflow release.yml, environment pypi. Then publish a GitHub release tagged with the matching package version. The release workflow runs tests and publishes the wheel and source archive through PyPI's trusted publishing flow.

Once the exact version is visible on PyPI, run the Publish to MCP Registry GitHub Actions workflow. It validates server.json and publishes it with GitHub OIDC, following the Registry publisher guide. The registry is a separate publication step. A repository or PyPI release alone does not create a registry listing.

License

MIT