# code-atlas

**Multi-language code intelligence MCP server** — gives Claude Code (and any MCP client) a structured view of your codebase instead of raw text: symbol search, file outlines, AST pattern queries, cross-file references, call/type hierarchies, import graphs, change-impact analysis with affected-test detection, web-framework route maps (Express/NestJS/Fastify/FastAPI/Flask/Django), Mermaid diagrams, precise LSP-backed answers, local-embedding semantic search, and game-engine asset understanding (Godot, Unity, Unreal). 25 languages indexed.

Instead of grepping and reading whole files, the model asks questions like *"map this repo"*, *"outline this file"*, *"who calls `parseConfig`?"*, *"how does the request handler reach the DB layer?"*, *"what changes whenever this file changes?"* — and gets compact, token-efficient answers backed by a persistent tree-sitter index.

Every answer is budgeted: tools take a `max_tokens` cap, and a clamped response returns a cursor you can pass back to continue rather than re-asking with a bigger budget.

> **Status: released** (npm `@lusiem/code-atlas`, MCP registry `io.github.lusiem/code-atlas`). 25 languages, 32 tools, LSP-exact answers with a structural floor, engine adapters, and an agent-workflow layer (`repo_map`, `context_pack`, `verify_changes`) built for token economy. Validated at 19k files / 6.3M LOC.

## How it works

```
your repo ──scan (gitignore-aware)──> tree-sitter parse ──> SQLite index (symbols, imports,
                                                             occurrences, call/type edges, FTS5)
                                                                   │
Claude Code ◄──────────── MCP tools over stdio ────────────────────┘
```

- **Persistent index** at `<repo>/.code-atlas/index.db` (self-gitignored), incrementally refreshed by content hash.
- **Live** — a gitignore-aware file watcher reindexes saves within a debounce beat and re-resolves only the affected files (`--no-watch` or `"watch": false` to disable).
- **Zero config** — point it at a repo root and it works. Optional `code-atlas.json` for include/exclude tweaks.
- **Everything local** — your code never leaves your machine.

## Install & use with Claude Code

```sh
claude mcp add code-atlas -- npx -y @lusiem/code-atlas serve
```

Or from a clone:

```sh
git clone https://github.com/lusiem/code-atlas && cd code-atlas
npm install && npm run build
claude mcp add code-atlas -- node /path/to/code-atlas/dist/index.js serve
```

The server indexes the current working directory; pass `--root <path>` to override.

### CLI

```sh
node dist/index.js index [--root <path>]              # one-shot index build (debugging / warm-up)
node dist/index.js serve [--root <path>] [--no-watch] [--no-lsp] [--no-embeddings] [--no-download]
                                                      # MCP server on stdio
```

## Tools

Full reference with example outputs: [docs/tools.md](docs/tools.md).

