@codeatlas/mcp 1.0.0 → 1.0.2

package/README.md

@@ -1,15 +1,67 @@
 # @codeatlas/mcp
 
-The CodeAtlas Model Context Protocol (MCP) server — 25 tools that expose live codebase architecture to any MCP-compatible LLM client (Claude Code, Cursor, VS Code Copilot, Codex CLI, Gemini CLI, Antigravity, Continue, etc.).
+> **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.
 
-## Quick start (Claude Code)
+Works with **Claude Code, Cursor, VS Code Copilot, Codex CLI, Gemini CLI, Antigravity, Continue** — anything that speaks the Model Context Protocol.
+
+---
+
+## 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)
 ```
 
-## Quick start (Cursor / VS Code Copilot agent / Gemini / Codex)
+### 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"]
+```
 
-Add to your client's MCP config (see your client docs for the right file):
+### Gemini CLI / Antigravity — `~/.gemini/settings.json`
 ```json
 {
   "mcpServers": {
@@ -21,10 +73,117 @@ Add to your client's MCP config (see your client docs for the right file):
 }
 ```
 
-## Workspace languages supported
+After registering, reload your client and the 25 tools appear alongside its built-ins.
+
+---
+
+## What it exposes
+
+### 25 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`
+
+### 5 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 |
+
+---
+
+## 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.
+
+**You can register the MCP server against a brand-new repo and the LLM gets working answers within seconds — no VS Code launch required.**
+
+---
+
+## 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
 
-Python, Java, Kotlin, Go, Rust, Ruby, PHP, Swift, Dart, C#, plus JS/TS. **Only the host machine needs Node.js ≥18** — the indexed workspace can be in any of these.
+- **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
+---
 
-## What it exposes (25 tools)
+## License
 
-See [the main CodeAtlas README](https://github.com/vamsikk7/codeatlas-live#ai-assistant-integration-mcp) for the full tool list and token-economics numbers.
+See [LICENSE.md](LICENSE.md).