db-mcp 1.1.1 → 2.0.0

package/dist/worker-script.js

@@ -1,7 +1,7 @@
+import { transformAutoReturn } from './chunk-OKOVZ5QE.js';
 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;
@@ -9,8 +9,12 @@ function buildSqliteProxy(bindings, rpcPort) {
     const p = pending.get(msg.id);
     if (p) {
       pending.delete(msg.id);
-      if (msg.error) {
-        p.reject(new Error(msg.error));
+      if (msg.error !== void 0) {
+        const err = new Error(msg.error || "Empty error message");
+        if (msg.errorDetails) {
+          Object.assign(err, msg.errorDetails);
+        }
+        p.reject(err);
       } else {
         p.resolve(msg.result);
       }
@@ -40,9 +44,19 @@ function buildSqliteProxy(bindings, rpcPort) {
   if (topLevel) {
     for (const method of topLevel) {
       if (method === "help") {
-        sqlite["help"] = () => ({
-          groups: groupNames
-        });
+        sqlite["help"] = () => {
+          let totalMethods = 0;
+          for (const k of groupNames) {
+            totalMethods += (bindings[k] ?? []).filter(
+              (m) => m !== "help"
+            ).length;
+          }
+          return {
+            groups: groupNames,
+            totalMethods,
+            usage: "Use sqlite.<group>.help() for group details. Example: sqlite.core.help()"
+          };
+        };
       } else {
         sqlite[method] = (...args) => new Promise((resolve, reject) => {
           const id = nextId++;
@@ -58,9 +72,19 @@ function buildSqliteProxy(bindings, rpcPort) {
     }
   }
   if (sqlite["help"] === void 0) {
-    sqlite["help"] = () => ({
-      groups: groupNames
-    });
+    sqlite["help"] = () => {
+      let totalMethods = 0;
+      for (const k of groupNames) {
+        totalMethods += (bindings[k] ?? []).filter(
+          (m) => m !== "help"
+        ).length;
+      }
+      return {
+        groups: groupNames,
+        totalMethods,
+        usage: "Use sqlite.<group>.help() for group details. Example: sqlite.core.help()"
+      };
+    };
   }
   return sqlite;
 }
@@ -97,7 +121,7 @@ async function executeInWorker() {
     const context = vm.createContext(sandbox, {
       name: "worker-sandbox"
     });
-    const wrappedCode = `(async () => { ${code} })()`;
+    const wrappedCode = `(async () => { ${transformAutoReturn(code)} })()`;
     const script = new vm.Script(wrappedCode, {
       filename: "user-code.js"
     });

package/logs/.gitkeep

@@ -0,0 +1 @@
+

package/mcp-config-example.json

@@ -0,0 +1,83 @@
+{
+  "mcpServers": {
+    "db-mcp": {
+      "command": "docker",
+      "args": [
+        "run",
+        "--rm",
+        "-i",
+        "-v",
+        "./data:/app/data",
+        "-e",
+        "MCP_HOST",
+        "-e",
+        "LOG_LEVEL",
+        "-e",
+        "METADATA_CACHE_TTL_MS",
+        "-e",
+        "CODEMODE_ISOLATION",
+        "-e",
+        "MCP_RATE_LIMIT_MAX",
+        "-e",
+        "SQLITE_DATABASE",
+        "-e",
+        "DB_MCP_TOOL_FILTER",
+        "-e",
+        "CSV_EXTENSION_PATH",
+        "-e",
+        "SPATIALITE_PATH",
+        "-e",
+        "MCP_AUTH_TOKEN",
+        "-e",
+        "OAUTH_ENABLED",
+        "-e",
+        "OAUTH_ISSUER",
+        "-e",
+        "OAUTH_AUDIENCE",
+        "-e",
+        "OAUTH_JWKS_URI",
+        "-e",
+        "OAUTH_CLOCK_TOLERANCE",
+        "-e",
+        "AUDIT_BACKUP",
+        "-e",
+        "AUDIT_REDACT",
+        "-e",
+        "AUDIT_READS",
+        "-e",
+        "AUDIT_BACKUP_DATA",
+        "-e",
+        "AUDIT_LOG",
+        "writenotenow/db-mcp:latest",
+        "--sqlite-native",
+        "/app/data/my-database.db",
+        "--tool-filter",
+        "codemode",
+        "--audit-log",
+        "/tmp/db-mcp-logs/audit.jsonl"
+      ],
+      "env": {
+        "MCP_HOST": "0.0.0.0",
+        "LOG_LEVEL": "info",
+        "METADATA_CACHE_TTL_MS": "5000",
+        "CODEMODE_ISOLATION": "worker",
+        "MCP_RATE_LIMIT_MAX": "100",
+        "SQLITE_DATABASE": "",
+        "DB_MCP_TOOL_FILTER": "",
+        "CSV_EXTENSION_PATH": "",
+        "SPATIALITE_PATH": "",
+        "MCP_AUTH_TOKEN": "",
+        "OAUTH_ENABLED": "false",
+        "OAUTH_ISSUER": "",
+        "OAUTH_AUDIENCE": "",
+        "OAUTH_JWKS_URI": "",
+        "OAUTH_CLOCK_TOLERANCE": "60",
+        "AUDIT_BACKUP": "false",
+        "AUDIT_REDACT": "false",
+        "AUDIT_READS": "false",
+        "AUDIT_BACKUP_DATA": "false",
+        "AUDIT_LOG": ""
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "db-mcp",
-  "version": "1.1.1",
+  "version": "2.0.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",
@@ -22,8 +22,8 @@
     "check": "npm run lint && npm run typecheck",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e": "playwright test",
+    "test:coverage": "vitest run --coverage && tsx scripts/update-badges.ts",
+    "test:e2e": "playwright test && tsx scripts/update-badges.ts",
     "bench": "vitest bench --run",
     "bench:verbose": "vitest bench --run --reporter=verbose",
     "clean": "rimraf dist",
@@ -73,8 +73,8 @@
     "globals": "^17.4.0",
     "rimraf": "^6.1.3",
     "tsup": "^8.5.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
+    "tsx": "^4.22.1",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.57.1",
     "vitest": "^4.0.17"
   },
@@ -85,9 +85,10 @@
     "better-sqlite3": "^12.8.0"
   },
   "overrides": {
-    "diff": "8.0.3",
+    "diff": "9.0.0",
     "@isaacs/brace-expansion": "5.0.1",
-    "tar": "7.5.11",
-    "minimatch": "10.2.4"
+    "tar": "7.5.15",
+    "minimatch": "10.2.5",
+    "brace-expansion": "5.0.6"
   }
 }

package/playwright.config.ts

@@ -8,7 +8,7 @@ export default defineConfig({
   // 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",
+  reporter: [["list"], ["json", { outputFile: "playwright-results.json" }]],
   use: {
     trace: "on-first-retry",
     // 60s timeout — allows slow operations (vector stats, code mode ETL)

package/scripts/update-badges.ts

@@ -0,0 +1,99 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT_DIR = path.resolve(__dirname, "..");
+
+function getBadgeColor(percentage: number): string {
+  if (percentage >= 95) return "brightgreen";
+  if (percentage >= 85) return "green";
+  if (percentage >= 75) return "yellowgreen";
+  if (percentage >= 65) return "yellow";
+  if (percentage >= 50) return "orange";
+  return "red";
+}
+
+function updateBadges() {
+  const summaryPath = path.join(ROOT_DIR, "coverage/coverage-summary.json");
+  const playwrightPath = path.join(ROOT_DIR, "playwright-results.json");
+
+  let linesPct = 0;
+  let coverageColor = "red";
+  let hasCoverage = false;
+
+  if (fs.existsSync(summaryPath)) {
+    const summary = JSON.parse(fs.readFileSync(summaryPath, "utf-8"));
+    linesPct = summary.total.lines.pct;
+    coverageColor = getBadgeColor(linesPct);
+    hasCoverage = true;
+  } else {
+    console.warn(`Coverage summary not found at ${summaryPath}`);
+  }
+
+  let e2ePassing = 0;
+  let e2eSkipped = 0;
+  let hasE2e = false;
+
+  if (fs.existsSync(playwrightPath)) {
+    const pw = JSON.parse(fs.readFileSync(playwrightPath, "utf-8"));
+    e2ePassing = pw.stats.expected || 0;
+    e2eSkipped = pw.stats.skipped || 0;
+    hasE2e = true;
+  } else {
+    console.warn(`Playwright results not found at ${playwrightPath}`);
+  }
+
+  // ![Coverage](https://img.shields.io/badge/Coverage-96.7%25-brightgreen.svg)
+  const covRegex =
+    /!\[Coverage\]\(https:\/\/img\.shields\.io\/badge\/Coverage-[0-9.]+.*?\.svg\)/g;
+  const newCovBadge = `![Coverage](https://img.shields.io/badge/Coverage-${linesPct}%25-${coverageColor}.svg)`;
+
+  // ![E2E](https://img.shields.io/badge/E2E-179%20tests%20%C2%B7%20224%20tools-blue.svg)
+  const e2eRegex =
+    /!\[E2E\]\(https:\/\/img\.shields\.io\/badge\/E2E-[a-zA-Z0-9%.-]+.*?\.svg\)/g;
+  const newE2eBadge = `![E2E](https://img.shields.io/badge/E2E-${e2ePassing}%20passing%20%C2%B7%20${e2eSkipped}%20skipped-blue.svg)`;
+
+  const filesToUpdate = ["README.md", "DOCKER_README.md"];
+
+  for (const file of filesToUpdate) {
+    const filePath = path.join(ROOT_DIR, file);
+    try {
+      let content = fs.readFileSync(filePath, "utf-8");
+      let changed = false;
+
+      if (hasCoverage) {
+        covRegex.lastIndex = 0;
+        if (covRegex.test(content)) {
+          covRegex.lastIndex = 0;
+          content = content.replace(covRegex, newCovBadge);
+          changed = true;
+          console.log(`Updated coverage badge in ${file} to ${linesPct}%`);
+        }
+      }
+
+      if (hasE2e) {
+        e2eRegex.lastIndex = 0;
+        if (e2eRegex.test(content)) {
+          e2eRegex.lastIndex = 0;
+          content = content.replace(e2eRegex, newE2eBadge);
+          changed = true;
+          console.log(
+            `Updated E2E badge in ${file} to ${e2ePassing} passing, ${e2eSkipped} skipped`,
+          );
+        }
+      }
+
+      if (changed) {
+        fs.writeFileSync(filePath, content, "utf-8");
+      } else {
+        console.log(`No badges found to update in ${file}.`);
+      }
+    } catch (err) {
+      console.warn(`Skipped updating ${file}: File not found or unreadable.`);
+    }
+  }
+}
+
+updateBadges();

package/server.json

@@ -2,20 +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, 139 tools, and smart tool filtering",
-  "version": "1.1.1",
+  "description": "SQLite MCP server with OAuth 2.1, HTTP/SSE, audit logging, 151 tools, and smart tool filtering",
+  "version": "2.0.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "db-mcp",
-      "version": "1.1.1",
+      "version": "2.0.0",
       "transport": {
         "type": "stdio"
       }
     },
     {
       "registryType": "oci",
-      "identifier": "docker.io/writenotenow/db-mcp:v1.1.1",
+      "identifier": "docker.io/writenotenow/db-mcp:v2.0.0",
       "transport": {
         "type": "stdio"
       }
@@ -36,7 +36,9 @@
     "vector-search",
     "geospatial",
     "spatialite",
-    "statistical-analysis"
+    "statistical-analysis",
+    "audit-logging",
+    "token-estimation"
   ],
   "author": {
     "name": "Chris LeRoux",

package/test-server/README.md

@@ -4,22 +4,20 @@
 
 ## 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                                              |
+| File                         | Size  | Purpose                                                                                                                                                        | When to Read                                                                        |
+| ---------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `test-tool-groups/`          | —     | **10 self-contained test prompts** — one per tool group. Each is a complete, standalone prompt (paste directly). See `test-tool-groups/README.md` for details. | **Primary testing method** — use instead of `test-tools.md` + `test-group-tools.md` |
+| `test-codemode/`             | —     | **10 self-contained Code Mode test prompts** — one per tool group. Tests via `sqlite_execute_code` only. See `test-codemode/README.md`.                        | **Primary Code Mode testing method**                                                |
+| `test-advanced/`             | —     | **10 self-contained advanced stress test prompts** — one per tool group. Second-pass edge cases via Code Mode. See `test-advanced/README.md`.                  | **Primary advanced testing method**                                                 |
+| `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-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 10 groups + codemode, 151 Native / 125 WASM tools. Source of truth for tool counts.                                         | Reference / auditing                                                                |
+| `tool-reference.md`          | ~18KB | **Complete Tool Reference** — Detailed list of all 151 Native / 125 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
 
@@ -59,7 +57,7 @@
 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)
+2. **Expected tool count**: 115 WASM vs 140 Native (25 fewer: 4 FTS5, 6 window, 8 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)
@@ -110,9 +108,8 @@ node test-server/test-tool-annotations.mjs
 ## 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`.
+2. Open the target group prompt from `test-tool-groups/` (e.g., `test-admin-core.md`). Each file is self-contained.
+3. Execute via direct MCP tool calls to test logic. Run both happy-path and error-path tests.
+4. Clean up any temporary tables generated during execution.
+5. Report findings using the designated reporting convention.
+6. (Optional) Run stress tests from `test-advanced/` folder.

package/test-server/code-map.md

@@ -2,7 +2,7 @@
 
 > **Agent-optimized navigation reference.** Read this before searching the codebase. Covers directory layout, handler→tool mapping, type/schema locations, error hierarchy, and key constants.
 >
-> Last updated: March 18, 2026
+> Last updated: May 16, 2026
 
 ---
 
@@ -81,6 +81,13 @@ src/
 │   ├── errors.ts                   # OAuth-specific error classes
 │   └── types.ts                    # OAuth TypeScript types
 │
+├── audit/                          # Audit logging subsystem
+│   ├── types.ts                    # AuditEntry, AuditConfig, BackupConfig, SnapshotMetadata types
+│   ├── logger.ts                   # AuditLogger — async-buffered JSONL writer with rotation
+│   ├── interceptor.ts              # createAuditInterceptor() — wraps tool handlers with around(), reads OAuth identity from AsyncLocalStorage
+│   ├── backup-manager.ts           # BackupManager — pre-mutation DDL snapshots (gzip)
+│   └── index.ts                    # Barrel
+│
 ├── transports/
 │   └── http/
 │       ├── transport.ts            # HTTP/SSE transport (Streamable HTTP + legacy SSE)
@@ -94,6 +101,7 @@ src/
 ├── codemode/                       # Code Mode sandbox (secure JS execution)
 │   ├── sandbox.ts                  # SandboxPool lifecycle manager
 │   ├── sandbox-factory.ts          # Sandbox creation factory
+│   ├── auto-return.ts              # Last-expression auto-return transform (IIFE helper)
 │   ├── worker-sandbox.ts           # Worker thread sandbox (MessagePort RPC bridge)
 │   ├── worker-script.ts            # Worker thread entry point (runs inside vm)
 │   ├── api.ts                      # sqlite.* API bridge (exposes tools to sandbox)
@@ -113,7 +121,7 @@ src/
 │   │   ├── schema-manager.ts       # Schema cache + metadata (TTL-based)
 │   │   ├── json-utils.ts           # JSON column detection and normalization
 │   │   ├── types.ts                # WASM-specific Zod schemas + TS types
-│   │   ├── resources.ts            # 8 data MCP resources (schema, tables, indexes, etc.)
+│   │   ├── resources.ts            # 10 data MCP resources (schema, tables, indexes, compile_options, etc.)
 │   │   ├── index.ts                # Barrel
 │   │   ├── output-schemas/         # Zod outputSchema definitions per group (see § below)
 │   │   ├── prompts/                # 10 MCP prompts (see § below)
@@ -144,6 +152,7 @@ Each file below registers tools with `group` labels. Native-only tools are marke
 | ----------------- | ----------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- |
 | **codemode**      | `codemode.ts`                             | 1     | `sqlite_execute_code`                                                                                                         |
 | **core**          | `core/queries.ts`                         | 2     | `sqlite_read_query`, `sqlite_write_query`                                                                                     |
+|                   | `core/convenience.ts`                     | 5     | `sqlite_upsert`, `sqlite_batch_insert`, `sqlite_count`, `sqlite_exists`, `sqlite_truncate`                                    |
 |                   | `core/tables.ts`                          | 4     | `create_table`, `list_tables`, `describe_table`, `drop_table`                                                                 |
 |                   | `core/indexes.ts`                         | 3     | `get_indexes`, `create_index`, `drop_index`                                                                                   |
 | **json**          | `json-operations/crud.ts`                 | 3     | `json_insert`, `json_update`, `json_select`                                                                                   |
@@ -155,9 +164,12 @@ Each file below registers tools with `group` labels. Native-only tools are marke
 |                   | `text/formatting.ts`                      | 6     | `text_split`, `text_concat`, `text_replace`, `text_trim`, `text_case`, `text_substring`                                       |
 |                   | `text/search.ts`                          | 3     | `fuzzy_match`, `phonetic_match`, `advanced_search`                                                                            |
 |                   | `text/validate.ts`                        | 2     | `text_normalize`, `text_validate`                                                                                             |
-| **text** (FTS5)   | `fts.ts`                                  | 4     | `fts_create`, `fts_search`, `fts_rebuild`, `fts_match_info`                                                                   |
+|                   | `text/sentiment.ts`                       | 1     | `text_sentiment`                                                                                                              |
+| **text** (FTS5)   | `fts.ts`                                  | 5     | `fts_create`, `fts_search`, `fts_rebuild`, `fts_match_info`, `fts_headline`                                                   |
 | **stats**         | `stats/basic.ts`                          | 7     | `stats_basic`, `stats_count`, `stats_group_by`, `stats_histogram`, `stats_percentile`, `stats_correlation`, `stats_top_n`     |
 |                   | `stats/advanced.ts`                       | 6     | `stats_distinct`, `stats_summary`, `stats_frequency`, `stats_outliers`, `stats_regression`, `stats_hypothesis`                |
+|                   | `stats/anomaly-detection.ts`              | 2     | `stats_detect_anomalies`, `stats_detect_bloat`                                                                                |
+|                   | `stats/schema-risks.ts`                   | 1     | `stats_detect_schema_risks`                                                                                                   |
 | **vector**        | `vector/storage.ts`                       | 4     | `vector_create_table`, `vector_store`, `vector_batch_store`, `vector_delete`                                                  |
 |                   | `vector/search.ts`                        | 2     | `vector_search`, `vector_get`                                                                                                 |
 |                   | `vector/metadata.ts`                      | 5     | `vector_count`, `vector_stats`, `vector_dimensions`, `vector_normalize`, `vector_distance`                                    |
@@ -189,12 +201,12 @@ Each file below registers tools with `group` labels. Native-only tools are marke
 
 ### Native-Only Handlers (`src/adapters/sqlite-native/tools/`)
 
-| Group                    | Handler File             | Tools | Notes                                                                                                              |
-| ------------------------ | ------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------ |
-| **stats** (window)       | `window.ts`              | 6     | `window_row_number`, `window_rank`, `window_lag_lead`, `window_running_total`, `window_moving_avg`, `window_ntile` |
-| **admin** (transactions) | `transactions.ts`        | 7     | `transaction_begin/commit/rollback/savepoint/release/rollback_to/execute`                                          |
-| **geo** (SpatiaLite)     | `spatialite/tools.ts`    | 4     | `spatialite_load/create_table/query/index`                                                                         |
-|                          | `spatialite/analysis.ts` | 3     | `spatialite_analyze/transform/import`                                                                              |
+| Group                | Handler File             | Tools | Notes                                                                                                              |
+| -------------------- | ------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------ |
+| **stats** (window)   | `window.ts`              | 6     | `window_row_number`, `window_rank`, `window_lag_lead`, `window_running_total`, `window_moving_avg`, `window_ntile` |
+| **transactions**     | `transactions.ts`        | 8     | `transaction_begin/status/commit/rollback/savepoint/release/rollback_to/execute`                                   |
+| **geo** (SpatiaLite) | `spatialite/tools.ts`    | 4     | `spatialite_load/create_table/query/index`                                                                         |
+|                      | `spatialite/analysis.ts` | 3     | `spatialite_analyze/transform/import`                                                                              |
 
 ### Utility Files (no tools, shared helpers)
 
@@ -241,7 +253,7 @@ Zod schemas that define the `outputSchema` for MCP tool responses. All output sc
 | `introspection.ts` | Introspection group output schemas (9 schemas: DependencyGraph, TopologicalSort, CascadeSimulator, SchemaSnapshot, ConstraintAnalysis, MigrationRisks, StorageAnalysis, IndexAudit, QueryPlan) |
 | `migration.ts`     | Migration group output schemas (7 schemas: MigrationInit, MigrationRecord, MigrationApply, MigrationRollback, MigrationHistory, MigrationStatus + MigrationRecordEntry)                        |
 | `virtual.ts`       | Virtual table output schemas (7 schemas: ListVirtualTables, VirtualTableInfo, DropVirtualTable, CreateCsvTable, AnalyzeCsvSchema, CreateRtreeTable, CreateSeriesTable)                         |
-| `native.ts`        | Native-only output schemas (transactions — 7 schemas, window functions — 6 schemas)                                                                                                            |
+| `native.ts`        | Native-only output schemas (transactions — 8 schemas, window functions — 6 schemas)                                                                                                            |
 | `spatialite.ts`    | SpatiaLite output schemas (7 tools — native only)                                                                                                                                              |
 | `server.ts`        | Type aliases for core output schemas (built-in tools use `content` pattern, not `structuredContent`)                                                                                           |
 | `index.ts`         | Barrel re-export                                                                                                                                                                               |
@@ -269,15 +281,17 @@ The `DbMcpError` constructor auto-refines generic codes (`DB_QUERY_FAILED`, `DB_
 
 ```
 DbMcpError (base.ts)
-├── ValidationError         code: VALIDATION_ERROR      category: validation
-├── ConnectionError         code: CONNECTION_ERROR       category: connection      recoverable: true
-├── QueryError              code: QUERY_ERROR            category: query            accepts: sql option
-├── PermissionError         code: PERMISSION_ERROR       category: permission
-├── ResourceNotFoundError   code: RESOURCE_NOT_FOUND     category: resource         accepts: resourceType, resourceName
-├── ConfigurationError      code: CONFIG_ERROR           category: config
-├── InternalError           code: INTERNAL_ERROR         category: internal
-├── AuthenticationError     code: AUTHENTICATION_ERROR   category: authentication
-└── AuthorizationError      code: AUTHORIZATION_ERROR    category: authorization
+├── ValidationError              code: VALIDATION_ERROR      category: validation
+├── ConnectionError              code: CONNECTION_ERROR       category: connection      recoverable: true
+├── QueryError                   code: QUERY_ERROR            category: query            accepts: sql option
+├── PermissionError              code: PERMISSION_ERROR       category: permission
+├── ResourceNotFoundError        code: RESOURCE_NOT_FOUND     category: resource         accepts: resourceType, resourceName
+├── ConfigurationError           code: CONFIG_ERROR           category: config
+├── InternalError                code: INTERNAL_ERROR         category: internal
+├── AuthenticationError          code: AUTHENTICATION_ERROR   category: authentication
+├── AuthorizationError           code: AUTHORIZATION_ERROR    category: authorization
+├── TransactionError             code: TRANSACTION_ERROR      category: query            recoverable: true
+└── ExtensionNotAvailableError   code: EXTENSION_MISSING      category: config           accepts: extensionName
 ```
 
 **Usage pattern** — all tool handlers:
@@ -308,14 +322,14 @@ catch (error) {
 
 ## Key Constants & Config
 
-| What                               | Where                                  | Notes                                                                                                |
-| ---------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| Server instructions (agent prompt) | `src/constants/server-instructions.ts` | Generated: slim `INSTRUCTIONS` (~680 chars) + `HELP_CONTENT` map. Source: `server-instructions/*.md` |
-| Tool group arrays                  | `src/filtering/tool-constants.ts`      | `TOOL_GROUPS` map, `META_GROUPS` shortcuts                                                           |
-| Tool filter logic                  | `src/filtering/tool-filter.ts`         | `ToolFilter` class                                                                                   |
-| JSON-RPC constants                 | `src/codemode/api-constants.ts`        | Error codes, method names for sandbox RPC                                                            |
-| Logger error codes                 | `src/utils/logger/error-codes.ts`      | Module-prefixed codes (`DB_`, `AUTH_`, etc.)                                                         |
-| Version SSoT                       | `src/version.ts`                       | Reads from `package.json` at build time                                                              |
+| What                               | Where                                  | Notes                                                                                                         |
+| ---------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Server instructions (agent prompt) | `src/constants/server-instructions.ts` | Generated: slim `INSTRUCTIONS` (~680 chars) + `HELP_CONTENT` map. Source: `server-instructions/*.md`          |
+| Tool group arrays                  | `src/filtering/tool-constants.ts`      | `TOOL_GROUPS` map, `META_GROUPS` shortcuts                                                                    |
+| Tool filter logic                  | `src/filtering/tool-filter.ts`         | `ToolFilter` class                                                                                            |
+| JSON-RPC constants                 | `src/codemode/api-constants.ts`        | Error codes, method names for sandbox RPC                                                                     |
+| Logger error codes                 | `src/utils/logger/error-codes.ts`      | Module-prefixed codes (`DB_`, `AUTH_`, etc.)                                                                  |
+| Version SSoT                       | `src/version.ts`                       | Reads from `package.json` at runtime. Both adapters `import { VERSION }` — **never hardcode version strings** |
 
 ---
 
@@ -356,13 +370,11 @@ catch (error) {
 | `test-server/README.md`                      | Agent testing orchestration doc                                                                                    |
 | `test-server/test-database.sql`              | Seed DDL+DML (10 tables, ~400 rows)                                                                                |
 | `test-server/reset-database.ps1`             | Reset script — drops + re-seeds `test.db`                                                                          |
-| `test-server/tool-reference.md`              | Complete 139/115 tool inventory with descriptions                                                                  |
+| `test-server/tool-reference.md`              | Complete 151/125 tool inventory with descriptions                                                                  |
 | `test-server/test-preflight.md`              | Pre-test verification checklist                                                                                    |
-| `test-server/test-tools.md`                  | Entry-point protocol (schema ref, reporting format)                                                                |
-| `test-server/test-group-tools.md`            | Per-group deterministic checklists                                                                                 |
-| `test-server/test-tools-advanced-1.md`       | Advanced stress test prompts (part 1)                                                                              |
-| `test-server/test-tools-advanced-2.md`       | Advanced stress test prompts (part 2)                                                                              |
-| `test-server/test-tools-codemode.md`         | Code mode specific test prompts                                                                                    |
+| `test-server/test-tool-groups/`              | 10 self-contained test prompts — one per tool group. Direct calls only.                                            |
+| `test-server/test-codemode/`                 | 10 self-contained test prompts — one per tool group. Code Mode execution only.                                     |
+| `test-server/test-advanced/`                 | 10 self-contained advanced stress test prompts — one per tool group.                                               |
 | `test-server/test-resources.md`              | MCP resource verification prompts                                                                                  |
 | `test-server/test-prompts.md`                | MCP prompt verification prompts                                                                                    |
 | `test-server/test-agent-experience.md`       | 20 open-ended scenarios — validates help resource sufficiency                                                      |