| Tool | What it answers |
|---|---|
| `repo_map` | **What is this repo and where do I start?** Annotated directory tree with import fan-in/fan-out (layering at a glance), entry points, importance-ranked key symbols with the reason each ranks, and the third-party dependency inventory — one budgeted call instead of a grep sweep. `path_prefix`/`depth` to zoom. |
| `project_overview` | The cheap version: languages, sizes, layout, index freshness. |
| `search_symbols` | Where is *X* defined? FTS + fuzzy over names and doc comments, filterable by kind/language/path. |
| `search_content` | Where does this *text* appear? String literals, error messages, env vars, config keys, TODOs — and the only tool that sees non-code files (md/json/yaml/toml/sql/Dockerfile/CI). The index proposes candidates, the disk verifies them, so a hit is never stale. |
| `semantic_search` | *"Where is retry backoff implemented?"* — natural-language search, hybrid keyword+embedding ranking, fully local. |
| `get_file_outline` | What's in this file? Hierarchical signatures without reading source — over budget it sheds nesting depth rather than tail lines, so every top-level symbol survives. Pass a **directory** for a package's public API surface in one call. |
| `get_symbol_info` | Everything about one symbol (by id, position, or name) incl. docs and source. |
| `context_pack` | One-call, token-budgeted briefing on a symbol: source, outline, callers/callees, types, route, related tests — instead of six lookups. Sections that don't fit the budget are named. |
| `batch_symbols` | Up to 50 `#id`s resolved to compact one-liners in a single call. |
| `ast_query` | Raw tree-sitter S-expression queries — structural search regex can't do. |
| `find_references` | Who uses this symbol? Exact (LSP) when available, else resolved usages first, name-matches as candidates. |
| `go_to_definition` | Definition of the identifier at a position. LSP-exact with index fallback. |
| `call_hierarchy` | Who calls this / what does it call, as a tree. `[lsp 1.00]` edges when a language server is running. |
| `type_hierarchy` | Supertypes and subtypes over extends/implements edges. |
| `get_dependencies` | File import graph, both directions (imports / imported-by). |
| `trace_path` | Shortest call chain between two symbols. |
| `change_impact` | Blast radius of a change: transitive callers + import reachability, affected **test files** first. Target a symbol, a file list, or nothing — no args analyzes the uncommitted git diff (hunk-level: only symbols you actually touched seed the traversal). Affected route handlers are tagged `[ROUTE GET /users/:id]`. |
| `verify_changes` | Post-edit structural check against git HEAD: imports that stopped resolving, removed exports other files still reference, signature changes with live callers. `change_impact` predicts; this confirms. |
| `tests_for_symbol` | Which tests exercise this symbol? Reverse graph walk to test files, naming the test case; import-chain-only hits reported as a weaker signal. |
| `find_similar_code` | *"Does a helper for this already exist?"* — near-duplicate search over the local embedding vectors, with a text-similarity fallback while coverage builds. |
| `find_dead_code` | Zero-reference symbols after entry-point/route/lifecycle exclusions, confidence-hedged (`possibly dead` when a same-name usage exists anywhere); unused exports listed separately. |
| `hotspots` | Churn × size risk ranking, answered from the cached commit history. |
| `change_coupling` | Which files historically change together with this one — **the coupling a structural index cannot see** (config, fixtures, docs, string-keyed dispatch). Directional confidence, and files with no import edge are flagged. |
| `symbol_history` | Why does this look like this, and who do I ask? `git log -L` over the symbol's line span: sha, date, author, subject. |
| `list_routes` | Web-framework routes across the workspace — Express, Fastify, NestJS, FastAPI, Flask, Django, plus file-based routing for Next.js, SvelteKit, Nuxt, and Remix — each linked to its handler symbol. |
| `find_route` | *"Which code serves `GET /api/users/7`?"* — matches a concrete URL against indexed route patterns (`:id`, `{id}`, `<int:pk>` are wildcards) and returns the handler. |
| `generate_diagram` | Mermaid diagrams of the above graphs: import graph (file or directory level), call graph around a symbol, type hierarchy, call path — paste straight into GitHub markdown or docs. |
| `get_scene_structure` | Godot scene node tree with attached scripts, instanced sub-scenes, and signal connections (handlers resolved to symbols). |
| `find_asset_references` | Which scenes/prefabs/Blueprints use this script, asset, or handler? Reverse lookup across Godot res:// paths, Unity GUIDs (via .meta), and Unreal modules + /Game/ Blueprint paths. |
| `search_reflection` | All `UPROPERTY(Replicated)`, `[SerializeField]`, `@export` vars, signals — engine reflection markers across the workspace. |
| `index_status` / `reindex` | Index health and manual refresh. |

Cross-file answers are **LSP-first with a structural floor**: when a language server is available
(found on PATH or auto-acquired into a per-user cache), references/definitions/hover/call
hierarchies are exact and tagged `lsp`; everywhere else, heuristic import/name resolution answers
with a confidence score per edge. Servers: typescript-language-server + pyright (npm), gopls
(go install), rust-analyzer + clangd (pinned, SHA-256-verified release binaries), Eclipse JDT LS
for Java (needs a Java 21+ runtime — detected via PATH/JAVA_HOME), kotlin-language-server (needs
any JRE), and csharp-ls for C# (needs the .NET SDK; installed as a dotnet tool — deliberately not
Microsoft's Roslyn LSP, whose license is VS-only). GDScript attaches to the Godot editor's
built-in language server (TCP 127.0.0.1:6005, override with `CODE_ATLAS_GODOT_LSP_PORT`)
whenever the editor has the project open — close the editor and answers fall back to structural,
reopen it and the next query reattaches. Missing runtimes degrade that language to
structural, reported honestly in `index_status`. A first-time acquisition (download + boot) never
blocks a query: tools wait up to 8 s, then answer structurally while the server finishes starting.
Disable with `--no-lsp`; disable auto-download with `--no-download`.

