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.

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)

# 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

pip install chuk-mcp-code-raptor

Optional dependencies

# 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:

{
  "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

{
  "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

# 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

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:

# 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

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

Running Tests

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

Code Quality

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

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	MCP framework (@tool decorator, transports, ToolRunner)
chuk-code-raptor	RAPTOR hierarchy, CPG, chunking engine, intelligent search
pydantic	Data validation and serialization
tree-sitter-python	Python AST parsing

Roadmap

See 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 for details.