# @codeatlas/mcp

> **Live codebase architecture and AI code review for any MCP-compatible LLM client.**
> 39 tools + 8 resources expose routes, sequences, dependency graphs, diffs, impact analysis, architecture violations, full SQL access, and AI-driven review findings over your workspace — so the model gets structured answers instead of grepping through files.

Works with **Claude Code, Cursor, VS Code Copilot, Codex CLI, Gemini CLI, Antigravity, Continue** — anything that speaks the Model Context Protocol.

**New in v2** — AI code review tools. Run a review with `run_review`, list findings with `list_ai_findings`, ask "what's wrong with auth?" with `search_ai_findings`, then ask for a one-shot context bundle to fix the issue with `review_and_fix_pack`. Findings are grounded in source quotes the model has to copy verbatim — no invented issues.

---

## Why it matters: token economics

Measured against a mid-sized test project, every query returns **5×–200× fewer tokens** than the equivalent file-walking approach:

| Query | Naive file-walk | MCP context pack | Reduction |
|---|---:|---:|---:|
| List every entry point | 14,088 tokens | 1,794 tokens | **7.9×** |
| One route's full context | 5,647 tokens | 703 tokens | **8.0×** |
| Impact-of-change for a function | ~20–30 files of grepping | 254 tokens | **~50×** |
| Diff summary | several KB of git output | 28 tokens | **>200×** |

A 2.7B-class model with a 16K context window can answer *"what handles this route?"* or *"what breaks if I change X?"* on a 1k-file codebase using **one MCP call instead of dozens of file reads.** The retrieval problem moves from the LLM to the framework.

---

## Quick start

### Claude Code
```bash
claude mcp add codeatlas -- npx -y @codeatlas/mcp $(pwd)
```

### Cursor — Settings → MCP → Add Server
```json
{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/absolute/path/to/your/repo"]
    }
  }
}
```

### VS Code (1.103+, Copilot Chat agent mode) — `.vscode/mcp.json`
```json
{
  "servers": {
    "codeatlas": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "${workspaceFolder}"]
    }
  }
}
```

### Codex CLI — `~/.codex/config.toml`
```toml
[mcp_servers.codeatlas]
command = "npx"
args = ["-y", "@codeatlas/mcp", "/absolute/path/to/your/repo"]
```

### Gemini CLI / Antigravity — `~/.gemini/settings.json`
```json
{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/absolute/path/to/your/repo"]
    }
  }
}
```

After registering, reload your client and the 25 tools appear alongside its built-ins.

---

## What it exposes

### 39 tools

**Context packs** — minimum-token retrieval primitives
`list_entrypoints` · `list_entrypoints_paged` · `get_entrypoint_pack` · `get_feature_pack` · `pre_edit_brief` · `get_function_source` · `trace_call_path`

**Diff & impact** — answer "what changed" and "what breaks"
`get_diff_summary` · `get_api_surface_diff` · `get_impact_of_change` · `get_impact_analysis` · `get_function_dependencies`

**Search & query** — weighted reverse index + read-only SQL over the snapshot
`search_workspace` · `query_snapshot` · `describe_snapshot_schema`

**Health & rules**
`get_health_report` · `list_architecture_violations` · `get_coverage_overlay`

**Workspace**
`get_workspace_status` · `find_similar_entities` · `list_saved_views` · `compare_workspaces`

**Interop**
`export_openapi_spec` · `export_function_calling_spec` · `summarise_payload`

**AI code review** — query, score, and act on findings (new in v2)
`list_ai_findings` · `get_ai_finding` · `get_ai_finding_counts` · `update_ai_finding_status` · `get_review_guidelines` · `set_review_guidelines` · `search_ai_findings` · `summarise_findings` · `list_findings_by_guideline` · `get_review_summary` · `clear_findings` · `review_and_fix_pack` · `score_findings` · `propose_guideline_from_finding` · `review_diff_with_baseline`

### 8 resources

| URI | Contents |
|-----|----------|
| `codeatlas://workspace/microservices` | All detected services — name, technology, API count, inter-service connections |
| `codeatlas://workspace/apis` | All REST / GraphQL / gRPC / WS / SSE / job / CLI entry points — method, route, handler, file path |
| `codeatlas://workspace/features` | Feature clusters — label, file membership, cohesion, API count |
| `codeatlas://workspace/entrypoints` | Every entry point flattened across all categories |
| `codeatlas://workspace/diff-summary` | Baseline-vs-working summary across all 6 diagram layers |
| `codeatlas://workspace/ai-findings` | All AI-review findings — severity, layer bindings, source quotes |
| `codeatlas://workspace/review-guidelines` | Team review rules currently injected into every review prompt |
| `codeatlas://workspace/review-summary` | Counts by layer + severity, top findings, last review metadata |

