db-mcp 3.0.2 → 5.0.0

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

@@ -1,25 +1,28 @@
-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 { VERSION, NAME, READ_ONLY, SERVER_ICONS, ASSISTANT_FOCUSED, toSDK, redactObject, getRequiredScope, estimateTokens, AuditListBackupsOutputSchema, AuditListBackupsSchema, AuditGetBackupOutputSchema, AuditCleanupOutputSchema, AuditDiffBackupOutputSchema, AuditRestoreBackupOutputSchema, AuditSearchOutputSchema, AuditSearchSchema } from './chunk-2TYICG7B.js';
+import { ErrorCategory, logger, parseToolFilter, getToolFilterFromEnv, ValidationError, getFilterSummary, DbMcpError, getAuthContext, scopesGrantToolAccess, registerToolScopes, metrics, InsufficientScopeError, formatHandlerError, InternalError, sanitizeErrorMessage } from './chunk-XLIYO3YA.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 { mkdirSync } from 'fs';
+import { readdir, stat, unlink, mkdtemp, writeFile, rename, rmdir, readFile, mkdir } from 'fs/promises';
 import { gzip, gunzipSync } from 'zlib';
 import { promisify } from 'util';
 import { performance } from 'perf_hooks';
 import { z } from 'zod';
+import { SubscribeRequestSchema, UnsubscribeRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 
 // 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   |
+| Purpose            | Action                     |
+| ------------------ | -------------------------- |
+| Health check       | \`server_health\` tool       |
+| Live server health | \`sqlite://health\` resource |
+| Server info        | \`server_info\` tool         |
+| Database schema    | \`sqlite://schema\` resource |
+| Tool help          | \`sqlite://help\` resource   |
 
 ## Built-in Tools
 
@@ -31,9 +34,7 @@ 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)
+  ["admin", `# db-mcp Help \u2014 Database Administration (31N/30W tools) + Server Audit (7 tools)
 
 ## Maintenance
 
@@ -42,7 +43,7 @@ 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_dbstat(); // 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
@@ -50,6 +51,8 @@ sqlite_reindex({ target: "orders" }); // rebuild all indexes for a table
 
 ## Backup/Restore (Native only)
 
+\u26A0\uFE0F Paths must be absolute and within explicitly authorized \`ALLOWED_IO_ROOTS\`.
+
 \`\`\`javascript
 sqlite_backup({ targetPath: "/path/to/backup.db" });
 sqlite_vacuum_into({ outputPath: "/path/to/compact.db" }); // create defragmented copy
@@ -58,14 +61,16 @@ sqlite_verify_backup({ backupPath: "/path/to/backup.db" }); // check integrity w
 sqlite_restore({ sourcePath: "/path/to/backup.db" }); // \u26A0\uFE0F WARNING: Replaces current database
 \`\`\`
 
-## Audit Backups
+## Server Management & Audit
 
 \`\`\`javascript
+sqlite_server_config({ action: "set", setting: "logLevel", value: "debug" }); // get or update runtime server configuration
 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
+sqlite_audit_search({ tool: "sqlite_drop_table", limit: 10 }); // search and filter structured audit logs
 \`\`\`
 
 ## PRAGMA
@@ -76,7 +81,7 @@ 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_attach_database({ filepath: "/path/to/other.db", alias: "archive" }); // attach external DB (\u26A0\uFE0F subject to ALLOWED_IO_ROOTS)
 sqlite_detach_database({ alias: "archive" }); // detach DB
 sqlite_pragma_optimize(); // run PRAGMA optimize
 \`\`\`
@@ -132,7 +137,7 @@ sqlite_create_rtree_table({ tableName: "locations_idx", dimensions: 2 }); // 2D:
 
 ## CSV Virtual Tables (Native only)
 
-\u26A0\uFE0F Requires ABSOLUTE file paths
+\u26A0\uFE0F Requires ABSOLUTE file paths that must fall within explicitly authorized \`ALLOWED_IO_ROOTS\`.
 
 \`\`\`javascript
 sqlite_analyze_csv_schema({ filePath: "/absolute/path/to/data.csv" }); // analyze CSV structure
@@ -140,22 +145,13 @@ 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)
+\`\`\``],
+  ["core", `# db-mcp Help \u2014 Core Operations (25 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)
+- \`sqlite_read_query({ query: "SELECT * FROM users LIMIT 10", cursor: "...", stream: true, chunkSize: 10 })\` \u2014 execute SELECT, PRAGMA, EXPLAIN, or WITH statements. Supports \`cursor\` for offset-based pagination (returns \`nextCursor\`). Set \`stream: true\` to return row-by-row chunks via progress notifications instead of full response buffering (requires client progressToken support; gracefully falls back if unavailable). **Agent Tip:** Avoid \`SELECT *\` on wide tables with large text/JSON columns to conserve token context; use \`sqlite_describe_table\` first and select specific columns.
+- \`sqlite_write_query({ query: "INSERT INTO users (name) VALUES ('Alice')" })\` \u2014 execute INSERT, UPDATE, DELETE, REPLACE, or trigger DDL (CREATE/DROP TRIGGER). Supports \`expectedVersion\` for OCC.
 
 ## Tables & Schema
 
@@ -175,19 +171,30 @@ sqlite_append_insight({ insight: "Q4 revenue increased 23% YoY" }); // add to me
 - \`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
 
+## Versioning & Concurrency (OCC)
+
+- \`sqlite_enable_versioning({ table: "users" })\` \u2014 add a \`_version\` column and a BEFORE UPDATE trigger to enforce optimistic concurrency control on a table
+- \`sqlite_disable_versioning({ table: "users" })\` \u2014 remove the \`_version\` column and concurrency trigger
+- \`sqlite_check_version({ table: "users", rowId: 1 })\` \u2014 get the current \`_version\` of a row
+- \`sqlite_conditional_update({ table: "users", conditions: [{ column: "id", operator: "=", value: 1 }], expectedVersion: 2, data: { name: "Bob" } })\` \u2014 safely update a row, incrementing \`_version\` atomically. Will fail if \`expectedVersion\` does not match
+
 ## 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_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, and \`expectedVersion\` for OCC.
 - \`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])
+- \`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.
+
+## \u26A0\uFE0F Core Gotchas
+
+1. **sqlite_write_query**: DML only (INSERT/UPDATE/DELETE/REPLACE) \u2014 use \`sqlite_read_query\` for SELECT, and dedicated DDL tools for schema modifications.
+2. **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\`.
+3. **Optimistic Concurrency Control (OCC)**: When a table is versioned (\`sqlite_enable_versioning\`), you MUST supply \`expectedVersion\` to \`sqlite_write_query\`, \`sqlite_upsert\`, and \`sqlite_conditional_update\`. Omitting it will result in a \`ConflictError\` to strictly prevent lost updates.
+4. **sqlite_batch_insert**: All rows must have the same keys \u2014 inconsistent column sets across rows will cause errors or unexpected NULLs.`],
+  ["geo", `# db-mcp Help \u2014 Geospatial Operations (11N/4W: 4 basic + 7 SpatiaLite [NATIVE ONLY])
 
 ## Basic Geo (always available \u2014 Haversine formula)
 
@@ -292,35 +299,15 @@ sqlite_spatialite_index({
   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\`
+\`\`\``],
+  ["gotchas", `# db-mcp Help \u2014 Gotchas & Code Mode
+
+## Server-Level Rules
+
+1. **CSV virtual tables & Backups**: Require ABSOLUTE file paths. Operations will be strictly blocked if paths do not fall within the explicitly authorized \`ALLOWED_IO_ROOTS\` directory list. Unconfigured stdio transports default to no filesystem access.
+2. **Resource Subscriptions**: The \`sqlite://schema\` and \`sqlite://health\` resources support MCP subscriptions, allowing the client to receive real-time push notifications when DDL changes occur or health metrics update without needing to poll.
+3. **HTTP Session Timeouts**: Stateful HTTP sessions automatically expire after 30 minutes of inactivity, or 24 hours total. Sessions are swept automatically; ensure client workflows re-authenticate or handle broken sessions gracefully.
+4. **Structured Errors**: The server returns strongly-typed JSON errors instead of generic stack traces. Execution timeouts surface as recoverable \`TimeoutError\` (category: \`timeout\`). Rate limit violations surface as \`RateLimitError\` (category: \`rate_limit\`). Input/schema rejections surface as \`ValidationError\` (category: \`validation\`). Use this metadata (\`code\`, \`category\`, \`recoverable\`) to programmatically retry or backoff.
 
 ## WASM vs Native
 
@@ -333,6 +320,7 @@ sqlite_spatialite_index({
 | 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   |
+| SQLCipher Encryption at Rest                      | \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               |
@@ -346,22 +334,19 @@ 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\`
+**Groups**: \`sqlite.core\`, \`sqlite.json\`, \`sqlite.text\`, \`sqlite.stats\`, \`sqlite.vector\`, \`sqlite.admin\`, \`sqlite.transactions\` (Native-only), \`sqlite.geo\`, \`sqlite.introspection\`, \`sqlite.migration\` (opt-in)
 
 > **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()\`
+Code Mode maps standard tools to an object-oriented sandbox API (\`sqlite_group_action\` \u2192 \`sqlite.group.action()\`).
 
-**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)
+- **Flexible Parameters**: Parameters are forgiven for casing discrepancies (e.g. \`conflict_columns\` vs \`conflictColumns\`).
+- **Flexible Methods**: Methods mapped into the Code Mode proxy forgive casing discrepancies (e.g. \`sqlite.core.read_query\` executes \`sqlite.core.readQuery()\`).
+- Methods support both an options object and **positional arguments** (e.g. \`sqlite.core.readQuery("SELECT...")\`, \`sqlite.json.insert("docs", "data", {...})\`).
+- **Discovery**: Call \`sqlite.help()\` or \`sqlite.core.help()\` to see available methods directly within the sandbox.`],
+  ["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.
 
@@ -434,6 +419,13 @@ 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
+// Run EXPLAIN QUERY PLAN on target queries to recommend composite/partial indexes
+sqlite_index_audit({
+  recommendComposite: true,
+  queriesToAnalyze: [
+    "SELECT * FROM orders WHERE user_id = 1 AND status = 'active'",
+  ],
+});
 
 // EXPLAIN QUERY PLAN with scan-type classification and optimization suggestions (SELECT/WITH only)
 sqlite_query_plan({ sql: "SELECT * FROM orders WHERE status = 'active'" });
@@ -442,11 +434,9 @@ 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)
+- \`sqlite_migration_risks\` analyzes DDL text statically \u2014 it does NOT execute the statements
+- \`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.`],
+  ["json", `# db-mcp Help \u2014 JSON Operations (25 tools)
 
 ## Collection & CRUD
 
@@ -520,11 +510,8 @@ sqlite_json_group_object({
 
 - \`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)
+- \`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.
 
@@ -566,11 +553,8 @@ 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])
+- 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)
 
@@ -689,11 +673,8 @@ sqlite_window_moving_avg({
   windowSize: 7,
   selectColumns: ["date"],
 });
-\`\`\``
-  ],
-  [
-    "text",
-    `# db-mcp Help \u2014 Text Processing & FTS5 (19N/14W: 14 text + 5 FTS5 [NATIVE ONLY])
+\`\`\``],
+  ["text", `# db-mcp Help \u2014 Text Processing & FTS5 (20N/15W: 15 text + 5 FTS5 [NATIVE ONLY])
 
 ## Full-Text Search / FTS5 (5 tools, Native only)
 
@@ -713,6 +694,8 @@ sqlite_fts_search({
   table: "articles_fts",
   query: "machine learning",
   limit: 10,
+  includeFacets: true, // optionally return breakdown by technique
+  cursor: "...", // Optional offset-based cursor for pagination (returns nextCursor)
 });
 sqlite_fts_match_info({ table: "articles_fts", query: "machine learning" }); // bm25 ranking info
 
@@ -732,7 +715,7 @@ sqlite_fts_headline({
 
 \u26A0\uFE0F FTS5 virtual tables (\`*_fts\`) and shadow tables (\`*_fts_*\`) are hidden from \`sqlite_list_tables\` for cleaner output
 
-## Text Processing (14 tools)
+## Text Processing (15 tools)
 
 \`\`\`javascript
 // Regex patterns: \u26A0\uFE0F Double-escape backslashes (\\\\) when passing through JSON/MCP
@@ -818,7 +801,19 @@ sqlite_advanced_search({
   searchTerm: "laptop",
   techniques: ["exact", "fuzzy", "phonetic"],
   fuzzyThreshold: 0.4,
+  includeFacets: true,
+});
+
+// Hybrid Search \u2014 combines FTS5 text search and vector embedding search via Reciprocal Rank Fusion (RRF)
+sqlite_hybrid_search({
+  table: "articles_fts",
+  query: "machine learning",
+  vectorColumn: "embedding",
+  queryVector: [0.1, 0.2, 0.3], // vector data from external embedding API
+  metric: "cosine",
+  limit: 10,
 });
+// \u26A0\uFE0F Requires an FTS5 table (Native only) and a vector column in the source table
 
 // Sentiment analysis \u2014 text analysis (can analyze raw text or database columns)
 sqlite_text_sentiment({ text: "This product is amazing and wonderful!" });
@@ -831,11 +826,8 @@ sqlite_text_sentiment({
   returnWords: true,
 });
 // \u2192 { sentiment: "neutral", score: 0, matchedPositive: ["great"], matchedNegative: ["slow"] }
-\`\`\``
-  ],
-  [
-    "transactions",
-    `# db-mcp Help \u2014 Transactions (8 tools, Native only)
+\`\`\``],
+  ["transactions", `# db-mcp Help \u2014 Transactions (8 tools, Native only)
 
 ## Atomic Execution (preferred for simple cases)
 
@@ -866,11 +858,8 @@ sqlite_transaction_status(); // \u2192 { status: "active" | "none", active: true
 
 - 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)
+- \`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
@@ -896,24 +885,29 @@ sqlite_vector_stats({ table: "docs", vectorColumn: "emb" }); // returns sampleSi
 // 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> }
-\`\`\``
-  ]
+\`\`\`
+
+## \u26A0\uFE0F Vector Gotchas
+
+- **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\`).`]
 ]);
