Distillation Labs

Distillation Labs / Contextro / Dokumentation

Contextro Docs

Installation, Transport, Konfiguration und Workflow Hinweise fur den Einsatz von Contextro als lokaler MCP Server in echten Entwicklungsworkflows.

Produktseite GitHub ↗

Uberblick

Contextro ist ein lokaler MCP Server fur Repository Intelligence, ausgeliefert als einzelnes kompiliertes Rust Binary mit dem Namen `contextro`. Er gibt Coding Agents eine kompakte, abfragbare Sicht auf Code, Graph Kanten, Git Historie, Memory und indexierte Docs, sodass nur das minimal nutzliche Kontextpaket geholt wird.

Das Betriebsmodell ist einfach: einmal installieren, MCP Client verbinden, `index(path)` ausfuhren und dann Symbole, Verhalten, Impact und gespeicherten Kontext uber stdio oder HTTP abfragen. Der Index bleibt auf der Festplatte bestehen, sodass wiederholte Sitzungen mit einer kleineren Suchflache starten.

Ohne Contextro

Sie suchen manuell, offnen mehrere Dateien, inspizieren Imports und verbrauchen Tokens, um die Aufrufkette jedes Mal neu zu rekonstruieren.

Mit Contextro

Sie fragen nach dem Verhalten, erhalten den relevanten Ausschnitt, verwandte Symbole und ein Vertrauenssignal und machen dann mit einem kleineren, saubereren Kontextfenster weiter.

Installation

Die meisten Nutzer sollten uber npm installieren oder via `npx` starten. Vorgebaute Binaries werden fur unterstutzte Plattformen veroffentlicht, und Quell Builds sind verfugbar, wenn Sie Contextro selbst entwickeln. 

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

Verwenden Sie den Cargo Pfad nur fur Source Builds aus dem Repository Workspace.

Kompatibilitat

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

Schnellstart

01

Installieren

npm install -g contextro

02

Server registrieren

claude mcp add contextro -- contextro

03

Repository indexieren

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

04

Verhalten abfragen

search(query="how does authentication work")

Client Konfiguration

Claude Code

claude mcp add contextro -- contextro

Claude Desktop / Cursor / Windsurf

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

Verwenden Sie `npx -y contextro@latest`, wenn Sie eine Zero Install Shared Config wollen.

HTTP mode

CTX_TRANSPORT=http CTX_HTTP_HOST=0.0.0.0 CTX_HTTP_PORT=8000 contextro

Stellt `GET /health` und `POST /mcp` fur lokale Services und Container Deployments bereit.

Konfiguration

Contextro verwendet `CTX_` Umgebungsvariablen fur das Runtime Verhalten. Die Defaults passen fur lokale Entwicklung, wahrend Docker und HTTP oft explizites Path Mapping und Warm Start Einstellungen hinzufugen.

Variable Beispiel Zweck
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.

Befehlsreferenz

Contextro liefert 35 MCP Tools. Das sind die Werkzeuge, zu denen Teams im Alltag zuerst greifen.

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.

Indexierungsmodell

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 kann repository und sessionbezogene Notizen behalten, damit der Agent Architekturentscheidungen, Namensregeln, Migrationsdetails und operatives Wissen uber die Zeit hinweg bewahrt.

Ein praktisches Muster ist, stabile Konventionen im Repo Memory zu speichern, Session Memory fur temporare Plane oder Debug Status zu nutzen und `knowledge()` fur externe Docs und Notizen zu verwenden, die neben dem Code abfragbar bleiben sollen.

Gute Kandidaten fur Memory

  • 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

Fehlersuche

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.