db-mcp 3.0.1 → 4.0.0

package/dist/{chunk-37G4DLL6.js → chunk-NIC5Z2CA.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, 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 { 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
 
@@ -33,7 +36,7 @@ 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)
+    `# db-mcp Help \u2014 Database Administration (31N/30W tools) + Server Audit (7 tools)
 
 ## Maintenance
 
@@ -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({ query: "DROP TABLE", limit: 50 }); // search and filter structured audit logs
 \`\`\`
 
 ## PRAGMA
@@ -140,12 +145,6 @@ 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
 \`\`\``
   ],
   [
@@ -154,7 +153,7 @@ sqlite_append_insight({ insight: "Q4 revenue increased 23% YoY" }); // add to me
 
 ## Basic Queries
 
-- \`sqlite_read_query({ query: "SELECT * FROM users LIMIT 10" })\` \u2014 execute SELECT, PRAGMA, EXPLAIN, or WITH statements
+- \`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)
 
 ## Tables & Schema
@@ -321,6 +320,7 @@ sqlite_spatialite_index({
 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.
 
 ## WASM vs Native
 
@@ -333,6 +333,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               |
@@ -434,6 +435,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'" });
@@ -693,7 +701,7 @@ sqlite_window_moving_avg({
   ],
   [
     "text",
-    `# db-mcp Help \u2014 Text Processing & FTS5 (19N/14W: 14 text + 5 FTS5 [NATIVE ONLY])
+    `# 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 +721,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 +742,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,6 +828,17 @@ 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,
 });
 
 // Sentiment analysis \u2014 text analysis (can analyze raw text or database columns)
@@ -899,21 +920,23 @@ sqlite_vector_distance({ vector1: [...], vector2: [...], metric: "cosine" }); //
 \`\`\``
   ]
 ]);
+
+// 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 +946,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.
    */
+  // eslint-disable-next-line @typescript-eslint/require-await
   async init() {
     if (this.stderrMode || !this.config.enabled) return;
-    try {
-      await this.ensureDirectory();
-      const fh = await open(this.config.logPath, "a");
-      await fh.close();
-    } catch (err) {
-      process.stderr.write(
-        `[AUDIT] Failed to initialise log file: ${this.config.logPath}
-`
-      );
-      throw err;
-    }
   }
   /**
    * Append an audit entry to the buffer.
-   * Non-blocking — the entry is serialised and queued; the
-   * actual file write happens on the next flush cycle.
+   * 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 +976,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 +1036,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 rotatedPath = `${this.config.logPath}.1`;
-      await rename(this.config.logPath, rotatedPath);
-    } catch {
+      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;
+      }
+      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 Error("SystemDb not initialized");
+    }
+    return this.db;
+  }
+  close() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
     }
   }
 };
@@ -1538,11 +1687,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 +1713,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(),
@@ -1730,15 +1888,18 @@ function registerHelpResources(server, toolFilter) {
         mimeType: "text/markdown",
         annotations: ASSISTANT_FOCUSED
       },
-      () => ({
-        contents: [
-          {
-            uri: "sqlite://help",
-            mimeType: "text/markdown",
-            text: gotchasContent
-          }
-        ]
-      })
+      () => {
+        metrics.recordResourceRead("sqlite://help");
+        return {
+          contents: [
+            {
+              uri: "sqlite://help",
+              mimeType: "text/markdown",
+              text: gotchasContent
+            }
+          ]
+        };
+      }
     );
   }
   const groupHelpKeys = [
@@ -1768,15 +1929,18 @@ function registerHelpResources(server, toolFilter) {
         mimeType: "text/markdown",
         annotations: ASSISTANT_FOCUSED
       },
-      () => ({
-        contents: [
-          {
-            uri: `sqlite://help/${key}`,
-            mimeType: "text/markdown",
-            text: content
-          }
-        ]
-      })
+      () => {
+        metrics.recordResourceRead(`sqlite://help/${key}`);
+        return {
+          contents: [
+            {
+              uri: `sqlite://help/${key}`,
+              mimeType: "text/markdown",
+              text: content
+            }
+          ]
+        };
+      }
     );
   }
   const registeredHelp = ["sqlite://help"];
@@ -1816,6 +1980,7 @@ function registerAuditResource(server, auditLogger, backupManager) {
       mimeType: "application/json"
     },
     async () => {
+      metrics.recordResourceRead("sqlite://audit");
       const recent = await auditLogger.recent(50);
       const backupStats = backupManager ? await backupManager.getStats() : void 0;
       const payload = {
@@ -2365,16 +2530,373 @@ function registerAuditBackupTools(server, backupManager, adaptersMap) {
     { module: "AUDIT" }
   );
 }
+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: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    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 ?? {});
+      } catch (error) {
+        const structured = formatHandlerError(error);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(structured, null, 2)
+            }
+          ],
+          isError: true,
+          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"]]]));
+  logger.info("Registered audit search tool: sqlite_audit_search", {
+    module: "AUDIT"
+  });
+}
+
+// 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: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false
+      }
+    },
+    (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"
+                      },
+                      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"
+                  },
+                  null,
+                  2
+                )
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ success: false, error: "Invalid action" })
+            }
+          ],
+          isError: true
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  success: false,
+                  error: error instanceof Error ? error.message : String(error)
+                },
+                null,
+                2
+              )
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  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
-    );
+    const result = originalCreateToolError.call(this, errorMessage);
     if (result.content?.[0]?.type === "text") {
       const rawError = result.content[0].text;
       if (rawError.includes("Input validation error")) {
@@ -2402,8 +2924,10 @@ var DbMcpServer = class {
   config;
   auditLogger = null;
   backupManager = null;
+  systemDb = null;
   auditInterceptor = null;
   auditInitPromise = null;
+  subscriptionManager;
   constructor(config) {
     this.config = config;
     this.toolFilter = config.toolFilter ? parseToolFilter(config.toolFilter) : getToolFilterFromEnv();
@@ -2419,6 +2943,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 Error(`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,6 +3000,10 @@ 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")) {
@@ -2459,6 +3029,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
@@ -2482,6 +3057,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) {
@@ -2544,7 +3122,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-2WGR3E5K.js');
     const oauthConfig = {
       enabled: this.config.oauth?.enabled ?? false,
       authorizationServerUrl: this.config.oauth?.authorizationServerUrl ?? "",
@@ -2573,7 +3151,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 +3186,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 +3205,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 +3226,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" }