compendio-mcp

<!-- mcp-name: io.github.RuloGB/compendio-mcp -->

<p align="center">
  <img width="1280" height="640" alt="compendio-mcp — your project's documentation, served to any agent in the fewest possible tokens" src="assets/branding/compendio-banner.png" />
</p>

<p align="center">
  <strong>Your project's documentation, served to any agent in the fewest possible tokens.</strong><br>
  <em>A local RAG retrieval layer exposed as an MCP server. Your agent stops grepping and dumping whole files — it reaches the right paragraph instead.</em>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/compendio-mcp"><img src="https://img.shields.io/npm/v/compendio-mcp.svg" alt="npm"></a>
  <a href="LICENSE"><img src="https://img.shields.io/npm/l/compendio-mcp.svg" alt="license"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/compendio-mcp.svg" alt="node"></a>
  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-blue" alt="platform: macOS | Linux | Windows">
</p>

<p align="center">
  <a href="https://lobehub.com/mcp/rulogb-compendio-mcp"><img src="https://lobehub.com/badge/mcp/rulogb-compendio-mcp?style=for-the-badge" alt="MCP Badge"></a>
</p>

<p align="center">
  <a href="#what-compendio-does">What it does</a> &bull;
  <a href="#requirements">Requirements</a> &bull;
  <a href="#quick-start">Quick Start</a> &bull;
  <a href="#configuration">Configuration</a> &bull;
  <a href="#mcp-tools">MCP Tools</a> &bull;
  <a href="#cli">CLI</a> &bull;
  <a href="#how-it-works">How it works</a> &bull;
  <a href="#incremental-sync">Incremental sync</a> &bull;
  <a href="#multilingual">Multilingual</a> &bull;
  <a href="docs/documentation-convention.md">Full docs</a>
</p>

---

## 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.

<p align="center">
  <img width="900" alt="The same question asked twice in OpenCode. Without Compendio the agent lists the whole repository, greps twice and opens three files. With Compendio it runs one search and reads one section." src="assets/demo/compendio-demo.gif" />
</p>

<p align="center">
  <sub>Same question, same model, and <strong>both answers are correct</strong> — the difference is what it cost to get there.<br>
  <strong>6 tool calls &bull; 29s &bull; 32,301 tokens</strong> &nbsp;→&nbsp; <strong>2 tool calls &bull; 12s &bull; 17,684 tokens</strong>.<br>
  Figures read from OpenCode's own elapsed label and cost tooltip, on an 81-document corpus.</sub>
</p>

## 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](#multilingual).
- 🧩 **Zero configuration** — works on *any* folder of `.md` files. No required frontmatter, no config file. An optional [documentation convention](#documentation-convention-optional) is there if your team already has a taxonomy to enforce.

## Requirements

- Node.js ≥ 22.12.
- Nothing else.

## Quick start

**1. Install it.**

```bash
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 or `{USER_FOLDER} .claude.json` to global install):

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

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows — or Settings → Developer → Edit Config):

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

**OpenCode** (`opencode.json`):

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

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

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

**Cursor** (`.cursor/mcp.json`):

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

**Codex** (`.codex/config.toml`):

```toml
[mcp_servers.compendio]
command = "npx"
args = ["compendio-mcp", "serve"]
enabled = true
startup_timeout_sec = 60
```

**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):

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

**Zed** (`settings.json`, or Settings → AI → MCP Servers → Add Custom Server):

```json
{
  "context_servers": {
    "compendio": {
      "command": "compendio",
      "args": ["serve"],
      "env": {}
    }
  }
}
```

**Cline** (MCP Servers icon → Configure → *Configure MCP Servers*; the CLI reads `~/.cline/mcp.json`):

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

**Gemini CLI** (`.gemini/settings.json` in the project, or `~/.gemini/settings.json`):

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

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

```bash
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](#incremental-sync)).

> **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:

```json
{
  "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" }
  }
}
```

| Key | What it's for |
|---|---|
| `docsDir` | One or more explicit documentation roots, relative to the project root. Always an array — there is no single-string form. Omit it or set `[]` to use discovery mode |
| `exclude` | Entries to skip when indexing: an exact path, a bare filename (matched anywhere), or a directory prefix (e.g. `"adr/superseded"` skips everything under it) |
| `db` | Where the SQLite index file is written |
| `search.k` | Default number of fragments returned per search |
| `chunk` | Fragment size bounds, in tokens |
| `sync.throttleMs` | Minimum time between automatic sync passes, in ms (30000 = 30 s). A floor, not a timer — gates only `serve`'s automatic triggers, not a manually-run `compendio sync` — see [Incremental sync](#incremental-sync) |
| `convention` | Optional documentation taxonomy — see below |

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:

```json
{ "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