@nifrajs/mcp-db 1.5.0

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+/**
+ * `@nifrajs/mcp-db` — serve a SQLite database as an MCP server, fail-closed.
+ *
+ * Out of the box only SCHEMA tools are exposed (`list_tables`, `describe_table`), and only for
+ * tables on the explicit `tables` allowlist. Query execution is OPT-IN and requires BOTH the
+ * allowlist and an `authorize` hook — a database is PII by default, and an MCP client is an LLM;
+ * this package refuses to be mounted open rather than defaulting open.
+ *
+ * Read-only is enforced in layers, not promised: `PRAGMA query_only = ON` on the connection
+ * (SQLite rejects every write at the engine), a single-statement gate, a SELECT/WITH-only gate,
+ * and `EXPLAIN QUERY PLAN` verification that a query touches ONLY allowlisted tables. Results are
+ * capped by rows and bytes (an LLM does not need 100k rows; a transport does not want them) with
+ * an explicit `truncated` marker.
+ *
+ * Bun/Node SQLite only (anything `bun:sqlite`-shaped, bound structurally — no driver dependency).
+ * There is deliberately NO D1 mode: D1 has no `query_only`, so read-only cannot be guaranteed.
+ *
+ *   import { Database } from "bun:sqlite"
+ *   const mcp = serveDatabaseAsMcp(new Database("app.db"), {
+ *     tables: ["habits", "entries"],
+ *     runQuery: { authorize: (ctx) => ctx.request?.headers.get("x-api-key") === env.MCP_KEY },
+ *   })
+ *   app.mount("/mcp", mcp.fetch)
+ */
+import { type McpServer } from "@nifrajs/mcp";
+/** The structural slice of `bun:sqlite`'s `Database` this package needs. */
+export interface SqliteDatabaseLike {
+    /** Prepare a statement; `all` runs it and returns row objects. */
+    prepare(sql: string): {
+        all(...params: unknown[]): unknown[];
+    };
+    /** Execute a statement for its side effect (used only for `PRAGMA query_only`). */
+    run(sql: string): unknown;
+}
+/** Context forwarded to `authorize` — the inbound HTTP Request carrying the `run_query` call. */
+export interface McpDbAuthorizeContext {
+    readonly toolName: "run_query";
+    readonly request: Request;
+}
+export interface RunQueryOptions {
+    /**
+     * REQUIRED. Authorize each `run_query` call at the transport boundary (inspect the inbound
+     * Request's auth). Return false to reject with a JSON-RPC error. There is no unauthenticated
+     * mode — schema tools are the anonymous surface. Note: `run_query` is therefore HTTP-only;
+     * direct `handle()` dispatch rejects it (no Request to authorize — fails closed).
+     */
+    readonly authorize: (context: McpDbAuthorizeContext) => boolean | Promise<boolean>;
+    /** Max rows returned per query (default 100). */
+    readonly maxRows?: number;
+    /** Max serialized result size in bytes (default 100 KB). */
+    readonly maxResultBytes?: number;
+}
+export interface ServeDatabaseAsMcpOptions {
+    /**
+     * REQUIRED allowlist of tables the MCP surface may see. `list_tables`/`describe_table` are
+     * restricted to it and `run_query` plans are verified against it. Empty array → construction
+     * throws; expose nothing by accident, ever.
+     */
+    readonly tables: readonly string[];
+    /** Enable the `run_query` tool. Omitted → schema tools only. */
+    readonly runQuery?: RunQueryOptions;
+    /** MCP server identity (defaults: name `nifra-db`, version `1.0.0`). */
+    readonly name?: string;
+    readonly version?: string;
+    /**
+     * Set `PRAGMA query_only = ON` on the connection at construction (default true). Disable ONLY
+     * when the same connection must also serve writes elsewhere in the app — with it disabled,
+     * `run_query` still gates on SELECT/WITH + plan verification, but the engine-level guarantee is
+     * yours to provide (e.g. open a second, read-only connection for the MCP mount — preferred).
+     */
+    readonly enforceQueryOnly?: boolean;
+}
+export declare class McpDbConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Serve `db` as a mountable MCP server (`mcp.fetch` at `POST /mcp`). See module docs for the
+ * security model. Throws {@link McpDbConfigError} on any unsafe configuration — always at
+ * construction (boot), never at request time.
+ */
+export declare function serveDatabaseAsMcp(db: SqliteDatabaseLike, options: ServeDatabaseAsMcpOptions): 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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAwD,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAEnG,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAAA;KAAE,CAAA;IAC9D,mFAAmF;IACnF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAC1B;AAED,iGAAiG;AACjG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAClF,iDAAiD;IACjD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAA;IACnC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CACpC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAwBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,kBAAkB,EACtB,OAAO,EAAE,yBAAyB,GACjC,SAAS,CAgMX"}

