Distillation Labs

Distillation Labs / Contextro / Documentatie

Contextro docs

Installatie, transport, configuratie en workflownotities voor het draaien van Contextro als lokale MCP server in echte ontwikkelworkflows.

Productpagina GitHub ↗

Overzicht

Contextro is een lokale MCP server voor repository intelligence, geleverd als een enkele gecompileerde Rust binary met de naam `contextro`. Het geeft coding agents een compact, bevraagbaar beeld van code, grafen, githistorie, geheugen en geindexeerde docs zodat alleen de minimaal nuttige context wordt opgehaald.

Het werkmodel is eenvoudig: een keer installeren, je MCP client verbinden, `index(path)` draaien en daarna symbolen, gedrag, impact en opgeslagen context opvragen over stdio of HTTP. De index blijft op schijf staan, zodat herhaalde sessies met een veel kleiner zoekoppervlak starten.

Zonder Contextro

Je zoekt handmatig, opent meerdere bestanden, inspecteert imports en verspilt tokens aan het opnieuw reconstrueren van de call chain telkens wanneer de vraag verandert.

Met Contextro

Je vraagt naar gedrag, krijgt de relevante slice, verwante symbolen en een vertrouwenssignaal terug en gaat verder met een kleiner en schoner contextvenster.

Installatie

De meeste gebruikers moeten installeren via npm of draaien via `npx`. Voor ondersteunde platforms zijn voorgebouwde binaries beschikbaar en source builds zijn mogelijk wanneer je Contextro zelf ontwikkelt. 

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

Gebruik het Cargo pad alleen voor source builds uit de repository workspace.

Compatibiliteit

  • 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`

Snelstart

01

Installeren

npm install -g contextro

02

Server registreren

claude mcp add contextro -- contextro

03

Repository indexeren

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

04

Gedrag opvragen

search(query="how does authentication work")

Client configuratie

Claude Code

claude mcp add contextro -- contextro

Claude Desktop / Cursor / Windsurf

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

Gebruik `npx -y contextro@latest` als je een zero install gedeelde configuratie wilt.

HTTP mode

CTX_TRANSPORT=http CTX_HTTP_HOST=0.0.0.0 CTX_HTTP_PORT=8000 contextro

Biedt `GET /health` en `POST /mcp` voor lokale services en containerdeployments.

Configuratie

Contextro gebruikt `CTX_` omgevingsvariabelen voor runtimegedrag. De defaults werken goed voor lokale ontwikkeling, terwijl Docker en HTTP vaak expliciete path mapping en warm start instellingen toevoegen.

Variabele Voorbeeld Doel
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.

Commandoreferentie

Contextro levert 35 MCP tools. Dit zijn de tools waar teams in dagelijks werk het eerst naar grijpen.

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.

Indexeringsmodel

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.

Geheugen

Contextro kan repository en sessiegebonden notities bewaren zodat de agent architectuurbeslissingen, naamgevingsregels, migratiedetails en operationele kennis in de tijd bewaart.

Een praktisch patroon is om stabiele conventies in repogeheugen te bewaren, sessiegeheugen te gebruiken voor tijdelijke plannen of debugstatus en `knowledge()` te gebruiken voor externe docs en notities die naast de code bevraagbaar moeten blijven.

Goede kandidaten voor geheugen

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

Prestaties

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

Probleemoplossing

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.