db-mcp 4.0.0 → 5.0.1

package/dist/{chunk-NIC5Z2CA.js → chunk-WYBUO4FL.js}

@@ -1,5 +1,5 @@
-import { VERSION, NAME, READ_ONLY, SERVER_ICONS, ASSISTANT_FOCUSED, redactObject, getRequiredScope, estimateTokens, AuditListBackupsOutputSchema, AuditListBackupsSchema, AuditGetBackupOutputSchema, AuditCleanupOutputSchema, AuditDiffBackupOutputSchema, AuditRestoreBackupOutputSchema, AuditSearchOutputSchema, AuditSearchSchema } from './chunk-R5M4WKDM.js';
-import { parseToolFilter, getToolFilterFromEnv, logger, getFilterSummary, DbMcpError, getAuthContext, scopesGrantToolAccess, registerToolScopes, metrics, InsufficientScopeError, sanitizeErrorMessage, formatHandlerError } from './chunk-Y57WFKAP.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 { dirname, join, basename, sep } from 'path';
@@ -34,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 (31N/30W tools) + Server Audit (7 tools)
+  ["admin", `# db-mcp Help \u2014 Database Administration (31N/30W tools) + Server Audit (7 tools)
 
 ## Maintenance
 
@@ -45,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
@@ -53,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
@@ -70,7 +70,7 @@ sqlite_audit_get_backup({ filename: "snapshot_123.json" }); // retrieve specific
 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({ query: "DROP TABLE", limit: 50 }); // search and filter structured audit logs
+sqlite_audit_search({ tool: "sqlite_drop_table", limit: 10 }); // search and filter structured audit logs
 \`\`\`
 
 ## PRAGMA
@@ -81,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
 \`\`\`
@@ -137,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
@@ -145,16 +145,13 @@ sqlite_create_csv_table({
   tableName: "csv_data",
   filePath: "/absolute/path/to/data.csv",
 });
-\`\`\``
-  ],
-  [
-    "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", cursor: "..." })\` \u2014 execute SELECT, PRAGMA, EXPLAIN, or WITH statements. Supports \`cursor\` for offset-based pagination (returns \`nextCursor\`). **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)
+- \`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
 
@@ -174,19 +171,30 @@ sqlite_create_csv_table({
 - \`sqlite_create_index({ indexName: "idx_users_email", table: "users", columns: ["email"], unique?: true })\` \u2014 create a new index
 - \`sqlite_drop_index({ indexName: "idx_users_email", ifExists?: true })\` \u2014 drop an existing index
 
+## 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)
 
@@ -291,36 +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\`
-22. **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.
+\`\`\``],
+  ["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
 
@@ -347,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.
 
@@ -450,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
 
@@ -528,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.
 
@@ -574,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)
 
@@ -697,11 +673,8 @@ sqlite_window_moving_avg({
   windowSize: 7,
   selectColumns: ["date"],
 });
