docs-search-mcp

A small, read-only MCP server that lets an AI client (Claude Desktop, Claude Code, your own agent…) search and read a folder of Markdown/text documents.

It has three tools and one resource type, hybrid search (BM25 + optional local embeddings), and — the part I cared about most — it treats the model calling it as untrusted.

$ npm run demo          # a 3B local model answering questions about ./examples/docs through this server
Q: What is the price of the Pro subscription plan?
  → search_documents({"query":"What is the price of the Pro subscription plan?","limit":5})
    ok: No passages matched "What is the price of the Pro subscription plan?".…
  → list_documents({"limit":5})
A: No passages matched … and I couldn't find the information in the provided documents.

Tools

| tool | what it does | bounds | | --- | --- | --- | | search_documents | best-matching passages for a natural-language query, with document id, title and character range | query 1–500 chars, limit 1–20 | | read_document | read a document by id, in pages (offset / length, returns nextOffset) | length ≤ 20 000 chars | | list_documents | ids, titles and sizes, paged | limit ≤ 200 | | resource docs://{id} | the full text of one document (for clients that attach resources) | — |

All tools carry readOnlyHint: true / destructiveHint: false annotations, declare an outputSchema, and return both human-readable text and structuredContent. Errors are returned as tool errors the model can act on (Unknown document id "setup.md". Did you mean: guides/setup.md?), not as crashes.

Use it

Requires Node 20+.

git clone https://github.com/JuanMiguelAbellan/docs-search-mcp && cd docs-search-mcp
npm install && npm run build
node dist/cli.js ./path/to/your/docs                       # BM25 search, no other dependencies
node dist/cli.js ./docs --ollama-model bge-m3 --cache .emb.json   # hybrid: + local embeddings via Ollama

Options: --ollama-model, --ollama-host (default http://127.0.0.1:11434), --cache <file> (remember embeddings between runs), --chunk <chars> (passage size, default 1000).

Claude Desktop / Claude Code (claude mcp add docs -- node /abs/path/dist/cli.js /abs/path/to/docs), or in a JSON config:

{ "mcpServers": { "docs": { "command": "node", "args": ["/abs/path/docs-search-mcp/dist/cli.js", "/abs/path/to/docs"] } } }

Security model

Tool arguments are written by an LLM, which can be manipulated by whatever text it has read. So:

• No argument is ever used as a file path. Documents are loaded once at startup and looked up by id in memory. read_document({id: "../../etc/passwd"}) is just an unknown id. (Tested with .., absolute, Windows and NUL-byte ids, and with docs:// URIs including percent-encoded traversal.)
• The served folder is a boundary. At load time every entry is realpath-resolved; files and directories (including symlinks) that resolve outside the folder are skipped and reported on stderr. Dot-directories and node_modules are skipped; files over 2 MB, binary files and anything past 5000 files are skipped too.
• Every argument has a hard schema bound (see the table), validated by zod before the handler runs.
• Read-only by construction: there is no write, delete or execute tool, and no network access except the optional call to your own Ollama.
• Returned text is untrusted data. A document can contain "ignore previous instructions…". The server can't stop a client from obeying it, so each tool description tells the model not to, and the README of any client you build should treat tool output as data. This is a mitigation, not a guarantee.
• stdout is the protocol channel. Logging goes to stderr only (a stray console.log would corrupt the JSON-RPC stream); an end-to-end test spawns the real CLI and checks this.

How search works

Documents are cut into passages of at most 1000 characters at paragraph boundaries (long paragraphs are split at whitespace), each remembering its exact character range in the source. BM25 (k1 = 1.5, b = 0.75) runs over accent-folded, stopword-filtered, 6-character-prefix-stemmed tokens (English and Spanish stopwords). With --ollama-model, cosine similarity over embeddings is computed too and the two rankings are merged with Reciprocal Rank Fusion.

These choices follow what I measured in rag-eval on Spanish text: paragraph chunks beat fixed windows at this size, a multilingual embedding model (bge-m3) beat nomic-embed-text, and BM25 + dense fusion was best. That study used a different corpus and code path; this server was not re-evaluated on it.

Demo, and what it shows honestly

examples/agent.ts runs a ReAct-style loop (the same JSON-action protocol as my react-agent-loop) with qwen2.5:3b on Ollama. Tool descriptions and schemas in the prompt are generated from what the server advertises over stdio. The unedited run is in examples/transcript.txt — I did not reword questions after seeing the answers. Checked against the documents:

1. Which change improved retrieval most in rag-eval, and what MRR did the best setup reach? — the model got 0.947 right but named "paragraph chunking" as the biggest change; the docs say the embedding model / BM25 (≈ +0.20 vs. +0.08). Half wrong.
2. What happens in react-agent-loop when the model answers in prose? — the retrieved passage is the right document, but its README doesn't say anything about prose, so the model's answer is filled in from general knowledge. Unsupported by the documents.
3. Price of the Pro plan? (not in any document) — searched, found nothing, said so. Correct.

The server did its job in all three (right documents, right passages, clean error handling). The mistakes are a 3B model reasoning over retrieved text — exactly what a retrieval tool cannot fix.

Bugs the tests found in my own code

• Same file loaded twice. A symlink inside the folder resolves to the same real path as its target, and ids are real paths, so the file appeared twice under one id. My first test asserted docs.length >= 1 and hid it; tightening it to the exact list exposed the bug.
• Document order depended on the machine's locale. localeCompare sorts differently per locale, so offset paging could return different pages on different machines. Ordering is now a plain code-unit comparison.

Tests

npm test — 30 tests, no Ollama needed (a fake embedder stands in): chunking invariants, loader security (symlink escape, binary/oversized/excess files, duplicate symlinks, locale-independent ordering), BM25 and hybrid search, the full MCP protocol through an in-memory client/server pair (schemas, bounds, pagination, traversal ids, resources), and an end-to-end test that spawns the real CLI over stdio.

Limitations

• Index is built at startup, in memory. New or edited files need a restart. Fine for hundreds of documents; not designed for very large corpora (dense search is a linear scan).
• Only .md, .markdown and .txt. No PDF, HTML or DOCX extraction.
• Prefix "stemming" is crude (works for English and Spanish inflection, wrong for other languages) and stopwords cover only English and Spanish.
• Embeddings need a local Ollama; there is no hosted-embedding option. The embedding cache is keyed by text and model only.
• Prompt-injection can only be mitigated, not prevented, at this layer (see above).
• Tested with the official TypeScript SDK client (1.30) and my own demo agent; I have not tested it inside Claude Desktop or Claude Code — the config snippets above follow their documented format but are untested.
• Not published to npm.

Licence

MIT.