Distillation Labs

Distillation Labs / Contextro / Dokumentacja

Docs Contextro

Instalacja, transport, konfiguracja i notatki workflow dla uruchamiania Contextro jako lokalnego serwera MCP w prawdziwych workflowach developerskich.

Strona produktu GitHub ↗

Przeglad

Contextro to lokalny serwer MCP dla inteligencji repozytorium, dostarczany jako pojedynczy skompilowany binarny program Rust o nazwie `contextro`. Daje agentom kodujacym zwarty, odpytywalny widok kodu, grafu, historii gita, pamieci i zindeksowanych docs, aby pobierac minimalny uzyteczny kontekst.

Model operacyjny jest prosty: zainstaluj raz, podlacz klienta MCP, uruchom `index(path)`, a potem odpytuj symbole, zachowanie, impact i zapisany kontekst przez stdio lub HTTP. Indeks utrzymuje sie na dysku, wiec kolejne sesje startuja z duzo mniejsza powierzchnia wyszukiwania.

Bez Contextro

Szukasz recznie, otwierasz wiele plikow, sprawdzasz importy i zuzywasz tokeny na odbudowywanie lancucha wywolan za kazdym razem, gdy zmienia sie pytanie.

Z Contextro

Pytasz o zachowanie, dostajesz wlasciwy fragment, powiazane symbole i sygnal pewnosci, a potem kontynuujesz z mniejszym i czystszym oknem kontekstu.

Instalacja

Wiekszosc uzytkownikow powinna instalowac z npm albo uruchamiac przez `npx`. Dla wspieranych platform dostepne sa gotowe binarki, a buildy ze zrodla sa mozliwe przy rozwoju samego Contextro. 

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

Uzywaj sciezki Cargo tylko dla buildow ze zrodla w workspace repozytorium.

Kompatybilnosc

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

Szybki start

01

Zainstaluj

npm install -g contextro

02

Zarejestruj serwer

claude mcp add contextro -- contextro

03

Zindeksuj repozytorium

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

04

Zapytaj o zachowanie

search(query="how does authentication work")

Konfiguracja klienta

Claude Code

claude mcp add contextro -- contextro

Claude Desktop / Cursor / Windsurf

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

Uzyj `npx -y contextro@latest`, kiedy chcesz wspoldzielona konfiguracje bez globalnej instalacji.

HTTP mode

CTX_TRANSPORT=http CTX_HTTP_HOST=0.0.0.0 CTX_HTTP_PORT=8000 contextro

Udostepnia `GET /health` i `POST /mcp` dla lokalnych uslug i wdrozen kontenerowych.

Konfiguracja

Contextro uzywa zmiennych `CTX_` do sterowania zachowaniem runtime. Domyslne wartosci dzialaja dobrze lokalnie, a Docker i HTTP czesto dodaja jawne mapowanie sciezek i warm start.

Zmienna Przyklad Cel
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.

Referencja komend

Contextro dostarcza 35 narzedzi MCP. To te, po ktore zespoly najczesciej siegaja na poczatku codziennej pracy.

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.

Model indeksowania

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 retrieval

  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.

Pamiec

Contextro moze przechowywac notatki scoped do repozytorium i sesji, aby agent zachowywal decyzje architektoniczne, reguly nazewnictwa, szczegoly migracji i wiedze operacyjna w czasie.

Praktyczny wzorzec to trzymanie stabilnych konwencji w pamieci repozytorium, wykorzystywanie pamieci sesji dla tymczasowych planow lub stanu debugowania oraz `knowledge()` dla zewnetrznych docs i notatek, ktore maja pozostac odpytywalne obok kodu.

Dobrzy kandydaci do pamieci

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

Wydajnosc

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

Rozwiazywanie problemow

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.