db-mcp 1.0.2 → 1.1.0

package/dist/worker-script.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/worker-script.js

@@ -0,0 +1,126 @@
+import { workerData, parentPort } from 'worker_threads';
+import vm from 'vm';
+
+// src/codemode/worker-script.ts
+function buildSqliteProxy(bindings, rpcPort) {
+  const pending = /* @__PURE__ */ new Map();
+  let nextId = 0;
+  rpcPort.on("message", (msg) => {
+    const p = pending.get(msg.id);
+    if (p) {
+      pending.delete(msg.id);
+      if (msg.error) {
+        p.reject(new Error(msg.error));
+      } else {
+        p.resolve(msg.result);
+      }
+    }
+  });
+  const sqlite = {};
+  const groupNames = [];
+  for (const [key, methods] of Object.entries(bindings)) {
+    if (key === "_topLevel") continue;
+    groupNames.push(key);
+    const groupApi = {};
+    for (const method of methods) {
+      if (method === "help") continue;
+      groupApi[method] = (...args) => new Promise((resolve, reject) => {
+        const id = nextId++;
+        pending.set(id, { resolve, reject });
+        rpcPort.postMessage({ id, group: key, method, args });
+      });
+    }
+    groupApi["help"] = () => ({
+      group: key,
+      methods: methods.filter((m) => m !== "help")
+    });
+    sqlite[key] = groupApi;
+  }
+  const topLevel = bindings["_topLevel"];
+  if (topLevel) {
+    for (const method of topLevel) {
+      if (method === "help") {
+        sqlite["help"] = () => ({
+          groups: groupNames
+        });
+      } else {
+        sqlite[method] = (...args) => new Promise((resolve, reject) => {
+          const id = nextId++;
+          pending.set(id, { resolve, reject });
+          rpcPort.postMessage({
+            id,
+            group: "_topLevel",
+            method,
+            args
+          });
+        });
+      }
+    }
+  }
+  if (sqlite["help"] === void 0) {
+    sqlite["help"] = () => ({
+      groups: groupNames
+    });
+  }
+  return sqlite;
+}
+async function executeInWorker() {
+  const data = workerData;
+  const { code, apiBindings, timeout, rpcPort } = data;
+  try {
+    rpcPort.ref();
+    const sqlite = buildSqliteProxy(apiBindings, rpcPort);
+    const sandbox = {
+      sqlite,
+      console: {
+        log: () => {
+        },
+        error: () => {
+        },
+        warn: () => {
+        },
+        info: () => {
+        },
+        debug: () => {
+        }
+      },
+      setTimeout: void 0,
+      setInterval: void 0,
+      setImmediate: void 0,
+      process: void 0,
+      require: void 0,
+      __dirname: void 0,
+      __filename: void 0,
+      globalThis: void 0,
+      global: void 0
+    };
+    const context = vm.createContext(sandbox, {
+      name: "worker-sandbox"
+    });
+    const wrappedCode = `(async () => { ${code} })()`;
+    const script = new vm.Script(wrappedCode, {
+      filename: "user-code.js"
+    });
+    const result = await script.runInContext(context, {
+      timeout,
+      displayErrors: true
+    });
+    rpcPort.unref();
+    rpcPort.close();
+    const response = {
+      success: true,
+      result
+    };
+    parentPort?.postMessage(response);
+  } catch (error) {
+    rpcPort.unref();
+    rpcPort.close();
+    const response = {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : void 0
+    };
+    parentPort?.postMessage(response);
+  }
+}
+void executeInWorker();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "db-mcp",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "SQLite MCP server with OAuth 2.1 authentication, HTTP/SSE transport, and smart tool filtering",
   "mcpName": "io.github.neverinfamous/db-mcp",
   "type": "module",
@@ -10,19 +10,24 @@
     "db-mcp": "./dist/cli.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsup",
     "dev": "tsx watch src/index.ts",
     "start": "node dist/index.js",
     "start:stdio": "node dist/cli.js --transport=stdio",
     "start:http": "node dist/cli.js --transport=http",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "lint:json": "eslint . --format json --output-file eslint-results.json",
     "typecheck": "tsc --noEmit",
     "check": "npm run lint && npm run typecheck",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "bench": "vitest bench --run",
+    "bench:verbose": "vitest bench --run --reporter=verbose",
     "clean": "rimraf dist",
+    "generate:instructions": "node scripts/generate-server-instructions.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -48,36 +53,41 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "cors": "^2.8.5",
-    "dotenv": "^17.2.3",
     "express": "^5.2.1",
