Distillation Labs

Distillation Labs / Contextro / Documentation

Docs Contextro

Installation, transport, configuration et notes de workflow pour executer Contextro comme serveur MCP local dans de vrais workflows de developpement.

Produit GitHub ↗

Vue d ensemble

Contextro est un serveur MCP local pour l intelligence de depot, distribue comme un binaire Rust compile nomme `contextro`. Il donne aux agents de code une vue compacte et interrogeable du code, du graphe, de l historique git, de la memoire et des docs indexees afin de recuperer le minimum de contexte utile.

Le modele operatoire est simple: installez une fois, connectez votre client MCP, lancez `index(path)`, puis interrogez symboles, comportement, impact et contexte stocke sur stdio ou HTTP. L index persiste sur disque, donc les sessions suivantes demarrent avec une surface de recherche beaucoup plus petite.

Sans Contextro

Vous cherchez manuellement, ouvrez plusieurs fichiers, inspectez les imports et depensez des tokens a reconstruire la chaine d appels a chaque changement de question.

Avec Contextro

Vous demandez un comportement, recevez la tranche pertinente, les symboles lies et un signal de confiance, puis continuez avec une fenetre de contexte plus petite et plus propre.

Installation

La plupart des utilisateurs devraient installer depuis npm ou executer via `npx`. Des binaires sont publies pour les plateformes supportees, et des builds source sont disponibles si vous developpez Contextro lui-meme. 

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

Utilisez le chemin Cargo uniquement pour les builds source depuis le workspace du depot.

Compatibilite

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

Demarrage rapide

01

Installer

npm install -g contextro

02

Enregistrer le serveur

claude mcp add contextro -- contextro

03

Indexer le depot

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

04

Interroger le comportement

search(query="how does authentication work")

Configuration client

Claude Code

claude mcp add contextro -- contextro

Claude Desktop / Cursor / Windsurf

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

Utilisez `npx -y contextro@latest` si vous voulez une configuration partagee sans installation globale.

HTTP mode

CTX_TRANSPORT=http CTX_HTTP_HOST=0.0.0.0 CTX_HTTP_PORT=8000 contextro

Expose `GET /health` et `POST /mcp` pour les services locaux et les deploiements conteneurises.

Configuration

Contextro utilise des variables `CTX_` pour le comportement runtime. Les valeurs par defaut fonctionnent bien en local, tandis que Docker et HTTP ajoutent souvent un mappage de chemins et un warm-start explicites.

Variable Exemple But
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.

Reference des commandes

Contextro expose 35 outils MCP. Ce sont ceux que les equipes utilisent le plus souvent au quotidien.

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.

Modele d indexation

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.

Pipeline de recuperation

  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.

Memoire

Contextro peut conserver des notes portees par le depot et par la session afin que l agent preserve les decisions d architecture, les regles de nommage, les details de migration et la connaissance operationnelle dans le temps.

Un schema pratique consiste a stocker les conventions stables dans la memoire du depot, a utiliser la memoire de session pour les plans temporaires ou l etat de debug, et `knowledge()` pour les docs et notes externes qui doivent rester interrogeables a cote du code.

Bons candidats pour la memoire

  • 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

Depannage

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.