db-mcp 2.0.0 → 3.0.1

package/dist/{chunk-WBER5YY4.js → chunk-37G4DLL6.js}

@@ -1,6 +1,5 @@
-import { TOOL_GROUP_SCOPES, getAuthContext, SCOPES } from './chunk-SFJQCNG7.js';
-import { VERSION, NAME, READ_ONLY, SERVER_ICONS } from './chunk-VIDSICEL.js';
-import { TOOL_GROUPS, parseToolFilter, getToolFilterFromEnv, logger, getFilterSummary, DbMcpError } from './chunk-645ZEFLA.js';
+import { 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';
@@ -24,17 +23,17 @@ var INSTRUCTIONS = `# db-mcp (SQLite MCP Server)
 
 ## Built-in Tools
 
-\`server_info\`, \`server_health\`, \`list_adapters\` \u2014 always available.
+\`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 (json, text, stats, vector, geo, admin, transactions, introspection, migration).
+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 (29 Native / 29 WASM)
+    `# db-mcp Help \u2014 Database Administration (32N/31W tools) + Server Audit (5 tools)
 
 ## Maintenance
 
@@ -44,21 +43,28 @@ 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 (Requires --audit-backup)
+## Audit Backups
 
 \`\`\`javascript
-sqlite_audit_list_backups(); // list pre-mutation DDL snapshots
+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
 \`\`\`
 
@@ -70,9 +76,21 @@ 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
@@ -132,19 +150,24 @@ sqlite_append_insight({ insight: "Q4 revenue increased 23% YoY" }); // add to me
   ],
   [
     "core",
-    `# db-mcp Help \u2014 Core Operations (14 tools)
+    `# 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, or DDL 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
-- \`sqlite_create_table({ table: "users", columns: [{ name: "id", type: "INTEGER PRIMARY KEY" }, { name: "email", type: "TEXT UNIQUE" }] })\` \u2014 create a new table
+- \`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
 
@@ -154,15 +177,17 @@ sqlite_append_insight({ insight: "Q4 revenue increased 23% YoY" }); // add to me
 
 ## Convenience Tools (High-Level Data Operations)
 
-- \`sqlite_upsert({ table: "users", data: [{ id: 1, name: "Alice" }], conflictColumns: ["id"], updateColumns: ["name"], returning: true })\` \u2014 insert or update rows using \`ON CONFLICT\` (or \`REPLACE\` fallback). Supports \`returning: true\` or array of columns.
-- \`sqlite_batch_insert({ table: "users", data: [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }], returning: true })\` \u2014 insert multiple rows in a single batch. Supports \`returning: true\` or array of columns.
-- \`sqlite_count({ table: "users", whereClause?: "status = 'active'" })\` \u2014 count rows in a table (faster than a full query)
-- \`sqlite_exists({ table: "users", whereClause: "email = 'test@example.com'" })\` \u2014 check if a row exists (stops at first match)
-- \`sqlite_truncate({ table: "users" })\` \u2014 quickly delete all rows from a table (executes \`DELETE FROM table\`)`
+- \`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 (4 basic + 7 SpatiaLite)
+    `# db-mcp Help \u2014 Geospatial Operations (11N/4W: 4 basic + 7 SpatiaLite [NATIVE ONLY])
 
 ## Basic Geo (always available \u2014 Haversine formula)
 
@@ -275,7 +300,7 @@ sqlite_spatialite_index({
 
 ## \u26A0\uFE0F Critical Gotchas
 
-1. **sqlite_write_query**: \u26D4 Only INSERT/UPDATE/DELETE \u2014 use \`sqlite_read_query\` for SELECT
+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"\`
@@ -286,13 +311,16 @@ sqlite_spatialite_index({
 9. **Fuzzy matching tokenization**: Matches WORD TOKENS by default \u2014 \`"laptop"\` matches \`"Laptop Pro 15"\` (distance 0 on first token). Use \`tokenize: false\` for full-string matching
 10. **SpatiaLite distances**: \`nearest_neighbor\`/\`distance_matrix\` return CARTESIAN distance (degrees), not geodetic (km/miles)
 11. **SpatiaLite buffer**: Auto-simplifies output by default (tolerance=0.0001). Use \`simplifyTolerance: 0\` to disable
-12. **sqlite_stats_top_n**: Auto-excludes long-content columns (description, body, notes, etc.) when \`selectColumns\` is omitted. Use \`selectColumns\` to override
+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
 
@@ -302,14 +330,14 @@ sqlite_spatialite_index({
 | Transactions (8 tools)                            | \u2705                    | \u274C          | None             |
 | Window functions (6 tools in stats group)         | \u2705                    | \u274C          | None             |
 | SpatiaLite GIS (7 tools; 4 basic geo always work) | \u2705                    | \u274C          | None             |
-| Backup/Restore (3 tools)                          | \u2705                    | \u274C          | Graceful error   |
+| 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 (1 tool)
+## Code Mode (Built-in)
 
 | Tool                  | Description                                                       |
 | --------------------- | ----------------------------------------------------------------- |
@@ -317,6 +345,7 @@ sqlite_spatialite_index({
 
 **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.
@@ -324,6 +353,7 @@ sqlite_spatialite_index({
 ## 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", {...})\`
 
@@ -331,7 +361,7 @@ sqlite_spatialite_index({
   ],
   [
     "introspection",
-    `# db-mcp Help \u2014 Schema Introspection (9 tools)
+    `# db-mcp Help \u2014 Schema Introspection (10 tools)
 
 All introspection tools are **read-only** \u2014 they query PRAGMAs and sqlite_master, never modify data.
 
@@ -347,11 +377,11 @@ 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
+sqlite_cascade_simulator({ table: "users", operation: "DELETE" });
+sqlite_cascade_simulator({ table: "users", operation: "DROP", compact: true }); // compact omits path arrays
 \`\`\`
 
-## Schema Analysis (3 tools)
+## Schema Analysis (4 tools)
 
 \`\`\`javascript
 // Full schema in one call \u2014 compact: true omits column details, sections limits scope
@@ -361,6 +391,20 @@ sqlite_schema_snapshot({
 });
 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({
@@ -402,13 +446,13 @@ sqlite_query_plan({ sql: "SELECT * FROM orders WHERE status = 'active'" });
   ],
   [
     "json",
-    `# db-mcp Help \u2014 JSON Operations (24 tools)
+    `# 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, extractPaths? })\` \u2014 select rows, optionally extract specific JSON paths
+- \`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
 
@@ -463,9 +507,10 @@ sqlite_json_group_object({
 \`\`\`
 
 - \`sqlite_json_keys({ table, column, path? })\` \u2014 get distinct keys of JSON objects
-- \`sqlite_json_pretty({ table, column, whereClause? })\` \u2014 format JSON with indentation
-- \`sqlite_json_valid({ table, column })\` \u2014 check if values are valid JSON
+- \`sqlite_json_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
 
@@ -492,8 +537,7 @@ sqlite_migration_init();
 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)",
+  sql: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE)",
   rollbackSql: "DROP TABLE users",
   sourceSystem: "agent",
   appliedBy: "claude",
@@ -522,11 +566,11 @@ sqlite_migration_status();
 ## \u26A0\uFE0F Gotchas
 
 - Rollback requires \`rollbackSql\` to have been provided when the migration was recorded/applied
-- Migration group is **opt-in** \u2014 not included in any shortcut except \`dev-schema\` and \`full\``
+- 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 (16 core + 6 window)
+    `# db-mcp Help \u2014 Statistical Analysis (23N/17W: 17 core + 6 window [NATIVE ONLY])
 
 ## Core Statistics (always available)
 
@@ -542,6 +586,7 @@ sqlite_stats_percentile({
 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"],
@@ -642,13 +687,13 @@ sqlite_window_moving_avg({
   column: "close_price",
   orderBy: "date",
   windowSize: 7,
-  selectColumns: ["date"]
+  selectColumns: ["date"],
 });
 \`\`\``
   ],
   [
     "text",
-    `# db-mcp Help \u2014 Text Processing & FTS5
+    `# db-mcp Help \u2014 Text Processing & FTS5 (19N/14W: 14 text + 5 FTS5 [NATIVE ONLY])
 
 ## Full-Text Search / FTS5 (5 tools, Native only)
 
@@ -775,11 +820,16 @@ sqlite_advanced_search({
   fuzzyThreshold: 0.4,
 });
 
-// Sentiment analysis \u2014 pure text analysis, no database query needed
+// 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({ text: "Great service but slow delivery", returnWords: true });
+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"] }
 \`\`\``
   ],
@@ -883,11 +933,12 @@ var AuditLogger = class {
       await this.ensureDirectory();
       const fh = await open(this.config.logPath, "a");
       await fh.close();
-    } catch {
+    } catch (err) {
       process.stderr.write(
         `[AUDIT] Failed to initialise log file: ${this.config.logPath}
 `
       );
+      throw err;
     }
   }
   /**
@@ -897,7 +948,8 @@ var AuditLogger = class {
    */
   log(entry) {
     if (this.closed || !this.config.enabled) return;
-    this.buffer.push(JSON.stringify(entry));
+    const safeEntry = redactObject(entry, 0, 5);
+    this.buffer.push(JSON.stringify(safeEntry));
     if (this.buffer.length >= BUFFER_HIGH_WATER) {
       void this.flush();
     }
@@ -1033,9 +1085,9 @@ var gzipAsync = promisify(gzip);
 var SNAPSHOT_TOOL_ARGS = {
   sqlite_drop_table: { targetKey: "table" },
   sqlite_drop_index: { targetKey: "index" },
-  sqlite_drop_view: { targetKey: "view" },
+  sqlite_drop_view: { targetKey: "viewName" },
   sqlite_import_csv: { targetKey: "table" },
-  sqlite_backup: { targetKey: "path" }
+  sqlite_backup: { targetKey: "targetPath" }
 };
 var SNAPSHOT_EXT = ".snapshot.json.gz";
 var SNAPSHOT_EXT_LEGACY = ".snapshot.json";
@@ -1087,14 +1139,18 @@ var BackupManager = class {
   /**
    * List available snapshots with metadata.
    */
-  async listSnapshots() {
+  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 files) {
-        if (!file.endsWith(SNAPSHOT_EXT) && !file.endsWith(SNAPSHOT_EXT_LEGACY))
-          continue;
+      for (const file of targetFiles) {
         try {
           const parsed = await this.readSnapshotFile(file);
           if (parsed) {
@@ -1103,10 +1159,9 @@ var BackupManager = class {
         } catch {
         }
       }
-      snapshots.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
-      return snapshots;
+      return { snapshots, total };
     } catch {
-      return [];
+      return { snapshots: [], total: 0 };
     }
   }
   /**
@@ -1400,32 +1455,57 @@ var BackupManager = class {
     }
   }
 };
-
-// src/auth/scope-map.ts
-var toolScopeMap = /* @__PURE__ */ new Map();
-for (const [group, tools] of Object.entries(TOOL_GROUPS)) {
-  const scope = TOOL_GROUP_SCOPES[group];
-  if (scope) {
-    for (const toolName of tools) {
-      toolScopeMap.set(toolName, scope);
-      toolScopeMap.set(`sqlite_${toolName}`, scope);
+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;
 }
-function getRequiredScope(toolName) {
-  return toolScopeMap.get(toolName) ?? SCOPES.READ;
-}
-
-// src/audit/interceptor.ts
 var ALWAYS_AUDITED_SCOPES = /* @__PURE__ */ new Set(["write", "admin"]);
 function scopeToCategory(scope) {
   if (scope === "admin") return "admin";
   if (scope === "read") return "read";
   return "write";
 }
-function createAuditInterceptor(auditLogger, backupManager, queryAdapter) {
+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) {
@@ -1438,6 +1518,18 @@ function createAuditInterceptor(auditLogger, backupManager, queryAdapter) {
       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) {
@@ -1455,7 +1547,9 @@ function createAuditInterceptor(auditLogger, backupManager, queryAdapter) {
         return result;
       } catch (err) {
         success = false;
-        error = err instanceof Error ? err.message : String(err);
+        error = sanitizeErrorMessage(
+          err instanceof Error ? err.message : String(err)
+        );
         const errorResult = {
           success: false,
           error,
@@ -1495,7 +1589,7 @@ function createAuditInterceptor(auditLogger, backupManager, queryAdapter) {
             durationMs,
             success,
             error,
-            args: auditLogger.config.redact ? void 0 : args,
+            args: auditLogger.config.redact ? void 0 : redactSensitiveKeys(args),
             backup: backupRef,
             tokenEstimate
           });
@@ -1504,6 +1598,803 @@ function createAuditInterceptor(auditLogger, backupManager, queryAdapter) {
     }
   };
 }
+
+// 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
+      }
+    },
+    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
+      }
+    },
+    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
+      }
+    },
+    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();
@@ -1536,8 +2427,35 @@ var DbMcpServer = class {
       toolFilter: config.toolFilter ?? "none",
       capabilities: ["logging"]
     });
