grounded-rag-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chetan C
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# 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

package/dist/chunking.d.ts

@@ -0,0 +1,17 @@
+/** Split documents into overlapping, word-based chunks. */
+import type { ChunkingConfig } from "./config.js";
+/** A retrievable unit of text plus where it came from (for citations). */
+export interface Chunk {
+    chunkId: string;
+    text: string;
+    source: string;
+}
+/**
+ * Split one document into overlapping, word-based chunks.
+ *
+ * Word-based (not character-based) so we never cut a word in half, and overlapping so a
+ * fact straddling a boundary still lives wholly inside at least one chunk. Chunk size is
+ * the single highest-impact retrieval knob: too large blurs the embedding across topics,
+ * too small strips the context needed to answer.
+ */
+export declare function chunkDocument(text: string, source: string, config?: ChunkingConfig): Chunk[];

package/dist/chunking.js

@@ -0,0 +1,31 @@
+/** Split documents into overlapping, word-based chunks. */
+import { DEFAULT_CHUNKING } from "./config.js";
+/**
+ * Split one document into overlapping, word-based chunks.
+ *
+ * Word-based (not character-based) so we never cut a word in half, and overlapping so a
+ * fact straddling a boundary still lives wholly inside at least one chunk. Chunk size is
+ * the single highest-impact retrieval knob: too large blurs the embedding across topics,
+ * too small strips the context needed to answer.
+ */
+export function chunkDocument(text, source, config = DEFAULT_CHUNKING) {
+    const words = text.split(/\s+/).filter((w) => w.length > 0);
+    if (words.length === 0)
+        return [];
+    const step = Math.max(1, config.size - config.overlap);
+    const chunks = [];
+    for (let start = 0; start < words.length; start += step) {
+        const window = words.slice(start, start + config.size);
+        if (window.length === 0)
+            break;
+        chunks.push({
+            chunkId: `${source}#${chunks.length}`,
+            text: window.join(" "),
+            source,
+        });
+        if (start + config.size >= words.length)
+            break; // reached the end; avoid a trailing dup
+    }
+    return chunks;
+}
+//# sourceMappingURL=chunking.js.map

package/dist/chunking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.js","sourceRoot":"","sources":["../src/chunking.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAG3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAS/C;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,MAAc,EACd,SAAyB,gBAAgB;IAEzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACvD,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,IAAI,EAAE,CAAC;QACxD,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM;QAC/B,MAAM,CAAC,IAAI,CAAC;YACV,OAAO,EAAE,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE;YACrC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;YACtB,MAAM;SACP,CAAC,CAAC;QACH,IAAI,KAAK,GAAG,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM;YAAE,MAAM,CAAC,wCAAwC;IAC1F,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/collection.d.ts

@@ -0,0 +1,21 @@
+/** A Collection ties chunks + embedder + vector store + BM25 into one retrievable unit. */
+import type { Chunk } from "./chunking.js";
+import type { RetrievalConfig } from "./config.js";
+import type { Embedder } from "./embeddings.js";
+/** A retrieval hit: the chunk, its final score, and per-stage scores for debugging. */
+export interface RetrievedChunk {
+    chunk: Chunk;
+    score: number;
+    stageScores: Record<string, number>;
+}
+export declare class Collection {
+    readonly name: string;
+    private embedder;
+    private chunks;
+    private store;
+    private bm25;
+    constructor(name: string, embedder: Embedder);
+    add(chunks: Chunk[]): void;
+    get numChunks(): number;
+    retrieve(query: string, config?: Partial<RetrievalConfig>): RetrievedChunk[];
+}

package/dist/collection.js