### Push notifications

Stdio clients that subscribe get `notifications/codeatlas/findings_changed` when findings are added, updated, or removed — no polling needed.

---

## Self-init: no VS Code required

The first time you point it at a workspace, the MCP server indexes the code and starts watching for changes. The AI gets working answers within seconds.

Both this server and the VS Code extension can run on the same repo at the same time — they keep their own state, so they don't conflict. Add `.codeatlas-sa/` to `.gitignore` (the index lives there).

---

## Browser diagrams (`--browser`)

Add `--browser` to view the architecture in a browser tab alongside the AI conversation:

```bash
npx @codeatlas/mcp /path/to/repo --browser
```

A tab opens at `http://localhost:7742` showing six linked diagram layers: system design, feature clusters, API list, sequences, file dependencies, and function flow. File edits propagate to the browser in real time. Click any node to open the file in your editor.

| Flag | Effect |
|------|--------|
| `--browser` | Start the diagram view alongside the AI server |
| `--port <N>` | Use a specific port (default 7742) |
| `--no-open` | Don't auto-open the browser; just print the URL |

Set `CODEATLAS_EDITOR=<cmd>` to pick the editor (defaults to `$EDITOR`, then `code`, `cursor`, `subl`, `nvim`, `vim`).

### Run a Code Review from the browser

The home page has a **Code Review** card that fans the review out across every entry point. **Changed only** restricts it to entry points whose code differs from baseline. **Specific review** opens a textarea so you can tell the AI exactly what to focus on. **Cancel** stops the in-flight LLM call immediately; **Clear** wipes findings and resets state.

When findings exist, the **Findings popover** opens with a top-down summary: an "Interpretation" line that names the dominant pattern across all findings (auth gaps, validation risks, secret leakage, N+1 queries…), per-layer breakdowns that name the actual clusters / routes / files affected, and a "Top concerns (focus here first)" shortlist. Every finding row carries **Resolve / Ignore / Comment / Copy** buttons. A "Copy ▾" dropdown copies all findings — or just errors / warnings / info — as Markdown ready to paste into a PR or ticket.

Inside every diagram (System Design, Feature Areas, API List, Sequence, File, Function Flow), entities with findings show a colored count marker. Click it to open the popover (same actions) right where the issue lives — state changes propagate to every open tab immediately.

Each finding is tagged with the commit SHA it was reviewed against (or a content-hash for non-git workspaces). Re-running with the same code + guidelines surfaces a **"Nothing changed since last review"** badge instead of burning another LLM call.

### Connect an LLM

Code Review and natural-language search use any OpenAI-compatible provider. Pick one:

| Provider | Env var | `provider` setting |
|----------|---------|--------------------|
| OpenRouter (default) | `OPENROUTER_API_KEY` | `openrouter` |
| OpenAI | `OPENAI_API_KEY` | `openai` |
| Anthropic | `ANTHROPIC_API_KEY` | `anthropic` |
| Ollama (local — no key) | — | `ollama` |
| Custom endpoint | `LLM_API_KEY` (optional) | `custom` |

Change provider + model from the browser (LLM settings panel) or write to `<workspace>/.codeatlas-sa/config.json`:
```json
{
  "codeatlas.llmProvider": "anthropic",
  "codeatlas.llmModel": "claude-3-5-sonnet-latest"
}
```

### Compare commits, branches, and pull requests

From the diagram view in your browser:

- **Compare Commits** — pick base + head from a list of recent commits.
- **Compare Branch** — pick a branch; the diff shows what that branch added relative to your current `HEAD`.
- **Compare PR** — pick a pull request from the connected GitHub repo. Public repos work without a token (60 requests/hour limit). For private repos or higher rate limits, set `GITHUB_TOKEN` (or `GH_TOKEN`) with at least `repo` scope.

### Pairing with your AI assistant

The AI doesn't open the browser — you do. Register the server with `--browser` and the AI can cite URLs you click to jump straight to a specific diagram.

**Claude Code:**
```bash
claude mcp add codeatlas -- npx -y @codeatlas/mcp $(pwd) --browser
```

**Cursor / VS Code / Codex / Gemini** — add `--browser` to the args:
```json
{
  "mcpServers": {
    "codeatlas": {
      "command": "npx",
      "args": ["-y", "@codeatlas/mcp", "/absolute/path/to/repo", "--browser"]
    }
  }
}
```

The AI can link directly to any layer:

