db-mcp 1.1.1 → 3.0.0

package/dist/chunk-THATOQRT.js

@@ -0,0 +1,2624 @@
+import { VERSION, NAME, READ_ONLY, SERVER_ICONS, ASSISTANT_FOCUSED, redactObject, getRequiredScope, AuditListBackupsOutputSchema, AuditListBackupsSchema, AuditGetBackupOutputSchema, AuditCleanupOutputSchema, AuditDiffBackupOutputSchema, AuditRestoreBackupOutputSchema } from './chunk-E5IESRTK.js';
+import { parseToolFilter, getToolFilterFromEnv, logger, getFilterSummary, DbMcpError, getAuthContext, scopesGrantToolAccess, registerToolScopes, InsufficientScopeError, sanitizeErrorMessage, formatHandlerError } from './chunk-L552U3QS.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\`, \`sqlite_execute_code\` \u2014 injected into all configurations.
+
+## Help Resources
+
+Read \`sqlite://help\` for gotchas and critical usage patterns.
+Read \`sqlite://help/{group}\` for group-specific tool reference (core, 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 (32N/31W tools) + Server Audit (5 tools)
+
+## 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)
+sqlite_reindex(); // rebuild all indexes
+sqlite_reindex({ target: "idx_users_email" }); // rebuild specific index
+sqlite_reindex({ target: "orders" }); // rebuild all indexes for a table
+\`\`\`
+
+## Backup/Restore (Native only)
+
+\`\`\`javascript
+sqlite_backup({ targetPath: "/path/to/backup.db" });
+sqlite_vacuum_into({ outputPath: "/path/to/compact.db" }); // create defragmented copy
+sqlite_dump({ outputPath: "/path/to/dump.sql" }); // export SQL text dump
+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
+
+\`\`\`javascript
+sqlite_audit_list_backups({ limit: 10, offset: 0 }); // list pre-mutation DDL snapshots
+sqlite_audit_get_backup({ filename: "snapshot_123.json" }); // retrieve specific snapshot
+sqlite_audit_diff_backup({ filename: "snapshot_123.json" }); // compare snapshot against live schema
+sqlite_audit_restore_backup({ filename: "snapshot_123.json", dryRun: true }); // restore schema from 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_attach_database({ filepath: "/path/to/other.db", alias: "archive" }); // attach external DB
+sqlite_detach_database({ alias: "archive" }); // detach DB
+sqlite_pragma_optimize(); // run PRAGMA optimize
+\`\`\`
+
+## WAL Management
+
+\`\`\`javascript
+sqlite_wal({ action: "status" }); // check current journal mode
+sqlite_wal({ action: "enable" }); // switch to WAL mode
+sqlite_wal({ action: "disable" }); // switch back to DELETE journal mode
+sqlite_wal({ action: "checkpoint" }); // run default checkpoint
+sqlite_wal({ action: "checkpoint", checkpointMode: "TRUNCATE" }); // checkpoint and truncate WAL file
+\`\`\`
+
+## 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 (21 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, REPLACE, or trigger DDL (CREATE/DROP TRIGGER)
+
+## 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. Detects generated columns (VIRTUAL/STORED) with expression.
+- \`sqlite_create_table({ table: "users", columns: [{ name: "id", type: "INTEGER PRIMARY KEY" }, { name: "email", type: "TEXT UNIQUE" }], foreignKeys: [{ column: "role_id", targetTable: "roles" }], checkConstraints: ["price > 0"] })\` \u2014 create a new table with optional table-level constraints. Use \`strict: true\` for STRICT mode (SQLite 3.37+) to enforce column type checking.
+- \`sqlite_drop_table({ table: "users", ifExists?: true })\` \u2014 drop an existing table
+- \`sqlite_alter_table({ table: "users", operation: "add_column", column: "age", type: "INTEGER", nullable: true })\` \u2014 add, rename, or drop columns, or rename a table. Operations: \`add_column\`, \`rename_column\`, \`drop_column\`, \`rename_table\`.
+- \`sqlite_list_triggers({ table?: "users" })\` \u2014 list database triggers, optionally filtered by table
+- \`sqlite_create_trigger({ name: "trg_updated", table: "users", timing: "AFTER", event: "UPDATE", body: "UPDATE users SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id" })\` \u2014 create a trigger with BEFORE/AFTER/INSTEAD OF timing, optional column-specific UPDATE triggers and WHEN conditions
+- \`sqlite_drop_trigger({ name: "trg_updated" })\` \u2014 drop a database trigger
+- \`sqlite_list_constraints({ table: "users" })\` \u2014 list primary key, foreign key, unique, and check constraints for a 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 a row using \`ON CONFLICT\` (or \`REPLACE\` fallback). Supports \`returning: true\` or array of columns.
+- \`sqlite_batch_insert({ table: "users", rows: [{ 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", where?: "status = 'active'" })\` \u2014 count rows in a table (faster than a full query)
+- \`sqlite_exists({ table: "users", where: "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\`)
+- \`sqlite_date_add({ table: "users", column: "created_at", amount: 7, unit: "days", whereClause: "id = 1" })\` \u2014 add or subtract time intervals from a date column. By default returns only the computed column; use \`selectColumns\` to return additional context.
+- \`sqlite_date_diff({ table: "users", column1: "ended_at", column2: "started_at", unit: "days", whereClause: "id = 1" })\` \u2014 calculate the difference between two date columns. By default returns only the computed column; use \`selectColumns\` to return additional context.`],
+  ["geo", `# db-mcp Help \u2014 Geospatial Operations (11N/4W: 4 basic + 7 SpatiaLite [NATIVE ONLY])
+
+## 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**: DML only (INSERT/UPDATE/DELETE/REPLACE) \u2014 use \`sqlite_read_query\` for SELECT, and dedicated DDL tools like \`sqlite_create_table\`, \`sqlite_create_trigger\`, and \`sqlite_drop_trigger\` for schema modifications.
+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**: Returns all columns by default which creates large payloads for wide tables \u2014 always pass \`selectColumns\` to control output size
+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.
+19. **sqlite_batch_insert**: All rows must have the same keys \u2014 inconsistent column sets across rows will cause errors or unexpected NULLs
+20. **sqlite_schema_diff**: \`baseline\` and \`target\` accept either the string \`"current"\` (queries live DB) or an inline snapshot object from a prior \`sqlite_schema_snapshot\` call. At least one side must be \`"current"\` unless doing an offline comparison
+21. **sqlite_upsert**: Always specify \`conflictColumns\` \u2014 without it, falls back to \`REPLACE\` which deletes and re-inserts the row, potentially losing columns not included in \`data\`
+
+## 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/Dump/VacuumInto/Verify (5 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 (Built-in)
+
+| 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.
+**Progress**: Use \`await sqlite.reportProgress(current, total, "Message")\` for custom long-running tasks.
+**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()\`)
+**Exception**: \`stats\` and \`migration\` keep their prefix: \`sqlite_stats_basic\` \u2192 \`sqlite.stats.statsBasic()\`, \`sqlite_migration_apply\` \u2192 \`sqlite.migration.migrationApply()\`
+
+**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 (10 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 (4 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
+
+// Compare a saved snapshot against the current live schema \u2014 structured drift analysis
+sqlite_schema_diff({
+  baseline: previousSnapshot, // from an earlier sqlite_schema_snapshot call
+  target: "current",
+});
+// Compare specific sections only
+sqlite_schema_diff({
+  baseline: "current",
+  target: modifiedSnapshot,
+  sections: ["tables", "indexes"],
+});
+// Both sides inline (offline diff, no DB queries)
+sqlite_schema_diff({ baseline: snapshotA, target: snapshotB });
+
+// 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 (25 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, paths? })\` \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({ json: "{\\"name\\": \\"Alice\\"}" })\` \u2014 format JSON string with indentation for readability
+- \`sqlite_json_valid({ json: "{\\"name\\": \\"Alice\\"}" })\` \u2014 check if a string is valid JSON
+- \`sqlite_json_analyze_schema({ table, column })\` \u2014 infer schema types
+- \`sqlite_json_diff({ table, column, path1, path2 })\` \u2014 compare two JSON paths within the same row
+
+## 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 by default. Enable via \`--tool-filter\` flag: use \`dev-schema\` (core+introspection+migration+codemode) or \`full\` (all groups)`],
+  ["stats", `# db-mcp Help \u2014 Statistical Analysis (23N/17W: 17 core + 6 window [NATIVE ONLY])
+
+## 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_sample({ table: "orders", sampleSize: 100 }); // random sample
+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 (19N/14W: 14 text + 5 FTS5 [NATIVE ONLY])
+
+## 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 text analysis (can analyze raw text or database columns)
+sqlite_text_sentiment({ text: "This product is amazing and wonderful!" });
+// \u2192 { sentiment: "very_positive", score: 2, confidence: "medium" }
+
+sqlite_text_sentiment({ table: "articles", column: "body" }); // analyzes all rows in a column
+
+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 (err) {
+      process.stderr.write(
+        `[AUDIT] Failed to initialise log file: ${this.config.logPath}
+`
+      );
+      throw err;
+    }
+  }
+  /**
+   * 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;
+    const safeEntry = redactObject(entry, 0, 5);
+    this.buffer.push(JSON.stringify(safeEntry));
+    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: "viewName" },
+  sqlite_import_csv: { targetKey: "table" },
+  sqlite_backup: { targetKey: "targetPath" }
+};
+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(limit = 10, offset = 0) {
+    try {
+      await this.ensureDirectory();
+      const files = await readdir(this.snapshotDir);
+      const snapshotFiles = files.filter(
+        (f) => f.endsWith(SNAPSHOT_EXT) || f.endsWith(SNAPSHOT_EXT_LEGACY)
+      );
+      snapshotFiles.sort((a, b) => b.localeCompare(a));
+      const total = snapshotFiles.length;
+      const targetFiles = snapshotFiles.slice(offset, offset + limit);
+      const snapshots = [];
+      for (const file of targetFiles) {
+        try {
+          const parsed = await this.readSnapshotFile(file);
+          if (parsed) {
+            snapshots.push({ ...parsed.metadata, filename: file });
+          }
+        } catch {
+        }
+      }
+      return { snapshots, total };
+    } catch {
+      return { snapshots: [], total: 0 };
+    }
+  }
+  /**
+   * 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;
+    }
+  }
+};
+var SENSITIVE_KEY_PATTERN = /^(password|passwd|token|secret|authorization|api_?key|credential|private_?key|access_?token|refresh_?token)$/i;
+var SENSITIVE_VALUE_PATTERN = /(?:sk-|Bearer |token\s*[:=]\s*|password\s*[:=]\s*|secret\s*[:=]\s*|apikey\s*[:=]\s*|api_key\s*[:=]\s*|AWS_SECRET_ACCESS_KEY\s*[:=]\s*|GITHUB_TOKEN\s*[:=]\s*|ghp_|gho_|ghu_|ghs_|xoxb-|xoxp-|xoxs-|AZURE_[A-Z_]*\s*[:=]\s*|DATABASE_URL\s*[:=]\s*|AKIA|sk-ant-api[a-zA-Z0-9_-]+|sk_live_[a-zA-Z0-9_]+|rk_live_[a-zA-Z0-9_]+|SG\.[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+|npm_[a-zA-Z0-9]{30,}|dpl_[a-zA-Z0-9]{30,}|hvs\.[a-zA-Z0-9_-]+)[^\s'",;)}\]]{4,}/gi;
+function redactSensitiveKeys(value, depth = 0) {
+  const MAX_DEPTH = 5;
+  if (depth > MAX_DEPTH || value === null || value === void 0) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSensitiveKeys(item, depth + 1));
+  }
+  if (typeof value === "string") {
+    const isSql = /^\s*(?:SELECT|INSERT|UPDATE|DELETE|WITH|CREATE|ALTER|DROP|PRAGMA)\b/i.test(
+      value
+    );
+    const scrubbed = isSql ? value.replace(/'(?:''|[^'])*'/g, "'***'") : value;
+    return scrubbed.replace(SENSITIVE_VALUE_PATTERN, "[REDACTED]");
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      if (SENSITIVE_KEY_PATTERN.test(key)) {
+        result[key] = "[REDACTED]";
+      } else if (typeof val === "object" && val !== null) {
+        result[key] = redactSensitiveKeys(val, depth + 1);
+      } else if (typeof val === "string") {
+        const isSql = key.toLowerCase() === "sql" || key.toLowerCase() === "query" || /^\s*(?:SELECT|INSERT|UPDATE|DELETE|WITH|CREATE|ALTER|DROP|PRAGMA)\b/i.test(
+          val
+        );
+        const scrubbed = isSql ? val.replace(/'(?:''|[^'])*'/g, "'***'") : val;
+        result[key] = scrubbed.replace(SENSITIVE_VALUE_PATTERN, "[REDACTED]");
+      } else {
+        result[key] = val;
+      }
+    }
+    return result;
+  }
+  return value;
+}
+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) {
+  const auditReads = auditLogger.config.auditReads;
+  let currentQueryAdapter;
+  return {
+    setQueryAdapter(adapter) {
+      currentQueryAdapter = adapter;
+    },
+    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;
+      if (backupManager !== void 0 && currentQueryAdapter !== void 0 && backupManager.shouldSnapshot(toolName)) {
+        try {
+          backupRef = await backupManager.createSnapshot(
+            toolName,
+            args ?? {},
+            requestId,
+            currentQueryAdapter,
+            options?.logAs
+          );
+        } catch {
+        }
+      }
+      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 = sanitizeErrorMessage(
+          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 : redactSensitiveKeys(args),
+            backup: backupRef,
+            tokenEstimate
+          });
+        }
+      }
+    }
+  };
+}
+
+// src/server/registration/built-in-tools.ts
+function registerBuiltInTools(server, adaptersMap, config, toolFilter) {
+  const serverInfoOpts = {
+    title: "Server Info",
+    description: "Get information about the db-mcp server and registered adapters",
+    icons: SERVER_ICONS,
+    annotations: READ_ONLY
+  };
+  server.registerTool("server_info", serverInfoOpts, () => {
+    const authCtx = getAuthContext();
+    if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "server_info")) {
+      throw new InsufficientScopeError(["read"], authCtx.scopes);
+    }
+    const adapterInfo = [];
+    for (const [id, adapter] of adaptersMap) {
+      adapterInfo.push({
+        id,
+        ...adapter.getInfo()
+      });
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              name: config.name,
+              version: config.version,
+              transport: config.transport,
+              adapters: adapterInfo,
+              toolFilter: {
+                raw: toolFilter.raw,
+                enabledGroups: [...toolFilter.enabledGroups]
+              }
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  });
+  const healthOpts = {
+    title: "Server Health",
+    description: "Check health status of all database connections",
+    icons: SERVER_ICONS,
+    annotations: READ_ONLY
+  };
+  server.registerTool("server_health", healthOpts, async () => {
+    const authCtx = getAuthContext();
+    if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "server_health")) {
+      throw new InsufficientScopeError(["read"], authCtx.scopes);
+    }
+    const health = {
+      server: "healthy",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      adapters: {}
+    };
+    for (const [id, adapter] of adaptersMap) {
+      try {
+        const adapterHealth = await adapter.getHealth();
+        health["adapters"][id] = adapterHealth;
+      } catch (error) {
+        let errorMsg = error instanceof Error ? error.message : "Unknown error";
+        errorMsg = errorMsg.replace(/(:[^:@/]+@)/g, ":***@");
+        health["adapters"][id] = {
+          connected: false,
+          error: errorMsg
+        };
+      }
+    }
+    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
+  };
+  server.registerTool("list_adapters", listAdaptersOpts, () => {
+    const authCtx = getAuthContext();
+    if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "list_adapters")) {
+      throw new InsufficientScopeError(["read"], authCtx.scopes);
+    }
+    const adapters = [];
+    for (const [, adapter] of adaptersMap) {
+      adapters.push({
+        id: `${adapter.type}:default`,
+        type: adapter.type,
+        name: adapter.name,
+        version: adapter.version,
+        connected: adapter.isConnected()
+      });
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(adapters, null, 2)
+        }
+      ]
+    };
+  });
+  registerToolScopes(
+    /* @__PURE__ */ new Map([
+      ["server_info", ["read"]],
+      ["server_health", ["read"]],
+      ["list_adapters", ["read"]]
+    ])
+  );
+}
+
+// src/server/registration/help-resources.ts
+function registerHelpResources(server, toolFilter) {
+  const gotchasContent = HELP_CONTENT.get("gotchas");
+  if (gotchasContent) {
+    server.registerResource(
+      "sqlite_help",
+      "sqlite://help",
+      {
+        description: "Critical gotchas, WASM vs Native comparison, and Code Mode API reference",
+        mimeType: "text/markdown",
+        annotations: ASSISTANT_FOCUSED
+      },
+      () => ({
+        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 = toolFilter.enabledGroups.size === 1 && toolFilter.enabledGroups.has("codemode");
+    if (!toolFilter.enabledGroups.has(group) && !isCodemodeOnly) {
+      continue;
+    }
+    const content = HELP_CONTENT.get(key);
+    if (!content) continue;
+    server.registerResource(
+      `sqlite_help_${key}`,
+      `sqlite://help/${key}`,
+      {
+        description: `Tool reference for the ${group} tool group`,
+        mimeType: "text/markdown",
+        annotations: ASSISTANT_FOCUSED
+      },
+      () => ({
+        contents: [
+          {
+            uri: `sqlite://help/${key}`,
+            mimeType: "text/markdown",
+            text: content
+          }
+        ]
+      })
+    );
+  }
+  const registeredHelp = ["sqlite://help"];
+  for (const { group, key } of groupHelpKeys) {
+    if (toolFilter.enabledGroups.has(group)) {
+      registeredHelp.push(`sqlite://help/${key}`);
+    }
+  }
+  logger.info(`Help resources: ${registeredHelp.join(", ")}`, {
+    module: "SERVER"
+  });
+}
+function redactSqlLiterals(text) {
+  return text.replace(/'(?:''|[^'])*'/g, "'***'");
+}
+function validateDdl(sql) {
+  const cleanSql = sql.replace(/\/\*[\s\S]*?\*\//g, "").replace(/--.*$/gm, "");
+  const upperSql = cleanSql.toUpperCase();
+  if (upperSql.includes("ATTACH ") || upperSql.includes("DETACH ") || upperSql.includes("PRAGMA ") || upperSql.includes("LOAD_EXTENSION(")) {
+    throw new Error(
+      `DDL validation failed: unauthorized command or function call`
+    );
+  }
+  if (upperSql.includes(" ON MAIN.") || upperSql.includes(" ON TEMP.")) {
+    throw new Error(
+      `DDL validation failed: trigger attempts to target a specific database`
+    );
+  }
+}
+function registerAuditResource(server, auditLogger, backupManager) {
+  if (!auditLogger) return;
+  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 }
+        }
+      };
+      const payloadStr = JSON.stringify(payload, null, 2);
+      return {
+        contents: [
+          {
+            uri: "sqlite://audit",
+            mimeType: "application/json",
+            text: redactSqlLiterals(payloadStr)
+          }
+        ]
+      };
+    }
+  );
+}
+function registerAuditBackupTools(server, backupManager, adaptersMap) {
+  if (!backupManager) return;
+  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.",
+      inputSchema: AuditListBackupsSchema,
+      outputSchema: AuditListBackupsOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+        // Requires admin scope
+      }
+    },
+    async (args) => {
+      const authCtx = getAuthContext();
+      if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_audit_list_backups")) {
+        throw new InsufficientScopeError(["admin", "full"], authCtx.scopes);
+      }
+      let parsed;
+      try {
+        parsed = AuditListBackupsSchema.parse(args ?? {});
+      } catch (error) {
+        const structured = formatHandlerError(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(structured, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: structured
+        };
+      }
+      const limit = parsed.limit ?? 10;
+      const offset = parsed.offset ?? 0;
+      const { snapshots, total } = await backupManager.listSnapshots(
+        limit,
+        offset
+      );
+      const result = {
+        success: true,
+        snapshots,
+        count: snapshots.length,
+        totalCount: total
+      };
+      const tokenEstimate = Math.ceil(
+        Buffer.byteLength(JSON.stringify(result), "utf8") / 4
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { ...result, _meta: { tokenEstimate } },
+              null,
+              2
+            )
+          }
+        ],
+        structuredContent: result
+      };
+    }
+  );
+  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().default("").describe("Snapshot filename from sqlite_audit_list_backups results")
+      }),
+      outputSchema: AuditGetBackupOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+        // Requires admin scope
+      }
+    },
+    async (args) => {
+      const authCtx = getAuthContext();
+      if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_audit_get_backup")) {
+        throw new InsufficientScopeError(["admin", "full"], authCtx.scopes);
+      }
+      let filename;
+      try {
+        const parsed = z.object({ filename: z.string().min(1, "filename is required") }).parse(args);
+        filename = parsed.filename;
+      } catch (error) {
+        const structured = formatHandlerError(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(structured, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: structured
+        };
+      }
+      const snapshot = await backupManager.getSnapshot(filename);
+      if (!snapshot) {
+        const errRes = {
+          success: false,
+          error: `Snapshot not found: ${filename}`
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(errRes, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: errRes
+        };
+      }
+      const result = { success: true, ...snapshot };
+      const snapshotStr = JSON.stringify(result, null, 2);
+      return {
+        content: [
+          {
+            type: "text",
+            text: redactSqlLiterals(snapshotStr)
+          }
+        ],
+        structuredContent: result
+      };
+    }
+  );
+  server.registerTool(
+    "sqlite_audit_cleanup",
+    {
+      title: "Cleanup Audit Backups",
+      description: "Apply retention policy to audit backup snapshots. Deletes snapshots exceeding age or count limits.",
+      outputSchema: AuditCleanupOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async () => {
+      const authCtx = getAuthContext();
+      if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_audit_cleanup")) {
+        throw new InsufficientScopeError(["admin", "full"], authCtx.scopes);
+      }
+      const deleted = await backupManager.cleanup();
+      const result = {
+        success: true,
+        deletedCount: deleted,
+        message: deleted > 0 ? `Cleaned up ${String(deleted)} snapshot(s)` : "No snapshots to clean up"
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ],
+        structuredContent: result
+      };
+    }
+  );
+  server.registerTool(
+    "sqlite_audit_diff_backup",
+    {
+      title: "Diff Audit Backup",
+      description: "Compare a pre-mutation DDL snapshot against the live database schema. Shows objects that have been added, removed, or modified since the snapshot was taken.",
+      inputSchema: z.object({
+        filename: z.string().default("").describe(
+          "Snapshot filename to compare against the live database schema"
+        )
+      }),
+      outputSchema: AuditDiffBackupOutputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+        // Requires admin scope
+      }
+    },
+    async (args) => {
+      const authCtx = getAuthContext();
+      if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_audit_diff_backup")) {
+        throw new InsufficientScopeError(["admin", "full"], authCtx.scopes);
+      }
+      let filename;
+      try {
+        const parsed = z.object({ filename: z.string().min(1, "filename is required") }).parse(args);
+        filename = parsed.filename;
+      } catch (error) {
+        const structured = formatHandlerError(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(structured, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: structured
+        };
+      }
+      const snapshot = await backupManager.getSnapshot(filename);
+      if (!snapshot) {
+        const errRes = {
+          success: false,
+          error: `Snapshot not found: ${filename}`
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(errRes, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: errRes
+        };
+      }
+      const adapter = [...adaptersMap.values()][0];
+      if (!adapter) {
+        const errRes = {
+          success: false,
+          error: "No connected adapter available"
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(errRes, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: errRes
+        };
+      }
+      try {
+        const liveResult = await adapter.executeReadQuery(
+          "SELECT name, type, sql FROM sqlite_master WHERE sql IS NOT NULL ORDER BY type, name"
+        );
+        const liveObjects = /* @__PURE__ */ new Map();
+        for (const row of liveResult.rows ?? []) {
+          liveObjects.set(row["name"], {
+            type: row["type"],
+            sql: row["sql"]
+          });
+        }
+        const snapshotDdl = snapshot.ddl ?? "";
+        const snapshotObjects = /* @__PURE__ */ new Map();
+        const statements = snapshotDdl.split(";").map((s) => s.trim()).filter(Boolean);
+        for (const stmt of statements) {
+          const match = /CREATE\s+(?:VIRTUAL\s+)?(?:TEMP(?:ORARY)?\s+)?(TABLE|INDEX|VIEW|TRIGGER)\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|(\S+))/i.exec(
+            stmt
+          );
+          if (match) {
+            const type = (match[1] ?? "").toLowerCase();
+            const name = match[2] ?? match[3] ?? "";
+            snapshotObjects.set(name, { type, sql: stmt });
+          }
+        }
+        const diffs = [];
+        const snapshotTarget = snapshot.metadata?.target;
+        for (const [name, live] of liveObjects) {
+          if (name === snapshotTarget || snapshotObjects.has(name)) {
+            if (!snapshotObjects.has(name)) {
+              diffs.push({
+                object: name,
+                type: live.type,
+                status: "added",
+                liveDefinition: live.sql
+              });
+            }
+          }
+        }
+        for (const [name, snap] of snapshotObjects) {
+          if (!liveObjects.has(name)) {
+            diffs.push({
+              object: name,
+              type: snap.type,
+              status: "removed",
+              snapshotDefinition: snap.sql
+            });
+          }
+        }
+        for (const [name, snap] of snapshotObjects) {
+          const live = liveObjects.get(name);
+          if (live && live.sql !== snap.sql) {
+            diffs.push({
+              object: name,
+              type: live.type,
+              status: "modified",
+              liveDefinition: live.sql,
+              snapshotDefinition: snap.sql
+            });
+          }
+        }
+        const result = {
+          success: true,
+          diffs,
+          snapshotTimestamp: snapshot.metadata?.timestamp ?? "",
+          snapshotTarget: snapshot.metadata?.target ?? ""
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ],
+          structuredContent: result
+        };
+      } catch (error) {
+        const errRes = {
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(errRes, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: errRes
+        };
+      }
+    }
+  );
+  server.registerTool(
+    "sqlite_audit_restore_backup",
+    {
+      title: "Restore Audit Backup",
+      description: "Restore a pre-mutation DDL snapshot by executing its DDL statements against the live database. Use dryRun=true to preview the DDL without applying changes.",
+      inputSchema: z.object({
+        filename: z.string().default("").describe("Snapshot filename to restore from"),
+        dryRun: z.unknown().optional().describe("If true, returns the DDL without executing it (boolean)")
+      }),
+      outputSchema: AuditRestoreBackupOutputSchema,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    async (args) => {
+      const authCtx = getAuthContext();
+      if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_audit_restore_backup")) {
+        throw new InsufficientScopeError(["admin", "full"], authCtx.scopes);
+      }
+      let filename;
+      let dryRun;
+      try {
+        const parsed = z.object({
+          filename: z.string().min(1, "filename is required"),
+          dryRun: z.boolean().optional().default(false)
+        }).parse(args);
+        filename = parsed.filename;
+        dryRun = parsed.dryRun;
+      } catch (error) {
+        const structured = formatHandlerError(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(structured, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: structured
+        };
+      }
+      const snapshot = await backupManager.getSnapshot(filename);
+      if (!snapshot) {
+        const errRes = {
+          success: false,
+          error: `Snapshot not found: ${filename}`
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(errRes, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: errRes
+        };
+      }
+      const ddl = snapshot.ddl ?? "";
+      if (!ddl.trim()) {
+        const errRes = {
+          success: false,
+          error: "Snapshot contains no DDL statements"
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(errRes, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: errRes
+        };
+      }
+      const adapter = [...adaptersMap.values()][0];
+      if (!adapter) {
+        const errRes = {
+          success: false,
+          error: "No connected adapter available"
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(errRes, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: errRes
+        };
+      }
+      if (dryRun) {
+        const result = {
+          success: true,
+          message: "Dry run: no changes applied",
+          dryRun: true,
+          ddl: redactSqlLiterals(ddl)
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ],
+          structuredContent: result
+        };
+      }
+      try {
+        const statements = ddl.split(";").map((s) => s.trim()).filter((s) => {
+          const cleanSql = s.replace(/\/\*[\s\S]*?\*\//g, "").replace(/--.*$/gm, "").trim();
+          return cleanSql.length > 0;
+        });
+        if (statements.length === 0) {
+          const result2 = {
+            success: true,
+            message: "No executable statements found in snapshot (only comments)",
+            changesApplied: 0
+          };
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(result2, null, 2)
+              }
+            ],
+            structuredContent: result2
+          };
+        }
+        await adapter.executeQuery("BEGIN TRANSACTION;");
+        try {
+          for (const stmt of statements) {
+            validateDdl(stmt);
+            await adapter.executeQuery(`${stmt};`);
+          }
+          await adapter.executeQuery("COMMIT;");
+        } catch (e) {
+          await adapter.executeQuery("ROLLBACK;");
+          throw e;
+        }
+        const result = {
+          success: true,
+          message: `Successfully executed ${statements.length} statement(s) from snapshot`,
+          changesApplied: statements.length
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ],
+          structuredContent: result
+        };
+      } catch (error) {
+        const errRes = {
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        };
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(errRes, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: errRes
+        };
+      }
+    }
+  );
+  registerToolScopes(
+    /* @__PURE__ */ new Map([
+      ["sqlite_audit_list_backups", ["admin", "full"]],
+      ["sqlite_audit_get_backup", ["admin", "full"]],
+      ["sqlite_audit_cleanup", ["admin", "full"]],
+      ["sqlite_audit_diff_backup", ["admin", "full"]],
+      ["sqlite_audit_restore_backup", ["admin", "full"]]
+    ])
+  );
+  logger.info(
+    "Registered audit backup tools: sqlite_audit_list_backups, sqlite_audit_get_backup, sqlite_audit_cleanup, sqlite_audit_diff_backup, sqlite_audit_restore_backup",
+    { module: "AUDIT" }
+  );
+}
+
+// src/server/mcp-server.ts
+var proto = McpServer.prototype;
+if (typeof proto["createToolError"] === "function") {
+  const originalCreateToolError = proto["createToolError"];
+  proto["createToolError"] = function(errorMessage) {
+    const result = originalCreateToolError.call(
+      this,
+      errorMessage
+    );
+    if (result.content?.[0]?.type === "text") {
+      const rawError = result.content[0].text;
+      if (rawError.includes("Input validation error")) {
+        const cleanError = rawError.replace(
+          /^MCP error -32602: Input validation error: /,
+          "Validation error: "
+        );
+        const structured = {
+          success: false,
+          error: cleanError,
+          code: "VALIDATION_ERROR",
+          category: "validation" /* VALIDATION */
+        };
+        result.content[0].text = JSON.stringify(structured, null, 2);
+        result.isError = true;
+      }
+    }
+    return result;
+  };
+}
+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"]
+    });
+    registerBuiltInTools(
+      this.server,
+      this.adapters,
+      this.config,
+      this.toolFilter
+    );
+    registerHelpResources(this.server, this.toolFilter);
+    const internalMcp = this.server;
+    const handlers = internalMcp.server._requestHandlers;
+    if (!handlers?.has("tools/list")) {
+      throw new DbMcpError(
+        "Security: SDK _requestHandlers monkey-patch failed. Scope filtering is disabled.",
+        "SERVER_START_FAILED",
+        "internal" /* INTERNAL */
+      );
+    }
+    const originalListToolsHandler = handlers.get("tools/list");
+    if (originalListToolsHandler) {
+      handlers.set("tools/list", async (request, extra) => {
+        const result = await originalListToolsHandler(request, extra);
+        const authCtx = getAuthContext();
+        if (authCtx && Array.isArray(result.tools)) {
+          result.tools = result.tools.filter(
+            (t) => scopesGrantToolAccess(authCtx.scopes, t.name)
+          );
+        }
+        return result;
+      });
+    }
+    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);
+      this.auditInterceptor.setQueryAdapter({
+        executeQuery: (sql, params) => adapter.executeReadQuery(sql, params)
+      });
+    }
+    if (this.backupManager && "setBackupManager" in adapter) {
+      adapter.setBackupManager(this.backupManager);
+    }
+    adapter.registerTools(this.server, this.toolFilter);
+    adapter.registerResources(this.server);
+    adapter.registerPrompts(this.server);
+    const toolDefs = adapter.getToolDefinitions();
+    const scopesMap = /* @__PURE__ */ new Map();
+    for (const tool of toolDefs) {
+      if (tool.requiredScopes) {
+        scopesMap.set(tool.name, tool.requiredScopes);
+        scopesMap.set(`sqlite_${tool.name}`, tool.requiredScopes);
+      }
+    }
+    registerToolScopes(scopesMap);
+    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;
+  }
+  /**
+   * 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"
+    });
+    logger.warning(
+      "SECURITY WARNING: Running in STDIO mode grants blanket 'admin' access to all tools. This implies full trust in the local client/agent. If this server is exposed over SSH or used by an untrusted client, consider using HTTP transport with OAuth (--oauth-enabled) for granular scope enforcement.",
+      { module: "SERVER", code: "STDIO_ADMIN_RISK" }
+    );
+  }
+  /**
+   * Start server with HTTP transport (Streamable HTTP with SSE support)
+   */
+  async startHttp() {
+    const { HttpTransport } = await import('./http-HWTUVFIA.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,
+      noAuthEnforcement: this.config.noAuthEnforcement ?? false
+    });
+    await transport.initialize(this.server);
+    await transport.start();
+    const mode = this.config.statelessHttp ? "stateless" : "stateful";
+    const host = this.config.host ?? "127.0.0.1";
+    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
+    );
+    registerAuditResource(this.server, this.auditLogger, this.backupManager);
+    if (this.backupManager && this.toolFilter.enabledGroups.has("admin")) {
+      registerAuditBackupTools(this.server, this.backupManager, this.adapters);
+    }
+    logger.info(
+      `Audit logging enabled (${auditConfig.logPath}, redact=${String(auditConfig.redact)}, reads=${String(auditConfig.auditReads)}, backup=${String(!!auditConfig.backup?.enabled)})`,
+      { module: "AUDIT" }
+    );
+  }
+};
+function createServer(config) {
+  return new DbMcpServer(config);
+}
+var DEFAULT_CONFIG = {
+  name: NAME,
+  version: VERSION,
+  transport: "stdio",
+  databases: []
+};
+
+export { DEFAULT_CONFIG, DbMcpServer, createServer };