@@ -0,0 +1,72 @@
+/** A Collection ties chunks + embedder + vector store + BM25 into one retrievable unit. */
+import { DEFAULT_RETRIEVAL } from "./config.js";
+import { BM25Index } from "./retrieval/bm25.js";
+import { reciprocalRankFusion, topKIds, weightedSumFusion } from "./retrieval/fusion.js";
+import { InMemoryVectorStore } from "./stores/memory.js";
+export class Collection {
+    name;
+    embedder;
+    chunks = new Map();
+    store;
+    bm25 = new BM25Index();
+    constructor(name, embedder) {
+        this.name = name;
+        this.embedder = embedder;
+        this.store = new InMemoryVectorStore(embedder.dim);
+    }
+    add(chunks) {
+        if (chunks.length === 0)
+            return;
+        for (const chunk of chunks)
+            this.chunks.set(chunk.chunkId, chunk);
+        const vectors = this.embedder.embed(chunks.map((c) => c.text));
+        this.store.add(chunks.map((c) => c.chunkId), vectors);
+        // BM25 is rebuilt over ALL chunks (index-time and query-time must agree).
+        const allIds = [...this.chunks.keys()];
+        this.bm25.build(allIds, allIds.map((id) => this.chunks.get(id)?.text ?? ""));
+    }
+    get numChunks() {
+        return this.chunks.size;
+    }
+    retrieve(query, config = {}) {
+        const cfg = { ...DEFAULT_RETRIEVAL, ...config };
+        if (this.chunks.size === 0)
+            return [];
+        const pool = cfg.candidatePool;
+        const queryVec = this.embedder.embed([query])[0];
+        if (queryVec === undefined)
+            return [];
+        const dense = new Map(this.store.search(queryVec, pool));
+        const bm25 = new Map(this.bm25.search(query, pool));
+        let fused;
+        if (cfg.mode === "dense") {
+            fused = dense;
+        }
+        else if (cfg.mode === "bm25") {
+            fused = bm25;
+        }
+        else if (cfg.fusion === "weighted") {
+            fused = weightedSumFusion([dense, bm25], [0.5, 0.5]);
+        }
+        else {
+            fused = reciprocalRankFusion([topKIds(dense, pool), topKIds(bm25, pool)], cfg.rrfK);
+        }
+        const results = [];
+        for (const chunkId of topKIds(fused, cfg.topK)) {
+            const chunk = this.chunks.get(chunkId);
+            if (chunk === undefined)
+                continue;
+            results.push({
+                chunk,
+                score: fused.get(chunkId) ?? 0,
+                stageScores: {
+                    dense: dense.get(chunkId) ?? 0,
+                    bm25: bm25.get(chunkId) ?? 0,
+                    fused: fused.get(chunkId) ?? 0,
+                },
+            });
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=collection.js.map

package/dist/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+/** Configuration types and defaults for chunking and retrieval. */
+export type RetrievalMode = "hybrid" | "dense" | "bm25";
+export type FusionMethod = "rrf" | "weighted";
+export interface ChunkingConfig {
+    /** Chunk size in words. */
+    size: number;
+    /** Overlap in words between consecutive chunks. */
+    overlap: number;
+}
+export declare const DEFAULT_CHUNKING: ChunkingConfig;
+export interface RetrievalConfig {
+    topK: number;
+    mode: RetrievalMode;
+    fusion: FusionMethod;
+    /** RRF dampening constant. */
+    rrfK: number;
+    /** Per-retriever candidates fed into fusion. */
+    candidatePool: number;
+}
+export declare const DEFAULT_RETRIEVAL: RetrievalConfig;

package/dist/config.js

@@ -0,0 +1,10 @@
+/** Configuration types and defaults for chunking and retrieval. */
+export const DEFAULT_CHUNKING = { size: 200, overlap: 40 };
+export const DEFAULT_RETRIEVAL = {
+    topK: 5,
+    mode: "hybrid",
+    fusion: "rrf",
+    rrfK: 60,
+    candidatePool: 20,
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,mEAAmE;AAYnE,MAAM,CAAC,MAAM,gBAAgB,GAAmB,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAY3E,MAAM,CAAC,MAAM,iBAAiB,GAAoB;IAChD,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,EAAE;IACR,aAAa,EAAE,EAAE;CAClB,CAAC"}

package/dist/embeddings.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Embedders: turn text into vectors.
+ *
+ * The default `HashingEmbedder` is dependency-free and deterministic (the hashing trick),
+ * so the package installs and runs with nothing extra — great for wiring, tests, and a
+ * zero-setup quickstart. It is semantically weak (it matches words, not meaning); a
+ * transformers.js-backed semantic embedder is a planned optional backend.
+ *
+ * Coding to the `Embedder` interface keeps the rest of the system ignorant of which
+ * embedder is in use — the pluggable-backend design decision.
+ */
+export interface Embedder {
+    readonly dim: number;
+    embed(texts: string[]): number[][];
+}
+export declare class HashingEmbedder implements Embedder {
+    readonly dim: number;
+    constructor(dim?: number);
+    /**
+     * Stable hash (not a per-process-randomized one) so the same token always maps to the
+     * same bucket across processes — this matters the moment an index is persisted and
+     * reloaded.
+     */
+    private bucket;
+    embed(texts: string[]): number[][];
+}

package/dist/embeddings.js

@@ -0,0 +1,47 @@
+/**
+ * Embedders: turn text into vectors.
+ *
+ * The default `HashingEmbedder` is dependency-free and deterministic (the hashing trick),
+ * so the package installs and runs with nothing extra — great for wiring, tests, and a
+ * zero-setup quickstart. It is semantically weak (it matches words, not meaning); a
+ * transformers.js-backed semantic embedder is a planned optional backend.
+ *
+ * Coding to the `Embedder` interface keeps the rest of the system ignorant of which
+ * embedder is in use — the pluggable-backend design decision.
+ */
+import { createHash } from "node:crypto";
+import { tokenize } from "./text.js";
+/** Scale a vector to unit length so a dot product equals cosine similarity. */
+function l2normalize(vec) {
+    let norm = Math.sqrt(vec.reduce((sum, x) => sum + x * x, 0));
+    if (norm === 0)
+        norm = 1; // guard against divide-by-zero on empty text
+    return vec.map((x) => x / norm);
+}
+export class HashingEmbedder {
+    dim;
+    constructor(dim = 256) {
+        this.dim = dim;
+    }
+    /**
+     * Stable hash (not a per-process-randomized one) so the same token always maps to the
+     * same bucket across processes — this matters the moment an index is persisted and
+     * reloaded.
+     */
+    bucket(token) {
+        const digest = createHash("md5").update(token).digest();
+        const value = digest.readBigUInt64LE(0);
+        return Number(value % BigInt(this.dim));
+    }
+    embed(texts) {
+        return texts.map((text) => {
+            const vec = new Array(this.dim).fill(0);
+            for (const token of tokenize(text)) {
+                const b = this.bucket(token);
+                vec[b] = (vec[b] ?? 0) + 1;
+            }
+            return l2normalize(vec);
+        });
+    }
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/embeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.js","sourceRoot":"","sources":["../src/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAOrC,+EAA+E;AAC/E,SAAS,WAAW,CAAC,GAAa;IAChC,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7D,IAAI,IAAI,KAAK,CAAC;QAAE,IAAI,GAAG,CAAC,CAAC,CAAC,6CAA6C;IACvE,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,OAAO,eAAe;IACjB,GAAG,CAAS;IAErB,YAAY,GAAG,GAAG,GAAG;QACnB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACK,MAAM,CAAC,KAAa;QAC1B,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QACxD,MAAM,KAAK,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACxC,OAAO,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,KAAe;QACnB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;YACxB,MAAM,GAAG,GAAG,IAAI,KAAK,CAAS,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChD,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACnC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAC7B,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YACD,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/eval.d.ts

@@ -0,0 +1,19 @@
+/** Retrieval evaluation: measure quality with numbers, not vibes. */
+import type { Collection } from "./collection.js";
+import type { RetrievalMode } from "./config.js";
+export interface EvalCase {
+    query: string;
+    relevantSources: string[];
+}
+export interface EvalMetrics {
+    cases: number;
+    hitRate: number;
+    mrr: number;
+    recallAtK: number;
+    topK: number;
+}
+/**
+ * hit_rate (any relevant in top-k), MRR (rank of first relevant), recall@k (fraction of a
+ * query's relevant sources found), averaged over cases — so retrieval quality is trackable.
+ */
+export declare function evaluate(collection: Collection, cases: EvalCase[], topK?: number, mode?: RetrievalMode): EvalMetrics;

package/dist/eval.js

@@ -0,0 +1,42 @@
+/** Retrieval evaluation: measure quality with numbers, not vibes. */
+const round4 = (x) => Math.round(x * 1e4) / 1e4;
+/**
+ * hit_rate (any relevant in top-k), MRR (rank of first relevant), recall@k (fraction of a
+ * query's relevant sources found), averaged over cases — so retrieval quality is trackable.
+ */
+export function evaluate(collection, cases, topK = 5, mode = "hybrid") {
+    if (cases.length === 0) {
+        return { cases: 0, hitRate: 0, mrr: 0, recallAtK: 0, topK };
+    }
+    let hits = 0;
+    let reciprocalRanks = 0;
+    let recallSum = 0;
+    for (const testCase of cases) {
+        const results = collection.retrieve(testCase.query, { topK, mode });
+        const retrievedSources = results.map((r) => r.chunk.source);
+        const relevant = new Set(testCase.relevantSources);
+        let firstRank = 0;
+        for (let i = 0; i < retrievedSources.length; i++) {
+            const src = retrievedSources[i];
+            if (src !== undefined && relevant.has(src)) {
+                firstRank = i + 1;
+                break;
+            }
+        }
+        if (firstRank > 0) {
+            hits += 1;
+            reciprocalRanks += 1 / firstRank;
+        }
+        const found = [...relevant].filter((s) => retrievedSources.includes(s)).length;
+        recallSum += found / relevant.size;
+    }
+    const n = cases.length;
+    return {
+        cases: n,
+        hitRate: round4(hits / n),
+        mrr: round4(reciprocalRanks / n),
+        recallAtK: round4(recallSum / n),
+        topK,
+    };
+}
+//# sourceMappingURL=eval.js.map

package/dist/eval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval.js","sourceRoot":"","sources":["../src/eval.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAkBrE,MAAM,MAAM,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AAEhE;;;GAGG;AACH,MAAM,UAAU,QAAQ,CACtB,UAAsB,EACtB,KAAiB,EACjB,IAAI,GAAG,CAAC,EACR,OAAsB,QAAQ;IAE9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC;IAC9D,CAAC;IAED,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5D,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QAEnD,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,gBAAgB,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACjD,MAAM,GAAG,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;YAChC,IAAI,GAAG,KAAK,SAAS,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC3C,SAAS,GAAG,CAAC,GAAG,CAAC,CAAC;gBAClB,MAAM;YACR,CAAC;QACH,CAAC;QACD,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,IAAI,IAAI,CAAC,CAAC;YACV,eAAe,IAAI,CAAC,GAAG,SAAS,CAAC;QACnC,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QAC/E,SAAS,IAAI,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;IACvB,OAAO;QACL,KAAK,EAAE,CAAC;QACR,OAAO,EAAE,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;QACzB,GAAG,EAAE,MAAM,CAAC,eAAe,GAAG,CAAC,CAAC;QAChC,SAAS,EAAE,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC;QAChC,IAAI;KACL,CAAC;AACJ,CAAC"}

package/dist/grounding.d.ts

@@ -0,0 +1,13 @@
+/** Grounding: turn retrieved chunks into cited context, and the honest "not found" message. */
+import type { RetrievedChunk } from "./collection.js";
+export declare const NOT_FOUND = "I couldn't find an answer to that in the provided documents.";
+export declare const GROUNDING_SYSTEM_PROMPT: string;
+export interface Citation {
+    ref: number;
+    source: string;
+    chunkId: string;
+    score: number;
+}
+export declare function buildCitations(hits: RetrievedChunk[]): Citation[];
+/** Number each passage and label it with its source, so the model can cite [n]. */
+export declare function buildContext(hits: RetrievedChunk[]): string;

package/dist/grounding.js

@@ -0,0 +1,19 @@
+/** Grounding: turn retrieved chunks into cited context, and the honest "not found" message. */
+export const NOT_FOUND = "I couldn't find an answer to that in the provided documents.";
+export const GROUNDING_SYSTEM_PROMPT = "You are a retrieval QA assistant. Answer the question using ONLY the numbered context " +
+    "passages provided. Cite the passages you rely on with their bracket numbers, e.g. [1]. " +
+    "If the answer is not contained in the context, say you couldn't find it in the documents " +
+    "— never use outside knowledge and never invent details.";
+export function buildCitations(hits) {
+    return hits.map((h, i) => ({
+        ref: i + 1,
+        source: h.chunk.source,
+        chunkId: h.chunk.chunkId,
+        score: Math.round(h.score * 1e6) / 1e6,
+    }));
+}
+/** Number each passage and label it with its source, so the model can cite [n]. */
+export function buildContext(hits) {
+    return hits.map((h, i) => `[${i + 1}] (source: ${h.chunk.source})\n${h.chunk.text}`).join("\n\n");
+}
+//# sourceMappingURL=grounding.js.map

package/dist/grounding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding.js","sourceRoot":"","sources":["../src/grounding.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAI/F,MAAM,CAAC,MAAM,SAAS,GAAG,8DAA8D,CAAC;AAExF,MAAM,CAAC,MAAM,uBAAuB,GAClC,wFAAwF;IACxF,yFAAyF;IACzF,2FAA2F;IAC3F,yDAAyD,CAAC;AAS5D,MAAM,UAAU,cAAc,CAAC,IAAsB;IACnD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACzB,GAAG,EAAE,CAAC,GAAG,CAAC;QACV,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM;QACtB,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO;QACxB,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG;KACvC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,IAAsB;IACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,KAAK,CAAC,MAAM,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACpG,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point: launch the MCP server over stdio (the transport local hosts use).
+ *
+ * We log only to stderr — for an stdio MCP server, stdout is the JSON-RPC channel and must
+ * never carry stray text.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`grounded-rag-mcp failed to start: ${String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qCAAqC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/ingest.d.ts

@@ -0,0 +1,12 @@
+/** Load documents from disk or raw strings into chunks. */
+import { type Chunk } from "./chunking.js";
+import { type ChunkingConfig } from "./config.js";
+/**
+ * Read text files (and directories of them) and chunk their contents.
+ *
+ * v1 handles plain text and markdown — the formats that need no parsing dependency.
+ * Richer parsing (PDF, HTML) is a pluggable loader layer, kept out of v1 on purpose.
+ */
+export declare function loadPaths(paths: string[], config?: ChunkingConfig): Chunk[];
+/** Chunk raw in-memory strings (each becomes its own source `text:N`). */
+export declare function loadTexts(texts: string[], config?: ChunkingConfig): Chunk[];

package/dist/ingest.js

@@ -0,0 +1,33 @@
+/** Load documents from disk or raw strings into chunks. */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { chunkDocument } from "./chunking.js";
+import { DEFAULT_CHUNKING } from "./config.js";
+const SUPPORTED = new Set([".txt", ".md", ".markdown"]);
+function walk(path) {
+    const stat = statSync(path);
+    if (stat.isDirectory()) {
+        return readdirSync(path).flatMap((entry) => walk(join(path, entry)));
+    }
+    return SUPPORTED.has(extname(path).toLowerCase()) ? [path] : [];
+}
+/**
+ * Read text files (and directories of them) and chunk their contents.
+ *
+ * v1 handles plain text and markdown — the formats that need no parsing dependency.
+ * Richer parsing (PDF, HTML) is a pluggable loader layer, kept out of v1 on purpose.
+ */
+export function loadPaths(paths, config = DEFAULT_CHUNKING) {
+    const files = paths.flatMap(walk);
+    const chunks = [];
+    for (const file of files) {
+        const text = readFileSync(file, "utf-8");
+        chunks.push(...chunkDocument(text, file, config));
+    }
+    return chunks;
+}
+/** Chunk raw in-memory strings (each becomes its own source `text:N`). */
+export function loadTexts(texts, config = DEFAULT_CHUNKING) {
+    return texts.flatMap((text, i) => chunkDocument(text, `text:${i}`, config));
+}
+//# sourceMappingURL=ingest.js.map

package/dist/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../src/ingest.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAE3D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAc,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAuB,MAAM,aAAa,CAAC;AAEpE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;AAExD,SAAS,IAAI,CAAC,IAAY;IACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACvB,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAe,EAAE,SAAyB,gBAAgB;IAClF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,KAAe,EAAE,SAAyB,gBAAgB;IAClF,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9E,CAAC"}

package/dist/retrieval/bm25.d.ts

@@ -0,0 +1,21 @@
+/**
+ * BM25 keyword retrieval, implemented from scratch (no extra dependency).
+ *
+ * Scores a document per query term via IDF (rare terms matter more), term-frequency
+ * saturation (`k1` — the 2nd occurrence helps a lot, the 20th barely more), and length
+ * normalization (`b` — long docs shouldn't win just for being long). Captures exact-term
+ * matches (names, codes, acronyms) that dense/semantic search misses.
+ */
+export declare class BM25Index {
+    private readonly k1;
+    private readonly b;
+    private ids;
+    private docs;
+    private docFreq;
+    private avgLen;
+    constructor(k1?: number, b?: number);
+    /** (Re)build from all chunks — cheap at local scale; rebuilt on every ingest. */
+    build(ids: string[], texts: string[]): void;
+    private idf;
+    search(query: string, topK: number): Array<[string, number]>;
+}

package/dist/retrieval/bm25.js

@@ -0,0 +1,69 @@
+/**
+ * BM25 keyword retrieval, implemented from scratch (no extra dependency).
+ *
+ * Scores a document per query term via IDF (rare terms matter more), term-frequency
+ * saturation (`k1` — the 2nd occurrence helps a lot, the 20th barely more), and length
+ * normalization (`b` — long docs shouldn't win just for being long). Captures exact-term
+ * matches (names, codes, acronyms) that dense/semantic search misses.
+ */
+import { tokenize } from "../text.js";
+export class BM25Index {
+    k1;
+    b;
+    ids = [];
+    docs = [];
+    docFreq = new Map();
+    avgLen = 0;
+    constructor(k1 = 1.5, b = 0.75) {
+        this.k1 = k1;
+        this.b = b;
+    }
+    /** (Re)build from all chunks — cheap at local scale; rebuilt on every ingest. */
+    build(ids, texts) {
+        this.ids = ids;
+        this.docs = texts.map((t) => tokenize(t));
+        this.docFreq = new Map();
+        for (const tokens of this.docs) {
+            for (const term of new Set(tokens)) {
+                this.docFreq.set(term, (this.docFreq.get(term) ?? 0) + 1);
+            }
+        }
+        const totalLen = this.docs.reduce((sum, d) => sum + d.length, 0);
+        this.avgLen = this.docs.length > 0 ? totalLen / this.docs.length : 0;
+    }
+    idf(term) {
+        const n = this.docs.length;
+        const df = this.docFreq.get(term) ?? 0;
+        // +0.5 smoothing; max(..., 0) keeps very common terms from going negative.
+        return Math.max(0, Math.log((n - df + 0.5) / (df + 0.5) + 1));
+    }
+    search(query, topK) {
+        if (this.docs.length === 0)
+            return [];
+        const queryTerms = tokenize(query);
+        const results = [];
+        for (let i = 0; i < this.ids.length; i++) {
+            const tokens = this.docs[i];
+            const id = this.ids[i];
+            if (tokens === undefined || id === undefined)
+                continue;
+            const counts = new Map();
+            for (const t of tokens)
+                counts.set(t, (counts.get(t) ?? 0) + 1);
+            const dl = tokens.length;
+            let score = 0;
+            for (const term of queryTerms) {
+                const tf = counts.get(term) ?? 0;
+                if (tf === 0)
+                    continue;
+                const denom = tf + this.k1 * (1 - this.b + (this.b * dl) / (this.avgLen || 1));
+                score += this.idf(term) * ((tf * (this.k1 + 1)) / denom);
+            }
+            if (score > 0)
+                results.push([id, score]);
+        }
+        results.sort((a, b) => b[1] - a[1]);
+        return results.slice(0, topK);
+    }
+}
+//# sourceMappingURL=bm25.js.map

package/dist/retrieval/bm25.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bm25.js","sourceRoot":"","sources":["../../src/retrieval/bm25.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/fusion.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Combine results from multiple retrievers into one ranking.
+ *
+ * - Reciprocal Rank Fusion (RRF): combines by *rank*, so it never has to make an unbounded
+ *   BM25 score and a 0-1 cosine score comparable. Robust, and the default.
+ * - Normalized weighted sum: combines by *score*, which first requires normalizing each
+ *   retriever to [0, 1] — and that normalization has a sharp edge (see below).
+ *
+ * War story encoded as a test: the inverted min-max `(max - x) / (max - min)` maps the BEST
+ * score to 0 and the WORST to 1, silently pushing the most relevant documents to the bottom
+ * where they get truncated before the model ever sees them. `fusion.test.ts` asserts the
+ * correct direction so that inversion can never return unnoticed.
+ */
+/** Fuse ranked ID lists. A doc's score is the sum of 1/(k + rank) across lists (rank is 1-based). */
+export declare function reciprocalRankFusion(rankings: string[][], k?: number): Map<string, number>;
+/**
+ * Rescale scores to [0, 1] preserving order: best -> 1, worst -> 0.
+ *
+ * CORRECT: norm(x) = (x - min) / (max - min).
+ * The inverted mistake, (max - x) / (max - min), flips the ranking. When all scores are
+ * equal (max === min), every item is equally relevant, so map to 1.
+ */
+export declare function minMaxNormalize(scores: Map<string, number>): Map<string, number>;
+/** Normalize each retriever's scores to [0, 1], then take a weighted sum. */
+export declare function weightedSumFusion(scoreMaps: Array<Map<string, number>>, weights: number[]): Map<string, number>;
+/** The k highest-scoring IDs, best first. */
+export declare function topKIds(scores: Map<string, number>, k: number): string[];

package/dist/retrieval/fusion.js

@@ -0,0 +1,70 @@
+/**
+ * Combine results from multiple retrievers into one ranking.
+ *
+ * - Reciprocal Rank Fusion (RRF): combines by *rank*, so it never has to make an unbounded
+ *   BM25 score and a 0-1 cosine score comparable. Robust, and the default.
+ * - Normalized weighted sum: combines by *score*, which first requires normalizing each
+ *   retriever to [0, 1] — and that normalization has a sharp edge (see below).
+ *
+ * War story encoded as a test: the inverted min-max `(max - x) / (max - min)` maps the BEST
+ * score to 0 and the WORST to 1, silently pushing the most relevant documents to the bottom
+ * where they get truncated before the model ever sees them. `fusion.test.ts` asserts the
+ * correct direction so that inversion can never return unnoticed.
+ */
+/** Fuse ranked ID lists. A doc's score is the sum of 1/(k + rank) across lists (rank is 1-based). */
+export function reciprocalRankFusion(rankings, k = 60) {
+    const scores = new Map();
+    for (const ranking of rankings) {
+        ranking.forEach((docId, position) => {
+            const rank = position + 1;
+            scores.set(docId, (scores.get(docId) ?? 0) + 1 / (k + rank));
+        });
+    }
+    return scores;
+}
+/**
+ * Rescale scores to [0, 1] preserving order: best -> 1, worst -> 0.
+ *
+ * CORRECT: norm(x) = (x - min) / (max - min).
+ * The inverted mistake, (max - x) / (max - min), flips the ranking. When all scores are
+ * equal (max === min), every item is equally relevant, so map to 1.
+ */
+export function minMaxNormalize(scores) {
+    const out = new Map();
+    if (scores.size === 0)
+        return out;
+    const values = [...scores.values()];
+    const lo = Math.min(...values);
+    const hi = Math.max(...values);
+    if (hi === lo) {
+        for (const key of scores.keys())
+            out.set(key, 1);
+        return out;
+    }
+    const span = hi - lo;
+    for (const [key, value] of scores)
+        out.set(key, (value - lo) / span);
+    return out;
+}
+/** Normalize each retriever's scores to [0, 1], then take a weighted sum. */
+export function weightedSumFusion(scoreMaps, weights) {
+    if (scoreMaps.length !== weights.length) {
+        throw new Error("scoreMaps and weights length mismatch");
+    }
+    const fused = new Map();
+    scoreMaps.forEach((scoreMap, i) => {
+        const weight = weights[i] ?? 0;
+        for (const [docId, value] of minMaxNormalize(scoreMap)) {
+            fused.set(docId, (fused.get(docId) ?? 0) + weight * value);
+        }
+    });
+    return fused;
+}
+/** The k highest-scoring IDs, best first. */
+export function topKIds(scores, k) {
+    return [...scores.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, k)
+        .map(([id]) => id);
+}
+//# sourceMappingURL=fusion.js.map

package/dist/retrieval/fusion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fusion.js","sourceRoot":"","sources":["../../src/retrieval/fusion.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP server: exposes the retrieval engine as MCP tools, resources, and prompts.
+ *
+ * Built on the MCP TypeScript SDK (`McpServer`). Each tool's zod `inputSchema` becomes the
+ * JSON Schema the host LLM reads to decide when and how to call it, so the descriptions are
+ * part of the interface, not just docs.
+ *
+ * `createServer()` returns a fresh instance with its own collection registry — so tests can
+ * spin up isolated servers instead of sharing global state.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Embedder } from "./embeddings.js";
+export declare function createServer(embedder?: Embedder): McpServer;

package/dist/server.js

@@ -0,0 +1,170 @@
+/**
+ * MCP server: exposes the retrieval engine as MCP tools, resources, and prompts.
+ *
+ * Built on the MCP TypeScript SDK (`McpServer`). Each tool's zod `inputSchema` becomes the
+ * JSON Schema the host LLM reads to decide when and how to call it, so the descriptions are
+ * part of the interface, not just docs.
+ *
+ * `createServer()` returns a fresh instance with its own collection registry — so tests can
+ * spin up isolated servers instead of sharing global state.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { Collection } from "./collection.js";
+import { HashingEmbedder } from "./embeddings.js";
+import { evaluate } from "./eval.js";
+import * as grounding from "./grounding.js";
+import { loadPaths, loadTexts } from "./ingest.js";
+import { VERSION } from "./version.js";
+function text(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+}
+export function createServer(embedder = new HashingEmbedder(512)) {
+    const collections = new Map();
+    const getOrCreate = (name) => {
+        let col = collections.get(name);
+        if (col === undefined) {
+            col = new Collection(name, embedder);
+            collections.set(name, col);
+        }
+        return col;
+    };
+    const mcp = new McpServer({ name: "grounded-rag-mcp", version: VERSION });
+    mcp.registerTool("ingest_documents", {
+        description: "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.",
+        inputSchema: {
+            collection: z.string().default("default"),
+            paths: z.array(z.string()).optional(),
+            texts: z.array(z.string()).optional(),
+            chunkSize: z.number().int().min(1).default(200),
+            chunkOverlap: z.number().int().min(0).default(40),
+        },
+    }, async ({ collection, paths, texts, chunkSize, chunkOverlap }) => {
+        if ((paths === undefined || paths.length === 0) &&
+            (texts === undefined || texts.length === 0)) {
+            throw new Error("Provide `paths` and/or `texts` to ingest.");
+        }
+        const cfg = { size: chunkSize, overlap: chunkOverlap };
+        const chunks = [
+            ...(paths ? loadPaths(paths, cfg) : []),
+            ...(texts ? loadTexts(texts, cfg) : []),
+        ];
+        const col = getOrCreate(collection);
+        col.add(chunks);
+        return text({ collection, chunksAdded: chunks.length, totalChunks: col.numChunks });
+    });
+    mcp.registerTool("search", {
+        description: "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.",
+        inputSchema: {
+            query: z.string(),
+            collection: z.string().default("default"),
+            topK: z.number().int().min(1).default(5),
+            mode: z.enum(["hybrid", "dense", "bm25"]).default("hybrid"),
+        },
+    }, async ({ query, collection, topK, mode }) => {
+        const col = collections.get(collection);
+        if (col === undefined)
+            return text([]);
+        const hits = col.retrieve(query, { topK, mode: mode });
+        return text(hits.map((h) => ({
+            text: h.chunk.text,
+            source: h.chunk.source,
+            chunkId: h.chunk.chunkId,
+            score: Math.round(h.score * 1e6) / 1e6,
+            stageScores: h.stageScores,
+        })));
+    });
+    mcp.registerTool("answer", {
+        description: "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.",
+        inputSchema: {
+            query: z.string(),
+            collection: z.string().default("default"),
+            topK: z.number().int().min(1).default(5),
+        },
+    }, async ({ query, collection, topK }) => {
+        const col = collections.get(collection);
+        const hits = col ? col.retrieve(query, { topK }) : [];
+        if (hits.length === 0) {
+            return text({ grounded: false, answer: grounding.NOT_FOUND, citations: [] });
+        }
+        const citations = grounding.buildCitations(hits);
+        const context = grounding.buildContext(hits);
+        try {
+            const result = await mcp.server.createMessage({
+                messages: [
+                    {
+                        role: "user",
+                        content: {
+                            type: "text",
+                            text: `Context passages:\n\n${context}\n\nQuestion: ${query}`,
+                        },
+                    },
+                ],
+                maxTokens: 512,
+                systemPrompt: grounding.GROUNDING_SYSTEM_PROMPT,
+                temperature: 0,
+            });
+            const answerText = result.content.type === "text" ? result.content.text : "";
+            return text({ grounded: true, answer: answerText, citations });
+        }
+        catch {
+            // Host has no sampling — hand back grounded context so it can answer itself.
+            return text({
+                grounded: true,
+                answer: null,
+                citations,
+                context,
+                note: "Host has no sampling; compose the answer from `context`, citing sources.",
+            });
+        }
+    });
+    mcp.registerTool("list_collections", { description: "List all ingested collections and how many chunks each contains." }, async () => text([...collections.entries()].map(([name, col]) => ({ name, chunks: col.numChunks }))));
+    mcp.registerTool("evaluate_retrieval", {
+        description: "Measure retrieval quality on labeled cases: hitRate, mrr, recallAtK. Each case is " +
+            "{query, relevantSources}. Use it to quantify quality and catch regressions.",
+        inputSchema: {
+            cases: z.array(z.object({ query: z.string(), relevantSources: z.array(z.string()) })),
+            collection: z.string().default("default"),
+            topK: z.number().int().min(1).default(5),
+            mode: z.enum(["hybrid", "dense", "bm25"]).default("hybrid"),
+        },
+    }, async ({ cases, collection, topK, mode }) => {
+        const col = collections.get(collection);
+        if (col === undefined)
+            return text({ cases: 0, hitRate: 0, mrr: 0, recallAtK: 0, topK });
+        return text(evaluate(col, cases, topK, mode));
+    });
+    mcp.registerResource("collections", "rag://collections", {
+        title: "Collections",
+        description: "Ingested collections and chunk counts",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                text: JSON.stringify([...collections.entries()].map(([name, col]) => ({ name, chunks: col.numChunks }))),
+            },
+        ],
+    }));
+    mcp.registerPrompt("grounded_answer", {
+        title: "Grounded answer",
+        description: "Instructs strict, cited, grounded answering.",
+        argsSchema: { question: z.string() },
+    }, ({ question }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `${grounding.GROUNDING_SYSTEM_PROMPT}\n\nQuestion: ${question}`,
+                },
+            },
+        ],
+    }));
+    return mcp;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/stores/memory.d.ts

@@ -0,0 +1,18 @@
+/** A dependency-free, in-memory vector store (dense retrieval by exact cosine). */
+export declare class InMemoryVectorStore {
+    readonly dim: number;
+    private ids;
+    private matrix;
+    constructor(dim: number);
+    add(ids: string[], vectors: number[][]): void;
+    /**
+     * Return [chunkId, cosine] for the top-k nearest vectors.
+     *
+     * Vectors are pre-normalized (the embedder does it), so a dot product IS the cosine.
+     * Zero-similarity hits are dropped: a 0 cosine means no shared signal at all, and
+     * surfacing it would feed the model irrelevant context and invite an ungrounded answer.
+     * Exact O(n) search is fine to tens of thousands of chunks; swap in an ANN index beyond.
+     */
+    search(query: number[], topK: number): Array<[string, number]>;
+    get size(): number;
+}

package/dist/stores/memory.js

@@ -0,0 +1,45 @@
+/** A dependency-free, in-memory vector store (dense retrieval by exact cosine). */
+export class InMemoryVectorStore {
+    dim;
+    ids = [];
+    matrix = [];
+    constructor(dim) {
+        this.dim = dim;
+    }
+    add(ids, vectors) {
+        if (ids.length !== vectors.length) {
+            throw new Error("ids and vectors length mismatch");
+        }
+        this.ids.push(...ids);
+        this.matrix.push(...vectors);
+    }
+    /**
+     * Return [chunkId, cosine] for the top-k nearest vectors.
+     *
+     * Vectors are pre-normalized (the embedder does it), so a dot product IS the cosine.
+     * Zero-similarity hits are dropped: a 0 cosine means no shared signal at all, and
+     * surfacing it would feed the model irrelevant context and invite an ungrounded answer.
+     * Exact O(n) search is fine to tens of thousands of chunks; swap in an ANN index beyond.
+     */
+    search(query, topK) {
+        const sims = [];
+        for (let i = 0; i < this.ids.length; i++) {
+            const row = this.matrix[i];
+            const id = this.ids[i];
+            if (row === undefined || id === undefined)
+                continue;
+            let dot = 0;
+            for (let j = 0; j < row.length; j++) {
+                dot += (row[j] ?? 0) * (query[j] ?? 0);
+            }
+            if (dot > 0)
+                sims.push([id, dot]);
+        }
+        sims.sort((a, b) => b[1] - a[1]);
+        return sims.slice(0, topK);
+    }
+    get size() {
+        return this.ids.length;
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/stores/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAEnF,MAAM,OAAO,mBAAmB;IACrB,GAAG,CAAS;IACb,GAAG,GAAa,EAAE,CAAC;IACnB,MAAM,GAAe,EAAE,CAAC;IAEhC,YAAY,GAAW;QACrB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,GAAG,CAAC,GAAa,EAAE,OAAmB;QACpC,IAAI,GAAG,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,KAAe,EAAE,IAAY;QAClC,MAAM,IAAI,GAA4B,EAAE,CAAC;QACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACzC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvB,IAAI,GAAG,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS;gBAAE,SAAS;YACpD,IAAI,GAAG,GAAG,CAAC,CAAC;YACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACpC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YACzC,CAAC;YACD,IAAI,GAAG,GAAG,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;IACzB,CAAC;CACF"}

package/dist/text.d.ts

@@ -0,0 +1,8 @@
+/** Shared text utilities: one tokenizer used by BM25 and the hashing embedder. */
+/**
+ * Lowercase and split into alphanumeric tokens.
+ *
+ * One shared tokenizer means index-time and query-time tokenization can never drift
+ * apart — a classic and hard-to-spot source of retrieval bugs.
+ */
+export declare function tokenize(text: string): string[];

package/dist/text.js

@@ -0,0 +1,12 @@
+/** Shared text utilities: one tokenizer used by BM25 and the hashing embedder. */
+const TOKEN_RE = /[a-z0-9]+/g;
+/**
+ * Lowercase and split into alphanumeric tokens.
+ *
+ * One shared tokenizer means index-time and query-time tokenization can never drift
+ * apart — a classic and hard-to-spot source of retrieval bugs.
+ */
+export function tokenize(text) {
+    return text.toLowerCase().match(TOKEN_RE) ?? [];
+}
+//# sourceMappingURL=text.js.map

package/dist/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;AAClD,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The package version, kept in one place and asserted by the smoke test. */
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1,3 @@
+/** The package version, kept in one place and asserted by the smoke test. */
+export const VERSION = "0.1.0";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "grounded-rag-mcp",
+  "version": "0.1.0",
+  "description": "An MCP server that gives any LLM host grounded, cited retrieval over your own documents — hybrid BM25 + dense retrieval, cross-encoder-ready reranking, and built-in eval.",
+  "type": "module",
+  "bin": {
+    "grounded-rag-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "mcp",
+    "rag",
+    "retrieval",
+    "llm",
+    "embeddings",
+    "hybrid-search",
+    "reranking",
+    "model-context-protocol"
+  ],
+  "author": "Chetan C",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chetan1521/grounded-rag-mcp-ts.git"
+  },
+  "homepage": "https://github.com/chetan1521/grounded-rag-mcp-ts",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "eslint": "^9.12.0",
+    "prettier": "^3.3.3",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.8.0",
+    "vitest": "^2.1.2"
+  }
+}