Code Atlas

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 /.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

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

Or from a clone:

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 to override.

CLI

node dist/index.js index [--root <path>]              # one-shot index build (debugging / warm-up)

node dist/index.js serve [--root ] [--no-watch] [--no-lsp] [--no-embeddings] [--no-download]

MCP server on stdio

Tools

Full reference with example outputs: docs/tools.md.

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 blocks (all of them, 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 r