db-mcp 1.1.1 → 2.0.0

package/dist/chunk-WBER5YY4.js

@@ -0,0 +1,2053 @@
+import { TOOL_GROUP_SCOPES, getAuthContext, SCOPES } from './chunk-SFJQCNG7.js';
+import { VERSION, NAME, READ_ONLY, SERVER_ICONS } from './chunk-VIDSICEL.js';
+import { TOOL_GROUPS, parseToolFilter, getToolFilterFromEnv, logger, getFilterSummary, DbMcpError } from './chunk-645ZEFLA.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { open, stat, mkdir, rename, readdir, unlink, mkdtemp, writeFile, rmdir, readFile, appendFile } from 'fs/promises';
+import { dirname, join, basename, sep } from 'path';
+import { gzip, gunzipSync } from 'zlib';
+import { promisify } from 'util';
+import { performance } from 'perf_hooks';
+import { z } from 'zod';
+
+// src/constants/server-instructions.ts
+var INSTRUCTIONS = `# db-mcp (SQLite MCP Server)
+
+## Quick Access
+
+| Purpose         | Action                     |
+| --------------- | -------------------------- |
+| Health check    | \`server_health\` tool       |
+| Server info     | \`server_info\` tool         |
+| Database schema | \`sqlite://schema\` resource |
+| Tool help       | \`sqlite://help\` resource   |
+
+## Built-in Tools
+
+\`server_info\`, \`server_health\`, \`list_adapters\` \u2014 always available.
+
+## Help Resources
+
+Read \`sqlite://help\` for gotchas and critical usage patterns.
+Read \`sqlite://help/{group}\` for group-specific tool reference (json, text, stats, vector, geo, admin, transactions, introspection, migration).
+Only help resources for your enabled tool groups are registered.`;
+var HELP_CONTENT = /* @__PURE__ */ new Map([
+  [
+    "admin",
+    `# db-mcp Help \u2014 Database Administration (29 Native / 29 WASM)
+
+## Maintenance
+
+\`\`\`javascript
+sqlite_integrity_check({ maxErrors: 10 }); // check for corruption
+sqlite_optimize({ analyze: true, reindex: true }); // optimize performance
+sqlite_vacuum(); // reclaim space
+sqlite_analyze({ table: "orders" }); // update statistics for query planner
+sqlite_dbstat({ summarize: true }); // storage stats (\u26A0\uFE0F summarize native-only; WASM returns counts only)
+\`\`\`
+
+## Backup/Restore (Native only)
+
+\`\`\`javascript
+sqlite_backup({ targetPath: "/path/to/backup.db" });
+sqlite_verify_backup({ backupPath: "/path/to/backup.db" }); // check integrity without restoring
+sqlite_restore({ sourcePath: "/path/to/backup.db" }); // \u26A0\uFE0F WARNING: Replaces current database
+\`\`\`
+
+## Audit Backups (Requires --audit-backup)
+
+\`\`\`javascript
+sqlite_audit_list_backups(); // list pre-mutation DDL snapshots
+sqlite_audit_get_backup({ filename: "snapshot_123.json" }); // retrieve specific snapshot
+sqlite_audit_cleanup(); // apply retention policy and delete old snapshots
+\`\`\`
+
+## PRAGMA
+
+\`\`\`javascript
+sqlite_pragma_settings({ pragma: "journal_mode" }); // get value
+sqlite_pragma_settings({ pragma: "cache_size", value: 10000 }); // set value
+sqlite_pragma_table_info({ table: "users" }); // column details
+sqlite_pragma_compile_options({ filter: "FTS" }); // \u26A0\uFE0F WASM may show FTS3, not FTS5
+sqlite_pragma_database_list(); // list attached databases
+sqlite_pragma_optimize(); // run PRAGMA optimize
+\`\`\`
+
+## Index & Stats
+
+- \`sqlite_index_stats({ table: "orders" })\` \u2014 stats for explicit indexes
+
+## Views
+
+\`\`\`javascript
+sqlite_create_view({
+  viewName: "active_orders",
+  selectQuery: "SELECT * FROM orders WHERE status = 'active'",
+});
+sqlite_create_view({ viewName: "v", selectQuery: "...", replace: true }); // CREATE OR REPLACE
+sqlite_list_views(); // list all views
+sqlite_drop_view({ viewName: "active_orders" });
+\`\`\`
+
+## Virtual Tables
+
+\`\`\`javascript
+sqlite_list_virtual_tables(); // list FTS5, R-Tree, CSV tables
+sqlite_virtual_table_info({ tableName: "articles_fts" }); // module and column info
+sqlite_drop_virtual_table({ tableName: "old_fts", ifExists: true });
+\`\`\`
+
+## Generate Series (pure JS)
+
+\`\`\`javascript
+sqlite_generate_series({ start: 1, stop: 100, step: 5 }); // returns array of values
+// \u26A0\uFE0F Creates a REGULAR table (not virtual) \u2014 use sqlite_drop_table to remove
+sqlite_create_series_table({ tableName: "numbers", start: 1, stop: 1000 });
+\`\`\`
+
+## R-Tree (Native only)
+
+\`\`\`javascript
+sqlite_create_rtree_table({ tableName: "locations_idx", dimensions: 2 }); // 2D: minX, maxX, minY, maxY
+// Returns graceful error with wasmLimitation: true in WASM
+\`\`\`
+
+## CSV Virtual Tables (Native only)
+
+\u26A0\uFE0F Requires ABSOLUTE file paths
+
+\`\`\`javascript
+sqlite_analyze_csv_schema({ filePath: "/absolute/path/to/data.csv" }); // analyze CSV structure
+sqlite_create_csv_table({
+  tableName: "csv_data",
+  filePath: "/absolute/path/to/data.csv",
+});
+\`\`\`
+
+## Business Insights
+
+\`\`\`javascript
+sqlite_append_insight({ insight: "Q4 revenue increased 23% YoY" }); // add to memo://insights
+\`\`\``
+  ],
+  [
+    "core",
+    `# db-mcp Help \u2014 Core Operations (14 tools)
+
+## Basic Queries
+
+- \`sqlite_read_query({ query: "SELECT * FROM users LIMIT 10" })\` \u2014 execute SELECT, PRAGMA, EXPLAIN, or WITH statements
+- \`sqlite_write_query({ query: "INSERT INTO users (name) VALUES ('Alice')" })\` \u2014 execute INSERT, UPDATE, DELETE, or DDL statements
+
+## Tables & Schema
+
+- \`sqlite_list_tables({ excludeSystemTables?: boolean })\` \u2014 list all tables in the database (system tables excluded by default)
+- \`sqlite_describe_table({ table: "users" })\` \u2014 get detailed schema, columns, and foreign keys for a specific table
+- \`sqlite_create_table({ table: "users", columns: [{ name: "id", type: "INTEGER PRIMARY KEY" }, { name: "email", type: "TEXT UNIQUE" }] })\` \u2014 create a new table
+- \`sqlite_drop_table({ table: "users", ifExists?: true })\` \u2014 drop an existing table
+
+## Indexes
+
+- \`sqlite_get_indexes({ table?: "users", excludeSystemIndexes?: true })\` \u2014 list indexes (optionally filtered by table)
+- \`sqlite_create_index({ indexName: "idx_users_email", table: "users", columns: ["email"], unique?: true })\` \u2014 create a new index
+- \`sqlite_drop_index({ indexName: "idx_users_email", ifExists?: true })\` \u2014 drop an existing index
+
+## Convenience Tools (High-Level Data Operations)
+
+- \`sqlite_upsert({ table: "users", data: [{ id: 1, name: "Alice" }], conflictColumns: ["id"], updateColumns: ["name"], returning: true })\` \u2014 insert or update rows using \`ON CONFLICT\` (or \`REPLACE\` fallback). Supports \`returning: true\` or array of columns.
+- \`sqlite_batch_insert({ table: "users", data: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }], returning: true })\` \u2014 insert multiple rows in a single batch. Supports \`returning: true\` or array of columns.
+- \`sqlite_count({ table: "users", whereClause?: "status = 'active'" })\` \u2014 count rows in a table (faster than a full query)
+- \`sqlite_exists({ table: "users", whereClause: "email = 'test@example.com'" })\` \u2014 check if a row exists (stops at first match)
+- \`sqlite_truncate({ table: "users" })\` \u2014 quickly delete all rows from a table (executes \`DELETE FROM table\`)`
+  ],
+  [
+    "geo",
+    `# db-mcp Help \u2014 Geospatial Operations (4 basic + 7 SpatiaLite)
+
+## Basic Geo (always available \u2014 Haversine formula)
+
+\`\`\`javascript
+sqlite_geo_distance({
+  lat1: 40.7128,
+  lon1: -74.006,
+  lat2: 34.0522,
+  lon2: -118.2437,
+}); // returns km
+sqlite_geo_bounding_box({
+  table: "stores",
+  latColumn: "lat",
+  lonColumn: "lon",
+  minLat: 40,
+  maxLat: 41,
+  minLon: -75,
+  maxLon: -73,
+});
+sqlite_geo_nearby({
+  table: "stores",
+  latColumn: "lat",
+  lonColumn: "lon",
+  centerLat: 40.7,
+  centerLon: -74,
+  radius: 10,
+  unit: "km",
+});
+sqlite_geo_cluster({
+  table: "customers",
+  latColumn: "lat",
+  lonColumn: "lon",
+  gridSize: 0.1,
+});
+\`\`\`
+
+## SpatiaLite (7 tools, Native only)
+
+\`\`\`javascript
+// Load extension first
+sqlite_spatialite_load(); // \u26A0\uFE0F Required before using other spatial tools
+
+// Create spatial table with geometry column
+sqlite_spatialite_create_table({
+  tableName: "places",
+  geometryColumn: "geom",
+  geometryType: "POINT",
+  srid: 4326,
+});
+
+// Import data (WKT or GeoJSON)
+sqlite_spatialite_import({
+  tableName: "places",
+  format: "wkt",
+  data: "POINT(-73.99 40.75)",
+  additionalData: { name: "NYC" },
+});
+sqlite_spatialite_import({
+  tableName: "places",
+  format: "geojson",
+  data: '{"type":"Point","coordinates":[-73.99,40.75]}',
+});
+
+// Spatial queries (SELECT only)
+sqlite_spatialite_query({
+  query: "SELECT name, AsText(geom) FROM places WHERE ST_Within(geom, ...)",
+});
+
+// Spatial analysis
+// analysisType: "spatial_extent" | "point_in_polygon" | "nearest_neighbor" | "distance_matrix"
+// \u26A0\uFE0F nearest_neighbor/distance_matrix return CARTESIAN distance (degrees), not geodetic (km/miles)
+// For same source/target table, use excludeSelf: true to avoid self-matches
+sqlite_spatialite_analyze({
+  analysisType: "spatial_extent",
+  sourceTable: "places",
+  geometryColumn: "geom",
+});
+sqlite_spatialite_analyze({
+  analysisType: "nearest_neighbor",
+  sourceTable: "pts",
+  targetTable: "pts",
+  excludeSelf: true,
+});
+
+// Geometry transforms
+// buffer: 'distance' = radius; simplify: 'distance' = tolerance (0.0001 for lat/lon)
+// \u26A0\uFE0F Buffer auto-simplifies output by default (tolerance=0.0001). Use simplifyTolerance: 0 to disable
+sqlite_spatialite_transform({
+  operation: "buffer",
+  geometry1: "POINT(-73.99 40.75)",
+  distance: 0.01,
+});
+sqlite_spatialite_transform({
+  operation: "simplify",
+  geometry1: "...",
+  distance: 0.001,
+});
+
+// Spatial index (R-Tree)
+sqlite_spatialite_index({
+  tableName: "places",
+  geometryColumn: "geom",
+  action: "create",
+}); // create, drop, or check
+\`\`\``
+  ],
+  [
+    "gotchas",
+    `# db-mcp Help \u2014 Gotchas & Code Mode
+
+## \u26A0\uFE0F Critical Gotchas
+
+1. **sqlite_write_query**: \u26D4 Only INSERT/UPDATE/DELETE \u2014 use \`sqlite_read_query\` for SELECT
+2. **Regex patterns**: Double-escape backslashes (\`\\\\\\\\\`) when passing through JSON/MCP
+3. **FTS5 virtual tables**: \`*_fts\` and shadow tables \`*_fts_*\` are hidden from \`sqlite_list_tables\` for cleaner output
+4. **FTS5 boolean logic**: Uses AND by default \u2014 \`"machine learning"\` = rows with BOTH words. Use OR explicitly: \`"machine OR learning"\`
+5. **json_each row multiplication**: Expands arrays to rows \u2014 use \`limit\` param for large arrays
+6. **json_group_object without groupByColumn**: Each row creates a key-value pair; duplicate keys result if key values aren't unique
+7. **allowExpressions**: For column extraction ONLY (e.g., \`json_extract\`), NOT aggregate functions \u2014 use \`aggregateFunction\` param instead
+8. **sqlite_json_normalize_column**: Defaults to \`preserve\` (maintains original format); use \`outputFormat: 'text'\` to force text
+9. **Fuzzy matching tokenization**: Matches WORD TOKENS by default \u2014 \`"laptop"\` matches \`"Laptop Pro 15"\` (distance 0 on first token). Use \`tokenize: false\` for full-string matching
+10. **SpatiaLite distances**: \`nearest_neighbor\`/\`distance_matrix\` return CARTESIAN distance (degrees), not geodetic (km/miles)
+11. **SpatiaLite buffer**: Auto-simplifies output by default (tolerance=0.0001). Use \`simplifyTolerance: 0\` to disable
+12. **sqlite_stats_top_n**: Auto-excludes long-content columns (description, body, notes, etc.) when \`selectColumns\` is omitted. Use \`selectColumns\` to override
+13. **CSV virtual tables**: Require ABSOLUTE file paths
+14. **sqlite_create_series_table**: Creates a REGULAR table (not virtual) \u2014 use \`sqlite_drop_table\` to remove
+15. **sqlite_dbstat**: \`summarize\` only works in native; WASM returns counts only
+16. **PRAGMA compile options**: WASM may show FTS3, not FTS5
+17. **Vector tool schemas**: Vector tools use distinct schemas for specific operations. E.g., \`sqlite.vector.dimensions\` requires \`vectorColumn\`. Additionally, \`sqlite.vector.get\` wraps metadata inside a \`metadata\` object (e.g., \`metadata.content\`), and \`sqlite.vector.stats\` returns \`sampleSize\` and \`magnitudeStats\` (not \`count\` and \`stats\`).
+18. **FTS5 trigger cleanup**: Dropping an FTS5 table with \`sqlite_drop_table\` automatically finds and removes the associated \`_ai\`, \`_ad\`, and \`_au\` sync triggers from the source table.
+
+## WASM vs Native
+
+| Feature                                           | Native                | WASM        | Fallback         |
+| ------------------------------------------------- | --------------------- | ----------- | ---------------- |
+| FTS5 full-text search                             | \u2705                    | \u274C          | None             |
+| Transactions (8 tools)                            | \u2705                    | \u274C          | None             |
+| Window functions (6 tools in stats group)         | \u2705                    | \u274C          | None             |
+| SpatiaLite GIS (7 tools; 4 basic geo always work) | \u2705                    | \u274C          | None             |
+| Backup/Restore (3 tools)                          | \u2705                    | \u274C          | Graceful error   |
+| R-Tree spatial indexing                           | \u2705                    | \u274C          | Graceful error   |
+| CSV virtual tables                                | \u2705                    | \u274C          | Graceful error   |
+| generate_series                                   | JS fallback           | JS fallback | \u2014                |
+| dbstat                                            | \u2705 native (per-table) | \u274C          | JS (counts only) |
+| soundex()                                         | \u2705 native             | \u274C          | JS               |
+
+## Code Mode (1 tool)
+
+| Tool                  | Description                                                       |
+| --------------------- | ----------------------------------------------------------------- |
+| \`sqlite_execute_code\` | Execute JavaScript in a sandboxed environment with \`sqlite.*\` API |
+
+**Usage**: \`sqlite_execute_code({ code: "const tables = await sqlite.core.listTables(); return tables;" })\`
+**Discover**: \`sqlite.help()\` for all groups, \`sqlite.<group>.help()\` for methods.
+**Groups**: \`sqlite.core\`, \`sqlite.json\`, \`sqlite.text\`, \`sqlite.stats\`, \`sqlite.vector\`, \`sqlite.admin\`, \`sqlite.transactions\` (Native-only), \`sqlite.geo\`, \`sqlite.introspection\`, \`sqlite.migration\`
+
+> **Note**: Code Mode dynamically filters capabilities. In WASM environments, \`sqlite.help()\` will omit unsupported groups (e.g., \`transactions\`) and tools (e.g., FTS5) to accurately reflect the active runtime.
+
+## Code Mode API Mapping
+
+\`sqlite_group_action\` \u2192 \`sqlite.group.action()\` (group prefixes dropped: \`sqlite_json_insert\` \u2192 \`sqlite.json.insert()\`)
+
+**Positional args work**: \`sqlite.core.readQuery("SELECT...")\`, \`sqlite.json.insert("docs", "data", {...})\`
+
+**Discovery**: \`sqlite.help()\` returns all groups and methods. \`sqlite.core.help()\`, \`sqlite.json.help()\` for group-specific methods.`
+  ],
+  [
+    "introspection",
+    `# db-mcp Help \u2014 Schema Introspection (9 tools)
+
+All introspection tools are **read-only** \u2014 they query PRAGMAs and sqlite_master, never modify data.
+
+## Graph Analysis (3 tools)
+
+\`\`\`javascript
+// Build FK dependency graph \u2014 nodesOnly: true for lightweight response (nodes without edges)
+sqlite_dependency_graph({ includeRowCounts: true, excludeSystemTables: true });
+sqlite_dependency_graph({ nodesOnly: true }); // lighter payload
+
+// Safe DDL execution order \u2014 "create" = parents first (default), "drop" = children first
+sqlite_topological_sort({ direction: "create", excludeSystemTables: true });
+sqlite_topological_sort({ direction: "drop" }); // safe DROP order
+
+// Simulate DELETE/DROP/TRUNCATE impact \u2014 shows affected tables, cascade paths, severity scoring
+sqlite_cascade_simulator({ table: "users", operation: "delete" });
+sqlite_cascade_simulator({ table: "users", operation: "drop", compact: true }); // compact omits path arrays
+\`\`\`
+
+## Schema Analysis (3 tools)
+
+\`\`\`javascript
+// Full schema in one call \u2014 compact: true omits column details, sections limits scope
+sqlite_schema_snapshot({
+  sections: ["tables", "indexes"],
+  excludeSystemTables: true,
+});
+sqlite_schema_snapshot({ compact: true }); // lighter payload
+
+// Find constraint health issues \u2014 missing PKs, nullable FKs, unindexed FKs
+sqlite_constraint_analysis({ excludeSystemTables: true });
+sqlite_constraint_analysis({
+  table: "orders",
+  checks: ["missing_pk", "unindexed_fk"],
+}); // limit scope
+
+// Analyze DDL for SQLite-specific risks \u2014 does NOT execute the statements
+sqlite_migration_risks({
+  statements: [
+    "ALTER TABLE users ADD COLUMN email TEXT",
+    "DROP TABLE old_logs",
+  ],
+});
+\`\`\`
+
+## Diagnostics (3 tools)
+
+\`\`\`javascript
+// Fragmentation, per-table size breakdown, optimization recommendations
+sqlite_storage_analysis({
+  includeTableDetails: true,
+  excludeSystemTables: true,
+});
+sqlite_storage_analysis({ limit: 10 }); // top 10 tables only
+
+// Audit index effectiveness \u2014 find redundant, missing FK, unindexed large tables
+sqlite_index_audit({ excludeSystemTables: true });
+sqlite_index_audit({ table: "orders", minSeverity: "warning" }); // reduce payload
+
+// EXPLAIN QUERY PLAN with scan-type classification and optimization suggestions (SELECT/WITH only)
+sqlite_query_plan({ sql: "SELECT * FROM orders WHERE status = 'active'" });
+\`\`\`
+
+## \u26A0\uFE0F Gotchas
+
+- \`excludeSystemTables\` defaults to \`true\` \u2014 SpatiaLite system tables are hidden for cleaner output. Pass \`false\` to include them
+- \`sqlite_migration_risks\` analyzes DDL text statically \u2014 it does NOT execute the statements`
+  ],
+  [
+    "json",
+    `# db-mcp Help \u2014 JSON Operations (24 tools)
+
+## Collection & CRUD
+
+- \`sqlite_create_json_collection({ tableName, indexes: [{ path: "$.type" }, { path: "$.author" }] })\` \u2014 creates table with JSON indexes
+- \`sqlite_json_insert({ table, column, data: { type: "article", title: "Hello", tags: ["news"] } })\` \u2014 insert JSON document
+- \`sqlite_json_select({ table, column, extractPaths? })\` \u2014 select rows, optionally extract specific JSON paths
+- \`sqlite_json_update({ table, column, path, value, whereClause })\` \u2014 update value at JSON path
+- \`sqlite_json_query({ table, column, filterPaths: { "$.type": "article" }, selectPaths: ["$.title"] })\` \u2014 query with path-based filters and projections
+
+## Path Operations
+
+- \`sqlite_json_extract({ table, column, path: "$.title" })\` \u2014 extract value at path. Returns null if path doesn't exist
+- \`sqlite_json_set({ table, column, path: "$.views", value: 100, whereClause: "id = 1" })\` \u2014 set value at path (creates if missing)
+- \`sqlite_json_merge({ table, column, mergeData: { featured: true }, whereClause: "id = 1" })\` \u2014 merge object into existing JSON
+- \`sqlite_json_remove({ table, column, path, whereClause })\` \u2014 remove key at path
+- \`sqlite_json_validate_path({ path: "$.store.books[0].title" })\` \u2014 validate JSON path syntax without executing a query
+- \`sqlite_json_type({ table, column, path })\` \u2014 get JSON type (null, true, false, integer, real, text, array, object)
+
+## Array Operations
+
+\u26A0\uFE0F \`json_each\` multiplies output rows \u2014 use \`limit\` param for large arrays
+
+- \`sqlite_json_array_append({ table, column, path: "$.tags", value: "featured", whereClause: "id = 1" })\` \u2014 append to array
+- \`sqlite_json_array_length({ table, column, path })\` \u2014 get array length
+- \`sqlite_json_each({ table, column, path: "$.tags", limit: 50 })\` \u2014 expand array to rows
+
+## Aggregation & Analysis
+
+\`\`\`javascript
+// Regular tables: use column names directly
+sqlite_json_group_array({
+  table: "events",
+  valueColumn: "user_id",
+  groupByColumn: "event_type",
+});
+
+// JSON collections: use allowExpressions with json_extract for both columns
+// \u26A0\uFE0F allowExpressions is for column extraction ONLY, NOT aggregate functions
+// \u26A0\uFE0F Without groupByColumn, each row creates a key-value pair; duplicate keys if values aren't unique
+sqlite_json_group_array({
+  table: "docs",
+  valueColumn: "json_extract(data, '$.author')",
+  groupByColumn: "json_extract(data, '$.type')",
+  allowExpressions: true,
+});
+
+// For aggregate values (COUNT, SUM, AVG), use aggregateFunction parameter instead
+sqlite_json_group_object({
+  table: "events",
+  keyColumn: "event_type",
+  aggregateFunction: "COUNT(*)",
+});
+sqlite_json_group_object({
+  table: "orders",
+  keyColumn: "status",
+  aggregateFunction: "SUM(total)",
+});
+\`\`\`
+
+- \`sqlite_json_keys({ table, column, path? })\` \u2014 get distinct keys of JSON objects
+- \`sqlite_json_pretty({ table, column, whereClause? })\` \u2014 format JSON with indentation
+- \`sqlite_json_valid({ table, column })\` \u2014 check if values are valid JSON
+- \`sqlite_json_analyze_schema({ table, column })\` \u2014 infer schema types
+
+## Security
+
+- \`sqlite_json_security_scan({ table, column, sampleSize?, whereClause? })\` \u2014 scan JSON column for sensitive keys (password, token, ssn, etc.), SQL injection patterns, and XSS patterns. Returns \`riskLevel\` (low/medium/high) and issue details. Use larger \`sampleSize\` for thorough scans
+
+## JSONB Optimization (SQLite 3.45+)
+
+- \`sqlite_json_storage_info({ table, column })\` \u2014 check text vs JSONB format
+- \`sqlite_jsonb_convert({ table, column })\` \u2014 convert to JSONB for faster queries
+- \`sqlite_json_normalize_column({ table, column, outputFormat? })\` \u2014 normalize JSON (sort keys, compact). \u26A0\uFE0F Defaults to \`"preserve"\` (maintains original format); use \`outputFormat: "text"\` to force text output`
+  ],
+  [
+    "migration",
+    `# db-mcp Help \u2014 Migration Tracking (6 tools)
+
+\u26A0\uFE0F Must call \`sqlite_migration_init()\` before using any other migration tool \u2014 it creates the tracking table.
+
+\`\`\`javascript
+// Initialize tracking table (idempotent \u2014 safe to call multiple times)
+sqlite_migration_init();
+
+// Apply migration: executes SQL and records atomically. If SQL fails, no record is created
+// SHA-256 dedup \u2014 submitting the same SQL twice is rejected as a duplicate
+sqlite_migration_apply({
+  version: "2024-01-15-add-users",
+  description: "Create users table",
+  sql:
+    "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE)",
+  rollbackSql: "DROP TABLE users",
+  sourceSystem: "agent",
+  appliedBy: "claude",
+});
+
+// Record externally-applied migration (does NOT execute the SQL)
+sqlite_migration_record({
+  version: "2024-01-10-initial",
+  description: "Initial schema (pre-existing)",
+  sql: "CREATE TABLE orders (...)",
+  sourceSystem: "manual",
+});
+
+// Rollback by ID or version \u2014 requires rollbackSql to have been recorded
+sqlite_migration_rollback({ version: "2024-01-15-add-users" });
+sqlite_migration_rollback({ id: 3, dryRun: true }); // preview SQL without executing
+
+// Query history with filters and pagination
+sqlite_migration_history({ status: "applied", limit: 10 });
+sqlite_migration_history({ sourceSystem: "agent", compact: true }); // compact omits hash and source system
+
+// Summary: latest version, counts by status, unique source systems
+sqlite_migration_status();
+\`\`\`
+
+## \u26A0\uFE0F Gotchas
+
+- Rollback requires \`rollbackSql\` to have been provided when the migration was recorded/applied
+- Migration group is **opt-in** \u2014 not included in any shortcut except \`dev-schema\` and \`full\``
+  ],
+  [
+    "stats",
+    `# db-mcp Help \u2014 Statistical Analysis (16 core + 6 window)
+
+## Core Statistics (always available)
+
+\`\`\`javascript
+sqlite_stats_basic({ table: "employees", column: "salary" }); // count, sum, avg, min, max
+sqlite_stats_count({ table: "orders", column: "status", distinct: true }); // count rows, optionally distinct
+sqlite_stats_group_by({ table: "orders", column: "total", groupBy: "status" }); // aggregate by group
+sqlite_stats_percentile({
+  table: "sales",
+  column: "revenue",
+  percentiles: [25, 50, 75, 90],
+});
+sqlite_stats_histogram({ table: "products", column: "price", buckets: 10 });
+sqlite_stats_correlation({ table: "data", column1: "x", column2: "y" }); // Pearson coefficient
+sqlite_stats_distinct({ table: "orders", column: "status" }); // distinct values
+sqlite_stats_summary({
+  table: "data",
+  columns: ["price", "quantity", "discount"],
+}); // multi-column summary
+sqlite_stats_frequency({ table: "orders", column: "status" }); // frequency distribution
+sqlite_stats_regression({ table: "data", xColumn: "year", yColumn: "revenue" }); // linear
+sqlite_stats_regression({
+  table: "data",
+  xColumn: "year",
+  yColumn: "revenue",
+  degree: 2,
+}); // quadratic
+sqlite_stats_outliers({ table: "sales", column: "amount", method: "iqr" }); // or "zscore". Use maxOutliers to limit payload
+sqlite_stats_hypothesis({
+  table: "samples",
+  column: "value",
+  testType: "ttest_one",
+  expectedMean: 100,
+});
+\`\`\`
+
+\u26A0\uFE0F \`sqlite_stats_top_n\` \u2014 always use \`selectColumns\` to avoid returning all columns (large payloads with text fields):
+
+\`\`\`javascript
+sqlite_stats_top_n({
+  table: "products",
+  column: "price",
+  n: 10,
+  selectColumns: ["id", "name", "price"],
+});
+\`\`\`
+
+## Anomaly Detection (3 tools)
+
+\`\`\`javascript
+// Data distribution anomaly detection \u2014 z-score analysis on numeric columns
+sqlite_stats_detect_anomalies({ table: "sales", threshold: 2.0 }); // auto-detects numeric columns
+sqlite_stats_detect_anomalies({
+  table: "metrics",
+  columns: ["latency_ms", "error_rate"],
+  threshold: 3.0,
+  limit: 20,
+});
+
+// Fragmentation/bloat risk scoring \u2014 PRAGMA + dbstat analysis
+sqlite_stats_detect_bloat(); // riskiest tables (>0 score), default limit 50
+sqlite_stats_detect_bloat({ includeZeroRisk: true, limit: 10 }); // include zero risk, top 10
+
+// Schema health risk scoring \u2014 FK indexes, PKs, wide tables
+sqlite_stats_detect_schema_risks(); // riskiest tables (>0 score)
+sqlite_stats_detect_schema_risks({ excludeSystemTables: false }); // include SpatiaLite tables
+\`\`\`
+
+## Window Functions (6 tools, Native only)
+
+\`\`\`javascript
+sqlite_window_row_number({
+  table: "employees",
+  orderBy: "hire_date",
+  partitionBy: "department",
+});
+sqlite_window_rank({
+  table: "sales",
+  orderBy: "revenue DESC",
+  partitionBy: "region",
+  rankType: "dense_rank",
+});
+sqlite_window_lag_lead({
+  table: "sales",
+  orderBy: "date",
+  column: "revenue",
+  partitionBy: "region",
+}); // access previous/next row values
+sqlite_window_running_total({
+  table: "transactions",
+  column: "amount",
+  orderBy: "date",
+});
+sqlite_window_moving_avg({
+  table: "stock_prices",
+  column: "close_price",
+  orderBy: "date",
+  windowSize: 7,
+});
+sqlite_window_ntile({
+  table: "employees",
+  orderBy: "salary DESC",
+  buckets: 4,
+  partitionBy: "department",
+}); // quartiles
+\`\`\`
+
+\u26A0\uFE0F **Payload Sizes**: Window functions retrieve all standard columns by default (up to the \`limit\`). When querying wide tables, this can result in large payloads. It is highly recommended to pass \`selectColumns\` to reduce token usage:
+
+\`\`\`javascript
+sqlite_window_moving_avg({
+  table: "stock_prices",
+  column: "close_price",
+  orderBy: "date",
+  windowSize: 7,
+  selectColumns: ["date"]
+});
+\`\`\``
+  ],
+  [
+    "text",
+    `# db-mcp Help \u2014 Text Processing & FTS5
+
+## Full-Text Search / FTS5 (5 tools, Native only)
+
+\`\`\`javascript
+// Create FTS5 table with triggers for auto-sync on future changes
+// (Dropping this FTS table via sqlite_drop_table will automatically clean up these sync triggers)
+sqlite_fts_create({
+  tableName: "articles_fts",
+  sourceTable: "articles",
+  columns: ["title", "content"],
+});
+sqlite_fts_rebuild({ table: "articles_fts" }); // \u26A0\uFE0F Required: populate index with existing data
+
+// FTS5 uses AND by default: "machine learning" = rows containing BOTH words
+// Use OR explicitly: "machine OR learning" for rows containing EITHER word
+sqlite_fts_search({
+  table: "articles_fts",
+  query: "machine learning",
+  limit: 10,
+});
+sqlite_fts_match_info({ table: "articles_fts", query: "machine learning" }); // bm25 ranking info
+
+// Highlighted snippets from FTS5 search matches (headline/snippet)
+sqlite_fts_headline({ table: "articles_fts", query: "machine learning" });
+// \u2192 results with <b>machine</b> <b>learning</b> highlighted in context
+
+// Custom markers and snippet window
+sqlite_fts_headline({
+  table: "articles_fts",
+  query: "database",
+  startSel: "**",
+  stopSel: "**",
+  snippetWords: 5,
+});
+\`\`\`
+
+\u26A0\uFE0F FTS5 virtual tables (\`*_fts\`) and shadow tables (\`*_fts_*\`) are hidden from \`sqlite_list_tables\` for cleaner output
+
+## Text Processing (14 tools)
+
+\`\`\`javascript
+// Regex patterns: \u26A0\uFE0F Double-escape backslashes (\\\\) when passing through JSON/MCP
+sqlite_regex_match({
+  table: "logs",
+  column: "message",
+  pattern: "ERROR:\\\\\\\\s+(\\\\\\\\w+)",
+});
+sqlite_regex_extract({
+  table: "users",
+  column: "email",
+  pattern: "@([a-zA-Z0-9.-]+)",
+  groupIndex: 1,
+});
+
+// Text manipulation
+sqlite_text_split({ table: "users", column: "email", delimiter: "@" }); // split into parts array
+sqlite_text_concat({
+  table: "users",
+  columns: ["first_name", "last_name"],
+  separator: " ",
+});
+sqlite_text_replace({
+  table: "docs",
+  column: "content",
+  searchPattern: "old",
+  replaceWith: "new",
+});
+sqlite_text_trim({ table: "users", column: "name" }); // trim whitespace
+sqlite_text_case({ table: "products", column: "name", mode: "upper" }); // or "lower"
+sqlite_text_substring({ table: "codes", column: "value", start: 1, length: 3 }); // extract substring
+sqlite_text_normalize({
+  table: "docs",
+  column: "content",
+  mode: "strip_accents",
+}); // or nfc, nfd, nfkc, nfkd
+
+// Validation patterns: email, phone, url, uuid, ipv4, custom
+sqlite_text_validate({ table: "users", column: "email", pattern: "email" });
+sqlite_text_validate({
+  table: "data",
+  column: "field",
+  pattern: "custom",
+  customPattern: "^[A-Z]{2}[0-9]{4}$",
+});
+
+// Fuzzy matching \u2014 matches WORD TOKENS by default (not entire value)
+// "laptop" matches "Laptop Pro 15" (distance 0 on first token). Use tokenize: false for full-string matching.
+sqlite_fuzzy_match({
+  table: "products",
+  column: "name",
+  search: "laptop",
+  maxDistance: 2,
+});
+sqlite_fuzzy_match({
+  table: "products",
+  column: "name",
+  search: "laptob",
+  maxDistance: 2,
+  tokenize: false,
+}); // full value
+
+// Phonetic matching \u2014 finds words that sound alike (matches against any word in value)
+// Use includeRowData: false for lighter payloads when only matching values are needed
+sqlite_phonetic_match({
+  table: "products",
+  column: "name",
+  search: "laptop",
+  algorithm: "soundex",
+});
+sqlite_phonetic_match({
+  table: "products",
+  column: "name",
+  search: "laptop",
+  includeRowData: false,
+}); // lighter
+
+// Advanced search \u2014 combines exact, fuzzy, and phonetic techniques
+// fuzzyThreshold: 0.3-0.4 = loose matching (more results), 0.6-0.8 = strict matching (fewer results)
+sqlite_advanced_search({
+  table: "products",
+  column: "name",
+  searchTerm: "laptop",
+  techniques: ["exact", "fuzzy", "phonetic"],
+  fuzzyThreshold: 0.4,
+});
+
+// Sentiment analysis \u2014 pure text analysis, no database query needed
+sqlite_text_sentiment({ text: "This product is amazing and wonderful!" });
+// \u2192 { sentiment: "very_positive", score: 2, confidence: "medium" }
+
+sqlite_text_sentiment({ text: "Great service but slow delivery", returnWords: true });
+// \u2192 { sentiment: "neutral", score: 0, matchedPositive: ["great"], matchedNegative: ["slow"] }
+\`\`\``
+  ],
+  [
+    "transactions",
+    `# db-mcp Help \u2014 Transactions (8 tools, Native only)
+
+## Atomic Execution (preferred for simple cases)
+
+\`\`\`javascript
+sqlite_transaction_execute({
+  statements: ["UPDATE a SET x=1", "UPDATE b SET y=2"],
+});
+\`\`\`
+
+## Manual Transaction Control
+
+\`\`\`javascript
+sqlite_transaction_begin({ mode: "immediate" }); // or "deferred", "exclusive"
+sqlite_transaction_savepoint({ name: "checkpoint" });
+sqlite_transaction_rollback_to({ name: "checkpoint" });
+sqlite_transaction_release({ name: "checkpoint" });
+sqlite_transaction_commit();
+sqlite_transaction_rollback();
+\`\`\`
+
+## Transaction State (read-only)
+
+\`\`\`javascript
+sqlite_transaction_status(); // \u2192 { status: "active" | "none", active: true/false }
+\`\`\`
+
+## \u26A0\uFE0F Gotchas
+
+- Transaction tools are **Native only** \u2014 WASM adapter does not support transactions
+- Use \`sqlite_transaction_execute\` for simple multi-statement operations; manual \`begin\`/\`commit\` for complex flows with savepoints
+- \`sqlite_transaction_status\` is read-only and requires only \`read\` scope; all other transaction tools require \`write\` scope`
+  ],
+  [
+    "vector",
+    `# db-mcp Help \u2014 Vector/Semantic Search (11 tools)
+
+\`\`\`javascript
+// Create vector table with metadata columns
+sqlite_vector_create_table({ tableName: "docs", dimensions: 384, additionalColumns: [{ name: "content", type: "TEXT" }] });
+
+// Store vectors (single and batch)
+sqlite_vector_store({ table: "docs", idColumn: "id", vectorColumn: "emb", id: 1, vector: [...] });
+sqlite_vector_batch_store({ table: "docs", idColumn: "id", vectorColumn: "emb", items: [{ id: 1, vector: [...] }, { id: 2, vector: [...] }] });
+
+// Search vectors (returnColumns omits vector data from results for smaller payloads)
+sqlite_vector_search({ table: "docs", vectorColumn: "emb", queryVector: [...], limit: 10, returnColumns: ["id", "title"] }); // returns { results: [...] } instead of rows
+
+// Retrieve and delete vectors
+// Note: sqlite_vector_get returns parsed 'vector' array + additional columns in a 'metadata' object for flexibility
+sqlite_vector_get({ table: "docs", idColumn: "id", vectorColumn: "emb", id: 1 });
+sqlite_vector_delete({ table: "docs", idColumn: "id", ids: [1, 2, 3] });
+
+// Vector metadata
+sqlite_vector_count({ table: "docs" }); // or with dimensions filter: { table: "docs", dimensions: 384 }
+sqlite_vector_dimensions({ table: "docs", vectorColumn: "emb" });
+sqlite_vector_stats({ table: "docs", vectorColumn: "emb" }); // returns sampleSize, magnitudeStats (min/max/avg)
+
+// Utility tools for preprocessing
+sqlite_vector_normalize({ vector: [3, 4, 0, 0] }); // returns unit vector [0.6, 0.8, 0, 0]
+sqlite_vector_distance({ vector1: [...], vector2: [...], metric: "cosine" }); // returns { value: <number> }
+\`\`\``
+  ]
+]);
+var BUFFER_HIGH_WATER = 50;
+var FLUSH_INTERVAL_MS = 100;
+var DEFAULT_RECENT_COUNT = 50;
+var STDERR_SENTINEL = "stderr";
+var TAIL_READ_BYTES = 65536;
+var AuditLogger = class {
+  config;
+  buffer = [];
+  flushTimer = null;
+  activeFlush = null;
+  closed = false;
+  dirEnsured = false;
+  stderrMode;
+  constructor(config) {
+    this.config = config;
+    this.stderrMode = config.logPath.toLowerCase() === STDERR_SENTINEL;
+    if (config.enabled) {
+      this.flushTimer = setInterval(() => {
+        void this.flush();
+      }, FLUSH_INTERVAL_MS);
+      this.flushTimer.unref();
+    }
+  }
+  /**
+   * Eagerly create the log directory and touch the log file on startup.
+   * Provides immediate confirmation that audit is configured correctly.
+   * Non-throwing — falls back silently if the path is inaccessible.
+   */
+  async init() {
+    if (this.stderrMode || !this.config.enabled) return;
+    try {
+      await this.ensureDirectory();
+      const fh = await open(this.config.logPath, "a");
+      await fh.close();
+    } catch {
+      process.stderr.write(
+        `[AUDIT] Failed to initialise log file: ${this.config.logPath}
+`
+      );
+    }
+  }
+  /**
+   * Append an audit entry to the buffer.
+   * Non-blocking — the entry is serialised and queued; the
+   * actual file write happens on the next flush cycle.
+   */
+  log(entry) {
+    if (this.closed || !this.config.enabled) return;
+    this.buffer.push(JSON.stringify(entry));
+    if (this.buffer.length >= BUFFER_HIGH_WATER) {
+      void this.flush();
+    }
+  }
+  /**
+   * Flush the buffer to disk.
+   * Safe to call concurrently — serialises via `this.activeFlush` Promise.
+   */
+  async flush() {
+    if (this.activeFlush) {
+      await this.activeFlush;
+      if (this.buffer.length === 0) return;
+    }
+    if (this.buffer.length === 0) return;
+    const doFlush = async () => {
+      await this.rotateIfNeeded();
+      const lines = this.buffer;
+      this.buffer = [];
+      try {
+        if (this.stderrMode) {
+          process.stderr.write(lines.join("\n") + "\n");
+        } else {
+          await this.ensureDirectory();
+          await appendFile(
+            this.config.logPath,
+            lines.join("\n") + "\n",
+            "utf-8"
+          );
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[AUDIT] Write failed: ${message}
+`);
+        this.buffer.unshift(...lines);
+      }
+    };
+    this.activeFlush = doFlush();
+    try {
+      await this.activeFlush;
+    } finally {
+      this.activeFlush = null;
+    }
+  }
+  /**
+   * Gracefully close the logger — flush remaining entries and stop the timer.
+   */
+  async close() {
+    this.closed = true;
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    await this.flush();
+  }
+  /**
+   * Read the most recent audit entries from the log file.
+   * Uses a streaming tail-read: only the last TAIL_READ_BYTES (64 KB) are
+   * read from disk, preventing O(n) memory spikes for large audit logs.
+   * Used by the `sqlite://audit` resource.
+   *
+   * @param count Maximum number of entries to return (default 50)
+   */
+  async recent(count = DEFAULT_RECENT_COUNT) {
+    if (this.stderrMode) return [];
+    await this.flush();
+    try {
+      let fh;
+      try {
+        fh = await open(this.config.logPath, "r");
+      } catch {
+        return [];
+      }
+      try {
+        const info = await stat(this.config.logPath);
+        const fileSize = info.size;
+        if (fileSize === 0) return [];
+        const readSize = Math.min(fileSize, TAIL_READ_BYTES);
+        const startOffset = fileSize - readSize;
+        const buf = Buffer.alloc(readSize);
+        await fh.read(buf, 0, readSize, startOffset);
+        const chunk = buf.toString("utf-8");
+        const rawLines = chunk.split("\n").filter(Boolean);
+        const lines = startOffset > 0 ? rawLines.slice(1) : rawLines;
+        const tail = lines.slice(-count);
+        return tail.reduce((acc, line) => {
+          try {
+            acc.push(JSON.parse(line));
+          } catch {
+          }
+          return acc;
+        }, []);
+      } finally {
+        await fh.close();
+      }
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Ensure the parent directory of the log file exists.
+   */
+  async ensureDirectory() {
+    if (this.dirEnsured) return;
+    try {
+      await mkdir(dirname(this.config.logPath), { recursive: true });
+      this.dirEnsured = true;
+    } catch {
+      this.dirEnsured = true;
+    }
+  }
+  /**
+   * Rotate the log file if it exceeds the configured size limit.
+   * Keeps up to 5 rotated files (`.1` through `.5`); older data is discarded.
+   * Rotation failure is non-fatal — audit must not block tool execution.
+   */
+  async rotateIfNeeded() {
+    if (this.stderrMode || !this.config.maxSizeBytes) return;
+    try {
+      const info = await stat(this.config.logPath).catch(() => null);
+      if (!info || info.size < this.config.maxSizeBytes) return;
+      for (let i = 4; i >= 1; i--) {
+        const oldFile = `${this.config.logPath}.${String(i)}`;
+        const newFile = `${this.config.logPath}.${String(i + 1)}`;
+        await rename(oldFile, newFile).catch(() => null);
+      }
+      const rotatedPath = `${this.config.logPath}.1`;
+      await rename(this.config.logPath, rotatedPath);
+    } catch {
+    }
+  }
+};
+var gzipAsync = promisify(gzip);
+var SNAPSHOT_TOOL_ARGS = {
+  sqlite_drop_table: { targetKey: "table" },
+  sqlite_drop_index: { targetKey: "index" },
+  sqlite_drop_view: { targetKey: "view" },
+  sqlite_import_csv: { targetKey: "table" },
+  sqlite_backup: { targetKey: "path" }
+};
+var SNAPSHOT_EXT = ".snapshot.json.gz";
+var SNAPSHOT_EXT_LEGACY = ".snapshot.json";
+var MAX_SAMPLE_ROWS = 100;
+var DEFAULT_MAX_DATA_SIZE_BYTES = 50 * 1024 * 1024;
+var BackupManager = class {
+  config;
+  snapshotDir;
+  dirEnsured = false;
+  pendingWrites = /* @__PURE__ */ new Set();
+  constructor(config, auditLogPath) {
+    this.config = config;
+    const logDir = dirname(auditLogPath);
+    this.snapshotDir = join(logDir, "snapshots");
+  }
+  /**
+   * Check if a tool should receive a pre-mutation snapshot.
+   */
+  shouldSnapshot(toolName) {
+    return this.config.enabled && toolName in SNAPSHOT_TOOL_ARGS;
+  }
+  /**
+   * Create a pre-mutation snapshot of the target object.
+   *
+   * @returns Relative path to the snapshot file, or undefined if skipped/failed
+   */
+  async createSnapshot(toolName, args, requestId, adapter, logAs) {
+    if (!this.shouldSnapshot(toolName)) return void 0;
+    try {
+      const mapping = SNAPSHOT_TOOL_ARGS[toolName];
+      if (!mapping) return void 0;
+      const rawTarget = args[mapping.targetKey];
+      const target = typeof rawTarget === "string" ? rawTarget : "unknown";
+      return await this.captureObjectSnapshot(
+        logAs ?? toolName,
+        target,
+        requestId,
+        adapter
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(
+        `[AUDIT-BACKUP] Snapshot failed for ${toolName}: ${message}
+`
+      );
+      return void 0;
+    }
+  }
+  /**
+   * List available snapshots with metadata.
+   */
+  async listSnapshots() {
+    try {
+      await this.ensureDirectory();
+      const files = await readdir(this.snapshotDir);
+      const snapshots = [];
+      for (const file of files) {
+        if (!file.endsWith(SNAPSHOT_EXT) && !file.endsWith(SNAPSHOT_EXT_LEGACY))
+          continue;
+        try {
+          const parsed = await this.readSnapshotFile(file);
+          if (parsed) {
+            snapshots.push({ ...parsed.metadata, filename: file });
+          }
+        } catch {
+        }
+      }
+      snapshots.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+      return snapshots;
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Read a specific snapshot by filename.
+   */
+  async getSnapshot(filename) {
+    try {
+      const safe = basename(filename);
+      return await this.readSnapshotFile(safe);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Apply retention policy — delete oldest snapshots that exceed limits.
+   */
+  async cleanup() {
+    if (!this.config.enabled) return 0;
+    try {
+      const files = await readdir(this.snapshotDir);
+      const snapshotFiles = files.filter(
+        (f) => f.endsWith(SNAPSHOT_EXT) || f.endsWith(SNAPSHOT_EXT_LEGACY)
+      );
+      if (snapshotFiles.length === 0) return 0;
+      const fileInfos = [];
+      for (const file of snapshotFiles) {
+        const filePath = join(this.snapshotDir, file);
+        try {
+          const stats = await stat(filePath);
+          fileInfos.push({ name: file, mtime: stats.mtime, path: filePath });
+        } catch {
+        }
+      }
+      fileInfos.sort((a, b) => a.mtime.getTime() - b.mtime.getTime());
+      let deleted = 0;
+      const now = Date.now();
+      const maxAgeMs = this.config.maxAgeDays * 24 * 60 * 60 * 1e3;
+      for (const info of fileInfos) {
+        const age = now - info.mtime.getTime();
+        const overAge = age > maxAgeMs;
+        const overCount = fileInfos.length - deleted > this.config.maxCount;
+        if (overAge || overCount) {
+          try {
+            await unlink(info.path);
+            deleted++;
+          } catch {
+          }
+        }
+      }
+      if (deleted > 0) {
+        process.stderr.write(
+          `[AUDIT-BACKUP] Cleaned up ${String(deleted)} snapshot(s)
+`
+        );
+      }
+      return deleted;
+    } catch {
+      return 0;
+    }
+  }
+  /**
+   * Flush all pending async snapshot writes.
+   * Call during graceful shutdown to ensure all snapshots are persisted.
+   */
+  async flush() {
+    if (this.pendingWrites.size > 0) {
+      await Promise.allSettled(this.pendingWrites);
+    }
+  }
+  async getStats() {
+    try {
+      const files = await readdir(this.snapshotDir);
+      const snapshotFiles = files.filter(
+        (f) => f.endsWith(SNAPSHOT_EXT) || f.endsWith(SNAPSHOT_EXT_LEGACY)
+      );
+      let totalSize = 0;
+      let oldestMtime;
+      for (const file of snapshotFiles) {
+        try {
+          const stats = await stat(join(this.snapshotDir, file));
+          totalSize += stats.size;
+          if (!oldestMtime || stats.mtime < oldestMtime) {
+            oldestMtime = stats.mtime;
+          }
+        } catch {
+        }
+      }
+      return {
+        count: snapshotFiles.length,
+        ...oldestMtime && { oldestAge: oldestMtime.toISOString() },
+        totalSizeKB: Math.round(totalSize / 1024)
+      };
+    } catch {
+      return { count: 0, totalSizeKB: 0 };
+    }
+  }
+  // =========================================================================
+  // Private snapshot capture methods
+  // =========================================================================
+  async captureObjectSnapshot(toolName, target, requestId, adapter) {
+    const ddl = await this.buildDdl(target, adapter);
+    const { rowCount } = await this.captureVolumeMetadata(target, adapter);
+    const { data, dataSkipped, dataSkippedReason } = await this.captureTableData(target, adapter);
+    return this.writeSnapshot(toolName, target, requestId, ddl, data, {
+      ...rowCount !== void 0 && { rowCount },
+      ...dataSkipped && { dataSkipped },
+      ...dataSkippedReason !== void 0 && { dataSkippedReason }
+    });
+  }
+  /**
+   * Build a DDL string from sqlite_master for the given object.
+   * Works for tables, views, indexes, and triggers.
+   */
+  async buildDdl(objectName, adapter) {
+    try {
+      const result = await adapter.executeQuery(
+        "SELECT sql FROM sqlite_master WHERE name = ?",
+        [objectName]
+      );
+      if (result.rows && result.rows.length > 0) {
+        const row = result.rows[0];
+        if (row?.["sql"] != null) {
+          const val = row["sql"];
+          return typeof val === "string" ? val : "";
+        }
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(
+        `[AUDIT-BACKUP] DDL capture failed for ${objectName}: ${msg}
+`
+      );
+    }
+    return `-- Object "${objectName}" does not exist or cannot be described`;
+  }
+  /**
+   * Capture row count using COUNT(*).
+   * Near-zero cost for small tables; failures are silently ignored (best-effort).
+   */
+  async captureVolumeMetadata(tableName, adapter) {
+    try {
+      const typeResult = await adapter.executeQuery(
+        "SELECT type FROM sqlite_master WHERE name = ?",
+        [tableName]
+      );
+      const objType = typeResult.rows?.[0]?.["type"];
+      if (objType !== "table") return {};
+      const countResult = await adapter.executeQuery(
+        `SELECT COUNT(*) as row_count FROM "${tableName}"`
+      );
+      const rawCount = countResult.rows?.[0]?.["row_count"];
+      if (typeof rawCount === "number") {
+        return { rowCount: rawCount };
+      }
+    } catch {
+    }
+    return {};
+  }
+  /**
+   * Capture row data as INSERT statements, subject to config limits.
+   * Returns empty output when `includeData` is disabled.
+   */
+  async captureTableData(tableName, adapter) {
+    if (!this.config.includeData) {
+      return { dataSkipped: false };
+    }
+    const maxDataSize = this.config.maxDataSizeBytes || DEFAULT_MAX_DATA_SIZE_BYTES;
+    try {
+      const typeResult = await adapter.executeQuery(
+        "SELECT type FROM sqlite_master WHERE name = ?",
+        [tableName]
+      );
+      const objType = typeResult.rows?.[0]?.["type"];
+      if (objType !== "table") return { dataSkipped: false };
+    } catch {
+      return { dataSkipped: false };
+    }
+    try {
+      const pageResult = await adapter.executeQuery(
+        "SELECT (SELECT page_count FROM pragma_page_count()) * (SELECT page_size FROM pragma_page_size()) as total_size"
+      );
+      const rawSize = pageResult.rows?.[0]?.["total_size"];
+      const totalSizeBytes = typeof rawSize === "number" ? rawSize : 0;
+      if (totalSizeBytes > maxDataSize) {
+        const sizeMB = Math.round(totalSizeBytes / (1024 * 1024));
+        const thresholdMB = Math.round(maxDataSize / (1024 * 1024));
+        return {
+          dataSkipped: true,
+          dataSkippedReason: `Database size ~${String(sizeMB)}MB exceeds ${String(thresholdMB)}MB threshold`
+        };
+      }
+    } catch {
+    }
+    try {
+      const result = await adapter.executeQuery(
+        `SELECT * FROM "${tableName}" LIMIT ${String(MAX_SAMPLE_ROWS)}`
+      );
+      if (result.rows && result.rows.length > 0) {
+        const firstRow = result.rows[0];
+        if (firstRow) {
+          const cols = Object.keys(firstRow).map((c) => `"${c}"`).join(", ");
+          const data = result.rows.map((row) => {
+            const vals = Object.values(row).map((v) => {
+              if (v === null) return "NULL";
+              if (typeof v === "string")
+                return `'${v.replace(/'/g, "''")}'`;
+              if (typeof v === "number" || typeof v === "boolean")
+                return String(v);
+              return `'${JSON.stringify(v).replace(/'/g, "''")}'`;
+            }).join(", ");
+            return `INSERT INTO "${tableName}" (${cols}) VALUES (${vals});`;
+          }).join("\n");
+          return { data, dataSkipped: false };
+        }
+      }
+    } catch {
+    }
+    return { dataSkipped: false };
+  }
+  async writeSnapshot(tool, target, requestId, ddl, data, volumeMeta) {
+    await this.ensureDirectory();
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const safeTarget = target.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const safeTool = tool.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const filename = `${timestamp.replace(/[:.]/g, "-")}_${safeTool}_${safeTarget}${SNAPSHOT_EXT}`;
+    const content = {
+      metadata: {
+        timestamp,
+        tool,
+        target,
+        type: data ? "ddl+data" : "ddl",
+        requestId,
+        sizeBytes: 0,
+        // Updated after serialization
+        ...volumeMeta?.rowCount !== void 0 && {
+          rowCount: volumeMeta.rowCount
+        },
+        ...volumeMeta?.dataSkipped && { dataSkipped: true },
+        ...volumeMeta?.dataSkippedReason && {
+          dataSkippedReason: volumeMeta.dataSkippedReason
+        }
+      },
+      ddl,
+      data
+    };
+    const json = JSON.stringify(content, null, 2);
+    const sizeBytes = Buffer.byteLength(json, "utf-8");
+    const finalJson = json.replace(
+      '"sizeBytes": 0',
+      `"sizeBytes": ${String(sizeBytes)}`
+    );
+    const compressed = await gzipAsync(Buffer.from(finalJson, "utf-8"));
+    const filePath = join(this.snapshotDir, filename);
+    const writePromise = mkdtemp(`${this.snapshotDir}${sep}.tmp-`).then(async (tempDir) => {
+      const tmpPath = join(tempDir, filename);
+      await writeFile(tmpPath, compressed, { flag: "wx" });
+      await rename(tmpPath, filePath);
+      await rmdir(tempDir).catch(() => null);
+    }).catch((err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(
+        `[AUDIT-BACKUP] Async write failed for ${filename}: ${msg}
+`
+      );
+    });
+    this.pendingWrites.add(writePromise);
+    void writePromise.finally(() => {
+      this.pendingWrites.delete(writePromise);
+    });
+    return filename;
+  }
+  /**
+   * Read and decompress a snapshot file (supports both gzip and legacy JSON).
+   */
+  async readSnapshotFile(filename) {
+    const filePath = join(this.snapshotDir, filename);
+    const raw = await readFile(filePath);
+    if (raw[0] === 31 && raw[1] === 139) {
+      const decompressed = gunzipSync(raw);
+      return JSON.parse(decompressed.toString("utf-8"));
+    }
+    return JSON.parse(raw.toString("utf-8"));
+  }
+  async ensureDirectory() {
+    if (this.dirEnsured) return;
+    try {
+      await mkdir(this.snapshotDir, { recursive: true });
+      this.dirEnsured = true;
+    } catch {
+      this.dirEnsured = true;
+    }
+  }
+};
+
+// src/auth/scope-map.ts
+var toolScopeMap = /* @__PURE__ */ new Map();
+for (const [group, tools] of Object.entries(TOOL_GROUPS)) {
+  const scope = TOOL_GROUP_SCOPES[group];
+  if (scope) {
+    for (const toolName of tools) {
+      toolScopeMap.set(toolName, scope);
+      toolScopeMap.set(`sqlite_${toolName}`, scope);
+    }
+  }
+}
+function getRequiredScope(toolName) {
+  return toolScopeMap.get(toolName) ?? SCOPES.READ;
+}
+
+// src/audit/interceptor.ts
+var ALWAYS_AUDITED_SCOPES = /* @__PURE__ */ new Set(["write", "admin"]);
+function scopeToCategory(scope) {
+  if (scope === "admin") return "admin";
+  if (scope === "read") return "read";
+  return "write";
+}
+function createAuditInterceptor(auditLogger, backupManager, queryAdapter) {
+  const auditReads = auditLogger.config.auditReads;
+  return {
+    async around(toolName, args, requestId, fn, options) {
+      const scope = getRequiredScope(toolName);
+      if (!ALWAYS_AUDITED_SCOPES.has(scope) && !auditReads) {
+        return fn();
+      }
+      const isReadScope = scope === "read";
+      const authCtx = getAuthContext();
+      const start = performance.now();
+      let success = true;
+      let error;
+      let backupRef;
+      let tokenEstimate;
+      try {
+        const result = await fn();
+        if (typeof result === "object" && result !== null) {
+          try {
+            const json = JSON.stringify({
+              ...result,
+              _meta: { tokenEstimate: 0 }
+            });
+            tokenEstimate = Math.ceil(Buffer.byteLength(json, "utf8") / 4);
+          } catch {
+          }
+        } else if (typeof result === "string") {
+          tokenEstimate = Math.ceil(Buffer.byteLength(result, "utf8") / 4);
+        }
+        return result;
+      } catch (err) {
+        success = false;
+        error = err instanceof Error ? err.message : String(err);
+        const errorResult = {
+          success: false,
+          error,
+          code: "INTERNAL_ERROR",
+          category: "internal",
+          recoverable: false
+        };
+        const enriched = JSON.stringify({
+          ...errorResult,
+          _meta: { tokenEstimate: 0 }
+        });
+        tokenEstimate = Math.ceil(Buffer.byteLength(enriched, "utf8") / 4);
+        throw err;
+      } finally {
+        const durationMs = Math.round(performance.now() - start);
+        if (isReadScope) {
+          auditLogger.log({
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            requestId,
+            tool: options?.logAs ?? toolName,
+            category: "read",
+            scope,
+            durationMs,
+            success,
+            error,
+            tokenEstimate
+          });
+        } else {
+          auditLogger.log({
+            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            requestId,
+            tool: options?.logAs ?? toolName,
+            category: scopeToCategory(scope),
+            scope,
+            user: authCtx?.claims?.sub ?? null,
+            scopes: authCtx?.scopes ?? [],
+            durationMs,
+            success,
+            error,
+            args: auditLogger.config.redact ? void 0 : args,
+            backup: backupRef,
+            tokenEstimate
+          });
+        }
+      }
+    }
+  };
+}
+var DbMcpServer = class {
+  server;
+  adapters = /* @__PURE__ */ new Map();
+  toolFilter;
+  config;
+  auditLogger = null;
+  backupManager = null;
+  auditInterceptor = null;
+  auditInitPromise = null;
+  constructor(config) {
+    this.config = config;
+    this.toolFilter = config.toolFilter ? parseToolFilter(config.toolFilter) : getToolFilterFromEnv();
+    this.server = new McpServer(
+      {
+        name: config.name,
+        version: config.version
+      },
+      {
+        capabilities: {
+          logging: {}
+        },
+        instructions: INSTRUCTIONS
+      }
+    );
+    logger.info(getFilterSummary(this.toolFilter), { module: "FILTER" });
+    logger.info("MCP Server initialized", {
+      module: "SERVER",
+      name: config.name,
+      version: config.version,
+      toolFilter: config.toolFilter ?? "none",
+      capabilities: ["logging"]
+    });
+    this.registerBuiltInTools();
+    this.registerHelpResources();
+    if (config.audit?.enabled) {
+      this.auditInitPromise = this.initializeAudit(config);
+    }
+  }
+  /**
+   * Register a database adapter
+   */
+  async registerAdapter(adapter, config) {
+    const adapterId = `${adapter.type}:${config.connectionString ?? "default"}`;
+    if (this.auditInitPromise) {
+      await this.auditInitPromise;
+    }
+    await adapter.connect(config);
+    this.adapters.set(adapterId, adapter);
+    if (this.auditInterceptor && "setAuditInterceptor" in adapter) {
+      adapter.setAuditInterceptor(this.auditInterceptor);
+    }
+    if (this.backupManager && "setBackupManager" in adapter) {
+      adapter.setBackupManager(this.backupManager);
+    }
+    adapter.registerTools(this.server, this.toolFilter);
+    adapter.registerResources(this.server);
+    adapter.registerPrompts(this.server);
+    logger.info(`Registered adapter: ${adapter.name} (${adapterId})`, {
+      module: "SERVER"
+    });
+  }
+  /**
+   * Get an adapter by ID
+   */
+  getAdapter(adapterId) {
+    return this.adapters.get(adapterId);
+  }
+  /**
+   * Get all registered adapters
+   */
+  getAdapters() {
+    return this.adapters;
+  }
+  /**
+   * Register built-in server tools (health, info, etc.)
+   */
+  registerBuiltInTools() {
+    const serverInfoOpts = {
+      title: "Server Info",
+      description: "Get information about the db-mcp server and registered adapters",
+      icons: SERVER_ICONS,
+      annotations: READ_ONLY
+    };
+    this.server.registerTool("server_info", serverInfoOpts, () => {
+      const adapterInfo = [];
+      for (const [id, adapter] of this.adapters) {
+        adapterInfo.push({
+          id,
+          ...adapter.getInfo()
+        });
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                name: this.config.name,
+                version: this.config.version,
+                transport: this.config.transport,
+                adapters: adapterInfo,
+                toolFilter: {
+                  raw: this.toolFilter.raw,
+                  enabledGroups: [...this.toolFilter.enabledGroups]
+                }
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    });
+    const healthOpts = {
+      title: "Server Health",
+      description: "Check health status of all database connections",
+      icons: SERVER_ICONS,
+      annotations: READ_ONLY
+    };
+    this.server.registerTool("server_health", healthOpts, async () => {
+      const health = {
+        server: "healthy",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        adapters: {}
+      };
+      for (const [id, adapter] of this.adapters) {
+        try {
+          const adapterHealth = await adapter.getHealth();
+          health["adapters"][id] = adapterHealth;
+        } catch (error) {
+          health["adapters"][id] = {
+            connected: false,
+            error: error instanceof Error ? error.message : "Unknown error"
+          };
+        }
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(health, null, 2)
+          }
+        ]
+      };
+    });
+    const listAdaptersOpts = {
+      title: "List Adapters",
+      description: "List all registered database adapters",
+      icons: SERVER_ICONS,
+      annotations: READ_ONLY
+    };
+    this.server.registerTool("list_adapters", listAdaptersOpts, () => {
+      const adapters = [];
+      for (const [id, adapter] of this.adapters) {
+        adapters.push({
+          id,
+          type: adapter.type,
+          name: adapter.name,
+          version: adapter.version,
+          connected: adapter.isConnected()
+        });
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(adapters, null, 2)
+          }
+        ]
+      };
+    });
+  }
+  /**
+   * Register sqlite://help resources for on-demand reference documentation.
+   * Always registers sqlite://help (gotchas). Group-specific help is filtered
+   * by the tool filter configuration.
+   */
+  registerHelpResources() {
+    const gotchasContent = HELP_CONTENT.get("gotchas");
+    if (gotchasContent) {
+      this.server.registerResource(
+        "sqlite_help",
+        "sqlite://help",
+        {
+          description: "Critical gotchas, WASM vs Native comparison, and Code Mode API reference",
+          mimeType: "text/markdown"
+        },
+        () => ({
+          contents: [
+            {
+              uri: "sqlite://help",
+              mimeType: "text/markdown",
+              text: gotchasContent
+            }
+          ]
+        })
+      );
+    }
+    const groupHelpKeys = [
+      { group: "core", key: "core" },
+      { group: "json", key: "json" },
+      { group: "text", key: "text" },
+      { group: "stats", key: "stats" },
+      { group: "vector", key: "vector" },
+      { group: "geo", key: "geo" },
+      { group: "admin", key: "admin" },
+      { group: "transactions", key: "transactions" },
+      { group: "introspection", key: "introspection" },
+      { group: "migration", key: "migration" }
+    ];
+    for (const { group, key } of groupHelpKeys) {
+      const isCodemodeOnly = this.toolFilter.enabledGroups.size === 1 && this.toolFilter.enabledGroups.has("codemode");
+      if (!this.toolFilter.enabledGroups.has(group) && !isCodemodeOnly) {
+        continue;
+      }
+      const content = HELP_CONTENT.get(key);
+      if (!content) continue;
+      this.server.registerResource(
+        `sqlite_help_${key}`,
+        `sqlite://help/${key}`,
+        {
+          description: `Tool reference for the ${group} tool group`,
+          mimeType: "text/markdown"
+        },
+        () => ({
+          contents: [
+            {
+              uri: `sqlite://help/${key}`,
+              mimeType: "text/markdown",
+              text: content
+            }
+          ]
+        })
+      );
+    }
+    const registeredHelp = ["sqlite://help"];
+    for (const { group, key } of groupHelpKeys) {
+      if (this.toolFilter.enabledGroups.has(group)) {
+        registeredHelp.push(`sqlite://help/${key}`);
+      }
+    }
+    logger.info(`Help resources: ${registeredHelp.join(", ")}`, {
+      module: "SERVER"
+    });
+  }
+  /**
+   * Start the server with the configured transport
+   */
+  async start() {
+    switch (this.config.transport) {
+      case "stdio":
+        await this.startStdio();
+        break;
+      case "http":
+        await this.startHttp();
+        break;
+      default:
+        throw new DbMcpError(
+          `Unsupported transport: ${this.config.transport}`,
+          "SERVER_START_FAILED",
+          "config" /* CONFIGURATION */
+        );
+    }
+  }
+  /**
+   * Start server with stdio transport
+   */
+  async startStdio() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    logger.info(`db-mcp server started (stdio transport)`, {
+      module: "SERVER"
+    });
+  }
+  /**
+   * Start server with HTTP transport (Streamable HTTP with SSE support)
+   */
+  async startHttp() {
+    const { HttpTransport } = await import('./http-6KF4ULDI.js');
+    const oauthConfig = {
+      enabled: this.config.oauth?.enabled ?? false,
+      authorizationServerUrl: this.config.oauth?.authorizationServerUrl ?? "",
+      audience: this.config.oauth?.audience ?? this.config.name
+    };
+    if (this.config.oauth?.issuer !== void 0) {
+      oauthConfig.issuer = this.config.oauth.issuer;
+    }
+    if (this.config.oauth?.jwksUri !== void 0) {
+      oauthConfig.jwksUri = this.config.oauth.jwksUri;
+    }
+    if (this.config.oauth?.clockTolerance !== void 0) {
+      oauthConfig.clockTolerance = this.config.oauth.clockTolerance;
+    }
+    if (this.config.oauth?.publicPaths !== void 0) {
+      oauthConfig.publicPaths = this.config.oauth.publicPaths;
+    }
+    const transport = new HttpTransport({
+      port: this.config.port ?? 3e3,
+      ...this.config.host !== void 0 && { host: this.config.host },
+      ...this.config.authToken !== void 0 && {
+        authToken: this.config.authToken
+      },
+      ...this.config.enableHSTS !== void 0 && {
+        enableHSTS: this.config.enableHSTS
+      },
+      oauth: oauthConfig,
+      stateless: this.config.statelessHttp ?? false
+    });
+    await transport.initialize(this.server);
+    await transport.start();
+    const mode = this.config.statelessHttp ? "stateless" : "stateful";
+    const host = this.config.host ?? "0.0.0.0";
+    const port = String(this.config.port ?? 3e3);
+    logger.info(
+      `db-mcp server started (HTTP transport on ${host}:${port}, ${mode} mode)`,
+      { module: "TRANSPORT", mode }
+    );
+  }
+  /**
+   * Gracefully shut down the server
+   */
+  async shutdown() {
+    logger.info("Shutting down db-mcp server...", { module: "SERVER" });
+    for (const [id, adapter] of this.adapters) {
+      try {
+        await adapter.disconnect();
+        logger.info(`Disconnected adapter: ${id}`, { module: "SERVER" });
+      } catch (error) {
+        logger.error(`Error disconnecting adapter ${id}`, {
+          module: "SERVER",
+          error: error instanceof Error ? error : void 0
+        });
+      }
+    }
+    if (this.auditLogger) {
+      await this.auditLogger.close();
+      logger.info("Audit logger closed", { module: "AUDIT" });
+    }
+    if (this.backupManager) {
+      await this.backupManager.flush();
+      logger.info("Backup manager flushed", { module: "AUDIT" });
+    }
+    await this.server.close();
+    logger.info("Server shutdown complete", { module: "SERVER" });
+  }
+  /**
+   * Initialize the audit subsystem: logger, interceptor, backup manager,
+   * sqlite://audit resource, and audit backup tools.
+   */
+  async initializeAudit(config) {
+    const auditConfig = config.audit;
+    if (!auditConfig?.enabled) return;
+    this.auditLogger = new AuditLogger(auditConfig);
+    await this.auditLogger.init();
+    if (auditConfig.backup?.enabled) {
+      this.backupManager = new BackupManager(
+        auditConfig.backup,
+        auditConfig.logPath
+      );
+    }
+    this.auditInterceptor = createAuditInterceptor(
+      this.auditLogger,
+      this.backupManager ?? void 0);
+    this.registerAuditResource();
+    if (this.backupManager && this.toolFilter.enabledGroups.has("admin")) {
+      this.registerAuditBackupTools();
+    }
+    logger.info(
+      `Audit logging enabled (${auditConfig.logPath}, redact=${String(auditConfig.redact)}, reads=${String(auditConfig.auditReads)}, backup=${String(!!auditConfig.backup?.enabled)})`,
+      { module: "AUDIT" }
+    );
+  }
+  /**
+   * Register the sqlite://audit resource for agent access to audit log.
+   */
+  registerAuditResource() {
+    if (!this.auditLogger) return;
+    const auditLogger = this.auditLogger;
+    const backupManager = this.backupManager;
+    this.server.registerResource(
+      "sqlite_audit",
+      "sqlite://audit",
+      {
+        description: "Recent audit log entries and backup statistics. Shows the last 50 tool invocations with timing, outcomes, and token estimates.",
+        mimeType: "application/json"
+      },
+      async () => {
+        const recent = await auditLogger.recent(50);
+        const backupStats = backupManager ? await backupManager.getStats() : void 0;
+        const payload = {
+          entries: recent,
+          stats: {
+            totalEntries: recent.length,
+            ...backupStats && { backups: backupStats }
+          }
+        };
+        return {
+          contents: [
+            {
+              uri: "sqlite://audit",
+              mimeType: "application/json",
+              text: JSON.stringify(payload, null, 2)
+            }
+          ]
+        };
+      }
+    );
+  }
+  /**
+   * Register audit backup tools for snapshot management.
+   */
+  registerAuditBackupTools() {
+    const backupManager = this.backupManager;
+    if (!backupManager) return;
+    this.server.registerTool(
+      "sqlite_audit_list_backups",
+      {
+        title: "List Audit Backups",
+        description: "List pre-mutation DDL snapshots captured before destructive operations. Returns metadata for each snapshot including timestamp, tool, target, and size.",
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false
+        }
+      },
+      async () => {
+        const snapshots = await backupManager.listSnapshots();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  snapshots,
+                  count: snapshots.length,
+                  _meta: {
+                    tokenEstimate: Math.ceil(
+                      Buffer.byteLength(JSON.stringify(snapshots), "utf8") / 4
+                    )
+                  }
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+    );
+    this.server.registerTool(
+      "sqlite_audit_get_backup",
+      {
+        title: "Get Audit Backup",
+        description: "Retrieve a specific pre-mutation DDL snapshot by filename. Returns the full snapshot content including DDL and optional data.",
+        inputSchema: z.object({
+          filename: z.string().describe(
+            "Snapshot filename from sqlite_audit_list_backups results"
+          )
+        }),
+        annotations: {
+          readOnlyHint: true,
+          destructiveHint: false,
+          idempotentHint: true,
+          openWorldHint: false
+        }
+      },
+      async (args) => {
+        const { filename } = args;
+        const snapshot = await backupManager.getSnapshot(filename);
+        if (!snapshot) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: false,
+                    error: `Snapshot not found: ${filename}`
+                  },
+                  null,
+                  2
+                )
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(snapshot, null, 2)
+            }
+          ]
+        };
+      }
+    );
+    this.server.registerTool(
+      "sqlite_audit_cleanup",
+      {
+        title: "Cleanup Audit Backups",
+        description: "Apply retention policy to audit backup snapshots. Deletes snapshots exceeding age or count limits.",
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: true,
+          idempotentHint: true,
+          openWorldHint: false
+        }
+      },
+      async () => {
+        const deleted = await backupManager.cleanup();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  success: true,
+                  deletedCount: deleted,
+                  message: deleted > 0 ? `Cleaned up ${String(deleted)} snapshot(s)` : "No snapshots to clean up"
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+    );
+    logger.info(
+      "Registered audit backup tools: sqlite_audit_list_backups, sqlite_audit_get_backup, sqlite_audit_cleanup",
+      { module: "AUDIT" }
+    );
+  }
+};
+function createServer(config) {
+  return new DbMcpServer(config);
+}
+var DEFAULT_CONFIG = {
+  name: NAME,
+  version: VERSION,
+  transport: "stdio",
+  databases: []
+};
+
+export { DEFAULT_CONFIG, DbMcpServer, createServer };