# 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

pip install chuk-mcp-code-raptor

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

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

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

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

# 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 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")

# 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

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

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

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)

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

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