# chuk-mcp-code-raptor

**Deep code intelligence for MCP** — an MCP server that gives AI agents semantic understanding of codebases via RAPTOR hierarchical indexing and code property graphs.

> Pure intelligence, no filesystem. This server only provides capabilities the client doesn't already have — semantic search, dependency graphs, hierarchical context, AST-aware symbol lookup.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)

## What It Does

Every MCP client (Claude Code, Cursor, etc.) already has file reading, text search, and shell access. This server adds the intelligence layer on top:

| What clients have | What this server adds |
|---|---|
| Keyword search (grep) | **Semantic search** — "how does auth work" finds the right code across abstraction levels |
| File reading | **Hierarchical context** — where a symbol sits in the architecture, what it affects |
| Symbol grep | **AST-aware symbol lookup** — knows the difference between a class and a function with the same name |
| Manual exploration | **Dependency graphs** — what imports what, data flow, blast radius analysis |
| Nothing | **Project detection** — auto-detect language, framework, test runner, package manager |
| Nothing | **Code outline** — symbols with signatures, line numbers, docstrings |

## Tools

10 tools across 5 groups. All return structured Pydantic JSON, not raw file contents.

### Session — Project Selection (1 tool)

| Tool | Description |
|---|---|
| `set_project` | Set the active project directory and build the index. Falls back to `CODE_RAPTOR_PROJECT` env var if no path given. Must be called before other tools. |

### Orient — Project Awareness (2 tools)

| Tool | Description |
|---|---|
| `get_project_info` | Detect language, framework, package manager, test framework, entry points |
| `get_outline` | Show symbols in a file or directory with line numbers, signatures, docstrings |

### Find — Search & Discovery (3 tools)

| Tool | Description |
|---|---|
| `search_semantic` | Semantic code search across RAPTOR hierarchy levels. Supports `max_results`, `token_budget` |
| `find_symbol` | Find a class, function, or method by name. Optional `kind` filter |
| `find_references` | Find everywhere a symbol is used — imports, calls, data flow |

### Understand — Context & Relationships (2 tools)

| Tool | Description |
|---|---|
| `get_context` | Hierarchical context — where a symbol sits in the architecture, related components, impact scope |
| `get_dependencies` | Import and data-flow graph — what a symbol depends on and what depends on it |

### Maintenance — Index Management (2 tools)

| Tool | Description |
|---|---|
| `reindex` | Full index rebuild after major changes |
| `reindex_file` | Incremental update after editing a single file |

All intelligence tools are **read-only** (`readOnlyHint=True`). Session and maintenance tools are **idempotent** (`idempotentHint=True`).

## Installation

### Using uv (Recommended)

```bash
# Install from PyPI
uv pip install chuk-mcp-code-raptor

# Or clone and install from source
git clone https://github.com/chrishayuk/chuk-mcp-code-raptor.git
cd chuk-mcp-code-raptor
uv sync --dev
```

### Using pip

```bash
pip install chuk-mcp-code-raptor
```

### Optional dependencies

```bash
# Local embeddings (sentence-transformers, recommended)
pip install "chuk-mcp-code-raptor[embeddings-local]"

# OpenAI embeddings
pip install "chuk-mcp-code-raptor[embeddings-openai]"

# Anthropic summarization (Phase 2)
pip install "chuk-mcp-code-raptor[summarization-anthropic]"
```

## Usage

### With mcp-cli (uv)

Add to your `server_config.json` or `~/.mcp.json`:

```json
{
  "servers": {
    "code-raptor": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/chuk-mcp-code-raptor", "chuk-mcp-code-raptor"],
      "type": "stdio"
    }
  }
}
```

Then in the chat, call `set_project` to choose a codebase:

```
💬 You: set_project to /path/to/my/repo then tell me the architecture
```

### With Claude Desktop

Add to your Claude Desktop configuration:

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

```json
{
  "mcpServers": {
    "code-raptor": {
      "command": "chuk-mcp-code-raptor",
      "env": {
        "CODE_RAPTOR_PROJECT": "/path/to/your/project"
      }
    }
  }
}
```

With `CODE_RAPTOR_PROJECT` set, call `set_project()` (no argument) to auto-initialize from the env var.

### Standalone

```bash
# STDIO mode (default, for MCP clients)
python -m chuk_mcp_code_raptor

# HTTP mode (for web access)
python -m chuk_mcp_code_raptor http
```

### From Python

```python
from chuk_mcp_code_raptor.config import ServerConfig
from chuk_mcp_code_raptor.state import ServerState, set_state
from chuk_mcp_code_raptor.tools.find import search_semantic

# Initialize the index
config = ServerConfig(target_repo="/path/to/project")
state = ServerState(config=config)
await state.initialize()
set_state(state)

# Semantic search
result = await search_semantic("how does authentication work")
```

