grounded-rag-mcp (TypeScript)

An MCP server that gives any LLM host grounded, cited retrieval over your own documents — hybrid retrieval (BM25 + dense), reranking-ready, citations, and a built-in eval harness. The TypeScript/Node twin of the Python package.

Point it at documents. Your MCP host (Claude Desktop, an IDE, a custom agent) can then search and answer over them — grounded in the real text, with citations, and an honest "not in the documents" path.

Why

Most RAG-over-MCP examples are toys. This one is built production-flavored:

Hybrid retrieval — BM25 (exact terms) + dense (semantics), fused with Reciprocal Rank Fusion.
Grounding + citations — answers cite sources; if the answer isn't in the docs, it says so.
Built-in eval — measure retrieval quality (recall@k, MRR, hit-rate), not just vibes.
Zero-dependency default — a deterministic hashing embedder runs with nothing extra.
Strict TypeScript, ESM, tested, CI on Node 18/20/22.

Status

Built in public, phase by phase.

Phase 0 — scaffold, packaging, CI
Phase 1 — core retrieval (chunk → embed → BM25 + dense → RRF)
Phase 2 — MCP server (stdio) with ingest / search
Phase 3 — grounding + answer (via MCP sampling)
Phase 4 — eval, resource + prompt, docs
Phase 5 — publish to npm

Install

npm install grounded-rag-mcp
# or run without installing:
npx grounded-rag-mcp

Tools

Tool	What it does
`ingest_documents`	Chunk, embed, and index files or raw text into a named collection
`search`	Hybrid / dense / bm25 retrieval, per-stage scores
`answer`	Grounded, cited answer via MCP sampling; refuses when nothing is found
`list_collections`	List collections and chunk counts
`evaluate_retrieval`	hitRate / mrr / recallAtK on labeled cases

Also exposes a resource (rag://collections) and a prompt (grounded_answer).

Use it with an MCP host (e.g. Claude Desktop)

{
  "mcpServers": {
    "grounded-rag": {
      "command": "npx",
      "args": ["-y", "grounded-rag-mcp"]
    }
  }
}

Development

npm install
npm run lint && npm run format:check && npm run typecheck && npm run build && npm test