Compendio MCP

Your project's documentation, served to any agent in the fewest possible tokens.

A local RAG retrieval layer exposed as an MCP server. Your agent stops grepping and dumping whole files — it reaches the right paragraph instead.

What it does • Requirements • Quick Start • Configuration • MCP Tools • CLI • How it works • Incremental sync • Multilingual • Full docs

---

The problem

Your agent doesn't know your documentation. So it does what it can: grep, then cat a 400-line file to answer a question that lived in one paragraph. Three files later the context window is full of noise and the answer is still a guess.

Attaching the whole docs/ folder doesn't fix it — it just moves the waste earlier. Neither does keyword search: nobody writes questions using the exact words the document uses.

Same question, same model, and both answers are correct — the difference is what it cost to get there.

6 tool calls • 29s • 32,301 tokens → 2 tool calls • 12s • 17,684 tokens .

Figures read from OpenCode's own elapsed label and cost tooltip, on an 81-document corpus.

What Compendio does

Compendio indexes your markdown documentation and gives any AI agent three tools to find and read exactly what it needs.

• 🔍 Hybrid retrieval, not grep — keyword search finds the exact term, semantic search finds the paraphrase. Compendio runs both and merges the results.
• ✂️ Token-frugal by design — orient for ~10 tokens per document, search for a handful of fragments, read a single section. Never the whole corpus.
• 🔒 100% local — one SQLite file, embeddings on CPU, zero network calls at query time. No API keys, no Docker, no services, nothing leaves your machine.
• ♻️ Stays current — a running server picks up your documentation edits on its own. No watcher process, no manual rebuild loop.
• 🗣️ Multilingual — index documentation in any language. The embeddings model is multilingual and search is diacritic-insensitive. See Multilingual.
• 🧩 Zero configuration — works on *any* folder of .md files. No required frontmatter, no config file. An optional documentation convention is there if your team already has a taxonomy to enforce.

Requirements

• Node.js ≥ 22.12.
• Nothing else.

Quick start

1. Install it.

npm install -g compendio-mcp

To update an existing installation:

compendio update

2. Register it as an MCP server in your client:

compendio install-mcp <agent>

Supported agents: claude, claude-desktop, cursor, vscode, opencode, codex, zed.

For manual installation or agents not supported by this command (Windsurf, Cline, Gemini CLI), see Manual Installation.

3. Build the index once, from the project root:

compendio index

That's it. With no config file, Compendio auto-discovers top-level folders that contain Markdown files — no hidden docs/ default needed. Add .compendio/ to your .gitignore.

Why this step exists. The server also indexes on startup, so strictly speaking you could skip it — but the first run downloads and caches the embeddings model (tens of MB), and whoever triggers it waits. Running it here pays that cost in your terminal, with a progress bar, instead of inside your agent's first tool call. From then on everything is offline, and the index keeps itself up to date (below).

Windows note. Some MCP clients can't spawn the compendio.cmd shim directly. If the server fails to start with ENOENT, use "command": "npx" with "args": ["compendio-mcp", "serve"].

Configuration

Entirely optional — Compendio works with no config file at all. Create compendio.config.json at your project root only to override what you need:

{

"docsDir": ["docs"], "exclude": ["INDEX.md"], "db": ".compendio/compendio.db", "embeddings": { "provider": "local", "model": "Xenova/multilingual-e5-small" }, "chunk": { "minTokens": 100, "maxTokens": 480 }, "search": { "k": 5 }, "sync": { "throttleMs": 30000 }, "convention": { "mode": "loose", "excludedStatuses": [], "frontmatterFields": { "type": "type", "module": "module", "status": "status" } } }

Declaring only part of the convention block merges with the defaults field by field; it never wipes the siblings you didn't mention. frontmatterFields maps type/module/status onto non-standard frontmatter keys (e.g. { "status": "estado" } reads a Spanish document's estado: field as status).

Every numeric key (search.k, chunk.minTokens, chunk.maxTokens, sync.throttleMs) is honored only when it is a finite number greater than 0 — search.k must additionally be a whole number. Anything else, including a quoted number like "480", falls back to the default exactly as an absent key would, and the fallback is reported: on stderr for every CLI command, and in docs_overview's response for an MCP client. An unrecognized key under embeddings, chunk or convention.frontmatterFields (a typo such as maxtokens) is reported the same way. A config with nothing wrong reports nothing.

Multiple documentation roots

Declare more than one root to index several folders — adr/, rfcs/, a spec directory — as one searchable corpus:

{ "docsDir": ["docs", "openspec"], "exclude": ["INDEX.md", "openspec/changes/archive"] }

Every document path is prefixed with its root's alias — the directory's own name, so docs/x.md and openspec/specs/y.md both read as the real project-relative path. This holds with a single explicit root and with discovered roots too: openspec/specs/y.md, not specs/y.md. search_docs, docs_overview, read_doc and the generated INDEX.md all use this prefixed shape; passing a path back to read_doc exactly as returned always resolves.

Declared roots may not collide: two roots resolving to the same directory, one nested inside another (in either declaration order), or two roots sharing the same directory name (and therefore the same alias) are all rejected before anything is indexed. A root that is declared but cannot be read (a typo, or a folder only some checkouts have) is reported and skipped — the run continues on the remaining roots, and only throws if every declared root fails. Removing a root from docsDir deletes its documents on the next sync pass, same as deleting the files themselves would.

In discovery mode, Compendio rescans top-level folders on every index, sync, and serve sync pass, selects those with .md files anywhere below them, skips symlinked content and generated/internal folders such as .git, .compendio, node_modules, dist, build, and coverage, and writes INDEX.md at the project root. Discovery fails closed: malformed top-level config JSON, unreadable candidate trees, traversal/read failures, or a previously indexed discovered root that disappears or becomes a symlink/junction before sync abort before mutating the index. A previously indexed root that is still a readable directory is still traversed even after its last Markdown file is deleted, so legitimate deletions are reconciled normally. The symlink checks use lstat/realpath at scan/traversal time, but they are not a kernel-level sandbox; a filesystem race between check and read remains out of scope. --dir (below) is explicit mode: it replaces the whole declared/discovered root set with that one directory and writes INDEX.md inside it.

Works with your SDD framework

Spec-driven development frameworks keep their planning artifacts in Markdown, which is exactly what Compendio indexes. Point docsDir at the folders your framework writes to:

Hidden directories such as .specify/ and .kiro/ are indexed normally, both as declared roots and in discovery mode — dot-prefixed *entries inside* a root are what gets skipped, not the root itself. So with no config file at all, a Spec Kit or Kiro project already indexes.

Three things worth knowing before you copy a line:

• A root's alias is its directory name, not the path you declared. .kiro/specs is aliased specs, so its documents come back as specs/auth/design.md. That also means it collides with a top-level specs/ root and