## Examples

Four runnable demos in the `examples/` directory:

```bash
# Tool registration and schema inspection
uv run examples/server_demo.py

# Agent workflow with hardcoded data (no indexing required)
uv run examples/agent_workflow_demo.py

# Full indexing pipeline — creates a project, indexes it, calls all 9 tools
uv run examples/live_indexing_demo.py

# MCP protocol interaction via ToolRunner
uv run examples/mcp_client_demo.py
```

| Demo | What it shows |
|---|---|
| `server_demo.py` | Tool registration, schemas, MCP hints |
| `agent_workflow_demo.py` | How an agent would use the tools in sequence |
| `live_indexing_demo.py` | Full RAPTOR + CPG pipeline on a realistic project |
| `mcp_client_demo.py` | MCP protocol calls through ToolRunner |

## Development

### Setup

```bash
git clone https://github.com/chrishayuk/chuk-mcp-code-raptor.git
cd chuk-mcp-code-raptor
uv sync --dev
```

### Running Tests

```bash
make test          # Run tests
make test-cov      # Run tests with coverage
make coverage-report  # Show coverage report
```

### Code Quality

```bash
make lint          # Run linters (ruff)
make format        # Auto-format code
make typecheck     # Run type checking (mypy)
make security      # Run security checks (bandit)
make check         # Run all checks (lint + typecheck + security + test)
```

### Building

```bash
make build         # Build package
make version       # Show current version
make bump-patch    # Bump patch version
make publish       # Create tag and trigger automated release
```

## Architecture

```
src/chuk_mcp_code_raptor/
├── __init__.py
├── __main__.py              # python -m chuk_mcp_code_raptor
├── server.py                # MCP server instance, tool registration
├── config.py                # ServerConfig (Pydantic)
├── state.py                 # ServerState — holds index, CPG, RAPTOR builder
├── constants.py             # All enums and constants (no magic strings)
├── protocols.py             # Structural typing protocols
├── models/                  # Pydantic models for tool I/O
│   ├── orient.py            # ProjectInfo, SymbolInfo, OutlineResult
│   ├── find.py              # SemanticMatch, SymbolMatch, ReferenceLocation
│   ├── understand.py        # HierarchyContext, DependencyGraph
│   └── maintenance.py       # ReindexResult, FileReindexResult
├── tools/                   # Tool handlers (pure async functions)
│   ├── session.py           # set_project
│   ├── orient.py            # get_project_info, get_outline
│   ├── find.py              # search_semantic, find_symbol, find_references
│   ├── understand.py        # get_context, get_dependencies
│   └── maintenance.py       # reindex, reindex_file
├── indexing/                # Index pipeline
│   ├── pipeline.py          # Orchestration: scan → chunk → embed → RAPTOR → CPG
│   ├── scanner.py           # Project detection (language, framework, tests)
│   ├── converters.py        # chuk-code-raptor ↔ Pydantic adapters
│   └── providers/
│       ├── embeddings.py    # EmbeddingProvider protocol + implementations
│       └── summarization.py # SummarizationProvider protocol (Phase 2)
└── utils/
    ├── async_bridge.py      # run_sync() — wraps sync calls in executor
    ├── paths.py             # Path resolution and validation
    ├── subprocess.py        # Async subprocess runner
    └── diff.py              # Unified diff generation
```

### Design Principles

- **Async native** — every I/O-touching function is `async def`
- **Pydantic native** — all data boundaries use typed models, not raw dicts
- **No magic strings** — every repeated string is an enum or constant
- **Composable** — tools don't know about transport, indexing doesn't know about MCP
- **Pure intelligence** — no file reading, no shell, no git — only what clients can't do themselves

### Dependencies

| Package | Role |
|---|---|
| [chuk-mcp-server](https://github.com/chrishayuk/chuk-mcp-server) | MCP framework (`@tool` decorator, transports, ToolRunner) |
| [chuk-code-raptor](https://github.com/chrishayuk/chuk-code-raptor) | RAPTOR hierarchy, CPG, chunking engine, intelligent search |
| [pydantic](https://docs.pydantic.dev/) | Data validation and serialization |
| [tree-sitter-python](https://github.com/tree-sitter/tree-sitter-python) | Python AST parsing |

## Roadmap

See [ROADMAP.md](ROADMAP.md) for the full phased delivery plan.

- **Phase 0** — Scaffold (complete)
- **Phase 1** — Working Intelligence (complete)
- **Phase 1.5** — MCP Client Integration (complete)
- **Phase 2** — LLM Summarization
- **Phase 3** — File Watching & Persistence
- **Phase 4** — Production Hardening

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.