codeatlas-mcp-server 0.15.0

CodeAtlas MCP - an enterprise-grade local-first Code Graph RAG MCP Server.

CodeAtlas MCP

CodeAtlas MCP is a local-first, enterprise-ready Code Graph RAG MCP Server. It converts a software repository into a queryable code knowledge graph, enriches it with Graph RAG, and exposes it through an MCP server so Claude Code and other AI coding agents can understand a codebase without repeatedly scanning files.

Status: Phases 1–7 implemented. The MCP server (codeatlas mcp start) exposes all 10 tools over stdio. Phase 8 adds the Java parser. See Implementation status.

MVP scope: Python and React/Node (JavaScript, TypeScript, JSX, TSX) projects. Additional languages (e.g. Java) and standalone SQL extraction are planned for future releases.

Why code-graph indexing helps AI agents

AI coding agents waste context re-reading files to answer "what calls what", "what breaks if I change this", and "which tests should run". CodeAtlas builds a structured graph once and answers these questions deterministically — with file paths, line numbers, and provenance for every relationship.

Requirements

• Python 3.11+
• SQLite (bundled with Python)

JavaScript/TypeScript parsing uses tree-sitter (installed automatically via prebuilt wheels — no Node.js runtime required). No LLM is required for indexing (spec constraint: indexing must work offline).

Installation

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -e ".[dev]"

Quick start

# 1. Initialize .codeatlas/, the SQLite database, and codeatlas.yaml
codeatlas init /path/to/repo

# 2. Build the index (deterministic, no LLM needed)
codeatlas index /path/to/repo

# 3. Inspect index status and row counts
codeatlas status /path/to/repo

# 4. Query the graph
codeatlas find-symbol create_order /path/to/repo
codeatlas trace-flow "POST /orders" /path/to/repo
codeatlas impact OrderService.create_order /path/to/repo
codeatlas recommend-tests /path/to/repo --changed-symbols create_order

# 5. Ask a natural-language question (Graph RAG)
codeatlas ask "Where is create_order implemented and what does it call?" /path/to/repo

# 6. Start the MCP server (for Claude Code, VS Code, Cursor, etc.)
CODEATLAS_REPO_PATH=/path/to/repo codeatlas mcp start

Graph RAG works fully offline: with no LLM configured it returns a deterministic, evidence-grounded answer built from the graph. Configuring an Ollama or Bedrock provider (and enabling indexing.generate_embeddings) adds semantic retrieval and LLM-written prose.

All commands print structured JSON on stdout. Logs go to stderr so the MCP stdio transport stays clean.

For the full command reference see docs/cli_usage.md. For connecting the MCP server to Claude Code, VS Code, and Cursor, see docs/mcp_usage.md.

Configuration

codeatlas init writes a codeatlas.yaml with safe enterprise defaults (local-only, no external LLM, embeddings off). See configs/codeatlas.example.yaml for the full schema. Environment overrides:

Variable	Effect
CODEATLAS_CONFIG	Explicit config file path
CODEATLAS_REPO_PATH	Overrides repository.path
CODEATLAS_LLM_PROVIDER	Overrides llm.provider (bedrock/ollama/none)

Security model

• Local-first: no code leaves the machine unless explicitly configured.
• Default exclusions: .git, node_modules, build dirs, secrets (.env, *.pem, *.key, ...), and binaries are skipped.
• Deterministic indexing: file hashes drive incremental re-indexing.
• Secret redaction: source snippets are scrubbed of keys, tokens, connection strings, and secret-like assignments before they enter any RAG context or reach an LLM (spec §15.2).
• Provider guardrails: remote LLM/embedding providers are refused unless security.allow_external_llm is set; the default is fully local/offline.
• Audit logging arrives with Phase 8.

Running tests

pytest              # full suite
pytest tests/unit   # unit tests only

Implementation status

Phase	Scope	Status
1	Project foundation (config, logging, models, CLI)	✅
2	Storage (SQLite schema, migrations, repository APIs, FTS5)	✅
3	Scanner & indexer (scan, filter, hash, incremental, run tracking)	✅
4	Parsers & graph builder (Python via ast; JS/TS/JSX/TSX via tree-sitter)	✅
5	Graph query (find-symbol, trace-flow, impact, recommend-tests, risk)	✅
6	Graph RAG (embeddings, vector + FTS retrieval, context builder, ask)	✅
7	MCP server (stdio, 10 tools: index, explore, find-symbol, trace-flow, impact, tests, RAG, context, modules, explain)	✅
8–10	Additional languages (Java), SQL extraction, watch mode, docs/hardening	⏳

License

Apache-2.0. See LICENSE.