Documentation MCP Server

An MCP server that indexes documentation from git repositories and makes it searchable by AI agents. Designed to run as a containerized service on a home server, providing documentation context to agents via the Model Context Protocol.

Architecture

Git Repos (local/remote)
        |
        v
  [Ingestion Worker]    Subprocess spawned per cycle (~5 min), parses markdown,
        |               chunks text, embeds; exits and releases RSS to the OS
        |
        v
  [Knowledge Base]      SQLite (WAL mode) for metadata
        |               ChromaDB sidecar (HTTP) for vector embeddings
        |
        v
  [MCP Server]          FastMCP with streamable HTTP transport. Long-running,
        |               isolated from ingestion's memory + GIL pressure.
        |
        v
  AI Agent (nanoclaw)   Queries docs via MCP tools

Docker Compose services

docker compose up -d brings up three containers:

The chroma sidecar is required, not optional: chromadb >= 1.5.x corrupts its store when two PersistentClient instances open the same on-disk path, so the long-running server and the per-cycle ingestion worker need a single process owning the database. The HTTP server fills that role.

Related MCP server: Embeddings Searcher

MCP Tools

search_docs -- Hybrid search with reranking

Find documentation relevant to a natural language question. Two-stage hybrid pipeline: BM25 (SQLite FTS5) + dense vector (ChromaDB) candidates fused with Reciprocal Rank Fusion, then reranked by a cross-encoder for final ordering. Returns chunk-level results.

query_docs -- Structured metadata query

Query document metadata by source, path, title, or date range. Useful for questions like "list all docs in source Y" or "what was added after date Z".

get_document -- Retrieve by ID

Retrieve a specific document or chunk by its ID. Document IDs follow the format source_name:relative/path for parent documents, or source_name:relative/path#chunkN for chunks.

list_sources -- List sources and status

List all configured documentation sources and their indexing status. Returns source names, file counts, chunk counts, and last indexed time. Takes no parameters.

reindex -- Trigger re-indexing

Trigger an immediate re-indexing of documentation sources.

Health Endpoint

GET /health returns the current status of the knowledge base, the most recent ingestion cycle, and the chat model configuration.

200 OK — server is reachable. The body is a structured snapshot:

{
  "status": "healthy",
  "total_sources": 3,
  "total_chunks": 542,
  "poll_interval_seconds": 1800,
  "sources": [ /* per-source health */ ],
  "last_ingestion": {
    "completed_at": "2026-04-29T17:25:00+00:00",
    "duration_s": 4.2,
    "rss_at_end_mb": 240.0,
    "flush_count": 3
  },
  "last_ingestion_failure": null,
  "chat_model_valid": true,
  "chat_model_error": null
}

Notable fields:

• last_ingestion — duration and peak-RSS metrics from the most recent worker cycle. Populated only after the first cycle has run; null on a freshly started container.

• last_ingestion_failure — set when the most recent worker subprocess exited non-zero, timed out, or did not emit a metrics line. Useful for spotting silent ingestion stalls without scraping logs.

• chat_model_valid / chat_model_error — set by a startup probe that calls models.retrieve(DOCSERVER_CHAT_MODEL) on the Anthropic API. When false, /api/chat and /api/chat/stream short-circuit with HTTP 503 instead of letting every request fail at the API call.

503 Service Unavailable — knowledge base is unreachable or errored:

{"status": "error"}

This endpoint is used by the Docker health check configured in docker-compose.yml and by the webapp's depends_on: condition: service_healthy gate.

Quick Start

1. Configure sources

cp config/sources.example.yaml config/sources.yaml
# Edit config/sources.yaml to add your documentation repos

2. Set required secrets

The chat agent calls the Anthropic API. Either export ANTHROPIC_API_KEY in your shell before running compose, or write it into a local .env file (Docker Compose auto-loads .env from the project root):

echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

If you do not need the chat endpoints, set ANTHROPIC_API_KEY=unset (or any non-empty value) and skip them — the search and metadata MCP tools work without an Anthropic key.

3. Run with Docker Compose