**Semantic search** embeds every function/class (signature + doc + body) with a code-tuned local
model — `jinaai/jina-embeddings-v2-base-code`, quantized ONNX — and fuses cosine similarity with
BM25 keyword rank. Everything stays on your machine. The ONNX runtime (~220 MB) and model
(~150 MB) are **not** part of this package: they download to the per-user cache the first time you
call `semantic_search`, never at install, and structural tools never wait on them. Until coverage
completes, results are keyword-weighted and say so. Embedding a 60k-symbol repo takes ~15 minutes
of background time, once; after that only edited symbols re-embed. `"embeddings": {"model":
"fast"}` swaps in a 4× faster general-purpose model; `--no-embeddings` turns the layer off.

## Languages

**Indexing today (25):** TypeScript, TSX, JavaScript, Python, C, C++, Rust, Go, Java, Kotlin, C#,
GDScript, PHP, Ruby, Lua, Solidity, Zig, Nix, Swift, Scala, Dart, Terraform/HCL, Pascal/Delphi,
Vue, Svelte.

Vue and Svelte single-file components index the `<script>` blocks (all of them, `<script setup>`
included) at their true file line numbers; component imports resolve, so `.vue`/`.svelte`
dependency graphs work in `get_dependencies` and `change_impact`. Terraform maps blocks to
symbols (`resource "aws_s3_bucket" "logs"` is searchable by either label) and resolves local
`module` sources as imports. Languages beyond the LSP-covered core answer structurally with
confidence-scored edges — same contract as everywhere else.

**Test-file awareness:** every indexed file is classified by per-language path conventions
(`*.test.ts`, `test_*.py`, `*_test.go`, `src/test/`, `*_spec.rb`, foundry `.t.sol`, …) — this
powers `change_impact`'s affected-test reporting. Inline test blocks (Rust `#[cfg(test)]`, Zig
`test`) are not path-classifiable and stay invisible by design.

