# Atlas Context Router Rs

> Graph-aware code context for CLI and MCP workflows

- **Type:** MCP server
- **Install:** `agentstack add mcp-ffimnsr-atlas-context-router-rs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ffimnsr](https://agentstack.voostack.com/s/ffimnsr)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ffimnsr](https://github.com/ffimnsr)
- **Source:** https://github.com/ffimnsr/atlas-context-router-rs
- **Website:** https://github.com/ffimnsr/atlas-context-router-rs/wiki

## Install

```sh
agentstack add mcp-ffimnsr-atlas-context-router-rs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Atlas Context Router

[](https://github.com/ffimnsr/atlas-context-router-rs/actions/workflows/ci.yml)
[](https://github.com/ffimnsr/atlas-context-router-rs/releases)
[](LICENSE)

```text
     _  _____ _      _   ___
    / \|_   _| |    / \ / __|
   / _ \ | | | |__ / _ \\__ \
  /_/ \_\|_| |____/_/ \_\___/

  graph-aware code context for CLI and MCP workflows
```

Atlas scans repository code, builds graph structure, stores it in SQLite, and serves graph-aware context to both CLI workflows and MCP-based coding agents.

| Area | What Atlas gives you |
|------|----------------------|
| Graph build | tracked-file scan, parse, persist into `.atlas/worldtree.db` |
| Incremental update | rebuild only from git or working-tree changes |
| Search and impact | symbol lookup, call/risk traversal, review context |
| Agent tooling | MCP broker/daemon server, install helpers, repo hooks, editor integration |

Supported languages in current build:

- Rust
- Go
- Python
- JavaScript
- TypeScript

## Install

### Latest release

Download installer from latest GitHub release assets:

```bash
curl -fsSLO https://github.com/ffimnsr/atlas-context-router-rs/releases/latest/download/install.sh
curl -fsSLO https://github.com/ffimnsr/atlas-context-router-rs/releases/latest/download/install.sh.sha256

sha256sum -c install.sh.sha256 2>/dev/null || shasum -a 256 -c install.sh.sha256
sh install.sh
```

Release notes:

- `install.sh.sha256` is not stored in repo root; release workflow generates it and publishes it as a release asset
- `install.sh.sha256` ships with each release
- `install.sh` verifies downloaded Atlas archive checksums before install
- release archives are published for Linux musl, macOS x86_64, and macOS arm64

If latest-release URLs are not available yet, use one of these fallback paths:

```bash
cargo install --path packages/atlas-cli
```

Maintainer-only raw installer fallback:

```bash
curl -fsSLO https://raw.githubusercontent.com/ffimnsr/atlas-context-router-rs/main/install.sh
sh install.sh
```

Raw `main` installer is not release-pinned. Prefer release assets once first tagged release exists.

### Build from source

```bash
cargo install --path packages/atlas-cli
```

### Run from workspace

```bash
cargo run -p atlas-cli -- --help
```

### Build container image

Build the multi-stage container image from the repository root:

```bash
podman build -f Containerfile -t atlas .
```

Docker works as well:

```bash
docker build -f Containerfile -t atlas .
```

The default builder and runtime images in [Containerfile](Containerfile) are pinned to immutable Chainguard digests.
Override them explicitly if you need newer base images during maintenance:

```bash
podman build \
  --build-arg RUST_IMAGE=cgr.dev/chainguard/rust:latest-dev \
  --build-arg GIT_RUNTIME_IMAGE=cgr.dev/chainguard/git:latest-glibc \
  -f Containerfile \
  -t atlas .
```

Refresh the pinned digests in [Containerfile](Containerfile) to the latest upstream tags:

```bash
scripts/update-containerfile-images.sh
```

Preview the resolved references without editing files:

```bash
scripts/update-containerfile-images.sh --dry-run
```

Run Atlas against the current repository by mounting the workspace into the container:

```bash
podman run --rm -it \
  -v "$PWD":/work \
  -w /work \
  atlas status
```

Atlas shells out to `git`, so the runtime stage uses a minimal Git-capable base image instead of a shell-free static runtime.

## Quick Start

Inside any git repository:

```bash
atlas init --profile standard
atlas build
atlas status
atlas debug-config
atlas query "symbol_name"
```

Repair local Atlas state without rebuilding graph data:

```bash
atlas migrate
atlas config show
atlas selfupdate
```

Review recent work against mainline:

```bash
atlas update --base origin/main
atlas detect-changes --base origin/main
atlas impact --base origin/main
atlas review-context --base origin/main
atlas review-context --base origin/main --format markdown
```

## Benchmarks

Local smoke benchmark on this repository, using `target/release/atlas` with a
prebuilt `.atlas/worldtree.db` graph. Host: Linux 6.19, AMD Ryzen 5 5600X,
12 logical CPUs. Numbers are best read as order-of-magnitude guidance, not a
portable guarantee.

Symbol lookup for `WatchRunner`, 30 warm runs:

| Tool | Command shape | Avg wall time | Output size |
|------|---------------|---------------|-------------|
| `grep` | `grep -RIn --include='*.rs' WatchRunner .` with build dirs excluded | 6.8 ms | 1.3 KiB |
| `rg` | `rg -n WatchRunner --glob '*.rs'` | 6.8 ms | 1.3 KiB |
| `atlas query` | `atlas --json query WatchRunner --limit 20` | 9.1 ms | 20.4 KiB |

Context gathering for `WatchRunner`, comparing raw nearby text against bounded
graph context:

| Tool | Command shape | Avg wall time | Context payload | Compression vs raw text |
|------|---------------|---------------|-----------------|-------------------------|
| `grep` | related-symbol regex with `-C 8` over known watch files | 3.3 ms | 47.8 KiB | baseline |
| `rg` | related-symbol regex with `-C 8` over known watch files | 5.6 ms | 47.8 KiB | baseline |
| `atlas context` | `atlas --json context WatchRunner --max-nodes 20 --max-edges 20 --max-files 10` | 35.5 ms | 3.1 KiB | 93.5% smaller |

Use `grep` or `rg` for raw text search. Use Atlas when caller/callee links,
impact, review context, or MCP token budget matter more than the fastest line
scan.

## Project Policy and Maintenance

Repository workflow and support docs live at the root:

- [CONTRIBUTING.md](CONTRIBUTING.md)
- [SECURITY.md](SECURITY.md)
- [SUPPORT.md](SUPPORT.md)
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- [CHANGELOG.md](CHANGELOG.md)
- [docs/error_codes.md](docs/error_codes.md)

GitHub triage defaults also live in `.github/`:

- `.github/CODEOWNERS`
- `.github/PULL_REQUEST_TEMPLATE.md`
- `.github/ISSUE_TEMPLATE/`

## LLM Agent Setup

Atlas can install MCP configuration for popular AI coding tools and add repo hooks so agents start with graph-aware context.

`atlas serve` remains a stdio MCP entrypoint for editors and agents. Repo-scoped installs now pin only `--repo`, while user/global installs stay portable with `type = "stdio"`, `command = "atlas"`, `args = ["serve"]`. When no repo is pinned, Atlas resolves repo root from MCP client `roots/list` and derives DB path as `REPO_ROOT/.atlas/worldtree.db`; if roots are unavailable it falls back to launch `cwd`.

If an editor MCP client is incompatible with broker/daemon indirection, use `atlas serve --direct-stdio` to run MCP directly in launched process with no relay layer.

### GitHub Copilot

```bash
atlas install --platform copilot
atlas build
```

Writes MCP config under `.vscode/mcp.json`.

### Claude Code

```bash
atlas install --platform claude
atlas build
```

Writes MCP config under `.mcp.json`.

### Codex

```bash
atlas install --platform codex
atlas build
```

Writes Codex MCP entry into `.codex/config.toml`.

### Auto-detect installed tools

```bash
atlas install
```

### Preview without writing files

```bash
atlas install --dry-run
```

`atlas install` will:

- write MCP server config for GitHub Copilot, Claude Code, or Codex
- install git hooks for `pre-commit`, `post-checkout`, `post-merge`, and `post-rewrite`
- inject graph-first instructions into platform-relevant agent files (`AGENTS.md` for Copilot/Codex, `CLAUDE.md` for Claude)

Hook behavior:

- `pre-commit` prints full change summary
- `post-checkout`, `post-merge`, and `post-rewrite` use brief output

After install, restart your editor or coding tool, then run:

```bash
atlas build
```

Repo-local MCP coordination state lives under `.atlas/mcp//`:

- `mcp.instance.lock`
- `mcp.instance.json`
- `mcp.sock` on Unix

`instance-id` is derived from canonical repo root plus canonical DB path, so same repo with different DBs can run separate daemons while same repo plus same DB reuses one backend.

## Canonical Path Migration

Atlas treats repo-relative paths as canonical identity for persisted graph rows, content source IDs, chunk seeds, and session file references.

Shared path normalization now happens in `atlas-repo`: separators become `/`, Unicode folds to NFC, Windows identities fold case, and CLI/watch boundary absolute paths prefer filesystem-canonical spelling so case-insensitive filesystems do not drift. Repo scan skips symlinks and dedupes canonical submodule roots to guard loop topologies.

Audit coverage:

- graph store persistence and lookup keys go through canonical `files.path` / `nodes.file_path` identity before reuse or persistence
- file-hash reuse in full and incremental build paths uses the same canonical graph file keys
- content `source_id` and `chunk_id` seeds require canonical repo-path identity for file-backed artifacts
- session payload normalization and resume snapshot file references canonicalize repo-file paths before persistence
- MCP explicit `files` inputs canonicalize repo-relative paths before change-source resolution
- future sidecar/cache/index keys, including parser tree-cache entries, must reuse the same canonical repo-path spelling

If `atlas doctor` or `atlas db-check` reports `noncanonical_path_rows`, rebuild from clean canonical inputs instead of trying to rewrite stale rows in place:

```bash
atlas purge-noncanonical
atlas build
```

`atlas purge-noncanonical` removes repo-local `context.db` and `session.db` state, keeps `worldtree.db`, and leaves rebuild plus session bootstrap explicit.

## Shell Completion

Generate completion script to stdout:

```bash
atlas completions bash
atlas completions zsh
atlas completions fish
atlas completions powershell
```

Example for Bash:

```bash
atlas completions bash > ~/.local/share/bash-completion/completions/atlas
```

Example for Zsh:

```bash
mkdir -p ~/.zfunc
atlas completions zsh > ~/.zfunc/_atlas
```

## Typical Workflows

### Bootstrap graph for a repo

```bash
atlas init
atlas build
atlas status
```

### Review branch against main

```bash
atlas update --base origin/main
atlas detect-changes --base origin/main
atlas impact --base origin/main
atlas review-context --base origin/main
```

### Install editor and hook integration

```bash
atlas install --platform copilot
atlas build
```

## Common Commands

Initialize repository state:

```bash
atlas init
```

Full rebuild:

```bash
atlas build
```

Incremental update from working tree or git base:

```bash
atlas update
atlas update --base origin/main
atlas update --staged
```

Show graph status:

```bash
atlas status
atlas status --base origin/main
```

Search graph nodes:

```bash
atlas query "AuthService"
atlas query "login" --kind function --language rust
atlas query "router" --subpath packages/atlas-cli --expand --expand-hops 2

# regex filter: text is the pattern, matched against name/qualified_name via SQL UDF
atlas query "^handle_[a-z]+" --regex
atlas query "(body|node)" --regex --kind function
```

Inspect changed files:

```bash
atlas detect-changes
atlas detect-changes --base origin/main
atlas detect-changes --staged
```

Compute blast radius:

```bash
atlas impact --base origin/main
atlas impact --files packages/atlas-cli/src/commands.rs
```

Assemble review context:

```bash
atlas review-context --base origin/main
atlas review-context --base origin/main --format markdown
atlas review-context --files packages/atlas-cli/src/install.rs
```

Explain changed code with impact and risk summary:

```bash
atlas explain-change --base origin/main
atlas explain-change --files packages/atlas-cli/src/commands.rs
```

Dead-code scan and deterministic rename preview:

```bash
atlas analyze dead-code --subpath packages/atlas-cli
atlas refactor rename --symbol src/lib.rs::fn::helper --to helper_renamed --dry-run
```

Run MCP server over stdio:

```bash
atlas serve
```

Health and integrity checks:

```bash
atlas doctor
atlas db-check
```

## Context Engine (`atlas context`)

`atlas context` builds bounded, machine-readable context around a symbol, file, or change-set.

Common forms:

```bash
atlas context "AuthService"
atlas context "who calls handle_request"
atlas context --file src/auth.rs
atlas context --files src/auth.rs src/session.rs --intent impact
atlas --json context --files src/auth.rs src/session.rs
```

Key knobs:

- `--intent`: `symbol`, `file`, `review`, `impact`, `usage_lookup`, `refactor_safety`, `dead_code_check`, `rename_preview`, `dependency_removal`
- limits: `--max-nodes`, `--max-edges`, `--max-files`, `--depth`
- extra detail: `--code-spans`, `--tests`, `--imports`, `--neighbors`

Default limits: 100 nodes, 100 edges, 20 files, depth 2.

JSON output uses `atlas_cli.v1` and returns request metadata, selected nodes and edges, file spans, truncation info, and optional ambiguity candidates. If target is ambiguous, `ambiguity` is populated instead of direct node results. `atlas review-context` remains available as focused shortcut for review-heavy workflows.

Contract references:

- [Output stability policy](docs/contracts/output-stability.md)
- [TOON contract](docs/contracts/atlas_toon.v1.md)
- `schemas/atlas_cli.v1/*.schema.json`

## Output Modes

Most user-facing commands support machine-readable output:

```bash
atlas --json status
atlas --json detect-changes --base origin/main
atlas --json install --platform claude
```

## Files Atlas Writes

- `.atlas/config.toml`
- `.atlas/worldtree.db`
- `.mcp.json` for Claude Code installs
- `.vscode/mcp.json` for GitHub Copilot installs
- `.codex/config.toml` entry for Codex installs
- `.git/hooks/*` for installed git hooks

## Insights

Atlas also exposes deterministic insight reports through CLI:

```bash
atlas insights architecture
atlas insights metrics --limit 20
atlas insights risk src/service.rs::fn::compute
atlas insights patterns --limit 20
atlas insights large-functions --threshold 80 --mode large-or-complex
atlas insights complex-functions --complexity-threshold 15
atlas --json insights metrics
```

Thresholds and layer rules live under `.atlas/config.toml`:

```toml
[insights]
large_function_loc = 80
high_fan_in = 20
high_fan_out = 10
high_coupling = 15
deep_chain_length = 6
repeated_call_chain_min_length = 3
risk_medium_threshold = 35.0
risk_high_threshold = 70.0

[[insights.layer_rules]]
name = "api"
path_prefixes = ["src/api"]
module_prefixes = []

[[insights.layer_rules]]
name = "domain"
path_prefixes = ["src/domain"]
module_prefixes = []
```

## MCP Tools

The MCP server (`atlas serve`) exposes these tools to agents:

| Tool | Description |
|------|-------------|
| `list_graph_stats` | Node/edge counts and language breakdown |
| `query_graph` | Keyword search with optional `regex` SQL-UDF filter; returns compact symbol list |
| `batch_query_graph` | Run up to 20 `query_graph` searches in a single round-trip |
| `search_files` | File-path discovery for config, templates, SQL, Markdown, and other non-code assets |
| `search_content` | Literal or regex content search outside graph-symbol lookup |
| `read_file_excerpt` | Repo-scoped file excerpt reads by line range or line-with-context |
| `get_docs_section` | Markdown section lookup by heading path/slug or line number |
| `read_file_around_match` | Grouped snippets around literal or regex matches in one file |
| `search_templates` | Discover HTML, Jinja, Handlebars, Tera, and related template files |
| `search_text_assets` | Discover SQL, config, env, and prompt files |
| `broker_status` | Lightweight broker liveness probe: PID, uptime, version |
| `status` | Compact graph health summary with machine-readable failure state |
| `doctor` | Full repo health checks: git, config, DB, build, and retrieval index |
| `db_check` | SQLite integrity plus orphan-node and dangling-edge scan |
| `debug_graph` | Graph internals: node/edge kinds, top files, and anomalies |
| `explain_query` | Explain how `query_graph` will tokenize and execute a request |
| `resolve_symbol` | Resolve a symbol or QN alias to canonical `qualified_name` |
| `analyze_architecture` | Deterministic architecture report with cycles, layers, an

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ffimnsr](https://github.com/ffimnsr)
- **Source:** [ffimnsr/atlas-context-router-rs](https://github.com/ffimnsr/atlas-context-router-rs)
- **License:** MIT
- **Homepage:** https://github.com/ffimnsr/atlas-context-router-rs/wiki

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ffimnsr-atlas-context-router-rs
- Seller: https://agentstack.voostack.com/s/ffimnsr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.