-    "jose": "^6.1.3",
-    "pg": "^8.18.0",
-    "sql.js": "^1.13.0",
+    "jose": "^6.2.1",
+    "sql.js": "^1.14.1",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.58.2",
     "@types/better-sqlite3": "^7.6.13",
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.2.0",
-    "@types/pg": "^8.16.0",
+    "@types/node": "^25.4.0",
     "@types/sql.js": "^1.4.9",
     "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.2",
-    "globals": "^17.3.0",
-    "rimraf": "^6.1.2",
+    "eslint": "^10.0.2",
+    "globals": "^17.4.0",
+    "rimraf": "^6.1.3",
+    "tsup": "^8.5.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.54.0",
+    "typescript-eslint": "^8.57.1",
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
   },
   "optionalDependencies": {
-    "better-sqlite3": "^12.6.2"
+    "better-sqlite3": "^12.8.0"
+  },
+  "overrides": {
+    "diff": "8.0.3",
+    "@isaacs/brace-expansion": "5.0.1",
+    "tar": "7.5.11",
+    "minimatch": "10.2.4"
   }
-}
+}

package/playwright.config.ts

@@ -0,0 +1,101 @@
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  // MCP SDK McpServer only supports one active transport at a time.
+  // Parallel workers create competing SSE connections that steal each other's transport.
+  workers: 1,
+  reporter: "list",
+  use: {
+    trace: "on-first-retry",
+    // 60s timeout — allows slow operations (vector stats, code mode ETL)
+    // to complete without flaky timeouts from rate-limit backpressure
+    actionTimeout: 0,
+  },
+  timeout: 60_000,
+  projects: [
+    {
+      name: "wasm",
+      use: {
+        ...devices["Desktop Chrome"],
+        baseURL: "http://localhost:3000",
+      },
+      testIgnore: [
+        /native\./,
+        /auth\./,
+        /payloads-window\./,
+        /payloads-fts\./,
+        /payloads-transactions\./,
+        /payloads-spatialite\./,
+        /payloads-csv\./,
+        /transactions-nested\./,
+        /integration-workflows\./,
+        /codemode-introspection\./,
+      ],
+    },
+    {
+      name: "native",
+      use: {
+        ...devices["Desktop Chrome"],
+        baseURL: "http://localhost:3001",
+      },
+      testIgnore: [/wasm\./, /auth\./],
+      dependencies: ["wasm"],
+    },
+    {
+      name: "auth",
+      use: {
+        ...devices["Desktop Chrome"],
+        baseURL: "http://localhost:3003",
+      },
+      testMatch: /auth\./,
+      dependencies: ["native"],
+    },
+  ],
+  webServer: [
+    {
+      command:
+        "node dist/cli.js --transport http --port 3000 --sqlite ./test-server/test.db --tool-filter +all",
+      url: "http://localhost:3000/health",
+      reuseExistingServer: !process.env.CI,
+      timeout: 30000,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        MCP_RATE_LIMIT_MAX: "10000",
+        MCP_CODEMODE_RATE_LIMIT: "10000",
+      },
+    },
+    {
+      command:
+        "node dist/cli.js --transport http --port 3001 --sqlite-native ./test-server/test.db --csv --spatialite --tool-filter +all",
+      url: "http://localhost:3001/health",
+      reuseExistingServer: !process.env.CI,
+      timeout: 30000,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: {
+        ...process.env,
+        MCP_RATE_LIMIT_MAX: "10000",
+        MCP_CODEMODE_RATE_LIMIT: "10000",
+        SPATIALITE_PATH:
+          "./extensions/mod_spatialite-5.1.0-win-amd64/mod_spatialite.dll",
+        CSV_EXTENSION_PATH: "./extensions/xsv0.dll",
+      },
+    },
+    {
+      command:
+        "node dist/cli.js --transport http --port 3003 --auth-token test-secret --sqlite ./test-server/test.db --tool-filter +all",
+      url: "http://localhost:3003/health",
+      reuseExistingServer: !process.env.CI,
+      timeout: 30000,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: { ...process.env, MCP_RATE_LIMIT_MAX: "10000" },
+    },
+  ],
+});

package/scripts/generate-server-instructions.ts

