docent
Semantic + BM25 document search — MCP server written in Rust that indexes markdown documents as a local knowledge base.
files ──▼── index (in-memory+cache) ──▶ MCP server ◀──── query
(HTTP)
Quick Start
docent index add ./docs # add a directory to the index
docent serve # start the MCP server and web UI
docent serve prints the URL it is listening on; open that URL for the built-in Web UI.
Usage
Configuration is stored in ~/.docent/settings.json and created automatically on first run.
How It Works
- Sources — Markdown files under indexed directories (
*.md). Add roots withdocent index addordocent watch, or list them inindex.doc_dirsin~/.docent/settings.json. - Section-aware chunking — Splits documents into chunks, preserving heading structure.
- Embedding — Converts chunks to vectors via
fastembedusing the configured model. - Persistent index — Chunk metadata and vectors are stored in
~/.docent/index/docent.db;serveloads this into an in-memory merged semantic + BM25 index on startup. - Initial scan — On
serve, all watched roots are reindexed in the background before search is available. - Auto-refresh — A file watcher reindexes changed files (debounced). Results from files currently being reindexed are flagged via
SearchResult.stale = true. - Semantic + BM25 search — Hybrid scoring with configurable ranking, fusion, and BM25 parameters.
- MCP server — Exposes the
search_doctool over streamable HTTP.
Configuration
~/.docent/settings.json is a JSON file with the following sections:
{
"index": {
"embedding_model": "BGESmallENV15Q",
"doc_dirs": [],
"cache_dir": "/home/<user>/.docent/cache/",
"chunk_size": 512,
"chunk_overlap": 64,
"watch": { "enabled": true, "debounce_ms": 5000, "max_batch_size": 64 }
},
"server": { "port": 0 },
"search": {
"ranking": { "same_src_score_decay": 0.9, "file_hint_boost": 1.5 },
"fusion": { "strategy": { "rrf": { "k": 60.0 } } },
"bm25": { "k1": 1.2, "b": 0.75 }
}
}
Install
Pre-built Linux x86_64 binaries are available on the releases page.
One-line install
curl -sSL https://github.com/cuzfrog/docent-mcp/releases/latest/download/install.sh | bash
This installs docent to ~/.local/bin and, if needed, updates your shell profile to include it in PATH.
Install a specific version
curl -sSL https://github.com/cuzfrog/docent-mcp/releases/download/v0.9.0/install.sh | DOCENT_VERSION=v0.9.0 bash
Manual install
Download the asset for your platform from the latest release, make it executable, and place it in a directory on your PATH:
curl -sSL -o docent https://github.com/cuzfrog/docent-mcp/releases/latest/download/docent-x86_64-unknown-linux-gnu
chmod +x docent
mv docent ~/.local/bin/
Build from source
cargo build --release
The binary is then available at target/release/docent.