Distillation Labs

Distillation Labs / Contextro / Documentacion

Docs de Contextro

Instalacion, transporte, configuracion y notas de flujo de trabajo para usar Contextro como servidor MCP local en flujos reales de desarrollo.

Producto GitHub ↗

Resumen

Contextro es un servidor MCP local para inteligencia de repositorios, distribuido como un binario Rust compilado llamado `contextro`. Les da a los agentes una vista compacta y consultable de codigo, grafo, historial git, memoria y docs indexadas para recuperar el minimo contexto util.

El modelo operativo es simple: instala una vez, conecta tu cliente MCP, ejecuta `index(path)` y luego consulta simbolos, comportamiento, impacto y contexto guardado sobre stdio o HTTP. El indice persiste en disco para que las sesiones repetidas empiecen con una superficie de busqueda mucho mas pequena.

Sin Contextro

Buscas manualmente, abres multiples archivos, inspeccionas imports y gastas tokens reconstruyendo la cadena de llamadas cada vez que cambia la pregunta.

Con Contextro

Pides el comportamiento, recibes la porcion relevante, simbolos relacionados y una senal de confianza, y continuas con una ventana de contexto mas pequena y limpia.

Instalacion

La mayoria de los usuarios deberia instalar desde npm o ejecutar via `npx`. Hay binarios para plataformas soportadas y compilaciones desde fuente para desarrollo de Contextro. 

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

Usa la ruta de Cargo solo para builds desde la fuente del workspace del repositorio.

Compatibilidad

  • Binario Rust unico, sin runtime de Python
  • macOS, Linux y Windows en plataformas soportadas
  • Claude Code, Claude Desktop, Cursor, Windsurf y clientes MCP genericos
  • Imagen Docker disponible en `ghcr.io/distillation-labs/contextro-mcp:latest`

Inicio rapido

01

Instalar

npm install -g contextro

02

Registrar servidor

claude mcp add contextro -- contextro

03

Indexar repositorio

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

04

Consultar comportamiento

search(query="how does authentication work")

Configuracion de clientes

Claude Code

claude mcp add contextro -- contextro

Claude Desktop / Cursor / Windsurf

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

Usa `npx -y contextro@latest` cuando quieras una configuracion compartida sin instalacion global.

HTTP mode

CTX_TRANSPORT=http CTX_HTTP_HOST=0.0.0.0 CTX_HTTP_PORT=8000 contextro

Expone `GET /health` y `POST /mcp` para servicios locales y despliegues en contenedores.

Configuracion

Contextro usa variables `CTX_` para comportamiento de runtime. Los valores por defecto funcionan bien en desarrollo local, mientras que Docker y HTTP suelen agregar mapeo de rutas y warm-start explicito.

Variable Ejemplo Proposito
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.

Referencia de comandos

Contextro trae 35 herramientas MCP. Estas son las que mas equipos usan primero en el trabajo diario.

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.

Modelo de indexado

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 recuperacion

  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.

Memoria

Contextro puede conservar notas del repositorio y de la sesion para que el agente preserve decisiones de arquitectura, reglas de nombres, detalles de migracion y conocimiento operativo a lo largo del tiempo.

Un patron practico es guardar convenciones estables en memoria de repo, usar memoria de sesion para planes temporales o estado de depuracion y usar `knowledge()` para docs y notas externas consultables junto al codigo.

Buenos candidatos para memoria

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

Rendimiento

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

Resolucion de problemas

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.