@@ -0,0 +1,111 @@
+/**
+ * Generates src/constants/server-instructions.ts from per-group markdown files.
+ *
+ * Reads server-instructions/*.md, escapes for template literals, and wraps them
+ * in a TypeScript module with a slim INSTRUCTIONS constant and a HELP_CONTENT map.
+ *
+ * Usage: node scripts/generate-server-instructions.ts
+ */
+
+import { readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = resolve(__dirname, "..");
+const constantsDir = resolve(projectRoot, "src/constants");
+const helpDir = resolve(constantsDir, "server-instructions");
+
+/**
+ * Escape content for use inside a JS/TS template literal.
+ * Handles: backslashes, backticks, and template expressions (${).
+ */
+function escapeForTemplateLiteral(content: string): string {
+  return content
+    .replace(/\\/g, "\\\\")
+    .replace(/`/g, "\\`")
+    .replace(/\$\{/g, "\\${");
+}
+
+// Read overview (slim instructions field content)
+const overviewMd = readFileSync(
+  resolve(helpDir, "overview.md"),
+  "utf-8",
+).trim();
+const overviewEscaped = escapeForTemplateLiteral(overviewMd);
+
+// Read all help files (everything except overview.md)
+const helpFiles = readdirSync(helpDir)
+  .filter((f) => f.endsWith(".md") && f !== "overview.md")
+  .sort();
+
+const helpEntries: { key: string; content: string }[] = [];
+for (const file of helpFiles) {
+  const key = basename(file, ".md"); // "gotchas", "json", "stats", etc.
+  const content = readFileSync(resolve(helpDir, file), "utf-8").trim();
+  helpEntries.push({ key, content });
+}
+
+// Use backtick char for building string to avoid nesting issues
+const BT = "`";
+
+// Build the TypeScript file using string concatenation
+const lines: string[] = [];
+
+lines.push("/**");
+lines.push(" * Server instructions for db-mcp (SQLite MCP Server).");
+lines.push(" *");
+lines.push(
+  " * \u26a0\ufe0f  AUTO-GENERATED \u2014 DO NOT EDIT THIS FILE DIRECTLY",
+);
+lines.push(" *     Edit src/constants/server-instructions/*.md instead,");
+lines.push(" *     then run: npm run generate:instructions");
+lines.push(" *");
+lines.push(
+  " * Slim instructions are sent to MCP clients during initialization.",
+);
+lines.push(
+  " * Detailed help is available on-demand via sqlite://help resources.",
+);
+lines.push(" */");
+lines.push("");
+lines.push("/**");
+lines.push(" * Slim instructions for the MCP instructions field (~600 chars).");
+lines.push(
+  " * Points agents to sqlite://help resources for detailed reference.",
+);
+lines.push(" */");
+lines.push("export const INSTRUCTIONS = " + BT + overviewEscaped + BT + ";");
+lines.push("");
+lines.push("/**");
+lines.push(" * Help content keyed by group name.");
+lines.push(" * 'gotchas' is the always-available help (sqlite://help).");
+lines.push(" * Other keys are tool groups (sqlite://help/{group}).");
+lines.push(" */");
+lines.push(
+  "export const HELP_CONTENT: ReadonlyMap<string, string> = new Map([",
+);
+for (const { key, content } of helpEntries) {
+  const escaped = escapeForTemplateLiteral(content);
+  lines.push("  [" + JSON.stringify(key) + ", " + BT + escaped + BT + "],");
+}
+lines.push("]);");
+lines.push("");
+
+const tsContent = lines.join("\n");
+const tsPath = resolve(constantsDir, "server-instructions.ts");
+writeFileSync(tsPath, tsContent, "utf-8");
+
+process.stderr.write(
+  [
+    "",
+    "\u2705 Generated server-instructions.ts (" +
+      tsContent.length.toLocaleString() +
+      " bytes) from " +
+      (helpEntries.length + 1) +
+      " markdown files",
+    "   Overview: " + overviewMd.length.toLocaleString() + " chars",
+    "   Help entries: " + helpEntries.map((e) => e.key).join(", "),
+    "",
+  ].join("\n"),
+);

package/server.json

@@ -2,21 +2,20 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.neverinfamous/db-mcp",
   "title": "db-mcp (SQLite MCP Server)",
-  "description": "SQLite MCP server with OAuth 2.1, HTTP/SSE, 122 tools, and smart tool filtering",
-  "version": "1.0.2",
+  "description": "SQLite MCP server with OAuth 2.1, HTTP/SSE, 139 tools, and smart tool filtering",
+  "version": "1.1.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "db-mcp",
-      "version": "1.0.2",
+      "version": "1.1.0",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "docker.io/writenotenow/db-mcp:v1.0.2",
-      "version": "1.0.2",
+      "identifier": "docker.io/writenotenow/db-mcp:v1.1.0",
       "transport": {
         "type": "stdio"
       }
@@ -50,4 +49,4 @@
     "source": "github"
   },
   "license": "MIT"
-}
+}

