ContextAtlas CLAUDE.md

CLAUDE.md

Instructions for Claude Code working on the ContextAtlas project.

---

What This Project Is

ContextAtlas is an MCP server that gives Claude Code a curated atlas of a user's codebase — fusing LSP-grade structural precision with architectural intent from ADRs, docs, and git history, delivered in single-call context bundles.

Read DESIGN.md for the full architecture. Read RUBRIC.md for benchmark methodology. Read README.md for the public-facing positioning.

Critical Constraints

These are decisions already made. Do not relitigate them.

• Language: TypeScript (Node 20+). No Python or Go in the server code itself — those are supported as target languages via language adapters, not as implementation languages.
• Dependencies: Minimize. Required: @modelcontextprotocol/sdk, @anthropic-ai/sdk, better-sqlite3, a YAML parser, a glob library. Do not add state management libraries, ORMs, or HTTP frameworks.
• typescript-language-server placement: User-provided, not a bundled dependency. The TS adapter spawns it as a subprocess, but the binary itself is expected to be on the user's PATH or pointed to via config. This keeps the package lean and lets users choose their tsserver version. package.json lists it as a peerDependency — do not promote to a direct dependency.
• LSP client strategy: Raw JSON-RPC over stdio. No vscode-languageclient / vscode-jsonrpc dependency. The LSP subset we need (initialize, documentSymbol, references, diagnostics, shutdown) is ~150 lines of framing and fits comfortably in src/adapters/lsp-client.ts without pulling VS Code's client machinery. Rationale: dependency minimization per the constraint above, and cleaner control over subprocess lifecycle.
• Storage: SQLite via better-sqlite3. Single file. No Postgres, no Redis, no external services.
• MCP SDK: @modelcontextprotocol/sdk. Follow their patterns.
• Output format: Compact text by default, JSON available via input parameter. Compact format is defined in DESIGN.md.
• Symbol ID format: sym:<lang-short-code>:<path>:<name> (see ADR-01). Line numbers are NOT part of the ID — they live as a field on the Symbol record. Locked; do not change without updating ADR-01, DESIGN.md, and bumping the version.
• Extraction model: claude-opus-4-7 at default effort. Not extended thinking. See DESIGN.md section on extraction pipeline.
• Pre-drafted extraction prompt: src/extraction/prompt.ts holds the EXTRACTION_PROMPT constant — validated on two empirical bases: (1) pre-scaffolding ADR validation on 12 production-grade documents (100% JSON parse success, 169 claims extracted correctly across hono and httpx ADRs); (2) v0.3 Step 9 docstring calibration on 13 samples across TypeScript / Python / Go (11/13 PASS; JSON parse 100%; severity discipline 100%; cost $0.45). The prompt handles ADR + docstring inputs via H1 (single shared prompt) design. The extraction pipeline imports from this file; do not duplicate the prompt elsewhere. The prompt content, severity taxonomy, and model choice are frozen per ADR-02; call signatures, error handling, and output validation around it evolve with the pipeline. Refinements within the prompt require calibration evidence parallel to v0.3 Step 9.