+
+// src/audit/logger.ts
 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) {
+  systemDb;
+  constructor(config, systemDb = null) {
     this.config = config;
+    this.systemDb = systemDb;
     this.stderrMode = config.logPath.toLowerCase() === STDERR_SENTINEL;
     if (config.enabled) {
       this.flushTimer = setInterval(() => {
@@ -923,39 +917,27 @@ var AuditLogger = class {
     }
   }
   /**
-   * 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.
+   * Initialization is handled externally by SystemDb.
    */
-  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;
-    }
+  init() {
+    if (this.stderrMode || !this.config.enabled) return Promise.resolve();
+    return Promise.resolve();
   }
   /**
    * 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.
+   * Non-blocking — the entry is queued; the
+   * actual DB 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));
+    this.buffer.push(safeEntry);
     if (this.buffer.length >= BUFFER_HIGH_WATER) {
       void this.flush();
     }
   }
   /**
-   * Flush the buffer to disk.
+   * Flush the buffer to SystemDb or stderr.
    * Safe to call concurrently — serialises via `this.activeFlush` Promise.
    */
   async flush() {
@@ -965,25 +947,45 @@ var AuditLogger = class {
     }
     if (this.buffer.length === 0) return;
     const doFlush = async () => {
-      await this.rotateIfNeeded();
-      const lines = this.buffer;
+      await Promise.resolve();
+      const entries = this.buffer;
       this.buffer = [];
       try {
         if (this.stderrMode) {
+          const lines = entries.map((e) => JSON.stringify(e));
           process.stderr.write(lines.join("\n") + "\n");
-        } else {
-          await this.ensureDirectory();
-          await appendFile(
-            this.config.logPath,
-            lines.join("\n") + "\n",
-            "utf-8"
-          );
+        } else if (this.systemDb) {
+          const db = this.systemDb.getDb();
+          const stmt = db.prepare(`
+            INSERT INTO audit_logs (timestamp, requestId, tool, category, scope, user, scopesJson, durationMs, success, tokenEstimate, error, argsJson, backupPath)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          `);
+          const transaction = db.transaction((logs) => {
+            for (const log of logs) {
+              stmt.run(
+                log.timestamp,
+                log.requestId,
+                log.tool,
+                log.category,
+                log.scope,
+                log.user ?? null,
+                JSON.stringify(log.scopes),
+                log.durationMs,
+                log.success ? 1 : 0,
+                log.tokenEstimate ?? null,
+                log.error ?? null,
+                log.args ? JSON.stringify(log.args) : null,
+                log.backup ?? null
+              );
+            }
+          });
+          transaction(entries);
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         process.stderr.write(`[AUDIT] Write failed: ${message}
 `);
-        this.buffer.unshift(...lines);
+        this.buffer.unshift(...entries);
       }
     };
     this.activeFlush = doFlush();
@@ -1005,79 +1007,197 @@ var AuditLogger = class {
     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)
+   * Read the most recent audit entries from the SystemDb.
+   * Retrieve recent entries directly from the SystemDb.
    */
-  async recent(count = DEFAULT_RECENT_COUNT) {
-    if (this.stderrMode) return [];
+  async recent(limit = DEFAULT_RECENT_COUNT) {
+    if (this.stderrMode || !this.systemDb) {
+      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();
-      }
+      const db = this.systemDb.getDb();
+      const rows = db.prepare(
+        `
+        SELECT * FROM audit_logs
+        ORDER BY timestamp DESC
+        LIMIT ?
+      `
+      ).all(limit);
+      return rows.map((row) => ({
+        timestamp: row.timestamp,
+        requestId: row.requestId,
+        tool: row.tool,
+        category: row.category,
+        scope: row.scope,
+        user: row.user,
+        scopes: row.scopesJson ? JSON.parse(row.scopesJson) : [],
+        durationMs: row.durationMs,
+        success: row.success === 1,
+        tokenEstimate: row.tokenEstimate ?? void 0,
+        error: row.error ?? void 0,
+        args: row.argsJson ? JSON.parse(row.argsJson) : void 0,
+        backup: row.backupPath ?? void 0
+      }));
     } catch {
       return [];
     }
   }
   /**
-   * Ensure the parent directory of the log file exists.
+   * Search and filter audit entries from the SystemDb.
    */
-  async ensureDirectory() {
-    if (this.dirEnsured) return;
+  async search(filters) {
+    if (this.stderrMode || !this.systemDb) {
+      return { entries: [], totalCount: 0 };
+    }
+    await this.flush();
     try {
-      await mkdir(dirname(this.config.logPath), { recursive: true });
-      this.dirEnsured = true;
+      const db = this.systemDb.getDb();
+      let sql = "SELECT * FROM audit_logs WHERE 1=1";
+      let countSql = "SELECT COUNT(*) as c FROM audit_logs WHERE 1=1";
+      const params = [];
+      if (filters.tool) {
+        sql += " AND tool = ?";
+        countSql += " AND tool = ?";
+        params.push(filters.tool);
+      }
+      if (filters.category) {
+        sql += " AND category = ?";
+        countSql += " AND category = ?";
+        params.push(filters.category);
+      }
+      if (filters.success !== void 0) {
+        sql += " AND success = ?";
+        countSql += " AND success = ?";
+        params.push(filters.success ? 1 : 0);
+      }
+      if (filters.requestId) {
+        sql += " AND requestId = ?";
+        countSql += " AND requestId = ?";
+        params.push(filters.requestId);
+      }
+      if (filters.fromTimestamp) {
+        sql += " AND timestamp >= ?";
+        countSql += " AND timestamp >= ?";
+        params.push(filters.fromTimestamp);
+      }
+      if (filters.toTimestamp) {
+        sql += " AND timestamp <= ?";
+        countSql += " AND timestamp <= ?";
+        params.push(filters.toTimestamp);
+      }
+      const totalCount = db.prepare(countSql).get(...params).c;
+      sql += " ORDER BY timestamp DESC LIMIT ? OFFSET ?";
+      params.push(filters.limit ?? 50);
+      params.push(filters.offset ?? 0);
+      const rows = db.prepare(sql).all(...params);
+      const entries = rows.map((row) => ({
+        timestamp: row.timestamp,
+        requestId: row.requestId,
+        tool: row.tool,
+        category: row.category,
+        scope: row.scope,
+        user: row.user,
+        scopes: row.scopesJson ? JSON.parse(row.scopesJson) : [],
+        durationMs: row.durationMs,
+        success: row.success === 1,
+        tokenEstimate: row.tokenEstimate ?? void 0,
+        error: row.error ?? void 0,
+        args: row.argsJson ? JSON.parse(row.argsJson) : void 0,
+        backup: row.backupPath ?? void 0
+      }));
+      return { entries, totalCount };
     } catch {
-      this.dirEnsured = true;
+      return { entries: [], totalCount: 0 };
     }
   }
-  /**
-   * 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;
+};
+var SystemDb = class {
+  db = null;
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  async init() {
     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 encryptionKey = process.env["DB_ENCRYPTION_KEY"];
+      let BetterSqlite3;
+      if (encryptionKey) {
+        BetterSqlite3 = (await import('better-sqlite3-multiple-ciphers')).default;
+      } else {
+        BetterSqlite3 = (await import('better-sqlite3')).default;
       }
-      const rotatedPath = `${this.config.logPath}.1`;
-      await rename(this.config.logPath, rotatedPath);
-    } catch {
+      if (this.config.dbPath !== ":memory:") {
+        mkdirSync(dirname(this.config.dbPath), { recursive: true });
+      }
+      this.db = new BetterSqlite3(this.config.dbPath);
+      if (encryptionKey && this.config.dbPath !== ":memory:" && this.config.dbPath !== "") {
+        const escapedKey = encryptionKey.replace(/"/g, '""');
+        this.db.pragma(`key = "${escapedKey}"`);
+      }
+      this.db.pragma("journal_mode = WAL");
+      this.db.pragma("synchronous = NORMAL");
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS audit_logs (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          timestamp TEXT NOT NULL,
+          requestId TEXT NOT NULL,
+          tool TEXT NOT NULL,
+          category TEXT NOT NULL,
+          scope TEXT NOT NULL,
+          user TEXT,
+          durationMs INTEGER NOT NULL,
+          success INTEGER NOT NULL,
+          tokenEstimate INTEGER,
+          error TEXT,
+          argsJson TEXT,
+          scopesJson TEXT,
+          backupPath TEXT
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_timestamp ON audit_logs(timestamp);
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_tool ON audit_logs(tool);
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_category ON audit_logs(category);
+        CREATE INDEX IF NOT EXISTS idx_audit_logs_success ON audit_logs(success);
+
+        CREATE TABLE IF NOT EXISTS metrics_snapshots (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          timestamp TEXT NOT NULL,
+          tool TEXT NOT NULL,
+          calls INTEGER NOT NULL,
+          errors INTEGER NOT NULL,
+          p50 INTEGER NOT NULL,
+          p95 INTEGER NOT NULL,
+          p99 INTEGER NOT NULL,
+          tokens INTEGER NOT NULL
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_metrics_snapshots_timestamp ON metrics_snapshots(timestamp);
+      `);
+      logger.info(`System database initialized at ${this.config.dbPath}`, {
+        module: "SYSTEM_DB"
+      });
+    } catch (err) {
+      logger.error(
+        "Failed to initialize SystemDb. better-sqlite3 may not be installed.",
+        {
+          module: "SYSTEM_DB",
+          error: err instanceof Error ? err : new Error(String(err))
+        }
+      );
+      throw err;
+    }
+  }
+  getDb() {
+    if (!this.db) {
+      throw new InternalError("SystemDb not initialized");
+    }
+    return this.db;
+  }
+  close() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
     }
   }
 };
@@ -1538,11 +1658,14 @@ function createAuditInterceptor(auditLogger, backupManager) {
               ...result,
               _meta: { tokenEstimate: 0 }
             });
-            tokenEstimate = Math.ceil(Buffer.byteLength(json, "utf8") / 4);
+            tokenEstimate = estimateTokens(json, "json");
           } catch {
           }
         } else if (typeof result === "string") {
-          tokenEstimate = Math.ceil(Buffer.byteLength(result, "utf8") / 4);
+          const isSql = /^\s*(?:SELECT|INSERT|UPDATE|DELETE|WITH|CREATE|ALTER|DROP|PRAGMA)\b/i.test(
+            result
+          );
+          tokenEstimate = estimateTokens(result, isSql ? "sql" : "text");
         }
         return result;
       } catch (err) {
@@ -1561,10 +1684,16 @@ function createAuditInterceptor(auditLogger, backupManager) {
           ...errorResult,
           _meta: { tokenEstimate: 0 }
         });
-        tokenEstimate = Math.ceil(Buffer.byteLength(enriched, "utf8") / 4);
+        tokenEstimate = estimateTokens(enriched, "json");
         throw err;
       } finally {
         const durationMs = Math.round(performance.now() - start);
+        metrics.recordToolCall(
+          options?.logAs ?? toolName,
+          durationMs,
+          success,
+          tokenEstimate ?? 0
+        );
         if (isReadScope) {
           auditLogger.log({
             timestamp: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1599,280 +1728,95 @@ function createAuditInterceptor(auditLogger, backupManager) {
   };
 }
 
-// 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
-          )
+// src/server/registration/audit-tools/helpers.ts
+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 ValidationError(
+      `DDL validation failed: unauthorized command or function call`
+    );
+  }
+  if (upperSql.includes(" ON MAIN.") || upperSql.includes(" ON TEMP.")) {
+    throw new ValidationError(
+      `DDL validation failed: trigger attempts to target a specific database`
+    );
+  }
+}
+
+// src/server/registration/audit-tools/resource.ts
+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 () => {
+      metrics.recordResourceRead("sqlite://audit");
+      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 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 payloadStr = JSON.stringify(payload, null, 2);
+      return {
+        contents: [
+          {
+            uri: "sqlite://audit",
+            mimeType: "application/json",
+            text: redactSqlLiterals(payloadStr)
+          }
+        ]
+      };
     }
-    const health = {
-      server: "healthy",
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      adapters: {}
-    };
-    for (const [id, adapter] of adaptersMap) {
+  );
+}
+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: toSDK({
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+        sensitiveHint: true
+      })
+    },
+    async (args) => {
+      const authCtx = getAuthContext();
+      if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_audit_list_backups")) {
+        throw new InsufficientScopeError(["admin", "full"], authCtx.scopes);
+      }
+      let parsed;
       try {
-        const adapterHealth = await adapter.getHealth();
-        health["adapters"][id] = adapterHealth;
+        parsed = AuditListBackupsSchema.parse(args ?? {});
       } 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 structured = formatHandlerError(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(structured, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: structured
         };
       }
       const limit = parsed.limit ?? 10;
@@ -1914,12 +1858,13 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
         filename: z.string().default("").describe("Snapshot filename from sqlite_audit_list_backups results")
       }),
       outputSchema: AuditGetBackupOutputSchema,
-      annotations: {
+      annotations: toSDK({
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
-        openWorldHint: false
-      }
+        openWorldHint: false,
+        sensitiveHint: true
+      })
     },
     async (args) => {
       const authCtx = getAuthContext();
@@ -1947,7 +1892,9 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
       if (!snapshot) {
         const errRes = {
           success: false,
-          error: `Snapshot not found: ${filename}`
+          error: `Snapshot not found: ${filename}`,
+          code: "NOT_FOUND",
+          category: "not_found"
         };
         return {
           content: [
@@ -1979,12 +1926,13 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
       title: "Cleanup Audit Backups",
       description: "Apply retention policy to audit backup snapshots. Deletes snapshots exceeding age or count limits.",
       outputSchema: AuditCleanupOutputSchema,
-      annotations: {
+      annotations: toSDK({
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: true,
-        openWorldHint: false
-      }
+        openWorldHint: false,
+        sensitiveHint: true
+      })
     },
     async () => {
       const authCtx = getAuthContext();
@@ -2019,12 +1967,13 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
         )
       }),
       outputSchema: AuditDiffBackupOutputSchema,
-      annotations: {
+      annotations: toSDK({
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
-        openWorldHint: false
-      }
+        openWorldHint: false,
+        sensitiveHint: true
+      })
     },
     async (args) => {
       const authCtx = getAuthContext();
@@ -2052,7 +2001,9 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
       if (!snapshot) {
         const errRes = {
           success: false,
-          error: `Snapshot not found: ${filename}`
+          error: `Snapshot not found: ${filename}`,
+          code: "NOT_FOUND",
+          category: "not_found"
         };
         return {
           content: [
@@ -2069,7 +2020,9 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
       if (!adapter) {
         const errRes = {
           success: false,
-          error: "No connected adapter available"
+          error: "No connected adapter available",
+          code: "INTERNAL_ERROR",
+          category: "internal"
         };
         return {
           content: [
@@ -2158,19 +2111,16 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
           structuredContent: result
         };
       } catch (error) {
-        const errRes = {
-          success: false,
-          error: error instanceof Error ? error.message : String(error)
-        };
+        const structured = formatHandlerError(error);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(errRes, null, 2)
+              text: JSON.stringify(structured, null, 2)
             }
           ],
           isError: true,
-          structuredContent: errRes
+          structuredContent: structured
         };
       }
     }
@@ -2185,12 +2135,13 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
         dryRun: z.unknown().optional().describe("If true, returns the DDL without executing it (boolean)")
       }),
       outputSchema: AuditRestoreBackupOutputSchema,
-      annotations: {
+      annotations: toSDK({
         readOnlyHint: false,
         destructiveHint: true,
         idempotentHint: false,
-        openWorldHint: false
-      }
+        openWorldHint: false,
+        sensitiveHint: true
+      })
     },
     async (args) => {
       const authCtx = getAuthContext();
@@ -2223,7 +2174,9 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
       if (!snapshot) {
         const errRes = {
           success: false,
-          error: `Snapshot not found: ${filename}`
+          error: `Snapshot not found: ${filename}`,
+          code: "NOT_FOUND",
+          category: "not_found"
         };
         return {
           content: [
@@ -2240,7 +2193,9 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
       if (!ddl.trim()) {
         const errRes = {
           success: false,
-          error: "Snapshot contains no DDL statements"
+          error: "Snapshot contains no DDL statements",
+          code: "VALIDATION_ERROR",
+          category: "validation"
         };
         return {
           content: [
@@ -2257,7 +2212,9 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
       if (!adapter) {
         const errRes = {
           success: false,
-          error: "No connected adapter available"
+          error: "No connected adapter available",
+          code: "INTERNAL_ERROR",
+          category: "internal"
         };
         return {
           content: [
@@ -2334,19 +2291,16 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
           structuredContent: result
         };
       } catch (error) {
-        const errRes = {
-          success: false,
-          error: error instanceof Error ? error.message : String(error)
-        };
+        const structured = formatHandlerError(error);
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(errRes, null, 2)
+              text: JSON.stringify(structured, null, 2)
             }
           ],
           isError: true,
-          structuredContent: errRes
+          structuredContent: structured
         };
       }
     }
@@ -2366,46 +2320,626 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
   );
 }
 
-// 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: "
+// src/server/registration/audit-tools/search.ts
+function registerAuditSearchTool(server, auditLogger) {
+  if (!auditLogger) return;
+  server.registerTool(
+    "sqlite_audit_search",
+    {
+      title: "Search Audit Log",
+      description: "Search and filter structured audit logs from the System Database. Returns recent tool invocations, outcomes, token estimates, and parameters.",
+      inputSchema: AuditSearchSchema,
+      outputSchema: AuditSearchOutputSchema,
+      annotations: toSDK({
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+        sensitiveHint: true
+      })
+    },
+    async (args) => {
+      try {
+        const authCtx = getAuthContext();
+        if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_audit_search")) {
+          throw new InsufficientScopeError(["admin", "full"], authCtx.scopes);
+        }
+        const parsed = AuditSearchSchema.parse(args ?? {});
+        const { entries, totalCount } = await auditLogger.search(parsed);
+        const result = {
+          success: true,
+          entries,
+          count: entries.length,
+          totalCount
+        };
+        const tokenEstimate = Math.ceil(
+          Buffer.byteLength(JSON.stringify(result), "utf8") / 4
         );
-        const structured = {
-          success: false,
-          error: cleanError,
-          code: "VALIDATION_ERROR",
-          category: "validation" /* VALIDATION */
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { ...result, _meta: { tokenEstimate } },
+                null,
+                2
+              )
+            }
+          ],
+          structuredContent: result
         };
-        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;
+      } catch (error) {
+        const structured = formatHandlerError(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(structured, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: structured
+        };
+      }
+    }
+  );
+  registerToolScopes(/* @__PURE__ */ new Map([["sqlite_audit_search", ["admin", "full"]]]));
+  logger.info("Registered audit search tool: sqlite_audit_search", {
+    module: "AUDIT"
+  });
+}
+
+// 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
+      },
+      () => {
+        metrics.recordResourceRead("sqlite://help");
+        return {
+          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
+      },
+      () => {
+        metrics.recordResourceRead(`sqlite://help/${key}`);
+        return {
+          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"
+  });
+}
+
+// src/server/registration/observability-resources.ts
+function registerObservabilityResources(server) {
+  server.registerResource(
+    "sqlite://metrics",
+    "sqlite://metrics",
+    {
+      description: "Returns in-memory streaming metrics including p50/p95/p99 latency percentiles and token usage.",
+      mimeType: "application/json"
+    },
+    () => {
+      const summary = metrics.getSummary();
+      return {
+        contents: [
+          {
+            uri: "sqlite://metrics",
+            mimeType: "application/json",
+            text: JSON.stringify(summary, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+function registerAdminTools(server) {
+  server.registerTool(
+    "sqlite_server_config",
+    {
+      title: "Server Configuration",
+      description: "Get or update runtime configuration values for the server. Currently supports updating the log level.",
+      inputSchema: z.object({
+        action: z.enum(["get", "set"]).describe("Whether to get or set the configuration value"),
+        setting: z.enum(["logLevel"]).optional().describe("The setting to modify"),
+        value: z.string().optional().describe(
+          "The new value for the setting (e.g., 'debug', 'info', 'warning')"
+        )
+      }),
+      annotations: toSDK({
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+        sensitiveHint: true
+      })
+    },
+    (args) => {
+      const authCtx = getAuthContext();
+      if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_server_config")) {
+        throw new InsufficientScopeError(["admin"], authCtx.scopes);
+      }
+      try {
+        const parsed = z.object({
+          action: z.enum(["get", "set"]),
+          setting: z.enum(["logLevel"]).optional(),
+          value: z.string().optional()
+        }).parse(args ?? {});
+        const { action, setting, value } = parsed;
+        if (action === "get") {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: true,
+                    config: {
+                      logLevel: logger.getLevel()
+                    }
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        if (action === "set") {
+          if (setting === "logLevel" && value) {
+            const validLevels = [
+              "debug",
+              "info",
+              "notice",
+              "warning",
+              "error",
+              "critical",
+              "alert",
+              "emergency"
+            ];
+            if (!validLevels.includes(value.toLowerCase())) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: JSON.stringify(
+                      {
+                        success: false,
+                        error: `Invalid log level: ${value}. Must be one of: ${validLevels.join(", ")}`,
+                        code: "INVALID_CONFIG",
+                        category: "validation"
+                      },
+                      null,
+                      2
+                    )
+                  }
+                ],
+                isError: true
+              };
+            }
+            logger.setLevel(value.toLowerCase());
+            logger.info(
+              `Log level dynamically changed to ${value} via sqlite_server_config tool`,
+              {
+                module: "SERVER"
+              }
+            );
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify(
+                    {
+                      success: true,
+                      message: `Log level successfully updated to ${value}`
+                    },
+                    null,
+                    2
+                  )
+                }
+              ]
+            };
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: false,
+                    error: "Missing setting or value for set action",
+                    code: "INVALID_CONFIG",
+                    category: "validation"
+                  },
+                  null,
+                  2
+                )
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                success: false,
+                error: "Invalid action",
+                code: "INVALID_CONFIG",
+                category: "validation"
+              })
+            }
+          ],
+          isError: true
+        };
+      } catch (error) {
+        const structured = formatHandlerError(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(structured, null, 2)
+            }
+          ],
+          isError: true,
+          structuredContent: structured
+        };
+      }
+    }
+  );
+  registerToolScopes(/* @__PURE__ */ new Map([["sqlite_server_config", ["admin"]]]));
+}
+
+// src/server/subscription-manager.ts
+var SubscriptionManager = class {
+  server;
+  // Map of URI string -> Set of Session IDs
+  subscriptions = /* @__PURE__ */ new Map();
+  constructor(server) {
+    this.server = server;
+  }
+  /**
+   * Subscribe a session to a resource URI.
+   */
+  subscribe(uri, sessionId) {
+    if (!sessionId) {
+      logger.debug(
+        `Subscription requested for ${uri} but no sessionId provided. Assuming stateless transport.`
+      );
+      return;
+    }
+    let sessions = this.subscriptions.get(uri);
+    if (!sessions) {
+      sessions = /* @__PURE__ */ new Set();
+      this.subscriptions.set(uri, sessions);
+    }
+    if (!sessions.has(sessionId)) {
+      sessions.add(sessionId);
+      logger.debug(`Session ${sessionId} subscribed to resource ${uri}`, {
+        module: "SERVER"
+      });
+    }
+  }
+  /**
+   * Unsubscribe a session from a resource URI.
+   */
+  unsubscribe(uri, sessionId) {
+    if (!sessionId) {
+      return;
+    }
+    const sessions = this.subscriptions.get(uri);
+    if (sessions?.has(sessionId)) {
+      sessions.delete(sessionId);
+      logger.debug(`Session ${sessionId} unsubscribed from resource ${uri}`, {
+        module: "SERVER"
+      });
+      if (sessions.size === 0) {
+        this.subscriptions.delete(uri);
+      }
+    }
+  }
+  /**
+   * Unsubscribe a session from all resources (useful on transport disconnect).
+   */
+  unsubscribeSession(sessionId) {
+    let count = 0;
+    for (const [uri, sessions] of this.subscriptions.entries()) {
+      if (sessions.has(sessionId)) {
+        sessions.delete(sessionId);
+        count++;
+        if (sessions.size === 0) {
+          this.subscriptions.delete(uri);
+        }
+      }
+    }
+    if (count > 0) {
+      logger.debug(
+        `Session ${sessionId} disconnected, removed ${count} subscriptions`,
+        { module: "SERVER" }
+      );
+    }
+  }
+  /**
+   * Notifies all subscribed clients that a resource has changed.
+   */
+  async notifyResourceUpdated(uri) {
+    if (!this.hasSubscribers(uri)) {
+      return;
+    }
+    try {
+      await this.server.server.sendResourceUpdated({ uri });
+      logger.debug(`Notified subscribers of update to ${uri}`, {
+        module: "SERVER"
+      });
+    } catch (error) {
+      logger.error(`Failed to notify subscribers for ${uri}`, {
+        module: "SERVER",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Notifies subscribers of schema-related resources (schema, tables, and specific tables).
+   */
+  async notifySchemaSubscribers() {
+    const urisToNotify = /* @__PURE__ */ new Set([
+      "sqlite://schema",
+      "sqlite://tables"
+    ]);
+    for (const uri of this.subscriptions.keys()) {
+      if (uri.startsWith("sqlite://table/")) {
+        urisToNotify.add(uri);
+      }
+    }
+    const promises = Array.from(urisToNotify).map(
+      (uri) => this.notifyResourceUpdated(uri)
+    );
+    await Promise.allSettled(promises);
+  }
+  /**
+   * Check if there are any active subscribers for a specific URI.
+   */
+  hasSubscribers(uri) {
+    const sessions = this.subscriptions.get(uri);
+    return sessions ? sessions.size > 0 : false;
+  }
+};
+
+// 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: ErrorCategory.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;
+  systemDb = null;
   auditInterceptor = null;
   auditInitPromise = null;
+  subscriptionManager;
   constructor(config) {
     this.config = config;
+    let allowedIoRoots = config.allowedIoRoots;
+    if (!allowedIoRoots) {
+      if (config.transport === "http") {
+        const errorMsg = `FATAL: Refusing to bind HTTP transport without explicit ALLOWED_IO_ROOTS. You MUST specify --allowed-io-roots (or ALLOWED_IO_ROOTS env var) to prevent ambient filesystem authority.`;
+        logger.error(errorMsg, { module: "SERVER" });
+        process.exit(1);
+      }
+      allowedIoRoots = [];
+      logger.warning(
+        "\u26A0\uFE0F SECURITY WARNING: ALLOWED_IO_ROOTS not explicitly provided. Defaulting to empty array (NO filesystem access). You MUST specify --allowed-io-roots (or ALLOWED_IO_ROOTS env var) to enable filesystem tools.",
+        { module: "SERVER" }
+      );
+    } else {
+      logger.info("IO sandbox configured", {
+        module: "SERVER",
+        allowedRoots: allowedIoRoots
+      });
+    }
+    this.config.allowedIoRoots = allowedIoRoots;
     this.toolFilter = config.toolFilter ? parseToolFilter(config.toolFilter) : getToolFilterFromEnv();
     this.server = new McpServer(
       {
@@ -2419,6 +2953,48 @@ var DbMcpServer = class {
         instructions: INSTRUCTIONS
       }
     );
+    this.subscriptionManager = new SubscriptionManager(this.server);
+    this.server.subscriptionManager = this.subscriptionManager;
+    this.server.server.registerCapabilities({
+      resources: {
+        subscribe: true
+      }
+    });
+    this.server.server.setRequestHandler(
+      SubscribeRequestSchema,
+      (request, extra) => {
+        const uri = request.params.uri;
+        let sessionId = extra.sessionId ?? extra.requestInfo?.headers["mcp-session-id"] ?? void 0;
+        if (sessionId === void 0 && this.config.transport === "stdio") {
+          sessionId = "stdio";
+        }
+        if (!["sqlite://schema", "sqlite://tables", "sqlite://health"].includes(
+          uri
+        ) && !uri.startsWith("sqlite://table/")) {
+          throw new ValidationError(`Resource ${uri} is not subscribable`);
+        }
+        this.subscriptionManager.subscribe(
+          uri,
+          sessionId
+        );
+        return {};
+      }
+    );
+    this.server.server.setRequestHandler(
+      UnsubscribeRequestSchema,
+      (request, extra) => {
+        const uri = request.params.uri;
+        let sessionId = extra.sessionId ?? extra.requestInfo?.headers["mcp-session-id"] ?? void 0;
+        if (sessionId === void 0 && this.config.transport === "stdio") {
+          sessionId = "stdio";
+        }
+        this.subscriptionManager.unsubscribe(
+          uri,
+          sessionId
+        );
+        return {};
+      }
+    );
     logger.info(getFilterSummary(this.toolFilter), { module: "FILTER" });
     logger.info("MCP Server initialized", {
       module: "SERVER",
@@ -2434,13 +3010,17 @@ var DbMcpServer = class {
       this.toolFilter
     );
     registerHelpResources(this.server, this.toolFilter);
+    registerObservabilityResources(this.server);
+    if (this.toolFilter.enabledGroups.has("admin")) {
+      registerAdminTools(this.server);
+    }
     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 */
+        ErrorCategory.INTERNAL
       );
     }
     const originalListToolsHandler = handlers.get("tools/list");
@@ -2459,6 +3039,11 @@ var DbMcpServer = class {
     if (config.audit?.enabled) {
       this.auditInitPromise = this.initializeAudit(config);
     }
+    setInterval(() => {
+      if (this.subscriptionManager.hasSubscribers("sqlite://health")) {
+        void this.subscriptionManager.notifyResourceUpdated("sqlite://health");
+      }
+    }, 6e4).unref();
   }
   /**
    * Register a database adapter
@@ -2470,6 +3055,9 @@ var DbMcpServer = class {
     }
     await adapter.connect(config);
     this.adapters.set(adapterId, adapter);
+    if ("setAllowedIoRoots" in adapter) {
+      adapter.setAllowedIoRoots(this.config.allowedIoRoots);
+    }
     if (this.auditInterceptor && "setAuditInterceptor" in adapter) {
       adapter.setAuditInterceptor(this.auditInterceptor);
       this.auditInterceptor.setQueryAdapter({
@@ -2482,6 +3070,9 @@ var DbMcpServer = class {
     adapter.registerTools(this.server, this.toolFilter);
     adapter.registerResources(this.server);
     adapter.registerPrompts(this.server);
+    adapter.on("schemaChanged", () => {
+      void this.subscriptionManager.notifySchemaSubscribers();
+    });
     const toolDefs = adapter.getToolDefinitions();
     const scopesMap = /* @__PURE__ */ new Map();
     for (const tool of toolDefs) {
@@ -2522,7 +3113,7 @@ var DbMcpServer = class {
         throw new DbMcpError(
           `Unsupported transport: ${this.config.transport}`,
           "SERVER_START_FAILED",
-          "config" /* CONFIGURATION */
+          ErrorCategory.CONFIGURATION
         );
     }
   }
@@ -2544,7 +3135,7 @@ var DbMcpServer = class {
    * Start server with HTTP transport (Streamable HTTP with SSE support)
    */
   async startHttp() {
-    const { HttpTransport } = await import('./http-HWTUVFIA.js');
+    const { HttpTransport } = await import('./http-ZDMK46QU.js');
     const oauthConfig = {
       enabled: this.config.oauth?.enabled ?? false,
       authorizationServerUrl: this.config.oauth?.authorizationServerUrl ?? "",
@@ -2573,7 +3164,10 @@ var DbMcpServer = class {
       },
       oauth: oauthConfig,
       stateless: this.config.statelessHttp ?? false,
-      noAuthEnforcement: this.config.noAuthEnforcement ?? false
+      noAuthEnforcement: this.config.noAuthEnforcement ?? false,
+      ...this.config.metricsExport !== void 0 && {
+        metricsExport: this.config.metricsExport
+      }
     });
     await transport.initialize(this.server);
     await transport.start();
@@ -2605,6 +3199,11 @@ var DbMcpServer = class {
       await this.auditLogger.close();
       logger.info("Audit logger closed", { module: "AUDIT" });
     }
+    metrics.close();
+    if (this.systemDb) {
+      this.systemDb.close();
+      logger.info("System database closed", { module: "SYSTEM_DB" });
+    }
     if (this.backupManager) {
       await this.backupManager.flush();
       logger.info("Backup manager flushed", { module: "AUDIT" });
@@ -2619,7 +3218,12 @@ var DbMcpServer = class {
   async initializeAudit(config) {
     const auditConfig = config.audit;
     if (!auditConfig?.enabled) return;
-    this.auditLogger = new AuditLogger(auditConfig);
+    if (auditConfig.logPath !== "stderr") {
+      this.systemDb = new SystemDb({ dbPath: auditConfig.logPath });
+      await this.systemDb.init();
+      metrics.setSystemDb(this.systemDb);
+    }
+    this.auditLogger = new AuditLogger(auditConfig, this.systemDb);
     await this.auditLogger.init();
     if (auditConfig.backup?.enabled) {
       this.backupManager = new BackupManager(
@@ -2635,6 +3239,9 @@ var DbMcpServer = class {
     if (this.backupManager && this.toolFilter.enabledGroups.has("admin")) {
       registerAuditBackupTools(this.server, this.backupManager, this.adapters);
     }
+    if (this.toolFilter.enabledGroups.has("admin")) {
+      registerAuditSearchTool(this.server, this.auditLogger);
+    }
     logger.info(
       `Audit logging enabled (${auditConfig.logPath}, redact=${String(auditConfig.redact)}, reads=${String(auditConfig.auditReads)}, backup=${String(!!auditConfig.backup?.enabled)})`,
       { module: "AUDIT" }