| URL | View |
|------|------|
| `http://localhost:7742/` | System design |
| `http://localhost:7742/#/features/service:main` | Feature clusters |
| `http://localhost:7742/#/apis/cluster:auth` | APIs in a cluster |
| `http://localhost:7742/#/sequence/<file>:<handler>` | Sequence for a route |
| `http://localhost:7742/#/file/<path>` | File diagram |
| `http://localhost:7742/#/flow/<path>/<fn>` | Function flow |

### If port 7742 is already in use

The server tries 7742 first and walks up (7743, 7744, …) up to four times if those are busy. The actual port appears in the startup log:

```
CodeAtlas browser ready: http://localhost:7743
```

To pick a specific port, pass `--port`:

```bash
npx @codeatlas/mcp /path/to/repo --browser --port 8080
```

### Restarting the server

The standalone is a single process. To restart:

- **Launched in a terminal:** press `Ctrl+C`, then re-run the command.
- **Launched by an AI client** (Claude Code, Cursor, etc.): use the client's "reload MCP servers" action, or quit and reopen the client.

After restart the browser reconnects automatically — just refresh the tab.

---

## Workspace languages & frameworks

Only the host machine needs **Node.js ≥18**. The indexed workspace can be in any of these:

**14 languages:** JavaScript, TypeScript, Python, Java, Kotlin, Go, Rust, C, C++, C#, PHP, Ruby, Swift, Dart

| Category | Frameworks |
|----------|-----------|
| **Node.js** | Express, Koa, Fastify, NestJS, Hono |
| **Meta-frameworks** | Next.js (App + Pages), Nuxt, Remix, SvelteKit |
| **API protocols** | tRPC, GraphQL, gRPC |
| **Python** | Django, FastAPI, Flask, Starlette, DRF |
| **Java/Kotlin** | Spring Boot, Micronaut, JAX-RS, Ktor |
| **Go** | Gin, Echo, Chi, Fiber |
| **PHP** | Laravel, Symfony |
| **Ruby** | Rails, Sinatra |
| **Rust** | Actix, Axum, Rocket |
| **C#** | ASP.NET Core, Minimal API |
| **Swift** | Vapor |
| **Mobile** | Android (Jetpack Compose, Hilt, Room), iOS (SwiftUI, UIKit, Combine), React Native, Flutter/Dart, Expo Router |

Plus **non-API entry points**: background jobs, message-queue consumers, CLI commands, ORM lifecycle hooks, DB migrations/seeds, socket events, GraphQL subscriptions, health endpoints, mobile push handlers, deep links, widgets, content providers, and lifecycle hooks.

**Infrastructure auto-detected:** PostgreSQL, MySQL, MongoDB, Redis, RabbitMQ, Kafka, Celery, Sidekiq, Entity Framework, Eloquent, Room, CoreData, Realm, Firebase, Prisma, Sequelize, and more.

---

## Any-workspace wrapper (optional)

If you want one config that works in any project, drop a tiny shim onto your `$PATH`:

```bash
#!/usr/bin/env bash
# /usr/local/bin/codeatlas-mcp
exec npx -y @codeatlas/mcp "$PWD"
```

Then your client configs become `command: codeatlas-mcp` with no args — workspace is wherever you launched the client.

---

## Running alongside the VS Code extension

When both the [CodeAtlas VS Code extension](https://marketplace.visualstudio.com/items?itemName=codeatlaslive.codeatlas-live) or [VSCodium](https://open-vsx.org/extension/codeatlaslive/codeatlas-live) and an MCP server target the same workspace, **MCP wins write ownership**. The extension watches for `.codeatlas/.mcp-preempt`, yields its lock when an MCP process requests it, disables auto-update for the session, and surfaces a recovery toast. Close + reopen the workspace once the MCP process exits to reclaim writes. No silent races on `state.db`.

---

## Privacy & security

- **Your code stays local.** All indexing and queries run on your machine; no source is uploaded.
- **No telemetry from this binary.** Telemetry only exists in the VS Code extension build, and even there it is anonymous, opt-out, and never includes source code, file names, or commit metadata.
- **Sensitive data scrubbed.** Passwords, tokens, and connection strings are redacted before being written to `.codeatlas/state.db`.
- **Path-traversal-safe.** Every file lookup is validated against the workspace boundary.
- **Read-only SQL.** `query_snapshot` enforces SELECT-only access — no mutations, no shell-out.

---

## Links

- **Issues / feature requests:** https://github.com/vamsikk7/codeatlas-live-issues/issues
- **Website:** https://codeatlas.live
- **Marketplace:** https://openvsx.org/extension/codeatlaslive/codeatlas-live
- **Docs:** https://www.codeatlas.live/docs/mcp/tools
---

## License

See [LICENSE.md](LICENSE.md).
