mcp-docpilot-server

An MCP server that exposes document retrieval as tools any LLM provider can call. It puts a single, stable interface in front of a vector index (built from DocPilot's ingestion pipeline) so a model never has to know how the documents are stored or which embedding backend is in use - it just calls docpilot_search.

The server provides the tools and data access; the connected model does the generation. That split is what makes it provider-agnostic: Claude Desktop, or any client that speaks MCP, gets the same retrieval tools.

Tools

Tool	What it does
docpilot_search	Semantic search over the corpus; returns ranked chunks with source and score
docpilot_list_sources	Lists indexed source documents with per-source chunk counts

Both tools are read-only.

How it works

docs/*.md ──ingest.py──> chunk + embed ──> ChromaDB (persistent)
                                              │
                          server.py exposes ──┤── docpilot_search
                          MCP tools over      └── docpilot_list_sources
                          stdio or HTTP
                                              │
            Claude Desktop / any MCP client ──┘  (model calls the tools)

Setup

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Build the index from the docs folder (swap in your own .txt/.md files)
python ingest.py ./docs

Embeddings use ChromaDB's local default model, so it runs with no API key. To point it at a hosted embedding provider instead, set a ChromaDB embedding function in ingest.py and server.py - the rest of the pipeline is unchanged.

Run

stdio (local clients like Claude Desktop):

python server.py

Streamable HTTP (remote server):

DOCPILOT_TRANSPORT=http python server.py
# serves MCP at http://localhost:8000/mcp

The SDK's HTTP transport supersedes the older SSE transport; point HTTP-based MCP clients at the /mcp endpoint.

Connect to Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "docpilot": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-docpilot-server/server.py"],
      "env": {
        "DOCPILOT_CHROMA_PATH": "/absolute/path/to/mcp-docpilot-server/chroma"
      }
    }
  }
}

Or, for an HTTP server:

claude mcp add --transport http docpilot http://localhost:8000/mcp

Configuration

Env var	Default	Meaning
DOCPILOT_CHROMA_PATH	./chroma	Persistent ChromaDB store
DOCPILOT_COLLECTION	docpilot	Collection name
DOCPILOT_TRANSPORT	stdio	stdio or http
DOCPILOT_CHUNK_SIZE	800	Characters per chunk (ingest)
DOCPILOT_CHUNK_OVERLAP	100	Overlap between chunks (ingest)
DOCPILOT_EMBEDDINGS	default	default (local ONNX model) or hash (offline, for CI/tests)

Switching the embedding backend changes the vector space, so re-ingest into a fresh store when you change it (rm -rf chroma && python ingest.py ./docs). All backend selection lives in embeddings.py - that one file is the seam for the embedding lifecycle.

Test

pytest -q

The test ingests a tiny corpus and confirms retrieval ranks the expected document first. CI runs it on every push (.github/workflows/ci.yml).