Distillation Labs

Distillation Labs / Contextro / Documentation

Contextro docs

Complete installation, transport, configuration, and workflow notes for running Contextro as a local MCP server in real development workflows.

Product page GitHub ↗

Overview

Contextro is a local MCP server for repository intelligence, shipped as a single compiled Rust binary named `contextro`. It gives coding agents a compact, queryable view of code, graph edges, git history, memory, and indexed docs so they can retrieve the minimum useful context instead of brute-force reading dozens of files.

The operating model is simple: install once, connect your MCP client, run `index(path)`, then query symbols, behavior, impact, and stored context over stdio or HTTP. The index persists on disk, so repeated sessions start from a much smaller search surface.

Without Contextro

Search manually, open multiple files, inspect imports, and spend tokens reconstructing the call chain every time the question changes.

With Contextro

Ask for the behavior, receive the relevant slice, related symbols, and confidence signal, then continue with a smaller and cleaner context window.

Installation

Most users should install from npm or run via `npx`. Pre-built binaries are published for supported platforms, and source builds are available when you're developing Contextro itself. 

npm install -g contextro
npx contextro@latest
cargo install --path contextro-server

Use the Cargo path only for source builds from the repository workspace.

Compatibility

  • Single compiled Rust binary, no Python runtime required
  • macOS (Apple Silicon + Intel), Linux (x86_64 + ARM64), and Windows (x86_64)
  • Claude Code, Claude Desktop, Cursor, Windsurf, and generic MCP clients
  • Docker image available at `ghcr.io/distillation-labs/contextro-mcp:latest`

Quickstart

01

Install

npm install -g contextro

02

Register server

claude mcp add contextro -- contextro

03

Index repository

index(path="/path/to/project")

04

Query behavior

search(query="how does authentication work")

Client configuration

Claude Code

claude mcp add contextro -- contextro

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "contextro": {
      "command": "contextro"
    }
  }
}

Use `npx -y contextro@latest` when you want a zero-install shared config.

HTTP mode

CTX_TRANSPORT=http CTX_HTTP_HOST=0.0.0.0 CTX_HTTP_PORT=8000 contextro

Exposes `GET /health` and `POST /mcp` for local services and container deployments.

Configuration

Contextro uses `CTX_` environment variables for runtime behavior. The defaults work well for local development, while Docker and HTTP setups usually add explicit path mapping and warm-start settings.

Variable Example Purpose
CTX_STORAGE_DIR ~/.contextro Base directory for indexes, caches, memory, and session state.
CTX_EMBEDDING_MODEL potion-code-16m Local embedding model used for semantic retrieval.
CTX_TRANSPORT stdio Use `stdio` for local MCP clients or `http` for service and container deployments.
CTX_HTTP_HOST 0.0.0.0 Bind address when running in HTTP mode.
CTX_HTTP_PORT 8000 Port exposed by the HTTP transport.
CTX_PATH_PREFIX_MAP /host/repo:/repos/platform Optional host-to-container path remap for mounted repositories.

Command reference

Contextro ships 35 MCP tools. These are the ones most teams reach for first when they start using it day to day.

Start here

status()

Check whether a repository is indexed, which branch is active, and whether the server is ready.

index(path="/path/to/project")

Index a codebase once, then refresh incrementally after changes.

overview()

Summarize repository structure, languages, and dominant directories.

architecture()

Map layers, hubs, boundaries, and entry points.

Search & change safety

search(query="authentication flow")

Hybrid semantic, keyword, and graph retrieval for behavior-oriented questions.

find_symbol(name="IndexingPipeline")

Locate a symbol even when the name is approximate.

impact(symbol_name="TokenBudget")

Estimate what breaks before you rename, delete, or move shared code.

code(operation="pattern_search", ...)

Run AST-based symbol search, structural search, and rewrites.

commit_search(query="payment flow refactor")

Search git history by meaning, not only by exact text.

Memory & knowledge

remember(content="...")

Store decisions, conventions, and debugging notes for later reuse.

knowledge(command="add", ...)

Index docs, notes, or directories alongside the codebase.

restore()

Rebuild project context when you return to the repo later.

compact(content="...")

Archive large session context and retrieve it on demand.

Indexing model

Chunking

Splits code into symbol-aware slices so functions, classes, and related context stay retrievable as coherent units.

Embeddings

Builds vector representations for semantic search using a code-oriented embedding model optimized for local speed.

Graph

Stores symbol relationships, call edges, and architectural connections to make dependency-aware retrieval possible.

Warm start and incremental updates

Persists indexes to disk, restores them on restart, and reprocesses only changed files instead of rebuilding everything from scratch.

Retrieval pipeline

  1. Step 01

    Reuse cached results when the query or repo state already matches.

  2. Step 02

    Run vector, BM25, and graph retrieval in parallel against the indexed codebase.

  3. Step 03

    Apply exact-match boosts and fallback handling for strong lexical hits.

  4. Step 04

    Fuse candidates with reciprocal rank fusion.

  5. Step 05

    Optionally rerank the shortlist for higher precision.

  6. Step 06

    Apply diversity penalties so one file does not dominate the answer.

  7. Step 07

    Compress snippets with AST-aware rules before returning them to the model.

  8. Step 08

    Sandbox large responses instead of flooding the client with raw output.

  9. Step 09

    Attach compact metadata and confidence signals to the final result set.

Memory

Contextro can keep repository-scoped and session-scoped notes so the agent preserves architectural decisions, naming rules, migration details, and operational knowledge over time. This is especially useful when the same project is revisited repeatedly across many sessions.

A practical pattern is to store stable conventions in repo memory, use session memory for temporary plans or debugging state, and use `knowledge()` for external docs and notes that should stay queryable beside the codebase.

Good memory candidates

  • Build commands and environment assumptions
  • Routing conventions and naming rules
  • Verified architectural boundaries
  • Known failure modes and their fixes

Performance

Cold start

<50ms

Warm search latency

<1ms

Indexing guidance

~2s for 3,000 files

Idle memory

<50MB

Binary size

~9MB stripped

Tool surface

35 MCP tools

Troubleshooting

Agent cannot launch Contextro

Verify `command -v contextro` returns a binary and that your MCP client points to `contextro`. For zero-install setups, use `npx -y contextro@latest`.

Results feel stale after a refactor

Run `index(path="/path/to/project")` again. Contextro refreshes incrementally, but large branch switches or moved directories still need a re-index.

Docker paths do not match host paths

Set `CTX_CODEBASE_HOST_PATH`, `CTX_CODEBASE_MOUNT_PATH`, and `CTX_PATH_PREFIX_MAP` so the server can map client paths to the mounted repository.

Global install finished but `contextro` is not found

Check your npm global bin directory is on `PATH`, or use `npx contextro@latest` to run without a global install.