Metadata-Version: 2.4
Name: codeatlas-mcp-server
Version: 0.14.0
Summary: CodeAtlas MCP - an enterprise-grade local-first Code Graph RAG MCP Server.
Author: CodeAtlas Team
License: Apache-2.0
Keywords: mcp,code-graph,rag,code-intelligence,sqlite
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.5
Requires-Dist: pydantic-settings>=2.1
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: alembic>=1.13
Requires-Dist: typer>=0.12
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.1
Requires-Dist: tree-sitter>=0.21
Requires-Dist: tree-sitter-language-pack>=0.9
Requires-Dist: mcp>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: setuptools>=83.0.0; extra == "dev"
Dynamic: license-file

# 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](#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

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

pip install -e ".[dev]"
```

## Quick start

```bash
# 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](docs/cli_usage.md). For
connecting the MCP server to Claude Code, VS Code, and Cursor, see
[docs/mcp_usage.md](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`](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

```bash
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](LICENSE).