package/dist/index.js

@@ -0,0 +1,229 @@
+/**
+ * `@nifrajs/mcp-db` — serve a SQLite database as an MCP server, fail-closed.
+ *
+ * Out of the box only SCHEMA tools are exposed (`list_tables`, `describe_table`), and only for
+ * tables on the explicit `tables` allowlist. Query execution is OPT-IN and requires BOTH the
+ * allowlist and an `authorize` hook — a database is PII by default, and an MCP client is an LLM;
+ * this package refuses to be mounted open rather than defaulting open.
+ *
+ * Read-only is enforced in layers, not promised: `PRAGMA query_only = ON` on the connection
+ * (SQLite rejects every write at the engine), a single-statement gate, a SELECT/WITH-only gate,
+ * and `EXPLAIN QUERY PLAN` verification that a query touches ONLY allowlisted tables. Results are
+ * capped by rows and bytes (an LLM does not need 100k rows; a transport does not want them) with
+ * an explicit `truncated` marker.
+ *
+ * Bun/Node SQLite only (anything `bun:sqlite`-shaped, bound structurally — no driver dependency).
+ * There is deliberately NO D1 mode: D1 has no `query_only`, so read-only cannot be guaranteed.
+ *
+ *   import { Database } from "bun:sqlite"
+ *   const mcp = serveDatabaseAsMcp(new Database("app.db"), {
+ *     tables: ["habits", "entries"],
+ *     runQuery: { authorize: (ctx) => ctx.request?.headers.get("x-api-key") === env.MCP_KEY },
+ *   })
+ *   app.mount("/mcp", mcp.fetch)
+ */
+import { createMcpServer, defineMcpTool } from "@nifrajs/mcp";
+export class McpDbConfigError extends Error {
+    constructor(message) {
+        super(`@nifrajs/mcp-db: ${message}`);
+        this.name = "McpDbConfigError";
+    }
+}
+/** A safe SQL identifier — quoting is not enough for PRAGMA args, so reject instead. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const stripSqlNoise = (sql) => sql
+    // Strings first so comment markers inside literals don't count.
+    .replace(/'(?:[^']|'')*'/g, "''")
+    .replace(/"(?:[^"]|"")*"/g, '""')
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ");
+/** Reject multi-statement input: any `;` outside literals/comments except one trailing. */
+const isSingleStatement = (sql) => {
+    const noise = stripSqlNoise(sql).trim().replace(/;$/, "");
+    return !noise.includes(";");
+};
+const isReadStatement = (sql) => {
+    const head = stripSqlNoise(sql).trim().toLowerCase();
+    return head.startsWith("select") || head.startsWith("with");
+};
+/**
+ * Serve `db` as a mountable MCP server (`mcp.fetch` at `POST /mcp`). See module docs for the
+ * security model. Throws {@link McpDbConfigError} on any unsafe configuration — always at
+ * construction (boot), never at request time.
+ */
+export function serveDatabaseAsMcp(db, options) {
+    if (options.tables.length === 0) {
+        throw new McpDbConfigError("an explicit non-empty `tables` allowlist is required — this package never defaults to exposing a whole database");
+    }
+    for (const table of options.tables) {
+        if (!SAFE_IDENTIFIER.test(table)) {
+            throw new McpDbConfigError(`allowlisted table ${JSON.stringify(table)} is not a plain SQL identifier`);
+        }
+    }
+    const allowlist = new Set(options.tables.map((table) => table.toLowerCase()));
+    if (options.enforceQueryOnly !== false) {
+        try {
+            db.run("PRAGMA query_only = ON");
+        }
+        catch (error) {
+            throw new McpDbConfigError(`could not set PRAGMA query_only on the connection (${String(error)}) — pass a bun:sqlite-shaped database or set enforceQueryOnly: false with a read-only connection`);
+        }
+    }
+    const maxRows = options.runQuery?.maxRows ?? 100;
+    const maxResultBytes = options.runQuery?.maxResultBytes ?? 100 * 1024;
+    const listTables = defineMcpTool({
+        name: "list_tables",
+        description: "List the tables this server exposes, with row counts.",
+        handler: () => {
+            const rows = options.tables.map((table) => {
+                const [count] = db.prepare(`SELECT count(*) AS n FROM "${table}"`).all();
+                return { table, rows: count?.n ?? 0 };
+            });
+            return { text: JSON.stringify(rows), structuredContent: { tables: rows } };
+        },
+    });
+    const describeTable = defineMcpTool({
+        name: "describe_table",
+        description: "Describe an exposed table: columns, types, nullability, primary key.",
+        inputSchema: {
+            type: "object",
+            properties: { table: { type: "string", description: "Table name (must be exposed)" } },
+            required: ["table"],
+        },
+        handler: (args) => {
+            const table = String(args.table ?? "");
+            if (!allowlist.has(table.toLowerCase())) {
+                return { isError: true, text: `table ${JSON.stringify(table)} is not exposed` };
+            }
+            // Identifier is allowlist-verified (and the allowlist is identifier-checked at boot),
+            // so interpolation here cannot inject.
+            const columns = db.prepare(`PRAGMA table_info("${table}")`).all();
+            return { text: JSON.stringify(columns), structuredContent: { table, columns } };
+        },
+    });
+    const tools = [listTables, describeTable];
+    if (options.runQuery !== undefined) {
+        const runQuery = defineMcpTool({
+            name: "run_query",
+            description: "Run one read-only SELECT against the exposed tables. Results are capped by rows and bytes.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    sql: { type: "string", description: "A single SELECT (or WITH…SELECT) statement" },
+                },
+                required: ["sql"],
+            },
+            intent: "table",
+            handler: (args) => {
+                const sql = String(args.sql ?? "").trim();
+                if (sql === "")
+                    return { isError: true, text: "empty query" };
+                if (!isSingleStatement(sql)) {
+                    return { isError: true, text: "only a single statement is allowed" };
+                }
+                if (!isReadStatement(sql)) {
+                    return { isError: true, text: "only SELECT (or WITH…SELECT) statements are allowed" };
+                }
+                // Verify via the query plan that only allowlisted tables are touched. SQLite names every
+                // scanned/searched relation in EXPLAIN QUERY PLAN detail rows.
+                let planRows;
+                try {
+                    planRows = db.prepare(`EXPLAIN QUERY PLAN ${sql}`).all();
+                }
+                catch (error) {
+                    return { isError: true, text: `query failed to plan: ${String(error)}` };
+                }
+                for (const row of planRows) {
+                    const detail = typeof row.detail === "string" ? row.detail : "";
+                    const match = /(?:SCAN|SEARCH)\s+(?:TABLE\s+)?([A-Za-z_][A-Za-z0-9_]*)/i.exec(detail);
+                    if (match !== null) {
+                        const relation = match[1]?.toLowerCase() ?? "";
+                        if (!allowlist.has(relation)) {
+                            return {
+                                isError: true,
+                                text: `query touches ${JSON.stringify(match[1])}, which is not exposed`,
+                            };
+                        }
+                    }
+                }
+                let rows;
+                try {
+                    rows = db.prepare(sql).all();
+                }
+                catch (error) {
+                    return { isError: true, text: `query failed: ${String(error)}` };
+                }
+                const total = rows.length;
+                let shown = Math.min(total, maxRows);
+                let payload = rows.slice(0, shown);
+                let serialized = JSON.stringify(payload);
+                while (serialized.length > maxResultBytes && shown > 0) {
+                    shown = Math.max(0, Math.floor(shown / 2));
+                    payload = rows.slice(0, shown);
+                    serialized = JSON.stringify(payload);
+                }
+                const truncated = shown < total;
+                const result = {
+                    rows: payload,
+                    ...(truncated ? { truncated: { shown, total } } : {}),
+                };
+                return { text: JSON.stringify(result), structuredContent: result };
+            },
+        });
+        tools.push(runQuery);
+    }
+    const server = createMcpServer({
+        name: options.name ?? "nifra-db",
+        version: options.version ?? "1.0.0",
+        tools,
+    });
+    if (options.runQuery === undefined)
+        return server;
+    // `run_query` is authorized at the TRANSPORT boundary, where the inbound Request's credentials
+    // are visible — the handler itself performs no auth, so every path to it must pass this gate:
+    // the wrapped fetch authorizes, and direct handle() dispatch fails closed (no Request → no auth).
+    const { authorize } = options.runQuery;
+    const rpcId = (id) => typeof id === "string" || typeof id === "number" ? id : null;
+    const unauthorizedResult = (id) => ({
+        jsonrpc: "2.0",
+        id: rpcId(id),
+        result: {
+            content: [{ type: "text", text: "unauthorized" }],
+            isError: true,
+        },
+    });
+    const isRunQueryCall = (message) => {
+        if (typeof message !== "object" || message === null)
+            return false;
+        const { method, params } = message;
+        return method === "tools/call" && params?.name === "run_query";
+    };
+    return {
+        ...server,
+        async fetch(request) {
+            if (request.method === "POST") {
+                let body;
+                try {
+                    body = await request.clone().json();
+                }
+                catch {
+                    return server.fetch(request); // malformed JSON → the protocol layer's error handling
+                }
+                const messages = Array.isArray(body) ? body : [body];
+                const queryCall = messages.find(isRunQueryCall);
+                if (queryCall !== undefined) {
+                    const ok = await authorize({ toolName: "run_query", request });
+                    if (!ok)
+                        return Response.json(unauthorizedResult(queryCall.id));
+                }
+            }
+            return server.fetch(request);
+        },
+        async handle(message) {
+            if (isRunQueryCall(message))
+                return unauthorizedResult(message.id);
+            return server.handle(message);
+        },
+    };
+}
+//# 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/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nifrajs/mcp-db",
+  "version": "1.5.0",
+  "description": "Serve a SQLite database as a fail-closed MCP server — allowlisted schema tools by default, opt-in read-only queries with plan verification.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "mcp",
+    "sqlite",
+    "ai",
+    "agent"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nifrajs/mcp": "1.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/mcp-db"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/index.ts