-    this.registerBuiltInTools();
-    this.registerHelpResources();
+    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);
     }
@@ -1554,6 +2472,9 @@ var DbMcpServer = class {
     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);
@@ -1561,6 +2482,15 @@ var DbMcpServer = class {
     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"
     });
@@ -1577,178 +2507,6 @@ var DbMcpServer = class {
   getAdapters() {
     return this.adapters;
   }
-  /**
-   * Register built-in server tools (health, info, etc.)
-   */
-  registerBuiltInTools() {
-    const serverInfoOpts = {
-      title: "Server Info",
-      description: "Get information about the db-mcp server and registered adapters",
-      icons: SERVER_ICONS,
-      annotations: READ_ONLY
-    };
-    this.server.registerTool("server_info", serverInfoOpts, () => {
-      const adapterInfo = [];
-      for (const [id, adapter] of this.adapters) {
-        adapterInfo.push({
-          id,
-          ...adapter.getInfo()
-        });
-      }
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              {
-                name: this.config.name,
-                version: this.config.version,
-                transport: this.config.transport,
-                adapters: adapterInfo,
-                toolFilter: {
-                  raw: this.toolFilter.raw,
-                  enabledGroups: [...this.toolFilter.enabledGroups]
-                }
-              },
-              null,
-              2
-            )
-          }
-        ]
-      };
-    });
-    const healthOpts = {
-      title: "Server Health",
-      description: "Check health status of all database connections",
-      icons: SERVER_ICONS,
-      annotations: READ_ONLY
-    };
-    this.server.registerTool("server_health", healthOpts, async () => {
-      const health = {
-        server: "healthy",
-        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        adapters: {}
-      };
-      for (const [id, adapter] of this.adapters) {
-        try {
-          const adapterHealth = await adapter.getHealth();
-          health["adapters"][id] = adapterHealth;
-        } catch (error) {
-          health["adapters"][id] = {
-            connected: false,
-            error: error instanceof Error ? error.message : "Unknown error"
-          };
-        }
-      }
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(health, null, 2)
-          }
-        ]
-      };
-    });
-    const listAdaptersOpts = {
-      title: "List Adapters",
-      description: "List all registered database adapters",
-      icons: SERVER_ICONS,
-      annotations: READ_ONLY
-    };
-    this.server.registerTool("list_adapters", listAdaptersOpts, () => {
-      const adapters = [];
-      for (const [id, adapter] of this.adapters) {
-        adapters.push({
-          id,
-          type: adapter.type,
-          name: adapter.name,
-          version: adapter.version,
-          connected: adapter.isConnected()
-        });
-      }
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(adapters, null, 2)
-          }
-        ]
-      };
-    });
-  }
-  /**
-   * Register sqlite://help resources for on-demand reference documentation.
-   * Always registers sqlite://help (gotchas). Group-specific help is filtered
-   * by the tool filter configuration.
-   */
-  registerHelpResources() {
-    const gotchasContent = HELP_CONTENT.get("gotchas");
-    if (gotchasContent) {
-      this.server.registerResource(
-        "sqlite_help",
-        "sqlite://help",
-        {
-          description: "Critical gotchas, WASM vs Native comparison, and Code Mode API reference",
-          mimeType: "text/markdown"
-        },
-        () => ({
-          contents: [
-            {
-              uri: "sqlite://help",
-              mimeType: "text/markdown",
-              text: gotchasContent
-            }
-          ]
-        })
-      );
-    }
-    const groupHelpKeys = [
-      { group: "core", key: "core" },
-      { group: "json", key: "json" },
-      { group: "text", key: "text" },
-      { group: "stats", key: "stats" },
-      { group: "vector", key: "vector" },
-      { group: "geo", key: "geo" },
-      { group: "admin", key: "admin" },
-      { group: "transactions", key: "transactions" },
-      { group: "introspection", key: "introspection" },
-      { group: "migration", key: "migration" }
-    ];
-    for (const { group, key } of groupHelpKeys) {
-      const isCodemodeOnly = this.toolFilter.enabledGroups.size === 1 && this.toolFilter.enabledGroups.has("codemode");
-      if (!this.toolFilter.enabledGroups.has(group) && !isCodemodeOnly) {
-        continue;
-      }
-      const content = HELP_CONTENT.get(key);
-      if (!content) continue;
-      this.server.registerResource(
-        `sqlite_help_${key}`,
-        `sqlite://help/${key}`,
-        {
-          description: `Tool reference for the ${group} tool group`,
-          mimeType: "text/markdown"
-        },
-        () => ({
-          contents: [
-            {
-              uri: `sqlite://help/${key}`,
-              mimeType: "text/markdown",
-              text: content
-            }
-          ]
-        })
-      );
-    }
-    const registeredHelp = ["sqlite://help"];
-    for (const { group, key } of groupHelpKeys) {
-      if (this.toolFilter.enabledGroups.has(group)) {
-        registeredHelp.push(`sqlite://help/${key}`);
-      }
-    }
-    logger.info(`Help resources: ${registeredHelp.join(", ")}`, {
-      module: "SERVER"
-    });
-  }
   /**
    * Start the server with the configured transport
    */