docker-compose.yml is the canonical deploy file and it works out of the box: it brings up the three services with named volumes only, no host-specific bind mounts. If you want to index a directory that lives on the host filesystem, uncomment the example bind-mount stanza in the docserver service's volumes: block and add a matching sources: entry in config/sources.yaml whose path: points at the container-side mount.

docker compose up -d

This brings up three containers — chroma, docserver, and documentation-webapp — and two named volumes (chroma-data, docserver-data). The webapp waits for the docserver's /health to be green before starting; the docserver waits for the chroma sidecar to be reachable.

Host ports (per docker-compose.yml):

4. Connect from an MCP client

Add to your MCP client configuration (e.g., .mcp.json):

{
 "mcpServers": {
  "documentation": {
   "url": "http://localhost:8085/mcp"
  }
 }
}

Updating to a new release

The latest tag on each image is overwritten on every push to main. To pull a fresh build:

docker compose pull              # pulls all 3 images
docker compose up -d             # recreates containers using the new images

The persistent volumes (docserver-data, chroma-data) are preserved across this — no re-ingestion is needed unless the sidecar's storage format has changed in a major Chroma upgrade. Roll back with docker compose pull --policy never plus an explicit older tag if a release is broken.

Persistent volumes

config/sources.yaml is bind-mounted read-only into the docserver container — edit it on the host and run docker compose restart docserver to pick up changes (see docs/operations.md § Configuration Changes).

Configuration

sources.yaml

sources:
 - name: "my-docs"
   path: "/repos/my-docs" # Local path (mount in docker-compose)
   branch: "main"
   patterns:
    - "**/*.md"

 - name: "remote-docs"
   path: "https://github.com/user/repo.git"
   branch: "main"

poll_interval: 1800 # Seconds between index cycles (default: 1800 = 30 min)
data_dir: "/data" # Persistent storage path

Environment Variables

See docs/operations.md for the full table including all options.

Development

uv sync --group dev
uv run pytest tests/ -v

How It Works

1. Ingestion runs as a separate process. An IngesterSupervisor in the docserver process owns an APScheduler timer. On each tick (and on every POST /rescan), it spawns python -m docserver.ingestion_worker as a subprocess. The worker loads the embedding model, runs one cycle, and exits — its peak RSS is fully released to the OS, so the long-running docserver process stays at its small steady-state working set even when a cycle peaks high. If the worker OOMs or crashes, the docserver keeps serving requests; only the cycle is lost.

2. Sync. The worker polls configured git repos. For remote repos, it clones on first run then pulls updates. For local repos (mounted as volumes), it pulls if they have a remote, or just reads the files directly.

3. Parsing. Markdown files are parsed to extract titles (first # heading), creation dates (from git history), and modification times. Documents are split into ~400-character chunks at section and paragraph boundaries, with each chunk prefixed by its heading hierarchy (e.g. [Setup > Ports]) and ~100 chars of overlap between chunks. Lists and code fences are kept intact.

4. Storage. Parent document metadata goes into SQLite (in WAL mode so the docserver can read while the worker writes). Each chunk lands in three places: the SQLite documents table (raw content + metadata), the chunks_fts FTS5 virtual table (BM25 inverted index over content + title), and the ChromaDB sidecar (dense embeddings). Only pre-computed vectors cross the wire to Chroma, so the sidecar stays small (~256 MB).

5. Search. Two-stage hybrid pipeline. L1: SQLite FTS5 BM25 and ChromaDB cosine each return their top-100 candidates; results are merged with Reciprocal Rank Fusion (k=60) and the top 50 chunks pass to L2. L2: a cross-encoder (ms-marco-MiniLM-L6-v2, ONNX int8) reranks the candidates with full query–passage attention, then dedup-to-parent picks the best chunk per parent. Both models are pre-baked into the Docker image so cold start avoids any network download.

6. Serving. The FastMCP server exposes tools over streamable HTTP. Agents can search hybrid-style, query by metadata, or retrieve specific documents. A /health endpoint returns indexing status (including the most recent worker cycle's RSS / duration) for container orchestration and operator visibility.