compendio-mcp

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.

Related MCP server: QMD - Query Markdown

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.

• 🗣️ Spanish-first — the tool contract, the accent handling and the reference corpus are built for Spanish documentation. See Spanish-first, by design.

• 🧩 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 ≥ 20.

• Nothing else.

Quick start

1. Install it.

npm install -g compendio-mcp

To update Compendio later, run that same command again — it always pulls the latest published version.

2. Register it as an MCP server in your client, pointed at your project root.

Claude Code (.mcp.json at the repo root):

{
  "mcpServers": {
    "compendio": {
      "command": "compendio",
      "args": ["serve"]
    }
  }
}

OpenCode (opencode.json):

{
  "mcp": {
    "compendio": {
      "type": "local",
      "command": ["compendio", "serve"],
      "enabled": true
    }
  }
}

VS Code / Copilot (.vscode/mcp.json):

{
  "servers": {
    "compendio": {
      "type": "stdio",
      "command": "compendio",
      "args": ["serve"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "compendio": {
      "command": "compendio",
      "args": ["serve"]
    }
  }
}

3. That's it. By default Compendio reads docs/ at the project root. On startup the server indexes everything it finds — no separate index step, no config file. Add .compendio/ to your .gitignore.

First run is the slow one. The embeddings model (tens of MB) is downloaded and cached the first time, and your agent's first tool call waits for it. To pay that cost up front, run compendio index once from the project root before starting the client. From then on everything is offline.

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 — every field has a default, and 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": 800 },
  "search": { "k": 5 },
  "sync": { "throttleMs": 30000 },
  "convencion": {
    "modo": "libre",
    "estadosExcluidos": [],
    "camposFrontmatter": { "tipo": "tipo", "modulo": "modulo", "estado": "estado" }
  }
}

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

Documentation convention (optional)

Two modes, selected by convencion.modo:

• libre (default, zero-config) — never rejects a file for missing metadata. The title comes from the first H1 (falling back to a humanized filename), the module is inferred from the folder, and tipo/estado are read from frontmatter when present and left absent otherwise.

• estricto (opt-in) — a linter: every document needs an H1 and non-empty tipo/modulo/estado, validated against the lists your project declares. Files that fail are skipped and reported, never breaking the run.

{
  "convencion": {
    "modo": "estricto",
    "tipos": ["funcional", "adr", "api", "qa", "guia"],
    "estados": ["borrador", "vigente", "obsoleto"],
    "estadosExcluidos": ["borrador", "obsoleto"]
  }
}

estadosExcluidos hides documents from search by lifecycle state — drafts and deprecated pages stop polluting results. See docs/convencion-documentacion.md for the full convention this repository's own docs follow.

MCP tools

Designed as progressive disclosure: orient cheaply → search cheaply → read only what is needed.

1. docs_overview() — the corpus map. Counts by type and module, plus one line per document. Roughly 10 tokens per document.

2. search_docs({ query, tipo?, modulo?, etiquetas?, k?, incluir_no_vigentes? }) — the top k fragments (5 by default, at most 2 per document), each with path, section, excerpt and score. tipo is an open, project-defined string, not a fixed list.

3. read_doc({ ruta, seccion? }) — one section, or the whole document. A path that doesn't exist returns the 3 most similar paths instead of an error, so the agent self-corrects instead of retrying blind.

CLI

Global option -C, --root <dir>: project root. Add --lexico to index or search to skip embeddings entirely.

How it works

docs/**/*.md
     │
     ├─▶ split into fragments at heading boundaries (tables are never cut)
     │
     ├─▶ index each fragment twice ─┬─ full-text (keywords)
     │                              └─ embeddings (meaning)
     │
     └─▶ one file: .compendio/compendio.db

At query time both indexes are searched independently and their rankings are merged with Reciprocal Rank Fusion — a rank-based merge with no weights to tune blindly. The agent gets back the smallest set of relevant fragments.

Compendio is the retrieval half of RAG. It never calls an LLM and generates nothing: it finds the right paragraphs and gets out of the way.

If the embeddings model is unavailable, Compendio doesn't crash — it degrades to keyword-only search and says so in its responses.

Incremental reindex

Documentation changes while you work, and Compendio keeps up on its own.

A running server reindexes at startup and then, at most once per throttle window (30 s by default), whenever your agent calls a tool. Each pass compares content hashes against what's already indexed, so only new, changed and deleted documents do any work — an unchanged corpus costs nothing. If a pass fails, it's logged and the tool still answers against the current index.

compendio index remains the authoritative full rebuild. Reach for it after a large restructuring, or if you ever suspect the index has drifted.

Spanish-first, by design

Compendio is built for Spanish-language documentation, and that shows up in the product, not just the examples:

• The MCP contract is in Spanish. Tool parameters (ruta, tipo, modulo, etiquetas, seccion), response fields and the tool descriptions the agent reads are all Spanish. Agents reason about your docs in the same language your team writes them in.

• Accents are handled properly. Search is diacritic-insensitive, so validación and validacion match. In a Spanish corpus this is not a nicety — accent-sensitive search silently loses results.

• The reference corpus and evaluation set are Spanish. The quality numbers below reflect real Spanish retrieval, not translated English.

The embeddings model is multilingual, so English or mixed-language documents index and retrieve fine. Spanish is the language the product was designed and tuned around, not a restriction on what you can index.

How much does semantics add over grep?

Measured with compendio eval on the example corpus (ejemplos/: 11 documents, 27 chunks, no config file — the zero-config path itself) and its goldenset of 22 real questions:

• Keyword search is already strong when the question uses the corpus terminology.

• The gap opens on paraphrases and synonyms: «¿Qué endpoint hay que llamar para crear un lead?» falls out of the top 5 without embeddings, and the semantic leg recovers it. Questions with zero word overlap with the matching document are solved only by semantics.

• Speed: with the model warm, hybrid search answers in 5–20 ms.

compendio eval reproduces this table at any time — it's also the instrument for tuning chunking and k without guessing.

Architecture

Hexagonal: the core knows nothing about SQLite, transformers.js, or the filesystem.

src/
├── domain/            # pure, no dependencies: model, chunking, ranking, convencion policy
├── application/       # use cases
├── infrastructure/    # adapters: SQLite, markdown parsing, filesystem, embeddings
├── composition.ts     # composition root — start here to see the whole app
├── cli.ts             # input adapter: commander
└── server.ts          # input adapter: MCP server (stdio)

Every external dependency sits behind a port in src/domain/ports.ts. Swapping the vector store or the embeddings provider is a local change in one adapter, not a rewrite.

Development

npm install
npm run build       # compiles to dist/
npm test            # vitest: domain, adapters and integration
npm run typecheck   # tsc --noEmit
npm run dev -- ...  # CLI without compiling (tsx)

Integration tests use a deterministic embeddings provider (no downloads) against the real ejemplos/ corpus.

Try the CLI against the bundled example corpus without installing the package:

node dist/cli.js --root ejemplos index
node dist/cli.js --root ejemplos search "¿cuándo se considera duplicado un lead?"

This repository ships a .mcp.json that serves the ejemplos/ corpus, so you can try the tools from Claude Code with zero configuration.

License

MIT © Raúl García Barciela