-\`\`\``
-  ],
-  [
-    "text",
-    `# db-mcp Help \u2014 Text Processing & FTS5 (20N/15W: 15 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)
 
@@ -840,6 +813,7 @@ sqlite_hybrid_search({
   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!" });
@@ -852,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)
 
@@ -887,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
@@ -917,8 +885,11 @@ 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
@@ -948,9 +919,9 @@ var AuditLogger = class {
   /**
    * Initialization is handled externally by SystemDb.
    */
-  // eslint-disable-next-line @typescript-eslint/require-await
-  async init() {
-    if (this.stderrMode || !this.config.enabled) return;
+  init() {
+    if (this.stderrMode || !this.config.enabled) return Promise.resolve();
+    return Promise.resolve();
   }
   /**
    * Append an audit entry to the buffer.
@@ -1219,7 +1190,7 @@ var SystemDb = class {
   }
   getDb() {
     if (!this.db) {
-      throw new Error("SystemDb not initialized");
+      throw new InternalError("SystemDb not initialized");
     }
     return this.db;
   }
@@ -1757,202 +1728,7 @@ 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
-          )
-        }
-      ]
-    };
-  });
-  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/audit-tools/helpers.ts
 function redactSqlLiterals(text) {
   return text.replace(/'(?:''|[^'])*'/g, "'***'");
 }
@@ -1960,16 +1736,18 @@ 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(
+    throw new ValidationError(
       `DDL validation failed: unauthorized command or function call`
     );
   }
   if (upperSql.includes(" ON MAIN.") || upperSql.includes(" ON TEMP.")) {
-    throw new Error(
+    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(
@@ -2012,12 +1790,13 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
       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: {
+      annotations: toSDK({
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
-        openWorldHint: false
-      }
+        openWorldHint: false,
+        sensitiveHint: true
+      })
     },
     async (args) => {
       const authCtx = getAuthContext();
@@ -2079,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();
@@ -2112,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: [
@@ -2144,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();
@@ -2184,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();
@@ -2217,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: [
@@ -2234,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: [
@@ -2323,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
         };
       }
     }
@@ -2350,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();
@@ -2388,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: [
@@ -2405,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: [
@@ -2422,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: [
@@ -2499,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
         };
       }
     }
@@ -2530,6 +2319,8 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
     { module: "AUDIT" }
   );
 }
+
+// src/server/registration/audit-tools/search.ts
 function registerAuditSearchTool(server, auditLogger) {
   if (!auditLogger) return;
   server.registerTool(
@@ -2539,21 +2330,44 @@ function registerAuditSearchTool(server, auditLogger) {
       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: {
+      annotations: toSDK({
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
-        openWorldHint: false
-      }
+        openWorldHint: false,
+        sensitiveHint: true
+      })
     },
     async (args) => {
-      const authCtx = getAuthContext();
-      if (authCtx && !scopesGrantToolAccess(authCtx.scopes, "sqlite_audit_search")) {
-        throw new InsufficientScopeError(["admin", "full"], authCtx.scopes);
-      }
-      let parsed;
       try {
-        parsed = AuditSearchSchema.parse(args ?? {});
+        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
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { ...result, _meta: { tokenEstimate } },
+                null,
+                2
+              )
+            }
+          ],
+          structuredContent: result
+        };
       } catch (error) {
         const structured = formatHandlerError(error);
         return {
@@ -2567,29 +2381,6 @@ function registerAuditSearchTool(server, auditLogger) {
           structuredContent: structured
         };
       }
-      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
-      );
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              { ...result, _meta: { tokenEstimate } },
-              null,
-              2
-            )
-          }
-        ],
-        structuredContent: result
-      };
     }
   );
   registerToolScopes(/* @__PURE__ */ new Map([["sqlite_audit_search", ["admin", "full"]]]));
@@ -2598,6 +2389,203 @@ function registerAuditSearchTool(server, auditLogger) {
   });
 }
 
+// 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(
@@ -2634,12 +2622,13 @@ function registerAdminTools(server) {
           "The new value for the setting (e.g., 'debug', 'info', 'warning')"
         )
       }),
-      annotations: {
+      annotations: toSDK({
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,
-        openWorldHint: false
-      }
+        openWorldHint: false,
+        sensitiveHint: true
+      })
     },
     (args) => {
       const authCtx = getAuthContext();
@@ -2693,7 +2682,8 @@ function registerAdminTools(server) {
                       {
                         success: false,
                         error: `Invalid log level: ${value}. Must be one of: ${validLevels.join(", ")}`,
-                        code: "INVALID_CONFIG"
+                        code: "INVALID_CONFIG",
+                        category: "validation"
                       },
                       null,
                       2
@@ -2734,7 +2724,8 @@ function registerAdminTools(server) {
                   {
                     success: false,
                     error: "Missing setting or value for set action",
-                    code: "INVALID_CONFIG"
+                    code: "INVALID_CONFIG",
+                    category: "validation"
                   },
                   null,
                   2
@@ -2748,27 +2739,27 @@ function registerAdminTools(server) {
           content: [
             {
               type: "text",
-              text: JSON.stringify({ success: false, error: "Invalid action" })
+              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(
-                {
-                  success: false,
-                  error: error instanceof Error ? error.message : String(error)
-                },
-                null,
-                2
-              )
+              text: JSON.stringify(structured, null, 2)
             }
           ],
-          isError: true
+          isError: true,
+          structuredContent: structured
         };
       }
     }
@@ -2908,7 +2899,7 @@ if (typeof proto["createToolError"] === "function") {
           success: false,
           error: cleanError,
           code: "VALIDATION_ERROR",
-          category: "validation" /* VALIDATION */
+          category: ErrorCategory.VALIDATION
         };
         result.content[0].text = JSON.stringify(structured, null, 2);
         result.isError = true;
@@ -2930,6 +2921,25 @@ var DbMcpServer = class {
   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(
       {
@@ -2961,7 +2971,7 @@ var DbMcpServer = class {
         if (!["sqlite://schema", "sqlite://tables", "sqlite://health"].includes(
           uri
         ) && !uri.startsWith("sqlite://table/")) {
-          throw new Error(`Resource ${uri} is not subscribable`);
+          throw new ValidationError(`Resource ${uri} is not subscribable`);
         }
         this.subscriptionManager.subscribe(
           uri,
@@ -3010,7 +3020,7 @@ var DbMcpServer = class {
       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");
@@ -3045,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({
@@ -3100,7 +3113,7 @@ var DbMcpServer = class {
         throw new DbMcpError(
           `Unsupported transport: ${this.config.transport}`,
           "SERVER_START_FAILED",
-          "config" /* CONFIGURATION */
+          ErrorCategory.CONFIGURATION
         );
     }
   }
@@ -3122,7 +3135,7 @@ var DbMcpServer = class {
    * Start server with HTTP transport (Streamable HTTP with SSE support)
    */
   async startHttp() {
-    const { HttpTransport } = await import('./http-2WGR3E5K.js');
+    const { HttpTransport } = await import('./http-2XDGZF4F.js');
     const oauthConfig = {
       enabled: this.config.oauth?.enabled ?? false,
       authorizationServerUrl: this.config.oauth?.authorizationServerUrl ?? "",