Skip to main content
Glama
Sign In
grounded-rag-mcp

grounded-rag-mcp

by chetan1521
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

Related MCP server: RAG Knowledge Base MCP Server

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

License

MIT © Chetan C

Available Tools

5 tools
answerA

Answer a question grounded in a collection, with citations. Retrieves relevant passages and asks the host's model (via MCP sampling) to answer using only those, citing them. Refuses (grounded=false) when nothing relevant is found.

Inputs: query (required), topK, collection.

evaluate_retrievalA

Measure retrieval quality on labeled cases: hitRate, mrr, recallAtK. Each case is {query, relevantSources}. Use it to quantify quality and catch regressions.

Inputs: cases (required), mode, topK, collection.

ingest_documentsB

Ingest documents into a named collection so they can be searched. Provide paths (files/dirs of .txt/.md) and/or texts (raw strings). Returns chunks added and total.

Inputs: paths, texts, chunkSize, collection, +1 more.

list_collectionsA

List all ingested collections and how many chunks each contains.

Inputs: no named parameters.

searchA

Search a collection and return the most relevant chunks, each with its source and per-stage scores. mode: hybrid (default) | dense | bm25. Empty result = not in the docs.

Inputs: query (required), mode, topK, collection.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • PDF MCP Server

      rhuanca
      F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI-powered querying of PDF documents using hybrid retrieval (BM25 + vector search) and retrieval-augmented generation, returning structured answers with source citations and confidence scores.
      -

    • RAG MCP Server

      johnylira
      F
      license
      Not graded
      quality
      C
      maintenance
      Enables document indexing and question answering with Retrieval-Augmented Generation, providing cited answers from user-supplied documents.
      -

    • grounded-rag-mcp

      chetan1521
      A
      license
      A
      quality
      C
      maintenance
      Enables any MCP host to search and answer over your own documents with hybrid BM25+dense retrieval, cross-encoder reranking, and grounded, cited responses that refuse when no evidence is found.
      5
      MIT