@@ -0,0 +1,306 @@
+/**
+ * `@nifrajs/mcp-db` — serve a SQLite database as an MCP server, fail-closed.
+ *
+ * Out of the box only SCHEMA tools are exposed (`list_tables`, `describe_table`), and only for
+ * tables on the explicit `tables` allowlist. Query execution is OPT-IN and requires BOTH the
+ * allowlist and an `authorize` hook — a database is PII by default, and an MCP client is an LLM;
+ * this package refuses to be mounted open rather than defaulting open.
+ *
+ * Read-only is enforced in layers, not promised: `PRAGMA query_only = ON` on the connection
+ * (SQLite rejects every write at the engine), a single-statement gate, a SELECT/WITH-only gate,
+ * and `EXPLAIN QUERY PLAN` verification that a query touches ONLY allowlisted tables. Results are
+ * capped by rows and bytes (an LLM does not need 100k rows; a transport does not want them) with
+ * an explicit `truncated` marker.
+ *
+ * Bun/Node SQLite only (anything `bun:sqlite`-shaped, bound structurally — no driver dependency).
+ * There is deliberately NO D1 mode: D1 has no `query_only`, so read-only cannot be guaranteed.
+ *
+ *   import { Database } from "bun:sqlite"
+ *   const mcp = serveDatabaseAsMcp(new Database("app.db"), {
+ *     tables: ["habits", "entries"],
+ *     runQuery: { authorize: (ctx) => ctx.request?.headers.get("x-api-key") === env.MCP_KEY },
+ *   })
+ *   app.mount("/mcp", mcp.fetch)
+ */
+
+import { createMcpServer, defineMcpTool, type JsonRpcResponse, type McpServer } from "@nifrajs/mcp"
+
+/** The structural slice of `bun:sqlite`'s `Database` this package needs. */
+export interface SqliteDatabaseLike {
+  /** Prepare a statement; `all` runs it and returns row objects. */
+  prepare(sql: string): { all(...params: unknown[]): unknown[] }
+  /** Execute a statement for its side effect (used only for `PRAGMA query_only`). */
+  run(sql: string): unknown
+}
+
+/** Context forwarded to `authorize` — the inbound HTTP Request carrying the `run_query` call. */
+export interface McpDbAuthorizeContext {
+  readonly toolName: "run_query"
+  readonly request: Request
+}
+
+export interface RunQueryOptions {
+  /**
+   * REQUIRED. Authorize each `run_query` call at the transport boundary (inspect the inbound
+   * Request's auth). Return false to reject with a JSON-RPC error. There is no unauthenticated
+   * mode — schema tools are the anonymous surface. Note: `run_query` is therefore HTTP-only;
+   * direct `handle()` dispatch rejects it (no Request to authorize — fails closed).
+   */
+  readonly authorize: (context: McpDbAuthorizeContext) => boolean | Promise<boolean>
+  /** Max rows returned per query (default 100). */
+  readonly maxRows?: number
+  /** Max serialized result size in bytes (default 100 KB). */
+  readonly maxResultBytes?: number
+}
+
+export interface ServeDatabaseAsMcpOptions {
+  /**
+   * REQUIRED allowlist of tables the MCP surface may see. `list_tables`/`describe_table` are
+   * restricted to it and `run_query` plans are verified against it. Empty array → construction
+   * throws; expose nothing by accident, ever.
+   */
+  readonly tables: readonly string[]
+  /** Enable the `run_query` tool. Omitted → schema tools only. */
+  readonly runQuery?: RunQueryOptions
+  /** MCP server identity (defaults: name `nifra-db`, version `1.0.0`). */
+  readonly name?: string
+  readonly version?: string
+  /**
+   * Set `PRAGMA query_only = ON` on the connection at construction (default true). Disable ONLY
+   * when the same connection must also serve writes elsewhere in the app — with it disabled,
+   * `run_query` still gates on SELECT/WITH + plan verification, but the engine-level guarantee is
+   * yours to provide (e.g. open a second, read-only connection for the MCP mount — preferred).
+   */
+  readonly enforceQueryOnly?: boolean
+}
+
+export class McpDbConfigError extends Error {
+  constructor(message: string) {
+    super(`@nifrajs/mcp-db: ${message}`)
+    this.name = "McpDbConfigError"
+  }
+}
+
+/** A safe SQL identifier — quoting is not enough for PRAGMA args, so reject instead. */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+const stripSqlNoise = (sql: string): string =>
+  sql
+    // Strings first so comment markers inside literals don't count.
+    .replace(/'(?:[^']|'')*'/g, "''")
+    .replace(/"(?:[^"]|"")*"/g, '""')
+    .replace(/--[^\n]*/g, " ")
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+
+/** Reject multi-statement input: any `;` outside literals/comments except one trailing. */
+const isSingleStatement = (sql: string): boolean => {
+  const noise = stripSqlNoise(sql).trim().replace(/;$/, "")
+  return !noise.includes(";")
+}
+
+const isReadStatement = (sql: string): boolean => {
+  const head = stripSqlNoise(sql).trim().toLowerCase()
+  return head.startsWith("select") || head.startsWith("with")
+}
+
+/**
+ * Serve `db` as a mountable MCP server (`mcp.fetch` at `POST /mcp`). See module docs for the
+ * security model. Throws {@link McpDbConfigError} on any unsafe configuration — always at
+ * construction (boot), never at request time.
+ */
+export function serveDatabaseAsMcp(
+  db: SqliteDatabaseLike,
+  options: ServeDatabaseAsMcpOptions,
+): McpServer {
+  if (options.tables.length === 0) {
+    throw new McpDbConfigError(
+      "an explicit non-empty `tables` allowlist is required — this package never defaults to exposing a whole database",
+    )
+  }
+  for (const table of options.tables) {
+    if (!SAFE_IDENTIFIER.test(table)) {
+      throw new McpDbConfigError(
+        `allowlisted table ${JSON.stringify(table)} is not a plain SQL identifier`,
+      )
+    }
+  }
+  const allowlist = new Set(options.tables.map((table) => table.toLowerCase()))
+
+  if (options.enforceQueryOnly !== false) {
+    try {
+      db.run("PRAGMA query_only = ON")
+    } catch (error) {
+      throw new McpDbConfigError(
+        `could not set PRAGMA query_only on the connection (${String(error)}) — pass a bun:sqlite-shaped database or set enforceQueryOnly: false with a read-only connection`,
+      )
+    }
+  }
+
+  const maxRows = options.runQuery?.maxRows ?? 100
+  const maxResultBytes = options.runQuery?.maxResultBytes ?? 100 * 1024
+
+  const listTables = defineMcpTool({
+    name: "list_tables",
+    description: "List the tables this server exposes, with row counts.",
+    handler: () => {
+      const rows = options.tables.map((table) => {
+        const [count] = db.prepare(`SELECT count(*) AS n FROM "${table}"`).all() as Array<{
+          n: number
+        }>
+        return { table, rows: count?.n ?? 0 }
+      })
+      return { text: JSON.stringify(rows), structuredContent: { tables: rows } }
+    },
+  })
+
+  const describeTable = defineMcpTool({
+    name: "describe_table",
+    description: "Describe an exposed table: columns, types, nullability, primary key.",
+    inputSchema: {
+      type: "object",
+      properties: { table: { type: "string", description: "Table name (must be exposed)" } },
+      required: ["table"],
+    },
+    handler: (args) => {
+      const table = String(args.table ?? "")
+      if (!allowlist.has(table.toLowerCase())) {
+        return { isError: true, text: `table ${JSON.stringify(table)} is not exposed` }
+      }
+      // Identifier is allowlist-verified (and the allowlist is identifier-checked at boot),
+      // so interpolation here cannot inject.
+      const columns = db.prepare(`PRAGMA table_info("${table}")`).all()
+      return { text: JSON.stringify(columns), structuredContent: { table, columns } }
+    },
+  })
+
+  const tools = [listTables, describeTable]
+
+  if (options.runQuery !== undefined) {
+    const runQuery = defineMcpTool({
+      name: "run_query",
+      description:
+        "Run one read-only SELECT against the exposed tables. Results are capped by rows and bytes.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          sql: { type: "string", description: "A single SELECT (or WITH…SELECT) statement" },
+        },
+        required: ["sql"],
+      },
+      intent: "table",
+      handler: (args) => {
+        const sql = String(args.sql ?? "").trim()
+        if (sql === "") return { isError: true, text: "empty query" }
+        if (!isSingleStatement(sql)) {
+          return { isError: true, text: "only a single statement is allowed" }
+        }
+        if (!isReadStatement(sql)) {
+          return { isError: true, text: "only SELECT (or WITH…SELECT) statements are allowed" }
+        }
+
+        // Verify via the query plan that only allowlisted tables are touched. SQLite names every
+        // scanned/searched relation in EXPLAIN QUERY PLAN detail rows.
+        let planRows: Array<{ detail?: unknown }>
+        try {
+          planRows = db.prepare(`EXPLAIN QUERY PLAN ${sql}`).all() as Array<{ detail?: unknown }>
+        } catch (error) {
+          return { isError: true, text: `query failed to plan: ${String(error)}` }
+        }
+        for (const row of planRows) {
+          const detail = typeof row.detail === "string" ? row.detail : ""
+          const match = /(?:SCAN|SEARCH)\s+(?:TABLE\s+)?([A-Za-z_][A-Za-z0-9_]*)/i.exec(detail)
+          if (match !== null) {
+            const relation = match[1]?.toLowerCase() ?? ""
+            if (!allowlist.has(relation)) {
+              return {
+                isError: true,
+                text: `query touches ${JSON.stringify(match[1])}, which is not exposed`,
+              }
+            }
+          }
+        }
+
+        let rows: unknown[]
+        try {
+          rows = db.prepare(sql).all()
+        } catch (error) {
+          return { isError: true, text: `query failed: ${String(error)}` }
+        }
+
+        const total = rows.length
+        let shown = Math.min(total, maxRows)
+        let payload = rows.slice(0, shown)
+        let serialized = JSON.stringify(payload)
+        while (serialized.length > maxResultBytes && shown > 0) {
+          shown = Math.max(0, Math.floor(shown / 2))
+          payload = rows.slice(0, shown)
+          serialized = JSON.stringify(payload)
+        }
+        const truncated = shown < total
+        const result: Record<string, unknown> = {
+          rows: payload,
+          ...(truncated ? { truncated: { shown, total } } : {}),
+        }
+        return { text: JSON.stringify(result), structuredContent: result }
+      },
+    })
+    tools.push(runQuery)
+  }
+
+  const server = createMcpServer({
+    name: options.name ?? "nifra-db",
+    version: options.version ?? "1.0.0",
+    tools,
+  })
+
+  if (options.runQuery === undefined) return server
+
+  // `run_query` is authorized at the TRANSPORT boundary, where the inbound Request's credentials
+  // are visible — the handler itself performs no auth, so every path to it must pass this gate:
+  // the wrapped fetch authorizes, and direct handle() dispatch fails closed (no Request → no auth).
+  const { authorize } = options.runQuery
+
+  const rpcId = (id: unknown): string | number | null =>
+    typeof id === "string" || typeof id === "number" ? id : null
+
+  const unauthorizedResult = (id: unknown): JsonRpcResponse =>
+    ({
+      jsonrpc: "2.0",
+      id: rpcId(id),
+      result: {
+        content: [{ type: "text", text: "unauthorized" }],
+        isError: true,
+      },
+    }) as JsonRpcResponse
+
+  const isRunQueryCall = (message: unknown): message is { id?: unknown } => {
+    if (typeof message !== "object" || message === null) return false
+    const { method, params } = message as { method?: unknown; params?: { name?: unknown } }
+    return method === "tools/call" && params?.name === "run_query"
+  }
+
+  return {
+    ...server,
+    async fetch(request: Request): Promise<Response> {
+      if (request.method === "POST") {
+        let body: unknown
+        try {
+          body = await request.clone().json()
+        } catch {
+          return server.fetch(request) // malformed JSON → the protocol layer's error handling
+        }
+        const messages = Array.isArray(body) ? body : [body]
+        const queryCall = messages.find(isRunQueryCall)
+        if (queryCall !== undefined) {
+          const ok = await authorize({ toolName: "run_query", request })
+          if (!ok) return Response.json(unauthorizedResult(queryCall.id))
+        }
+      }
+      return server.fetch(request)
+    },
+    async handle(message) {
+      if (isRunQueryCall(message)) return unauthorizedResult(message.id)
+      return server.handle(message)
+    },
+  }
+}