**Game engines:** engine assets index alongside code — Godot `.tscn`/`.tres` scenes (node trees,
script attachments, signal connections, autoloads; `res://` resolved per `project.godot`, monorepos
of many projects included), Unity `.unity`/`.prefab`/`.asset` + `.meta` GUID maps (MonoBehaviour →
C# class links, serialized references), and Unreal `.uproject`/`.uplugin`/`Build.cs` module graphs
plus indexed reflection macros: `UCLASS`/`USTRUCT`/`UFUNCTION`/`UPROPERTY` specifiers attach to the
symbol they annotate (searchable, shown in `get_symbol_info`), and dllexport macros
(`class MYGAME_API AMyActor`) no longer break C++ class extraction.

**Unreal Blueprints (`.uasset`/`.umap`):** binary editor packages are parsed natively (package
summary, name/import/export tables, asset-registry tags, and bounded tagged-property reads — no
Unreal installation needed). Blueprints surface their functions, event dispatchers, and member
variables as searchable symbols (`search_symbols kind:event_dispatcher`, `lang:uasset`), a
`get_file_outline` per asset, graph-node comments in full-text search, and asset/`/Game/`-path +
parent-class + called-function references in `find_asset_references` (including
"who handles `ReceiveBeginPlay`" via `handles_event`). Blueprint→C++ links (parent classes via
Unreal's `A`/`U`/`F` naming, called `UFUNCTION`s) materialize as confidence-scored
`provenance: engine` edges, lighting up `type_hierarchy`, `call_hierarchy`, and `change_impact`.
Uncooked (editor) assets are the target — validated against a real UE 5.6 project (1,763/1,764
assets parsing, save vintages from UE 4.25 through 5.6); cooked/marketplace packages are detected
and skipped with a recorded reason. Binary assets are capped by `maxAssetFileBytes` (default 64 MB) and
change-gated by size+mtime so warm sweeps never re-read them. Godot binary `.scn` remains out of
scope.

## Roadmap

1. ~~Structural core: scanner, SQLite+FTS5 index, TS/JS/Python extractors, first 6 tools~~ ✅
2. ~~All 11 language extractors, cross-file import resolution, call graph (`find_references`, `call_hierarchy`, `trace_path`)~~ ✅
3. ~~File watcher + incremental reindexing (scoped re-resolution, schema migrations)~~ ✅
4. ~~LSP layer (auto-acquired ts-ls/pyright/gopls; checksum-pinned rust-analyzer/clangd binaries; JDT LS/kotlin-language-server/csharp-ls with JRE/.NET detection; precise references/definitions/hover/call hierarchy with graceful fallback)~~ ✅
5. ~~Local-embedding semantic search (`semantic_search`, hybrid BM25+vector reciprocal-rank fusion, lazy model download, incremental re-embedding)~~ ✅
6. ~~Game-engine adapters: GDScript grammar (vendored wasm build), Godot scenes/autoloads, Unity prefabs/GUIDs, Unreal module graph + reflection search, Godot editor LSP attach (TCP 6005, nightly-tested against a real editor)~~ ✅
7. ~~Docs, benchmarks in CI (cold index 157k LOC ≈ 5 s, warm queries p95 < 10 ms), cross-platform CI, npm pack smoke~~ ✅ — npm publish + MCP registry submission pending
8. ~~Competitive push: `change_impact` (blast radius + affected tests, git-diff mode), web-framework route indexing (`list_routes`/`find_route`), 13 more languages incl. Vue/Svelte SFCs~~ ✅
9. ~~Agent-workflow release (0.4.0): `context_pack` (token-budgeted one-call briefings), `verify_changes` (post-edit check vs git HEAD), `tests_for_symbol`, `find_similar_code`, `find_dead_code` + `hotspots`, `batch_symbols`, `max_tokens` on every list-shaped tool, file-based routing (Next.js/SvelteKit/Nuxt/Remix), PHP PSR-4 / C# namespace / Swift SPM import resolution, opt-in LSP edge promotion, sqlite-vec vec0 KNN~~ ✅
10. ~~Orientation release (0.5.0): `repo_map` (annotated architecture map, importance ranking, entry points, dependency inventory), resumable cursors + a recalibrated token estimator, depth-collapsing outlines and directory outlines, `change_coupling` + `symbol_history` on a persisted commit cache, streaming resolution for million-symbol repos~~ ✅
11. ~~Token-honesty and text release (0.6.0): an estimator that no longer under-counts high-entropy output (base64 was charged a quarter of its true cost, so `max_tokens` could be exceeded), provenance stated once per answer instead of on every row, `search_content` over a contentless FTS index with on-disk verification, non-code files (md/json/yaml/Dockerfile/CI) indexed for the first time~~ ✅

Performance (vuejs/core, 157k LOC, 536 files incl. `.vue` SFCs): cold index **3.8 s**, warm tool
calls **p95 ≤ 6 ms** through a full MCP round-trip. `scripts/bench.mjs` runs in CI.

Scale (Unreal Engine `Engine/Source/Runtime`, **19,097 files, 6.3M LOC, 622k symbols, 502k edges**):
cold index 413 s, warm structural queries **p95 ≤ 18 ms**, and `repo_map` returns the whole
architecture in **p95 126 ms within a 2,500-token budget**. Text search over all 19k files costs
**p50 69 ms**, and the content index is **45.6 MB — 4% of the database**, because it stores no file
text: it proposes candidates and the disk verifies them.

## Development

```sh
npm install        # also copies grammar wasm files into grammars/
npm test           # vitest: extractor golden tests, store, scanner, MCP end-to-end
npm run lint
npm run dev serve  # run from source via tsx
```

Position convention: lines are 1-based, columns 0-based, paths root-relative with forward slashes.
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add languages, servers, and grammars.

## License

MIT