retrieval-lens 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# retrieval-lens
+
+> A black-box flight recorder for RAG retrieval inside MCP agents.
+
+**retrieval-lens** is an MCP server that logs every retrieval step your RAG agent makes — what chunks were retrieved, their scores, sources, and rankings — so you can audit, replay, and diff retrieval runs after the fact.
+
+```bash
+npx retrieval-lens
+```
+
+---
+
+## The Problem
+
+When a RAG agent gives a wrong answer, you need to know: did retrieval fail, or did generation fail? Right now there's no easy way to answer that. Your observability tool shows you the LLM call. It doesn't show you which chunks the model saw before it answered, what scores they had, or how retrieval changed between yesterday and today.
+
+retrieval-lens fixes that. Every retrieval run is logged. Nothing is hidden.
+
+---
+
+## MCP Tools
+
+| Tool | What it does |
+|---|---|
+| `retrieval_observe` | Log a retrieval run — query, chunks, scores, sources, rankings |
+| `retrieval_query` | Replay what the model saw before a specific answer |
+| `retrieval_diff` | Compare two retrieval runs — what changed, what score drifted |
+| `retrieval_stats` | Aggregate score distributions, top sources, runs over time |
+
+---
+
+## Quickstart
+
+Add to your MCP client config (Claude Desktop, Cursor, Windsurf):
+
+```json
+{
+  "mcpServers": {
+    "retrieval-lens": {
+      "command": "npx",
+      "args": ["retrieval-lens"]
+    }
+  }
+}
+```
+
+Then call `retrieval_observe` after every retrieval step in your RAG pipeline:
+
+```typescript
+await mcp.call("retrieval_observe", {
+  run_id: crypto.randomUUID(),
+  query: "what is the refund policy?",
+  chunks: [
+    { content: "Refunds are processed within 5 days...", score: 0.91, source: "policy.md", rank: 1 },
+    { content: "Contact support for refund requests...", score: 0.74, source: "faq.md", rank: 2 }
+  ],
+  pipeline_tag: "support-bot"
+});
+```
+
+---
+
+## Why not LangSmith / Langfuse?
+
+Those are full observability platforms. retrieval-lens is surgical:
+
+- **Local-first** — SQLite, zero signup, no data leaves your machine
+- **MCP-native** — one config line, works in any MCP client
+- **Retrieval-only** — focused on the layer where most RAG failures actually happen
+
+---
+
+## Status
+
+🚧 Active development. Harness-first build using [harness engineering](https://walkinglabs.github.io/learn-harness-engineering/en/) principles.
+
+- [x] F05 — scaffold
+- [ ] F01 — `retrieval_observe`
+- [ ] F02 — `retrieval_query`
+- [ ] F03 — `retrieval_diff`
+- [ ] F04 — `retrieval_stats`
+
+---
+
+## License
+
+MIT

package/dist/db/index.d.ts

@@ -0,0 +1,63 @@
+import { type Client } from "@libsql/client";
+export interface ObservedChunkRecord {
+    content: string;
+    content_hash: string;
+    score: number;
+    source: string;
+    rank: number;
+}
+export interface ObservedRunRecord {
+    run_id: string;
+    query: string;
+    pipeline_tag: string | null;
+    created_at: string;
+    chunks: ObservedChunkRecord[];
+}
+export interface QueryRunFilter {
+    run_id?: string | undefined;
+    pipeline_tag?: string | undefined;
+    since_iso?: string | undefined;
+    limit: number;
+}
+export interface RetrievedChunkRecord {
+    content: string;
+    score: number;
+    source: string;
+    rank: number;
+}
+export interface RetrievedRunRecord {
+    run_id: string;
+    query: string;
+    pipeline_tag: string | null;
+    created_at: string;
+    chunks: RetrievedChunkRecord[];
+}
+export interface StatsRunFilter {
+    pipeline_tag?: string | undefined;
+    since_iso?: string | undefined;
+    until_iso?: string | undefined;
+}
+export interface StatsChunkRecord {
+    score: number;
+    source: string;
+    rank: number;
+}
+export interface StatsRunRecord {
+    run_id: string;
+    created_at: string;
+    chunks: StatsChunkRecord[];
+}
+export interface DiffChunkRecord {
+    content: string;
+    content_hash: string;
+    score: number;
+    source: string;
+    rank: number;
+}
+export declare function getDb(): Promise<Client>;
+export declare function insertObservedRun(run: ObservedRunRecord): Promise<boolean>;
+export declare function findRetrievedRuns(filter: QueryRunFilter): Promise<RetrievedRunRecord[]>;
+export declare function runExists(runId: string): Promise<boolean>;
+export declare function findDiffChunks(runId: string): Promise<DiffChunkRecord[]>;
+export declare function findStatsRuns(filter: StatsRunFilter): Promise<StatsRunRecord[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAS3D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,mBAAmB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAGD,MAAM,WAAW,cAAc;IAC7B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AA0DD,wBAAsB,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAQ7C;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAgChF;AAkBD,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA4D7F;AAED,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ/D;AAED,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAc9E;AAGD,wBAAsB,aAAa,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAwDrF"}

package/dist/db/index.js

@@ -0,0 +1,222 @@
+import { createClient } from "@libsql/client";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, tmpdir } from "node:os";
+let db;
+let initializing;
+function defaultDbUrl() {
+    return `file:${join(homedir(), ".retrieval-lens", "audit.db")}`;
+}
+function configuredDbUrl() {
+    const configured = process.env.RETRIEVAL_LENS_DB;
+    if (configured === undefined || configured.length === 0) {
+        return defaultDbUrl();
+    }
+    if (configured === ":memory:") {
+        return `file:${join(tmpdir(), `retrieval-lens-${process.pid}.db`)}`;
+    }
+    if (configured.includes(":")) {
+        return configured;
+    }
+    return `file:${configured}`;
+}
+async function readSchema() {
+    const currentFile = fileURLToPath(import.meta.url);
+    const localSchemaPath = join(dirname(currentFile), "schema.sql");
+    try {
+        return await readFile(localSchemaPath, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return readFile(join(process.cwd(), "src", "db", "schema.sql"), "utf8");
+        }
+        throw error;
+    }
+}
+async function initializeDb() {
+    const url = configuredDbUrl();
+    if (url.startsWith("file:") && url !== "file::memory:") {
+        await mkdir(dirname(url.slice("file:".length)), { recursive: true });
+    }
+    const client = createClient({ url });
+    const schema = await readSchema();
+    await client.migrate(schema
+        .split(";")
+        .map((statement) => statement.trim())
+        .filter((statement) => statement.length > 0));
+    return client;
+}
+export async function getDb() {
+    if (db !== undefined) {
+        return db;
+    }
+    initializing ??= initializeDb();
+    db = await initializing;
+    return db;
+}
+export async function insertObservedRun(run) {
+    const client = await getDb();
+    const transaction = await client.transaction("write");
+    let committed = false;
+    try {
+        const insertRun = await transaction.execute({
+            sql: "INSERT OR IGNORE INTO runs (run_id, query, pipeline_tag, created_at) VALUES (?, ?, ?, ?)",
+            args: [run.run_id, run.query, run.pipeline_tag, run.created_at],
+        });
+        if (insertRun.rowsAffected === 0) {
+            await transaction.commit();
+            committed = true;
+            return false;
+        }
+        for (const chunk of run.chunks) {
+            await transaction.execute({
+                sql: "INSERT INTO chunks (run_id, content, content_hash, score, source, rank) VALUES (?, ?, ?, ?, ?, ?)",
+                args: [run.run_id, chunk.content, chunk.content_hash, chunk.score, chunk.source, chunk.rank],
+            });
+        }
+        await transaction.commit();
+        committed = true;
+        return true;
+    }
+    finally {
+        if (!committed) {
+            transaction.close();
+        }
+    }
+}
+function textValue(value) {
+    return typeof value === "string" ? value : String(value);
+}
+function nullableTextValue(value) {
+    if (value === null) {
+        return null;
+    }
+    return textValue(value);
+}
+function numericValue(value) {
+    return typeof value === "number" ? value : Number(value);
+}
+export async function findRetrievedRuns(filter) {
+    const client = await getDb();
+    const conditions = [];
+    const args = [];
+    const limit = filter.run_id === undefined ? filter.limit : 1;
+    if (filter.run_id !== undefined) {
+        conditions.push("run_id = ?");
+        args.push(filter.run_id);
+    }
+    else {
+        if (filter.pipeline_tag !== undefined) {
+            conditions.push("pipeline_tag = ?");
+            args.push(filter.pipeline_tag);
+        }
+        if (filter.since_iso !== undefined) {
+            conditions.push("created_at >= ?");
+            args.push(filter.since_iso);
+        }
+    }
+    const whereClause = conditions.length === 0 ? "" : `WHERE ${conditions.join(" AND ")}`;
+    const runResult = await client.execute({
+        sql: `SELECT run_id, query, pipeline_tag, created_at FROM runs ${whereClause} ORDER BY created_at DESC LIMIT ?`,
+        args: [...args, limit],
+    });
+    const runs = runResult.rows.map((row) => ({
+        run_id: textValue(row.run_id),
+        query: textValue(row.query),
+        pipeline_tag: nullableTextValue(row.pipeline_tag),
+        created_at: textValue(row.created_at),
+        chunks: [],
+    }));
+    if (runs.length === 0) {
+        return [];
+    }
+    const chunksByRun = new Map(runs.map((run) => [run.run_id, run.chunks]));
+    const placeholders = runs.map(() => "?").join(", ");
+    const chunkResult = await client.execute({
+        sql: `SELECT run_id, content, score, source, rank FROM chunks WHERE run_id IN (${placeholders}) ORDER BY run_id, rank ASC`,
+        args: runs.map((run) => run.run_id),
+    });
+    for (const row of chunkResult.rows) {
+        const runChunks = chunksByRun.get(textValue(row.run_id));
+        if (runChunks !== undefined) {
+            runChunks.push({
+                content: textValue(row.content),
+                score: numericValue(row.score),
+                source: textValue(row.source),
+                rank: numericValue(row.rank),
+            });
+        }
+    }
+    return runs;
+}
+export async function runExists(runId) {
+    const client = await getDb();
+    const result = await client.execute({
+        sql: "SELECT 1 FROM runs WHERE run_id = ? LIMIT 1",
+        args: [runId],
+    });
+    return result.rows.length > 0;
+}
+export async function findDiffChunks(runId) {
+    const client = await getDb();
+    const result = await client.execute({
+        sql: "SELECT content, content_hash, score, source, rank FROM chunks WHERE run_id = ? ORDER BY rank ASC",
+        args: [runId],
+    });
+    return result.rows.map((row) => ({
+        content: textValue(row.content),
+        content_hash: textValue(row.content_hash),
+        score: numericValue(row.score),
+        source: textValue(row.source),
+        rank: numericValue(row.rank),
+    }));
+}
+export async function findStatsRuns(filter) {
+    const client = await getDb();
+    const conditions = [];
+    const args = [];
+    if (filter.pipeline_tag !== undefined) {
+        conditions.push("pipeline_tag = ?");
+        args.push(filter.pipeline_tag);
+    }
+    if (filter.since_iso !== undefined) {
+        conditions.push("created_at >= ?");
+        args.push(filter.since_iso);
+    }
+    if (filter.until_iso !== undefined) {
+        conditions.push("created_at <= ?");
+        args.push(filter.until_iso);
+    }
+    const whereClause = conditions.length === 0 ? "" : `WHERE ${conditions.join(" AND ")}`;
+    const runResult = await client.execute({
+        sql: `SELECT run_id, created_at FROM runs ${whereClause} ORDER BY created_at ASC`,
+        args,
+    });
+    const runs = runResult.rows.map((row) => ({
+        run_id: textValue(row.run_id),
+        created_at: textValue(row.created_at),
+        chunks: [],
+    }));
+    if (runs.length === 0) {
+        return [];
+    }
+    const chunksByRun = new Map(runs.map((run) => [run.run_id, run.chunks]));
+    const placeholders = runs.map(() => "?").join(", ");
+    const chunkResult = await client.execute({
+        sql: `SELECT run_id, score, source, rank FROM chunks WHERE run_id IN (${placeholders}) ORDER BY run_id, rank ASC`,
+        args: runs.map((run) => run.run_id),
+    });
+    for (const row of chunkResult.rows) {
+        const runChunks = chunksByRun.get(textValue(row.run_id));
+        if (runChunks !== undefined) {
+            runChunks.push({
+                score: numericValue(row.score),
+                source: textValue(row.source),
+                rank: numericValue(row.rank),
+            });
+        }
+    }
+    return runs;
+}
+//# sourceMappingURL=index.js.map

package/dist/db/index.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA2BpE,wBAAgB,YAAY,IAAI,SAAS,CAmGxC"}

package/dist/index.js

@@ -0,0 +1,108 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getDb } from "./db/index.js";
+import { retrievalObserve } from "./tools/observe.js";
+import { retrievalQuery } from "./tools/query.js";
+import { retrievalDiff } from "./tools/diff.js";
+import { retrievalStats } from "./tools/stats.js";
+import { logger } from "./utils/logger.js";
+const chunkSchema = z.object({
+    content: z.string(),
+    score: z.number(),
+    source: z.string(),
+    rank: z.number().int(),
+});
+const retrievedChunkSchema = chunkSchema;
+function asStructuredContent(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value) }],
+        structuredContent: value,
+    };
+}
+export function createServer() {
+    const server = new McpServer({ name: "retrieval-lens", version: "0.1.0" });
+    server.registerTool("retrieval_observe", {
+        title: "Retrieval Observe",
+        description: "Stub capture tool for retrieval runs.",
+        inputSchema: z.object({
+            run_id: z.string(),
+            query: z.string(),
+            chunks: z.array(chunkSchema),
+            pipeline_tag: z.string().optional(),
+        }),
+        outputSchema: z.object({
+            stored: z.boolean(),
+            run_id: z.string(),
+            chunk_count: z.number(),
+        }),
+    }, async (input) => asStructuredContent(await retrievalObserve(input)));
+    server.registerTool("retrieval_query", {
+        title: "Retrieval Query",
+        description: "Stub playback tool for retrieval runs.",
+        inputSchema: z.object({
+            run_id: z.string().optional(),
+            pipeline_tag: z.string().optional(),
+            limit: z.number().optional(),
+            since_iso: z.string().optional(),
+        }),
+        outputSchema: z.object({
+            runs: z.array(z.object({
+                run_id: z.string(),
+                query: z.string(),
+                pipeline_tag: z.string().nullable(),
+                timestamp: z.string(),
+                chunks: z.array(retrievedChunkSchema),
+            })),
+        }),
+    }, async (input) => asStructuredContent(await retrievalQuery(input)));
+    server.registerTool("retrieval_diff", {
+        title: "Retrieval Diff",
+        description: "Stub comparison tool for retrieval runs.",
+        inputSchema: z.object({
+            run_id_a: z.string(),
+            run_id_b: z.string(),
+            match_by: z.enum(["source", "content_hash"]),
+        }),
+        outputSchema: z.object({
+            only_in_a: z.array(retrievedChunkSchema),
+            only_in_b: z.array(retrievedChunkSchema),
+            shared: z.array(z.object({
+                chunk: retrievedChunkSchema,
+                score_a: z.number(),
+                score_b: z.number(),
+                score_delta: z.number(),
+            })),
+            summary: z.string(),
+        }),
+    }, async (input) => asStructuredContent(await retrievalDiff(input)));
+    server.registerTool("retrieval_stats", {
+        title: "Retrieval Stats",
+        description: "Stub aggregate stats tool for retrieval runs.",
+        inputSchema: z.object({
+            pipeline_tag: z.string().optional(),
+            since_iso: z.string().optional(),
+            until_iso: z.string().optional(),
+        }),
+        outputSchema: z.object({
+            total_runs: z.number(),
+            avg_top1_score: z.number(),
+            p50_score: z.number(),
+            p90_score: z.number(),
+            top_sources: z.array(z.object({ source: z.string(), count: z.number() })),
+            runs_per_day: z.array(z.object({ date: z.string(), count: z.number() })),
+        }),
+    }, async (input) => asStructuredContent(await retrievalStats(input)));
+    return server;
+}
+async function main() {
+    await getDb();
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(message);
+    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":"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"}

package/dist/tools/diff.d.ts

@@ -0,0 +1,26 @@
+export type MatchBy = "source" | "content_hash";
+export interface DiffInput {
+    run_id_a: string;
+    run_id_b: string;
+    match_by: MatchBy;
+}
+export interface DiffChunk {
+    content: string;
+    score: number;
+    source: string;
+    rank: number;
+}
+export interface SharedChunk {
+    chunk: DiffChunk;
+    score_a: number;
+    score_b: number;
+    score_delta: number;
+}
+export interface DiffOutput {
+    only_in_a: DiffChunk[];
+    only_in_b: DiffChunk[];
+    shared: SharedChunk[];
+    summary: string;
+}
+export declare function retrievalDiff(input: DiffInput): Promise<DiffOutput>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/tools/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/tools/diff.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEhD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB;AA6CD,wBAAsB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CA4CzE"}

package/dist/tools/diff.js

@@ -0,0 +1,71 @@
+import { findDiffChunks, runExists } from "../db/index.js";
+function publicChunk(chunk) {
+    return {
+        content: chunk.content,
+        score: chunk.score,
+        source: chunk.source,
+        rank: chunk.rank,
+    };
+}
+function matchKey(chunk, matchBy) {
+    return matchBy === "source" ? chunk.source : chunk.content_hash;
+}
+function indexChunks(chunks, matchBy) {
+    const indexed = new Map();
+    chunks.forEach((chunk, index) => {
+        const key = matchKey(chunk, matchBy);
+        const existing = indexed.get(key);
+        const value = { chunk, index };
+        if (existing === undefined) {
+            indexed.set(key, [value]);
+        }
+        else {
+            existing.push(value);
+        }
+    });
+    return indexed;
+}
+function buildSummary(onlyInA, onlyInB, shared) {
+    const averageDelta = shared.length === 0 ? 0 : shared.reduce((total, current) => total + current.score_delta, 0) / shared.length;
+    return `${onlyInA.length} chunks only in A, ${onlyInB.length} only in B, ${shared.length} shared (avg delta ${averageDelta.toFixed(2)})`;
+}
+export async function retrievalDiff(input) {
+    const [runAExists, runBExists] = await Promise.all([runExists(input.run_id_a), runExists(input.run_id_b)]);
+    if (!runAExists) {
+        throw new Error(`run_id ${input.run_id_a} not found`);
+    }
+    if (!runBExists) {
+        throw new Error(`run_id ${input.run_id_b} not found`);
+    }
+    const [chunksA, chunksB] = await Promise.all([findDiffChunks(input.run_id_a), findDiffChunks(input.run_id_b)]);
+    const indexedB = indexChunks(chunksB, input.match_by);
+    const matchedBIndexes = new Set();
+    const onlyInA = [];
+    const shared = [];
+    for (const chunkA of chunksA) {
+        const candidates = indexedB.get(matchKey(chunkA, input.match_by));
+        const match = candidates?.find((candidate) => !matchedBIndexes.has(candidate.index));
+        if (match === undefined) {
+            onlyInA.push(publicChunk(chunkA));
+        }
+        else {
+            matchedBIndexes.add(match.index);
+            shared.push({
+                chunk: publicChunk(chunkA),
+                score_a: chunkA.score,
+                score_b: match.chunk.score,
+                score_delta: match.chunk.score - chunkA.score,
+            });
+        }
+    }
+    const onlyInB = chunksB
+        .filter((_chunk, index) => !matchedBIndexes.has(index))
+        .map((chunk) => publicChunk(chunk));
+    return {
+        only_in_a: onlyInA,
+        only_in_b: onlyInB,
+        shared,
+        summary: buildSummary(onlyInA, onlyInB, shared),
+    };
+}
+//# sourceMappingURL=diff.js.map

package/dist/tools/diff.js.map

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

package/dist/tools/observe.d.ts

@@ -0,0 +1,18 @@
+export interface ObserveInput {
+    run_id: string;
+    query: string;
+    chunks: Array<{
+        content: string;
+        score: number;
+        source: string;
+        rank: number;
+    }>;
+    pipeline_tag?: string | undefined;
+}
+export interface ObserveOutput {
+    stored: boolean;
+    run_id: string;
+    chunk_count: number;
+}
+export declare function retrievalObserve(input: ObserveInput): Promise<ObserveOutput>;
+//# sourceMappingURL=observe.d.ts.map

package/dist/tools/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/tools/observe.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,KAAK,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAMD,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAoBlF"}

package/dist/tools/observe.js

@@ -0,0 +1,24 @@
+import { createHash } from "node:crypto";
+import { insertObservedRun } from "../db/index.js";
+function contentHash(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export async function retrievalObserve(input) {
+    const createdAt = new Date().toISOString();
+    const chunks = input.chunks.map((chunk) => ({
+        ...chunk,
+        content_hash: contentHash(chunk.content),
+    }));
+    const stored = await insertObservedRun({
+        run_id: input.run_id,
+        query: input.query,
+        pipeline_tag: input.pipeline_tag ?? null,
+        created_at: createdAt,
+        chunks,
+    });
+    if (!stored) {
+        return { stored: false, run_id: input.run_id, chunk_count: 0 };
+    }
+    return { stored: true, run_id: input.run_id, chunk_count: input.chunks.length };
+}
+//# sourceMappingURL=observe.js.map

package/dist/tools/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/tools/observe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAoBnD,SAAS,WAAW,CAAC,OAAe;IAClC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAmB;IACxD,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,GAAG,KAAK;QACR,YAAY,EAAE,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC;KACzC,CAAC,CAAC,CAAC;IAEJ,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC;QACrC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,UAAU,EAAE,SAAS;QACrB,MAAM;KACP,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IACjE,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;AAClF,CAAC"}

package/dist/tools/query.d.ts

@@ -0,0 +1,24 @@
+export interface QueryInput {
+    run_id?: string | undefined;
+    pipeline_tag?: string | undefined;
+    limit?: number | undefined;
+    since_iso?: string | undefined;
+}
+export interface RetrievedChunk {
+    content: string;
+    score: number;
+    source: string;
+    rank: number;
+}
+export interface RunRecord {
+    run_id: string;
+    query: string;
+    pipeline_tag: string | null;
+    timestamp: string;
+    chunks: RetrievedChunk[];
+}
+export interface QueryOutput {
+    runs: RunRecord[];
+}
+export declare function retrievalQuery(input?: QueryInput): Promise<QueryOutput>;
+//# sourceMappingURL=query.d.ts.map

package/dist/tools/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,EAAE,CAAC;CACnB;AAaD,wBAAsB,cAAc,CAAC,KAAK,GAAE,UAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAiBjF"}

package/dist/tools/query.js

@@ -0,0 +1,27 @@
+import { findRetrievedRuns } from "../db/index.js";
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+function normalizeLimit(limit) {
+    if (limit === undefined) {
+        return DEFAULT_LIMIT;
+    }
+    return Math.min(Math.max(Math.trunc(limit), 0), MAX_LIMIT);
+}
+export async function retrievalQuery(input = {}) {
+    const runs = await findRetrievedRuns({
+        run_id: input.run_id,
+        pipeline_tag: input.pipeline_tag,
+        since_iso: input.since_iso,
+        limit: normalizeLimit(input.limit),
+    });
+    return {
+        runs: runs.map((run) => ({
+            run_id: run.run_id,
+            query: run.query,
+            pipeline_tag: run.pipeline_tag,
+            timestamp: run.created_at,
+            chunks: run.chunks,
+        })),
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/tools/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/tools/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AA4BnD,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB,SAAS,cAAc,CAAC,KAAyB;IAC/C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAoB,EAAE;IACzD,MAAM,IAAI,GAAG,MAAM,iBAAiB,CAAC;QACnC,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC;KACnC,CAAC,CAAC;IAEH,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACvB,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,YAAY,EAAE,GAAG,CAAC,YAAY;YAC9B,SAAS,EAAE,GAAG,CAAC,UAAU;YACzB,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC"}

package/dist/tools/stats.d.ts

@@ -0,0 +1,21 @@
+export interface StatsInput {
+    pipeline_tag?: string | undefined;
+    since_iso?: string | undefined;
+    until_iso?: string | undefined;
+}
+export interface StatsOutput {
+    total_runs: number;
+    avg_top1_score: number;
+    p50_score: number;
+    p90_score: number;
+    top_sources: Array<{
+        source: string;
+        count: number;
+    }>;
+    runs_per_day: Array<{
+        date: string;
+        count: number;
+    }>;
+}
+export declare function retrievalStats(input?: StatsInput): Promise<StatsOutput>;
+//# sourceMappingURL=stats.d.ts.map

package/dist/tools/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../../src/tools/stats.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,KAAK,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;IACH,YAAY,EAAE,KAAK,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;CACJ;AA6CD,wBAAsB,cAAc,CAAC,KAAK,GAAE,UAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CA2CjF"}

package/dist/tools/stats.js

@@ -0,0 +1,73 @@
+import { findStatsRuns } from "../db/index.js";
+const EMPTY_STATS = {
+    total_runs: 0,
+    avg_top1_score: 0,
+    p50_score: 0,
+    p90_score: 0,
+    top_sources: [],
+    runs_per_day: [],
+};
+function average(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+function median(sortedValues) {
+    if (sortedValues.length === 0) {
+        return 0;
+    }
+    const midpoint = Math.floor(sortedValues.length / 2);
+    if (sortedValues.length % 2 === 1) {
+        return sortedValues[midpoint] ?? 0;
+    }
+    const lower = sortedValues[midpoint - 1] ?? 0;
+    const upper = sortedValues[midpoint] ?? 0;
+    return (lower + upper) / 2;
+}
+function nearestRankPercentile(sortedValues, percentile) {
+    if (sortedValues.length === 0) {
+        return 0;
+    }
+    const rawIndex = Math.ceil((percentile / 100) * sortedValues.length) - 1;
+    const index = Math.max(0, Math.min(sortedValues.length - 1, rawIndex));
+    return sortedValues[index] ?? 0;
+}
+export async function retrievalStats(input = {}) {
+    const runs = await findStatsRuns(input);
+    if (runs.length === 0) {
+        return { ...EMPTY_STATS, top_sources: [], runs_per_day: [] };
+    }
+    const top1Scores = [];
+    const allScores = [];
+    const sourceCounts = new Map();
+    const runsPerDay = new Map();
+    for (const run of runs) {
+        const day = run.created_at.slice(0, 10);
+        runsPerDay.set(day, (runsPerDay.get(day) ?? 0) + 1);
+        for (const chunk of run.chunks) {
+            allScores.push(chunk.score);
+            sourceCounts.set(chunk.source, (sourceCounts.get(chunk.source) ?? 0) + 1);
+            if (chunk.rank === 1) {
+                top1Scores.push(chunk.score);
+            }
+        }
+    }
+    const sortedScores = [...allScores].sort((left, right) => left - right);
+    const topSources = [...sourceCounts.entries()]
+        .map(([source, count]) => ({ source, count }))
+        .sort((left, right) => right.count - left.count || left.source.localeCompare(right.source))
+        .slice(0, 10);
+    const runsPerDayRows = [...runsPerDay.entries()]
+        .map(([date, count]) => ({ date, count }))
+        .sort((left, right) => left.date.localeCompare(right.date));
+    return {
+        total_runs: runs.length,
+        avg_top1_score: average(top1Scores),
+        p50_score: median(sortedScores),
+        p90_score: nearestRankPercentile(sortedScores, 90),
+        top_sources: topSources,
+        runs_per_day: runsPerDayRows,
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/tools/stats.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,8 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export declare const logger: {
+    debug(message: string): void;
+    info(message: string): void;
+    warn(message: string): void;
+    error(message: string): void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAwB3D,eAAO,MAAM,MAAM;mBACF,MAAM,GAAG,IAAI;kBAGd,MAAM,GAAG,IAAI;kBAGb,MAAM,GAAG,IAAI;mBAGZ,MAAM,GAAG,IAAI;CAG7B,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,32 @@
+const levelRanks = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+function configuredLevel() {
+    const configured = process.env.RETRIEVAL_LENS_LOG;
+    return configured === "debug" || configured === "info" || configured === "warn" || configured === "error"
+        ? configured
+        : "warn";
+}
+function write(level, message, writer = process.stderr.write.bind(process.stderr)) {
+    if (levelRanks[level] >= levelRanks[configuredLevel()]) {
+        writer(`[${level}] ${message}\n`);
+    }
+}
+export const logger = {
+    debug(message) {
+        write("debug", message);
+    },
+    info(message) {
+        write("info", message);
+    },
+    warn(message) {
+        write("warn", message);
+    },
+    error(message) {
+        write("error", message);
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,SAAS,eAAe;IACtB,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;IAClD,OAAO,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,OAAO;QACvG,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,MAAM,CAAC;AACb,CAAC;AAED,SAAS,KAAK,CAAC,KAAe,EAAE,OAAe,EAAE,SAAoB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC5G,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,eAAe,EAAE,CAAC,EAAE,CAAC;QACvD,MAAM,CAAC,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,CAAC,OAAe;QACnB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;IACD,IAAI,CAAC,OAAe;QAClB,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,IAAI,CAAC,OAAe;QAClB,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;IACD,KAAK,CAAC,OAAe;QACnB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "retrieval-lens",
+  "version": "0.1.0",
+  "description": "MCP server that audits RAG retrieval — logs what chunks the model saw, scores, queries, and sources before any answer was generated.",
+  "keywords": [
+    "mcp",
+    "rag",
+    "retrieval",
+    "audit",
+    "observability",
+    "llm",
+    "ai-agents"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "retrieval-lens": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit && tsc",
+    "dev": "tsx watch src/index.ts",
+    "test": "vitest run --coverage",
+    "lint": "eslint src/ tests/ && tsc --noEmit",
+    "inspect": "npx @modelcontextprotocol/inspector dist/index.js",
+    "prepublishOnly": "npm run lint && npm test && npm run build"
+  },
+  "dependencies": {
+    "@libsql/client": "^0.17.3",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.20",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "eslint": "^9.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}