@@ -1777,12 +2535,16 @@ var DbMcpServer = class {
     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-6KF4ULDI.js');
+    const { HttpTransport } = await import('./http-HWTUVFIA.js');
     const oauthConfig = {
       enabled: this.config.oauth?.enabled ?? false,
       authorizationServerUrl: this.config.oauth?.authorizationServerUrl ?? "",
@@ -1810,12 +2572,13 @@ var DbMcpServer = class {
         enableHSTS: this.config.enableHSTS
       },
       oauth: oauthConfig,
-      stateless: this.config.statelessHttp ?? false
+      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 ?? "0.0.0.0";
+    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)`,
@@ -1866,179 +2629,17 @@ var DbMcpServer = class {
     }
     this.auditInterceptor = createAuditInterceptor(
       this.auditLogger,
-      this.backupManager ?? void 0);
-    this.registerAuditResource();
+      this.backupManager ?? void 0
+    );
+    registerAuditResource(this.server, this.auditLogger, this.backupManager);
     if (this.backupManager && this.toolFilter.enabledGroups.has("admin")) {
-      this.registerAuditBackupTools();
+      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" }
     );
   }
-  /**
-   * Register the sqlite://audit resource for agent access to audit log.
-   */
-  registerAuditResource() {
-    if (!this.auditLogger) return;
-    const auditLogger = this.auditLogger;
-    const backupManager = this.backupManager;
-    this.server.registerResource(
-      "sqlite_audit",
-      "sqlite://audit",
-      {
-        description: "Recent audit log entries and backup statistics. Shows the last 50 tool invocations with timing, outcomes, and token estimates.",
-        mimeType: "application/json"
-      },
-      async () => {
-        const recent = await auditLogger.recent(50);
-        const backupStats = backupManager ? await backupManager.getStats() : void 0;
-        const payload = {
-          entries: recent,
-          stats: {
-            totalEntries: recent.length,
-            ...backupStats && { backups: backupStats }
-          }
-        };
-        return {
-          contents: [
-            {
-              uri: "sqlite://audit",
-              mimeType: "application/json",
-              text: JSON.stringify(payload, null, 2)
-            }
-          ]
-        };
-      }
-    );
-  }
-  /**
-   * Register audit backup tools for snapshot management.
-   */
-  registerAuditBackupTools() {
-    const backupManager = this.backupManager;
-    if (!backupManager) return;
-    this.server.registerTool(
-      "sqlite_audit_list_backups",
-      {
-        title: "List Audit Backups",
-        description: "List pre-mutation DDL snapshots captured before destructive operations. Returns metadata for each snapshot including timestamp, tool, target, and size.",
-        annotations: {
-          readOnlyHint: true,
-          destructiveHint: false,
-          idempotentHint: true,
-          openWorldHint: false
-        }
-      },
-      async () => {
-        const snapshots = await backupManager.listSnapshots();
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  snapshots,
-                  count: snapshots.length,
-                  _meta: {
-                    tokenEstimate: Math.ceil(
-                      Buffer.byteLength(JSON.stringify(snapshots), "utf8") / 4
-                    )
-                  }
-                },
-                null,
-                2
-              )
-            }
-          ]
-        };
-      }
-    );
-    this.server.registerTool(
-      "sqlite_audit_get_backup",
-      {
-        title: "Get Audit Backup",
-        description: "Retrieve a specific pre-mutation DDL snapshot by filename. Returns the full snapshot content including DDL and optional data.",
-        inputSchema: z.object({
-          filename: z.string().describe(
-            "Snapshot filename from sqlite_audit_list_backups results"
-          )
-        }),
-        annotations: {
-          readOnlyHint: true,
-          destructiveHint: false,
-          idempotentHint: true,
-          openWorldHint: false
-        }
-      },
-      async (args) => {
-        const { filename } = args;
-        const snapshot = await backupManager.getSnapshot(filename);
-        if (!snapshot) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify(
-                  {
-                    success: false,
-                    error: `Snapshot not found: ${filename}`
-                  },
-                  null,
-                  2
-                )
-              }
-            ],
-            isError: true
-          };
-        }
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(snapshot, null, 2)
-            }
-          ]
-        };
-      }
-    );
-    this.server.registerTool(
-      "sqlite_audit_cleanup",
-      {
-        title: "Cleanup Audit Backups",
-        description: "Apply retention policy to audit backup snapshots. Deletes snapshots exceeding age or count limits.",
-        annotations: {
-          readOnlyHint: false,
-          destructiveHint: true,
-          idempotentHint: true,
-          openWorldHint: false
-        }
-      },
-      async () => {
-        const deleted = await backupManager.cleanup();
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  success: true,
-                  deletedCount: deleted,
-                  message: deleted > 0 ? `Cleaned up ${String(deleted)} snapshot(s)` : "No snapshots to clean up"
-                },
-                null,
-                2
-              )
-            }
-          ]
-        };
-      }
-    );
-    logger.info(
-      "Registered audit backup tools: sqlite_audit_list_backups, sqlite_audit_get_backup, sqlite_audit_cleanup",
-      { module: "AUDIT" }
-    );
-  }
 };
 function createServer(config) {
   return new DbMcpServer(config);