@codeatlas/mcp 1.1.0 → 2.0.0

package/README.md

@@ -1,10 +1,12 @@
 # @codeatlas/mcp
 
-> **Live codebase architecture for any MCP-compatible LLM client.**
-> 25 tools + 5 resources expose routes, sequences, dependency graphs, diffs, impact analysis, architecture violations, and full SQL access over your workspace — so the model gets structured answers instead of grepping through files.
+> **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
@@ -79,7 +81,7 @@ After registering, reload your client and the 25 tools appear alongside its buil
 
 ## What it exposes
 
-### 25 tools
+### 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`
@@ -99,7 +101,10 @@ After registering, reload your client and the 25 tools appear alongside its buil
 **Interop**
 `export_openapi_spec` · `export_function_calling_spec` · `summarise_payload`
 
-### 5 resources
+**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 |
 |-----|----------|
@@ -108,14 +113,124 @@ After registering, reload your client and the 25 tools appear alongside its buil
 | `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 MCP server bootstraps the snapshot itself when launched against a workspace that has no `.codeatlas/state.db` yet — scans the workspace, classifies it as a codebase (or returns `status: 'not_a_codebase'` for docs-only / empty dirs), runs the full indexing pipeline, and starts a file watcher to keep state current.
+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`).
+
+### Connect an LLM
+
+AI 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.
 
-**You can register the MCP server against a brand-new repo and the LLM gets working answers within seconds — no VS Code launch required.**
+After restart the browser reconnects automatically — just refresh the tab.
 
 ---