Standalone MCP Server

@codeatlas/mcp is a 39-tool Model Context Protocol server that exposes a live architectural map of your codebase — and an AI code review built on the same six-layer model — as JSON-RPC over stdio. Plug it into any MCP-compatible LLM client; your assistant gains structured access to routes, sequence diagrams, dependencies, impact analysis, a SQL-queryable snapshot, and review findings grounded in source quotes.

What you get

  • 39 tools covering entrypoints, packs, diffs, impact, health, function source, call paths, API surface diffs, pre-edit briefs, pagination, architecture rules, coverage overlay, find-similar, saved views, search, SQL, snapshot schema, cross-workspace compare, deterministic summarise, OpenAPI / function- calling spec exporters, and 15 AI code review tools (new in v2) — list findings, search them in plain English, score them against a query, propose guidelines from confirmed findings, and bundle fix context for an agent.
  • 8 resources: codeatlas://workspace/microservices, /apis, /features, /entrypoints, /diff-summary, /ai-findings, /review-guidelines, /review-summary.
  • Push notifications. Stdio clients that subscribe get a findings_changed event whenever findings are added, updated, or removed — no polling needed.
  • Self-init. On first launch the server scans the workspace, builds the snapshot DB at .codeatlas/state.db, and starts a file watcher. No editor required.
  • Polyglot. Indexes Python, Java, Kotlin, Go, Rust, Ruby, PHP, Swift, Dart, C#, plus JS/TS — the host only needs Node.js ≥ 18.
  • Multi-provider AI. Bring your own LLM — OpenRouter, OpenAI, Anthropic, Ollama (local), or any OpenAI-compatible endpoint. Local Ollama doesn't need an API key.

Install

The MCP server ships as an npm package; npx handles install + run:

Run on any workspacebash
npx -y @codeatlas/mcp /absolute/path/to/your/workspace

That command speaks JSON-RPC over stdio — you almost never call it directly. Configure your MCP client to spawn it for you. Pick your client:

Claude CodeCodex CLIGemini CLICursor
Want the full tool list?
Tools reference → — one-paragraph description plus a sample input/output for each of the 39 tools.

How self-init works

  1. On first launch the server calls classifyWorkspace(): scans up to 11 supported language extensions, skipping node_modules/,.git/, build directories.
  2. If the workspace is empty or doc-only, every tool returns { status: "not_a_codebase", reason: … } with a diagnostic — no diagrams, no crash.
  3. Otherwise SyncOrchestrator.initialize() runs headlessly and builds .codeatlas/state.db. A polling watcher keeps the snapshot in sync as files change.

Concurrency & the write-lock

When the MCP server starts it tries to acquire an atomic lock at .codeatlas/.mcp-owner. If the VS Code extension already holds it, the MCP server writes a preempt signal at .codeatlas/.mcp-preempt; the extension sees it, releases the lock, and drops to read-only with a toast.

In the reverse direction (MCP holds the lock, then you open VS Code), the extension activates in read-only mode and shows the same toast.

SQL access (no LLM)

query_snapshot runs read-only SQL against the snapshot DB with strict guardrails: SELECT or WITH only, table allowlist, multi-statement blocked, CTE-aware, row cap. Pair it with describe_snapshot_schema so the model can introspect first.

Sample: group routes by HTTP methodsql
SELECT method, COUNT(*) AS n
FROM apis
GROUP BY method
ORDER BY n DESC
LIMIT 10;

Token economics (measured)

File-walking ~14k tokens for a medium test repo; list_entrypoints returns ~1.8k; a single-route pack ~700 tokens; a diff summary ~28. 5×–60× reductions depending on query shape.

Where to get it