grounded-rag-mcp
# 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](https://pypi.org/project/grounded-rag-mcp/).
> 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.
- [x] Phase 0 — scaffold, packaging, CI
- [x] Phase 1 — core retrieval (chunk → embed → BM25 + dense → RRF)
- [x] Phase 2 — MCP server (stdio) with `ingest` / `search`
- [x] Phase 3 — grounding + `answer` (via MCP sampling)
- [x] Phase 4 — eval, resource + prompt, docs
- [ ] Phase 5 — publish to npm
## Install
```bash
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)
```json
{
"mcpServers": {
"grounded-rag": {
"command": "npx",
"args": ["-y", "grounded-rag-mcp"]
}
}
}
```
## Development
```bash
npm install
npm run lint && npm run format:check && npm run typecheck && npm run build && npm test
```
## License
MIT © Chetan C
TDQS
Scored across 5 tools
Each tool has a clearly distinct role: ingest_documents adds content, search retrieves chunks, list_collections inspects collections, answer produces grounded responses with citations, and evaluate_retrieval measures quality. There is no meaningful overlap that would cause an agent to select the wrong tool.
Most tool names follow a clear verb_noun pattern like ingest_documents, list_collections, and evaluate_retrieval. search and answer are single verbs but are still intuitive and consistent in style, creating only minor deviation.
Five tools is well-scoped for a grounded RAG server: ingestion, listing, retrieval, grounded answering, and evaluation. Each tool earns its place without redundancy or bloat.
The core RAG workflow is covered end-to-end, including ingestion, retrieval, grounded answering, and retrieval evaluation. The main gap is the lack of deletion or update operations for documents and collections, which agents would need for full lifecycle management.