package/test-server/README.md

@@ -0,0 +1,118 @@
+# db-mcp Test Database — Agent Testing Instructions
+
+> **This README is optimized for AI agent consumption.** It serves as the primary orchestration document for running manual MCP functionality tests against the local SQLite database.
+
+## Files
+
+| File                         | Size  | Purpose                                                                                                                                                             | When to Read                                                               |
+| ---------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `test-tools.md`              | ~12KB | **Entry-point protocol** — schema reference, error pattern docs, reporting format, cleanup rules. Paste a group checklist from `test-group-tools.md` at the bottom. | Always read first (Step 1 says read help resources, Step 2 is the testing) |
+| `test-group-tools.md`        | ~54KB | Per-group **deterministic checklists** (core, json, text, stats, vector, admin, geo, introspection, migration). Copy the relevant section into `test-tools.md`.     | When running a specific tool group                                         |
+| `test-tools-advanced-1.md`   | ~28KB | **Second-pass stress tests (Part 1)** — boundary values, state pollution, error message quality, WASM parity.                                                       | After basic checklist passes                                               |
+| `test-tools-advanced-2.md`   | ~32KB | **Second-pass stress tests (Part 2)** — cross-group integration. Self-contained.                                                                                    | After basic checklist passes                                               |
+| `test-resources.md`          | ~6KB  | Resource testing plan (8 data + 7 help resources via `read_resource`)                                                                                               | When testing resources                                                     |
+| `test-preflight.md`          | ~2KB  | **Pre-flight check** — validates slim instructions, help resources, data resources, and tool-filter alignment in 5 steps                                            | Before any test pass                                                       |
+| `test-agent-experience.md`   | ~9KB  | **Agent experience test** — 29 open-ended scenarios across 7 passes validating help resource sufficiency                                                            | After help resource changes                                                |
+| `test-prompts.md`            | ~10KB | Prompt testing plan (10 prompts, tested manually since agents typically don't invoke prompts)                                                                       | When testing prompts                                                       |
+| `tool-groups-list.md`        | —     | **Canonical tool inventory** — all 9 groups + codemode, 139 Native / 115 WASM tools. Source of truth for tool counts.                                               | Reference / auditing                                                       |
+| `tool-reference.md`          | ~18KB | **Complete Tool Reference** — Detailed list of all 139 Native / 115 WASM tools organized by group.                                                                  | Reference                                                                  |
+| [`code-map.md`](code-map.md) | ~12KB | **Source Code Map** — Directory tree, handler→tool mapping, type/schema locations, error hierarchy, constants, architecture patterns.                               | When debugging source code or making changes                               |
+| `reset-database.ps1`         | ~11KB | PowerShell script to delete + re-seed `test.db` from `test-database.sql`. Verifies row counts.                                                                      | After migration group testing or if data is polluted                       |
+| `test-database.sql`          | ~21KB | Seed SQL (DDL + DML) for all `test_*` tables                                                                                                                        | Reference only — reset script consumes this                                |
+| `sample.csv`                 | <1KB  | CSV fixture for `sqlite_create_csv_table` / `sqlite_analyze_csv_schema` testing                                                                                     | Used by admin group checklist                                              |
+
+## Test Database Schema
+
+| Table               | Rows | Notable Columns                                                                                                   |
+| ------------------- | ---- | ----------------------------------------------------------------------------------------------------------------- |
+| `test_products`     | 16   | price (REAL), category (TEXT, lowercase). Row 16: `Café Décor Light` (accented)                                   |
+| `test_orders`       | 20   | product_id FK → test_products, status (TEXT)                                                                      |
+| `test_jsonb_docs`   | 6    | **doc** (JSON), **metadata** (nested JSON), **tags** (JSON array). Row 4: `$.nested.level1.level2 = "deep value"` |
+| `test_articles`     | 8    | FTS5 searchable: SQLite, database, JSON, FTS, vector, API, search, MCP                                            |
+| `test_users`        | 9    | email, phone (`+1-555-...` format), bio. 1 NULL phone.                                                            |
+| `test_measurements` | 200  | sensor_id (INTEGER 1-5), temperature, humidity, pressure                                                          |
+| `test_embeddings`   | 20   | 8-dim float vectors. Categories: tech, database, food, fitness, travel                                            |
+| `test_locations`    | 15   | latitude/longitude. Cities: NYC(3), Paris(3), London(3), Tokyo(2), Sydney(2), SF(2)                               |
+| `test_categories`   | 17   | Hierarchical: name, path, level                                                                                   |
+| `test_events`       | 100  | **payload** (JSON), event_type, user_id (INT, 8 values)                                                           |
+
+**Key FK:** `test_orders.product_id → test_products.id`
+**Redundant index (intentional):** `idx_orders_status` is a prefix of `idx_orders_status_date` — used to test index audit tools.
+
+## Conventions
+
+| Convention                     | Rule                                                                                                                       |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| **Temp tables (basic tests)**  | `temp_*` prefix → drop after testing                                                                                       |
+| **Temp tables (stress tests)** | `stress_*` prefix → drop after testing                                                                                     |
+| **String values**              | Lowercase (`'electronics'`, not `'Electronics'`)                                                                           |
+| **sensor_id**                  | INTEGER (use `= 1`, not `= 'S001'`)                                                                                        |
+| **Reporting**                  | ❌ Fail, ⚠️ Issue, 📦 Payload concern. ✅ inline only, omit from final summary.                                            |
+| **Error testing**              | Every tool: test (a) domain error + (b) Zod error (`{}`). Must return `{success: false, error: "..."}`, NOT raw MCP error. |
+| **Error item prefix**          | All error-path checklist items use 🔴 prefix to distinguish from happy-path items                                          |
+| **Code mode**                  | Don't pass `readonly: true` unless specifically testing read-only filtering                                                |
+| **Post-test**                  | Clean up temps → plan fixes → implement → lint+typecheck → changelog → commit (no push) → re-test fixes                    |
+| **Database reset**             | Run `.\reset-database.ps1` after migration testing or data pollution                                                       |
+
+## WASM Parity Protocol
+
+To validate WASM mode produces identical results for shared tools:
+
+1. **Configure for WASM**: Set `--sqlite` (not `--sqlite-native`) in your MCP client config
+2. **Expected tool count**: 115 WASM vs 139 Native (24 fewer: 4 FTS5, 6 window, 7 transaction, 7 SpatiaLite)
+3. **Run the same checklists**: Use `test-group-tools.md` but skip items marked `[NATIVE ONLY]`
+4. **Verify shared tools**: All non-`[NATIVE ONLY]` items should produce identical output in both backends
+5. **Verify absent tools**: Calling a Native-only tool in WASM mode should return a structured error (not crash)
+6. **Key groups to verify**: text (FTS5 absent), stats (window functions absent), admin (transactions absent), geo (SpatiaLite absent)
+
+## Integration Test Scripts
+
+These scripts test features that require separate server processes — they **cannot** be run via MCP tool calls. All scripts are Node.js (`.mjs`), require no dependencies beyond Node.js, and exit with code 0 on success.
+
+> [!IMPORTANT]
+> Always `npm run build` before running these scripts — they execute `dist/cli.js` directly.
+
+### Script Reference
+
+| Script                      | Tests                                                           | Transport | Duration |
+| --------------------------- | --------------------------------------------------------------- | --------- | -------- |
+| `test-help-resources.mjs`   | Slim instructions + `sqlite://help` resource filtering by group | stdio     | ~15s     |
+| `test-tool-annotations.mjs` | `tools/list` openWorldHint annotation presence and consistency  | stdio     | ~5s      |
+
+### Quick Run
+
+```powershell
+cd C:\Users\chris\Desktop\db-mcp
+npm run build
+
+# Help resources
+node test-server/test-help-resources.mjs
+
+# Tool annotations
+node test-server/test-tool-annotations.mjs
+```
+
+### Success Criteria
+
+#### Help Resources
+
+- [ ] Instructions under 1000 chars (~680)
+- [ ] `sqlite://help` always registered
+- [ ] Group-specific help only for enabled groups
+- [ ] No old content leaked into slim instructions
+
+#### Tool Annotations
+
+- [ ] All tools have `annotations` object with `openWorldHint` set
+- [ ] All `openWorldHint` values are `false` (db-mcp tools are local-only)
+- [ ] 0 missing annotations
+
+## Agent Workflow
+
+1. Read `sqlite://help` resource (or `view_file` on `src/constants/server-instructions/gotchas.md`).
+2. Read `test-tools.md` for protocol and schema details.
+3. Access `test-group-tools.md` and copy the target group checklist.
+4. Execute via direct MCP tool calls to test logic. Run both happy-path and error-path tests.
+5. Clean up any temporary tables generated during execution.
+6. Report findings using the designated reporting convention.
+7. (Optional) Run stress tests from `test-tools-advanced-1.md` or `test-tools-advanced-2.md`.