Metadata-Version: 2.4
Name: codeatlas-mcp-server
Version: 0.17.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).

## Install from PyPI

CodeAtlas is published to PyPI as
[`codeatlas-mcp-server`](https://pypi.org/project/codeatlas-mcp-server/). The
distribution name is `codeatlas-mcp-server`; the installed command and import
package are both `codeatlas`.

```bash
pip install codeatlas-mcp-server
```

For MCP use, install it so the `codeatlas` command is on your `PATH` even
without an activated virtualenv (MCP clients launch it as a subprocess). The
cleanest way is [`pipx`](https://pipx.pypa.io):

```bash
pipx install codeatlas-mcp-server
```

Verify the install:

```bash
codeatlas version
```

## Install from source (development)

```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).

## Using CodeAtlas

There are two ways to use CodeAtlas: directly from the **command line**, or as
an **MCP server** wired into an AI coding assistant. Both read the same
`.codeatlas/` index, so index once and use it either way.

### Via the CLI

After `pip install codeatlas-mcp-server`, the `codeatlas` command is available.
Point it at any repository (defaults to the current directory).

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

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

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

Once indexed, query the graph:

```bash
# Locate a symbol definition and its usages
codeatlas find-symbol create_order /path/to/repo

# Trace a request flow (route → handler → service → repository → DB)
codeatlas trace-flow "POST /orders" /path/to/repo

# See what a change to a symbol would affect (callers, routes, tests)
codeatlas impact OrderService.create_order /path/to/repo

# Recommend tests for changed symbols/files
codeatlas recommend-tests /path/to/repo --changed-symbols create_order

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

Every command prints structured **JSON on stdout**; logs go to stderr. Add
`-v`/`--verbose` for debug logging. Run `codeatlas --help` (or
`codeatlas <command> --help`) for all options, and see
[docs/cli_usage.md](docs/cli_usage.md) for the full reference.

### Via the MCP server

CodeAtlas exposes its code graph over the **Model Context Protocol** on stdio,
so AI agents can query it without re-scanning files. Index the repo first, then
start the server:

```bash
codeatlas init  /path/to/repo
codeatlas index /path/to/repo

# Start the MCP server over stdio (normally launched by the client, see below)
CODEATLAS_REPO_PATH=/path/to/repo codeatlas mcp start
```

The server is configured entirely through environment variables:

| Variable | Required | Purpose |
| --- | --- | --- |
| `CODEATLAS_REPO_PATH` | ✅ | Absolute path to the repository to serve. |
| `CODEATLAS_CONFIG` | optional | Absolute path to `codeatlas.yaml`. |
| `CODEATLAS_LLM_PROVIDER` | optional | `bedrock` \| `ollama` \| `none`. |
| `CODEATLAS_LOG_LEVEL` | optional | e.g. `DEBUG`, `INFO`. |

It exposes 10 tools — `index_repository`, `explore_codebase`, `find_symbol`,
`trace_flow`, `impact_analysis`, `recommend_tests`, `query_graph_rag`,
`get_code_context`, `list_modules`, and `explain_symbol`. All deterministic
tools work offline; `query_graph_rag` uses your configured LLM provider if one
is set, and otherwise returns structured, evidence-only results.

#### Asking in plain English (and the CLI equivalent)

You don't call MCP tools directly — you ask your AI assistant in plain English
and it picks the right tool. Each request maps to an equivalent `codeatlas`
command you can run yourself:

| Ask your assistant… | MCP tool | CLI equivalent |
| --- | --- | --- |
| "Index / re-index this repository." | `index_repository` | `codeatlas index <repo>` |
| "Give me an overview of this codebase." | `explore_codebase` | *(MCP-only; see `codeatlas status`)* |
| "Where is `create_order` defined and who calls it?" | `find_symbol` | `codeatlas find-symbol create_order <repo>` |
| "Trace what happens on `POST /orders`." | `trace_flow` | `codeatlas trace-flow "POST /orders" <repo>` |
| "If I change `create_order`, what breaks?" | `impact_analysis` | `codeatlas impact create_order <repo>` |
| "Which tests should I run after editing `create_order`?" | `recommend_tests` | `codeatlas recommend-tests <repo> --changed-symbols create_order` |
| "How does the checkout flow work?" | `query_graph_rag` | `codeatlas ask "How does the checkout flow work?" <repo>` |
| "Give me the full context for `create_order`." | `get_code_context` | *(MCP-only)* |
| "List all modules in the index." | `list_modules` | *(MCP-only; see `codeatlas status`)* |
| "Explain what `create_order` does." | `explain_symbol` | *(MCP-only)* |

You don't need to name the tool — the assistant maps intent automatically. For
the full prompt-and-argument reference see
[docs/mcp_usage.md](docs/mcp_usage.md#calling-the-tools--plain-english--cli-equivalents).

## AI IDE / client configuration

MCP clients launch `codeatlas mcp start` as a subprocess, so the `codeatlas`
command must resolve on your `PATH` (use `pipx install codeatlas-mcp-server`, or
point `command` at the absolute path to the executable). Every client uses the
same three pieces: `command: codeatlas`, `args: ["mcp", "start"]`, and an `env`
block with at least `CODEATLAS_REPO_PATH`.

### Claude Code

**Option A — CLI (recommended):**

```bash
claude mcp add codeatlas \
  --env CODEATLAS_REPO_PATH=/path/to/repo \
  --env CODEATLAS_CONFIG=/path/to/repo/codeatlas.yaml \
  -- codeatlas mcp start
```

**Option B — project `.mcp.json`** (checked in so your team shares it):

```json
{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": {
        "CODEATLAS_REPO_PATH": "/path/to/repo",
        "CODEATLAS_CONFIG": "/path/to/repo/codeatlas.yaml"
      }
    }
  }
}
```

Run `/mcp` inside Claude Code to confirm `codeatlas` is connected.

### Claude Desktop

Edit the config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": {
        "CODEATLAS_REPO_PATH": "/path/to/repo",
        "CODEATLAS_CONFIG": "/path/to/repo/codeatlas.yaml"
      }
    }
  }
}
```

Restart Claude Desktop; the CodeAtlas tools appear in the tools (🔨) menu.

### VS Code (Copilot agent mode)

Create `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "codeatlas": {
      "type": "stdio",
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": {
        "CODEATLAS_REPO_PATH": "${workspaceFolder}",
        "CODEATLAS_CONFIG": "${workspaceFolder}/codeatlas.yaml"
      }
    }
  }
}
```

`${workspaceFolder}` expands to the open project path, keeping the config
portable. Use **MCP: List Servers** to start/stop and view logs.

### Cursor

Add to `.cursor/mcp.json` (project scope) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": {
        "CODEATLAS_REPO_PATH": "/path/to/repo",
        "CODEATLAS_CONFIG": "/path/to/repo/codeatlas.yaml"
      }
    }
  }
}
```

Then open **Cursor Settings → MCP** and confirm `codeatlas` shows a green
"connected" indicator.

### Windsurf & other MCP clients

Any stdio-capable MCP client works with the same shape. Windsurf reads
`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "codeatlas": {
      "command": "codeatlas",
      "args": ["mcp", "start"],
      "env": { "CODEATLAS_REPO_PATH": "/path/to/repo" }
    }
  }
}
```

If `codeatlas` is not on the global `PATH`, point `command` at the absolute
path instead — e.g. `C:\\path\\to\\.venv\\Scripts\\codeatlas.exe` on Windows
(note the doubled backslashes in JSON) or
`/path/to/.venv/bin/codeatlas` on macOS/Linux. For the full connection guide,
tool reference, and LLM-provider setup, 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).
