@bytebase/dbhub 1.0.0 → 1.1.0

package/README.md

@@ -32,7 +32,7 @@
 
 DBHub is a zero-dependency, token efficient MCP server implementing the Model Context Protocol (MCP) server interface. This lightweight gateway allows MCP-compatible clients to connect to and explore different databases:
 
-- **Local Development First**: Zero dependency, token efficient with just two MCP tools to maximize context window
+- **Local Development First**: Zero dependency, token efficient with a minimal set of MCP tools to maximize context window
 - **Multi-Database**: PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite through a single interface
 - **Multi-Connection**: Connect to multiple databases simultaneously with TOML configuration
 - **Guardrails**: Read-only mode, row limiting, and query timeout to prevent runaway operations
@@ -48,6 +48,8 @@ DBHub implements MCP tools for database operations:
 
 - **[execute_sql](https://dbhub.ai/tools/execute-sql)**: Execute SQL queries with transaction support and safety controls
 - **[search_objects](https://dbhub.ai/tools/search-objects)**: Search and explore database schemas, tables, columns, indexes, and procedures with progressive disclosure
+- **[explain_sql](https://dbhub.ai/tools/explain-sql)** (opt-in): Show a query's execution plan without running it
+- **[health_check](https://dbhub.ai/tools/health-check)** (opt-in, PostgreSQL/MySQL/MariaDB/SQL Server for now): Report connection pool state and buffer cache hit ratio
 - **[Custom Tools](https://dbhub.ai/tools/custom-tools)**: Define reusable, parameterized SQL operations in your `dbhub.toml` configuration file
 
 ## Workbench
@@ -58,61 +60,17 @@ DBHub includes a [built-in web interface](https://dbhub.ai/workbench/overview) f
 
 ## Installation
 
-See the full [Installation Guide](https://dbhub.ai/installation) for detailed instructions.
-
-### Quick Start
-
-**Docker:**
-
-```bash
-docker run --rm --init \
-   --name dbhub \
-   --publish 8080:8080 \
-   bytebase/dbhub \
-   --transport http \
-   --port 8080 \
-   --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
-```
-
-**NPM:** (requires Node.js >= 22.5.0)
-
 ```bash
 npx @bytebase/dbhub@latest --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
 ```
 
-**MCP Bundle (one-click install):**
-
-Download `dbhub-<version>.mcpb` from the [latest release](https://github.com/bytebase/dbhub/releases/latest) and install it in any [MCPB-compatible client](https://github.com/modelcontextprotocol/mcpb) — Claude Desktop (double-click, or drag into Settings → Extensions), Claude Code, or MCP for Windows — then enter your database connection string. The bundle runs locally over stdio, is **read-only by design** (writes are rejected and the database session is set to read-only at the engine level), and needs no remote endpoint or OAuth setup — ideal for giving non-technical teammates curated, read-only database access. Pair it with a least-privilege, read-only database account. See the [MCP Bundle guide](https://dbhub.ai/mcpb) for details and for packaging your own bundle.
-
-**Claude Code Plugin:**
-
-For Claude Code, the [DBHub plugin](https://dbhub.ai/claude-code-plugin) registers the MCP server with one install command — Claude Code prompts for your connection string and stores it in secure storage — and adds `/dbhub:setup` and `/dbhub:explore` skills. Read-only by design, like the MCP Bundle.
-
-**Demo Mode:**
-
-```bash
-npx @bytebase/dbhub@latest --transport http --port 8080 --demo
-```
-
-**Restrict to loopback (recommended for production):**
-
-```bash
-npx @bytebase/dbhub@latest --transport http --host 127.0.0.1 --port 8080 --demo
-```
-
-> The HTTP transport defaults to `--host 0.0.0.0`, exposing DBHub on every network interface. For production, bind to `127.0.0.1` and front DBHub with a reverse proxy (nginx/Caddy) or firewall — DBHub does not authenticate HTTP clients.
->
-> The HTTP transport also has built-in DNS-rebinding protection: it only accepts requests whose `Host` is loopback, this machine's own hostname/IPs, or a name you allow via [`--allowed-hosts`](https://dbhub.ai/config/command-line#allowed-hosts). If a client behind a reverse proxy or custom DNS name gets a `403`, add that hostname with `--allowed-hosts`.
->
-> DBHub serves both MCP protocol eras on the same `/mcp` endpoint: the stateless **2026-07-28** revision (cacheable `tools/list`, no session state — safe behind round-robin load balancers) and the 2025-era Streamable HTTP protocol for older clients. 2026-era clients send the standard `Mcp-Method` / `Mcp-Name` headers on every request, so a fronting gateway or WAF can route and rate-limit `execute_sql` separately from `search_objects` without parsing JSON bodies.
-
-See [Command-Line Options](https://dbhub.ai/config/command-line) for all available parameters.
-
-### Multi-Database Setup
+Also available as:
 
-Connect to multiple databases simultaneously using TOML configuration files. Perfect for managing production, staging, and development databases from a single DBHub instance.
+- [Docker image](https://dbhub.ai/installation#docker)
+- [MCP Bundle](https://dbhub.ai/mcpb) (one-click install, read-only)
+- [Claude Code plugin](https://dbhub.ai/claude-code-plugin)
 
-See [Multi-Database Configuration](https://dbhub.ai/config/toml) for complete setup instructions.
+See the [Installation Guide](https://dbhub.ai/installation) for all options, [Command-Line Options](https://dbhub.ai/config/command-line) for parameters, and [Multi-Database Configuration](https://dbhub.ai/config/toml) for connecting several databases at once.
 
 ## Development
 

package/dist/{chunk-JO7YQPBQ.js → chunk-EPOKWSFC.js}

@@ -52,6 +52,22 @@ var sqlServerPassThroughPattern = new RegExp(
   `\\b(?:${sqlServerPassThroughKeywords.join("|")})\\s*\\(`,
   "i"
 );
+var escapeHatchFunctionKeywords = {
+  mysql: ["load_file", "get_lock", "release_lock", "release_all_locks"],
+  mariadb: ["load_file", "get_lock", "release_lock", "release_all_locks"],
+  postgres: ["pg_read_file", "pg_read_binary_file", "pg_ls_dir"],
+  sqlserver: sqlServerPassThroughKeywords
+};
+var escapeHatchFunctionPatterns = Object.fromEntries(
+  Object.entries(escapeHatchFunctionKeywords).map(([type, keywords]) => [
+    type,
+    new RegExp(`\\b(?:${keywords.join("|")})\\s*\\(`, "i")
+  ])
+);
+function hasEscapeHatchFunction(strippedSQL, connectorType) {
+  const pattern = escapeHatchFunctionPatterns[connectorType];
+  return pattern !== void 0 && pattern.test(strippedSQL);
+}
 var mutatingPatternSqlServer = new RegExp(
   `\\b(?:${[...mutatingKeywords, ...sqlServerDynamicSqlKeywords].join("|")})\\b`,
   "i"
@@ -78,6 +94,10 @@ function isReadOnlySQL(sql, connectorType) {
     connectorType
   );
 }
+function getFirstKeyword(sql, connectorType) {
+  const cleaned = stripCommentsAndStrings(sql, connectorType).trim();
+  return cleaned.match(/\S+/)?.[0]?.toLowerCase() ?? "";
+}
 function checkReadOnly(cleanedSQL, connectorType) {
   if (!cleanedSQL) {
     return false;
@@ -87,7 +107,7 @@ function checkReadOnly(cleanedSQL, connectorType) {
   if (!keywordList.includes(firstWord)) {
     return false;
   }
-  if (connectorType === "sqlserver" && sqlServerPassThroughPattern.test(cleanedSQL)) {
+  if (hasEscapeHatchFunction(cleanedSQL, connectorType)) {
     return false;
   }
   if (firstWord === "with") {
@@ -126,5 +146,7 @@ export {
   sqlServerDynamicSqlPattern,
   sqlServerPassThroughKeywords,
   sqlServerPassThroughPattern,
-  isReadOnlySQL
+  hasEscapeHatchFunction,
+  isReadOnlySQL,
+  getFirstKeyword
 };

package/dist/chunk-FU2ZJE4E.js

@@ -0,0 +1,16 @@
+// src/connectors/health-check-utils.ts
+function toNullableNumber(value) {
+  return value === null || value === void 0 ? null : Number(value);
+}
+function computeHitRatioPct(logicalReads, physicalReads) {
+  if (!Number.isFinite(logicalReads) || !Number.isFinite(physicalReads) || logicalReads === 0) {
+    return null;
+  }
+  const pct = Math.round((logicalReads - physicalReads) / logicalReads * 1e4) / 100;
+  return Math.min(100, Math.max(0, pct));
+}
+
+export {
+  toNullableNumber,
+  computeHitRatioPct
+};

package/dist/{chunk-MQR6VX5F.js → chunk-GSSLHJB6.js}

@@ -13,10 +13,17 @@ import {
 // src/tools/builtin-tools.ts
 var BUILTIN_TOOL_EXECUTE_SQL = "execute_sql";
 var BUILTIN_TOOL_SEARCH_OBJECTS = "search_objects";
+var BUILTIN_TOOL_EXPLAIN_SQL = "explain_sql";
+var BUILTIN_TOOL_HEALTH_CHECK = "health_check";
 var BUILTIN_TOOLS = [
   BUILTIN_TOOL_EXECUTE_SQL,
   BUILTIN_TOOL_SEARCH_OBJECTS
 ];
+var ALL_BUILTIN_TOOL_NAMES = [
+  ...BUILTIN_TOOLS,
+  BUILTIN_TOOL_EXPLAIN_SQL,
+  BUILTIN_TOOL_HEALTH_CHECK
+];
 
 // src/utils/ssh-tunnel.ts
 import { Client } from "ssh2";
@@ -1130,7 +1137,7 @@ function validateToolsConfig(tools, sources, configPath) {
         `Configuration file ${configPath}: tool '${tool.name}' references unknown source '${tool.source}'`
       );
     }
-    const isBuiltin = BUILTIN_TOOLS.includes(tool.name);
+    const isBuiltin = ALL_BUILTIN_TOOL_NAMES.includes(tool.name);
     const isExecuteSql = tool.name === BUILTIN_TOOL_EXECUTE_SQL;
     if (isBuiltin) {
       if (tool.description || tool.statement || tool.parameters) {
@@ -2278,7 +2285,7 @@ var ToolRegistry = class {
    * Check if a tool name is a built-in tool
    */
   isBuiltinTool(toolName) {
-    return BUILTIN_TOOLS.includes(toolName);
+    return ALL_BUILTIN_TOOL_NAMES.includes(toolName);
   }
   /**
    * Validate a custom tool parameter definition
@@ -2350,10 +2357,10 @@ var ToolRegistry = class {
         `Tool '${toolConfig.name}' references unknown source '${toolConfig.source}'. Available sources: ${availableSources.join(", ")}`
       );
     }
-    for (const builtinName of BUILTIN_TOOLS) {
+    for (const builtinName of ALL_BUILTIN_TOOL_NAMES) {
       if (toolConfig.name === builtinName || toolConfig.name.startsWith(`${builtinName}_`)) {
         throw new Error(
-          `Tool name '${toolConfig.name}' conflicts with built-in tool naming pattern. Custom tools cannot use names starting with: ${BUILTIN_TOOLS.join(", ")}`
+          `Tool name '${toolConfig.name}' conflicts with built-in tool naming pattern. Custom tools cannot use names starting with: ${ALL_BUILTIN_TOOL_NAMES.join(", ")}`
         );
       }
     }
@@ -2488,6 +2495,8 @@ export {
   resolveSourceConfigs,
   BUILTIN_TOOL_EXECUTE_SQL,
   BUILTIN_TOOL_SEARCH_OBJECTS,
+  BUILTIN_TOOL_EXPLAIN_SQL,
+  BUILTIN_TOOL_HEALTH_CHECK,
   loadTomlConfig,
   resolveTomlConfigPath,
   classifyConnectionError,

package/dist/chunk-NIILHXTG.js

@@ -0,0 +1,190 @@
+import {
+  computeHitRatioPct,
+  toNullableNumber
+} from "./chunk-FU2ZJE4E.js";
+import {
+  obfuscateDSNPassword
+} from "./chunk-JEZZN2YZ.js";
+
+// src/connectors/mysql-family-health-check.ts
+async function getMySQLFamilyHealthCheck(query) {
+  const [processlistRows, maxConnRows, bufferPoolRows, trxOutcome] = await Promise.all([
+    query(`
+      SELECT
+        COUNT(*) AS total,
+        SUM(CASE WHEN COMMAND != 'Sleep' THEN 1 ELSE 0 END) AS active,
+        SUM(CASE WHEN COMMAND = 'Sleep' THEN 1 ELSE 0 END) AS idle,
+        MAX(CASE WHEN COMMAND != 'Sleep' THEN TIME ELSE NULL END) AS longest_active_query_seconds
+      FROM information_schema.PROCESSLIST
+      WHERE ID <> CONNECTION_ID()
+    `),
+    query(`SHOW VARIABLES LIKE 'max_connections'`),
+    query(`
+      SHOW GLOBAL STATUS WHERE Variable_name IN ('Innodb_buffer_pool_read_requests', 'Innodb_buffer_pool_reads')
+    `),
+    // Joining PROCESSLIST against INNODB_TRX to detect idle-in-transaction
+    // sessions requires the PROCESS privilege - unlike a plain PROCESSLIST
+    // select, which silently narrows to the caller's own session instead of
+    // erroring. Run concurrently with the other queries above, but resolve
+    // rather than reject on failure so it degrades instead of failing the
+    // whole health check.
+    query(`
+      SELECT
+        COUNT(*) AS idle_in_transaction,
+        MAX(TIMESTAMPDIFF(SECOND, t.trx_started, NOW())) AS longest_idle_in_transaction_seconds
+      FROM information_schema.INNODB_TRX t
+      JOIN information_schema.PROCESSLIST p ON p.ID = t.trx_mysql_thread_id
+      WHERE p.COMMAND = 'Sleep'
+    `).then(
+      (rows) => ({ ok: true, rows }),
+      () => ({ ok: false })
+    )
+  ]);
+  const notes = [];
+  let idleInTransaction = 0;
+  let longestIdleInTransactionSeconds = null;
+  if (trxOutcome.ok) {
+    idleInTransaction = Number(trxOutcome.rows[0].idle_in_transaction);
+    longestIdleInTransactionSeconds = toNullableNumber(trxOutcome.rows[0].longest_idle_in_transaction_seconds);
+  } else {
+    notes.push(
+      "Connected user lacks the PROCESS privilege: PROCESSLIST visibility is restricted to the connecting user's own sessions, and this diagnostic session is excluded from the count, so connection counts and active-query duration may under-report (down to 0). Idle-in-transaction detection is unavailable."
+    );
+  }
+  const proc = processlistRows[0];
+  const bufferPoolStats = Object.fromEntries(bufferPoolRows.map((row) => [row.Variable_name, row.Value]));
+  const readRequests = Number(bufferPoolStats.Innodb_buffer_pool_read_requests ?? 0);
+  const reads = Number(bufferPoolStats.Innodb_buffer_pool_reads ?? 0);
+  return {
+    connections: {
+      total: Number(proc.total),
+      active: Number(proc.active),
+      idle: Number(proc.idle),
+      idleInTransaction,
+      // MySQL/MariaDB's InnoDB has no equivalent of Postgres's "idle in
+      // transaction (aborted)" state - a failed statement doesn't leave the
+      // session's transaction in a distinct aborted-but-open state the way
+      // Postgres does - so idleInTransactionAborted is left undefined.
+      maxConnections: maxConnRows.length > 0 ? Number(maxConnRows[0].Value) : null,
+      longestIdleInTransactionSeconds,
+      longestActiveQuerySeconds: toNullableNumber(proc.longest_active_query_seconds)
+    },
+    bufferCache: {
+      hitRatioPct: computeHitRatioPct(readRequests, reads),
+      blocksHit: readRequests - reads,
+      blocksRead: reads
+    },
+    ...notes.length > 0 ? { notes } : {}
+  };
+}
+
+// src/utils/dsn-database.ts
+var MissingDatabaseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "MissingDatabaseError";
+  }
+};
+function requireDatabaseInDSN(database, dsn, label) {
+  if (database) {
+    return;
+  }
+  throw new MissingDatabaseError(
+    `${label} DSN must name a database.
+Provided: ${obfuscateDSNPassword(dsn)}
+Add the database to the DSN, e.g. ...:3306/mydb
+To work with several databases, define one [[sources]] entry per database in a TOML config file: https://dbhub.ai/config/toml`
+  );
+}
+
+// src/utils/multi-statement-result-parser.ts
+function isMetadataObject(element) {
+  if (!element || typeof element !== "object" || Array.isArray(element)) {
+    return false;
+  }
+  return "affectedRows" in element || "insertId" in element || "fieldCount" in element || "warningStatus" in element;
+}
+function isMultiStatementResult(results) {
+  if (!Array.isArray(results) || results.length === 0) {
+    return false;
+  }
+  const firstElement = results[0];
+  return isMetadataObject(firstElement) || Array.isArray(firstElement);
+}
+function extractRowsFromMultiStatement(results) {
+  if (!Array.isArray(results)) {
+    return [];
+  }
+  const allRows = [];
+  for (const result of results) {
+    if (Array.isArray(result)) {
+      allRows.push(...result);
+    }
+  }
+  return allRows;
+}
+function extractAffectedRows(results) {
+  if (isMetadataObject(results)) {
+    return results.affectedRows || 0;
+  }
+  if (!Array.isArray(results)) {
+    return 0;
+  }
+  if (isMultiStatementResult(results)) {
+    let totalAffected = 0;
+    for (const result of results) {
+      if (isMetadataObject(result)) {
+        totalAffected += result.affectedRows || 0;
+      } else if (Array.isArray(result)) {
+        totalAffected += result.length;
+      }
+    }
+    return totalAffected;
+  }
+  return results.length;
+}
+function parseQueryResults(results) {
+  if (!Array.isArray(results)) {
+    return [];
+  }
+  if (isMultiStatementResult(results)) {
+    return extractRowsFromMultiStatement(results);
+  }
+  return results;
+}
+
+// src/utils/readonly-transaction.ts
+async function withReadOnlyTransaction(conn, readonly, supportsReadOnlyTransaction, execute) {
+  if (!readonly) {
+    return execute();
+  }
+  try {
+    await conn.query(
+      supportsReadOnlyTransaction ? "START TRANSACTION READ ONLY" : "START TRANSACTION"
+    );
+    const result = await execute();
+    await conn.query(supportsReadOnlyTransaction ? "COMMIT" : "ROLLBACK");
+    return result;
+  } catch (error) {
+    try {
+      await conn.query("ROLLBACK");
+    } catch {
+    }
+    throw error;
+  }
+}
+
+// src/utils/server-flavor.ts
+function isTiDBVersion(version) {
+  return typeof version === "string" && /tidb/i.test(version);
+}
+
+export {
+  getMySQLFamilyHealthCheck,
+  MissingDatabaseError,
+  requireDatabaseInDSN,
+  extractAffectedRows,
+  parseQueryResults,
+  withReadOnlyTransaction,
+  isTiDBVersion
+};

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import {
   BUILTIN_TOOL_EXECUTE_SQL,
+  BUILTIN_TOOL_EXPLAIN_SQL,
+  BUILTIN_TOOL_HEALTH_CHECK,
   BUILTIN_TOOL_SEARCH_OBJECTS,
   ConnectorManager,
   classifyConnectionError,
@@ -15,13 +17,14 @@ import {
   resolveSourceConfigs,
   resolveTomlConfigPath,
   resolveTransport
-} from "./chunk-MQR6VX5F.js";
+} from "./chunk-GSSLHJB6.js";
 import {
   allowedKeywords,
+  getFirstKeyword,
+  hasEscapeHatchFunction,
   isReadOnlySQL,
-  sqlServerDynamicSqlPattern,
-  sqlServerPassThroughPattern
-} from "./chunk-JO7YQPBQ.js";
+  sqlServerDynamicSqlPattern
+} from "./chunk-EPOKWSFC.js";
 import {
   loadConnectors
 } from "./chunk-WVVMH6FJ.js";
@@ -114,7 +117,8 @@ var dmlPattern = /\b(?:insert|update|delete|merge|replace\s+(?:(?:low_priority|d
 var grantRevokePattern = /\b(?:grant|revoke)\b/i;
 function isAdminStatement(stripped, connectorType) {
   if (grantRevokePattern.test(stripped)) return true;
-  return connectorType === "sqlserver" && (sqlServerDynamicSqlPattern.test(stripped) || sqlServerPassThroughPattern.test(stripped));
+  if (hasEscapeHatchFunction(stripped, connectorType)) return true;
+  return connectorType === "sqlserver" && sqlServerDynamicSqlPattern.test(stripped);
 }
 function policyFromReadonly(readonly) {
   const write = readonly === true ? "deny" : "allow";
@@ -206,10 +210,22 @@ function getClientIdentifier(ctx) {
   return "stdio";
 }
 
+// src/utils/normalize-id.ts
+function normalizeSourceId(id) {
+  return id.replace(/[^a-zA-Z0-9]/g, "_");
+}
+
 // src/utils/tool-handler-helpers.ts
 function getEffectiveSourceId(sourceId) {
   return sourceId || "default";
 }
+function resolveTrackedToolName(sourceId, baseName) {
+  const isSingleSource = ConnectorManager.getAvailableSourceIds().length === 1;
+  if (isSingleSource) {
+    return baseName;
+  }
+  return `${baseName}_${normalizeSourceId(getEffectiveSourceId(sourceId))}`;
+}
 function createReadonlyViolationMessage(toolName, sourceId, connectorType) {
   return `Tool '${toolName}' cannot execute in readonly mode for source '${sourceId}'. Only read-only SQL operations are allowed: ${allowedKeywords[connectorType]?.join(", ") || "none"}`;
 }
@@ -785,15 +801,151 @@ function createSearchDatabaseObjectsToolHandler(sourceId) {
   };
 }
 
-// src/utils/tool-metadata.ts
+// src/tools/explain-sql.ts
 import { z as z3 } from "zod";
+var explainSqlSchema = {
+  sql: z3.string().describe("Single SQL statement to explain (no trailing semicolon-separated statements)")
+};
+var explainSqlInputSchema = z3.object(explainSqlSchema);
+function buildExplainStatement(connectorType, sql) {
+  if (connectorType === "sqlite") {
+    return `EXPLAIN QUERY PLAN ${sql}`;
+  }
+  return `EXPLAIN ${sql}`;
+}
+function validateExplainInput(sql, connectorType) {
+  const statements = splitSQLStatements(sql, connectorType);
+  if (statements.length !== 1) {
+    return "explain_sql only supports a single SQL statement";
+  }
+  const firstWord = getFirstKeyword(statements[0], connectorType);
+  if (firstWord === "explain") {
+    return "explain_sql input must not itself start with EXPLAIN";
+  }
+  if (firstWord === "analyze") {
+    return "explain_sql does not support ANALYZE (it must never execute the statement)";
+  }
+  const cleaned = stripCommentsAndStrings(statements[0], connectorType).trim();
+  const leadingOptions = cleaned.match(/^\(([\s\S]*?)\)/)?.[1];
+  if (leadingOptions && /\banalyze\b/i.test(leadingOptions)) {
+    return "explain_sql does not support ANALYZE (it must never execute the statement)";
+  }
+  return null;
+}
+function createExplainSqlToolHandler(sourceId) {
+  return async (args, extra) => {
+    const { sql } = args;
+    const startTime = Date.now();
+    const effectiveSourceId = getEffectiveSourceId(sourceId);
+    let success = true;
+    let errorMessage;
+    let result;
+    try {
+      await ConnectorManager.ensureConnected(sourceId);
+      const connector = ConnectorManager.getCurrentConnector(sourceId);
+      const validationError = validateExplainInput(sql, connector.id);
+      if (validationError) {
+        success = false;
+        errorMessage = validationError;
+        return createToolErrorResponse(errorMessage, "INVALID_INPUT");
+      }
+      const explainStatement = buildExplainStatement(connector.id, sql);
+      result = await connector.executeSQL(explainStatement, { readonly: true });
+      const responseData = {
+        rows: result.rows,
+        count: result.rowCount,
+        source_id: effectiveSourceId,
+        ...result.messages && result.messages.length > 0 ? { messages: result.messages } : {}
+      };
+      return createToolSuccessResponse(responseData);
+    } catch (error) {
+      success = false;
+      errorMessage = error.message;
+      const classified = tryClassifyConnectionError(error, sourceId, effectiveSourceId);
+      if (classified) return classified;
+      return createToolErrorResponse(errorMessage, "EXECUTION_ERROR");
+    } finally {
+      trackToolRequest(
+        {
+          sourceId: effectiveSourceId,
+          toolName: resolveTrackedToolName(sourceId, "explain_sql"),
+          sql
+        },
+        startTime,
+        extra,
+        success,
+        errorMessage
+      );
+    }
+  };
+}
 
-// src/utils/normalize-id.ts
-function normalizeSourceId(id) {
-  return id.replace(/[^a-zA-Z0-9]/g, "_");
+// src/tools/health-check.ts
+import { z as z4 } from "zod";
+var healthCheckSchema = {};
+var healthCheckInputSchema = z4.object(healthCheckSchema);
+function createHealthCheckToolHandler(sourceId) {
+  return async (_args, extra) => {
+    const startTime = Date.now();
+    const effectiveSourceId = getEffectiveSourceId(sourceId);
+    let success = true;
+    let errorMessage;
+    try {
+      await ConnectorManager.ensureConnected(sourceId);
+      const connector = ConnectorManager.getCurrentConnector(sourceId);
+      if (!connector.getHealthCheck) {
+        success = false;
+        errorMessage = `health_check is not supported for '${connector.id}' sources yet`;
+        return createToolErrorResponse(errorMessage, "UNSUPPORTED");
+      }
+      const health = await connector.getHealthCheck();
+      return createToolSuccessResponse({
+        source_id: effectiveSourceId,
+        ...health.connections ? {
+          connections: {
+            total: health.connections.total,
+            active: health.connections.active,
+            idle: health.connections.idle,
+            idle_in_transaction: health.connections.idleInTransaction,
+            ...health.connections.idleInTransactionAborted !== void 0 ? { idle_in_transaction_aborted: health.connections.idleInTransactionAborted } : {},
+            max_connections: health.connections.maxConnections,
+            longest_idle_in_transaction_seconds: health.connections.longestIdleInTransactionSeconds,
+            longest_active_query_seconds: health.connections.longestActiveQuerySeconds
+          }
+        } : {},
+        ...health.bufferCache ? {
+          buffer_cache: {
+            hit_ratio_pct: health.bufferCache.hitRatioPct,
+            blocks_hit: health.bufferCache.blocksHit,
+            blocks_read: health.bufferCache.blocksRead
+          }
+        } : {},
+        ...health.notes && health.notes.length > 0 ? { notes: health.notes } : {}
+      });
+    } catch (error) {
+      success = false;
+      errorMessage = error.message;
+      const classified = tryClassifyConnectionError(error, sourceId, effectiveSourceId);
+      if (classified) return classified;
+      return createToolErrorResponse(errorMessage, "EXECUTION_ERROR");
+    } finally {
+      trackToolRequest(
+        {
+          sourceId: effectiveSourceId,
+          toolName: effectiveSourceId === "default" ? "health_check" : `health_check_${effectiveSourceId}`,
+          sql: ""
+        },
+        startTime,
+        extra,
+        success,
+        errorMessage
+      );
+    }
+  };
 }
 
 // src/utils/tool-metadata.ts
+import { z as z5 } from "zod";
 function buildSourceDescriptionPrefix(description) {
   const trimmed = description?.trim() ?? "";
   if (!trimmed) return "";
@@ -803,17 +955,17 @@ function zodToParameters(schema) {
   const parameters = [];
   for (const [key, zodType] of Object.entries(schema)) {
     const description = zodType.description || "";
-    const required = !(zodType instanceof z3.ZodOptional);
+    const required = !(zodType instanceof z5.ZodOptional);
     let type = "string";
-    if (zodType instanceof z3.ZodString) {
+    if (zodType instanceof z5.ZodString) {
       type = "string";
-    } else if (zodType instanceof z3.ZodNumber) {
+    } else if (zodType instanceof z5.ZodNumber) {
       type = "number";
-    } else if (zodType instanceof z3.ZodBoolean) {
+    } else if (zodType instanceof z5.ZodBoolean) {
       type = "boolean";
-    } else if (zodType instanceof z3.ZodArray) {
+    } else if (zodType instanceof z5.ZodArray) {
       type = "array";
-    } else if (zodType instanceof z3.ZodObject) {
+    } else if (zodType instanceof z5.ZodObject) {
       type = "object";
     }
     parameters.push({
@@ -825,20 +977,28 @@ function zodToParameters(schema) {
   }
   return parameters;
 }
-function getExecuteSqlMetadata(sourceId) {
+function resolveBuiltinToolNaming(sourceId, baseName, titleLabel) {
   const sourceIds = ConnectorManager.getAvailableSourceIds();
   const sourceConfig = ConnectorManager.getSourceConfig(sourceId);
   const dbType = sourceConfig.type;
   const isSingleSource = sourceIds.length === 1;
+  const name = isSingleSource ? baseName : `${baseName}_${normalizeSourceId(sourceId)}`;
+  const title = isSingleSource ? `${titleLabel} (${dbType})` : `${titleLabel} on ${sourceId} (${dbType})`;
+  const userDescPrefix = buildSourceDescriptionPrefix(sourceConfig.description);
+  return { dbType, isSingleSource, name, title, userDescPrefix };
+}
+function getExecuteSqlMetadata(sourceId) {
+  const { dbType, isSingleSource, name, title, userDescPrefix } = resolveBuiltinToolNaming(
+    sourceId,
+    "execute_sql",
+    "Execute SQL"
+  );
   const registry = getToolRegistry();
   const toolConfig = registry.getBuiltinToolConfig(BUILTIN_TOOL_EXECUTE_SQL, sourceId);
   const executeOptions = {
     readonly: toolConfig?.readonly,
     maxRows: toolConfig?.max_rows
   };
-  const toolName = isSingleSource ? "execute_sql" : `execute_sql_${normalizeSourceId(sourceId)}`;
-  const title = isSingleSource ? `Execute SQL (${dbType})` : `Execute SQL on ${sourceId} (${dbType})`;
-  const userDescPrefix = buildSourceDescriptionPrefix(sourceConfig.description);
   const readonlyNote = executeOptions.readonly ? " [READ-ONLY MODE]" : "";
   const maxRowsNote = executeOptions.maxRows ? ` (limited to ${executeOptions.maxRows} rows)` : "";
   const description = isSingleSource ? `${userDescPrefix}Execute SQL queries on the ${dbType} database${readonlyNote}${maxRowsNote}` : `${userDescPrefix}Execute SQL queries on the '${sourceId}' ${dbType} database${readonlyNote}${maxRowsNote}`;
@@ -855,25 +1015,62 @@ function getExecuteSqlMetadata(sourceId) {
     openWorldHint: false
   };
   return {
-    name: toolName,
+    name,
     description,
     schema: executeSqlSchema,
     annotations
   };
 }
 function getSearchObjectsMetadata(sourceId) {
-  const sourceIds = ConnectorManager.getAvailableSourceIds();
-  const sourceConfig = ConnectorManager.getSourceConfig(sourceId);
-  const dbType = sourceConfig.type;
-  const isSingleSource = sourceIds.length === 1;
-  const toolName = isSingleSource ? "search_objects" : `search_objects_${normalizeSourceId(sourceId)}`;
-  const title = isSingleSource ? `Search Database Objects (${dbType})` : `Search Database Objects on ${sourceId} (${dbType})`;
-  const userDescPrefix = buildSourceDescriptionPrefix(sourceConfig.description);
+  const { dbType, isSingleSource, name, title, userDescPrefix } = resolveBuiltinToolNaming(
+    sourceId,
+    "search_objects",
+    "Search Database Objects"
+  );
   const description = isSingleSource ? `${userDescPrefix}Search and list database objects on the ${dbType} database` : `${userDescPrefix}Search and list database objects on the '${sourceId}' ${dbType} database`;
+  return { name, description, title };
+}
+function getExplainSqlMetadata(sourceId) {
+  const { dbType, isSingleSource, name, title, userDescPrefix } = resolveBuiltinToolNaming(
+    sourceId,
+    "explain_sql",
+    "Explain Query Plan"
+  );
+  const description = isSingleSource ? `${userDescPrefix}Show the execution plan for a SQL statement on the ${dbType} database without running it. Always read-only and safe, independent of the source's read/write mode.` : `${userDescPrefix}Show the execution plan for a SQL statement on the '${sourceId}' ${dbType} database without running it. Always read-only and safe, independent of the source's read/write mode.`;
+  const annotations = {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  };
+  return {
+    name,
+    description,
+    schema: explainSqlSchema,
+    annotations
+  };
+}
+function getHealthCheckMetadata(sourceId) {
+  const { dbType, isSingleSource, name, title, userDescPrefix } = resolveBuiltinToolNaming(
+    sourceId,
+    "health_check",
+    "Health Check"
+  );
+  const description = isSingleSource ? `${userDescPrefix}Report operational health metrics (connection pool state, buffer cache hit ratio) for the ${dbType} database. Read-only, independent of the source's read/write mode.` : `${userDescPrefix}Report operational health metrics (connection pool state, buffer cache hit ratio) for the '${sourceId}' ${dbType} database. Read-only, independent of the source's read/write mode.`;
+  const annotations = {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: false,
+    // Metrics change from call to call, unlike explain_sql's plan output
+    openWorldHint: false
+  };
   return {
-    name: toolName,
+    name,
     description,
-    title
+    schema: healthCheckSchema,
+    annotations
   };
 }
 function customParamsToToolParams(params) {
@@ -947,6 +1144,16 @@ function buildSearchObjectsTool(sourceId) {
     // search_objects is always readonly
   };
 }
+function buildExplainSqlTool(sourceId) {
+  const explainMetadata = getExplainSqlMetadata(sourceId);
+  return {
+    name: explainMetadata.name,
+    description: explainMetadata.description,
+    parameters: zodToParameters(explainMetadata.schema),
+    readonly: true
+    // explain_sql is always readonly
+  };
+}
 function buildCustomTool(toolConfig) {
   return {
     name: toolConfig.name,
@@ -965,6 +1172,8 @@ function getToolsForSource(sourceId) {
       return buildExecuteSqlTool(sourceId, toolConfig);
     } else if (toolConfig.name === "search_objects") {
       return buildSearchObjectsTool(sourceId);
+    } else if (toolConfig.name === "explain_sql") {
+      return buildExplainSqlTool(sourceId);
     } else {
       return buildCustomTool(toolConfig);
     }
@@ -972,7 +1181,7 @@ function getToolsForSource(sourceId) {
 }
 
 // src/tools/custom-tool-handler.ts
-import { z as z4 } from "zod";
+import { z as z6 } from "zod";
 function buildZodSchemaFromParameters(parameters) {
   if (!parameters || parameters.length === 0) {
     return {};
@@ -982,26 +1191,26 @@ function buildZodSchemaFromParameters(parameters) {
     let fieldSchema;
     switch (param.type) {
       case "string":
-        fieldSchema = z4.string().describe(param.description);
+        fieldSchema = z6.string().describe(param.description);
         break;
       case "integer":
-        fieldSchema = z4.number().int().describe(param.description);
+        fieldSchema = z6.number().int().describe(param.description);
         break;
       case "float":
-        fieldSchema = z4.number().describe(param.description);
+        fieldSchema = z6.number().describe(param.description);
         break;
       case "boolean":
-        fieldSchema = z4.boolean().describe(param.description);
+        fieldSchema = z6.boolean().describe(param.description);
         break;
       case "array":
-        fieldSchema = z4.array(z4.unknown()).describe(param.description);
+        fieldSchema = z6.array(z6.unknown()).describe(param.description);
         break;
       default:
         throw new Error(`Unsupported parameter type: ${param.type}`);
     }
     if (param.allowed_values && param.allowed_values.length > 0) {
       if (param.type === "string") {
-        fieldSchema = z4.enum(param.allowed_values).describe(param.description);
+        fieldSchema = z6.enum(param.allowed_values).describe(param.description);
       } else {
         fieldSchema = fieldSchema.refine(
           (val) => param.allowed_values.includes(val),
@@ -1022,7 +1231,7 @@ var customToolInputSchemas = /* @__PURE__ */ new WeakMap();
 function getCustomToolInputSchema(toolConfig) {
   let schema = customToolInputSchemas.get(toolConfig);
   if (!schema) {
-    schema = z4.object(buildZodSchemaFromParameters(toolConfig.parameters));
+    schema = z6.object(buildZodSchemaFromParameters(toolConfig.parameters));
     customToolInputSchemas.set(toolConfig, schema);
   }
   return schema;
@@ -1068,7 +1277,7 @@ function createCustomToolHandler(toolConfig) {
       errorMessage = error.message;
       const classified = tryClassifyConnectionError(error, toolConfig.source, toolConfig.source);
       if (classified) return classified;
-      if (error instanceof z4.ZodError) {
+      if (error instanceof z6.ZodError) {
         const issues = error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
         errorMessage = `Parameter validation failed: ${issues}`;
       } else {
@@ -1108,6 +1317,10 @@ function registerTools(server) {
         registerExecuteSqlTool(server, sourceId);
       } else if (toolConfig.name === BUILTIN_TOOL_SEARCH_OBJECTS) {
         registerSearchObjectsTool(server, sourceId);
+      } else if (toolConfig.name === BUILTIN_TOOL_EXPLAIN_SQL) {
+        registerExplainSqlTool(server, sourceId);
+      } else if (toolConfig.name === BUILTIN_TOOL_HEALTH_CHECK) {
+        registerHealthCheckTool(server, sourceId);
       } else {
         registerCustomTool(server, sourceId, toolConfig);
       }
@@ -1144,6 +1357,30 @@ function registerSearchObjectsTool(server, sourceId) {
     createSearchDatabaseObjectsToolHandler(sourceId)
   );
 }
+function registerExplainSqlTool(server, sourceId) {
+  const metadata = getExplainSqlMetadata(sourceId);
+  server.registerTool(
+    metadata.name,
+    {
+      description: metadata.description,
+      inputSchema: explainSqlInputSchema,
+      annotations: metadata.annotations
+    },
+    createExplainSqlToolHandler(sourceId)
+  );
+}
+function registerHealthCheckTool(server, sourceId) {
+  const metadata = getHealthCheckMetadata(sourceId);
+  server.registerTool(
+    metadata.name,
+    {
+      description: metadata.description,
+      inputSchema: healthCheckInputSchema,
+      annotations: metadata.annotations
+    },
+    createHealthCheckToolHandler(sourceId)
+  );
+}
 function registerCustomTool(server, sourceId, toolConfig) {
   const sourceConfig = ConnectorManager.getSourceConfig(sourceId);
   const dbType = sourceConfig.type;
@@ -1639,7 +1876,7 @@ See documentation for more details on configuring database connections.
     const sources = sourceConfigsData.sources;
     console.error(`Configuration source: ${sourceConfigsData.source}`);
     await connectorManager.connectWithSources(sources);
-    const { initializeToolRegistry: initializeToolRegistry2 } = await import("./registry-ZU6ZFNQ2.js");
+    const { initializeToolRegistry: initializeToolRegistry2 } = await import("./registry-JYRRNC3E.js");
     initializeToolRegistry2({
       sources: sourceConfigsData.sources,
       tools: sourceConfigsData.tools
@@ -1780,11 +2017,11 @@ See documentation for more details on configuring database connections.
 
 // src/index.ts
 var connectorModules = [
-  { load: () => import("./postgres-YAYHDXVD.js"), name: "PostgreSQL", driver: "pg" },
-  { load: () => import("./sqlserver-COKW7RIK.js"), name: "SQL Server", driver: "mssql" },
+  { load: () => import("./postgres-5ZOFYV6X.js"), name: "PostgreSQL", driver: "pg" },
+  { load: () => import("./sqlserver-PSAZRH7G.js"), name: "SQL Server", driver: "mssql" },
   { load: () => import("./sqlite-5M7SDAQZ.js"), name: "SQLite", driver: "node:sqlite" },
-  { load: () => import("./mysql-CDUKJMNN.js"), name: "MySQL", driver: "mysql2" },
-  { load: () => import("./mariadb-72C2BNCG.js"), name: "MariaDB", driver: "mariadb" }
+  { load: () => import("./mysql-265M3KBD.js"), name: "MySQL", driver: "mysql2" },
+  { load: () => import("./mariadb-DUDFBY5W.js"), name: "MariaDB", driver: "mariadb" }
 ];
 loadConnectors(connectorModules).then(() => main()).catch((error) => {
   console.error("Fatal error:", error);

package/dist/{mariadb-72C2BNCG.js → mariadb-DUDFBY5W.js}

@@ -1,11 +1,13 @@
 import {
   MissingDatabaseError,
   extractAffectedRows,
+  getMySQLFamilyHealthCheck,
   isTiDBVersion,
   parseQueryResults,
   requireDatabaseInDSN,
   withReadOnlyTransaction
-} from "./chunk-DUCNPMNW.js";
+} from "./chunk-NIILHXTG.js";
+import "./chunk-FU2ZJE4E.js";
 import {
   quoteIdentifier
 } from "./chunk-JFWX35TB.js";
@@ -338,6 +340,13 @@ var MariaDBConnector = class _MariaDBConnector {
       return null;
     }
   }
+  async getHealthCheck() {
+    if (!this.pool) {
+      throw new Error("Not connected to database");
+    }
+    const pool = this.pool;
+    return getMySQLFamilyHealthCheck((sql) => pool.query(sql));
+  }
   async getStoredProcedures(schema, routineType) {
     if (!this.pool) {
       throw new Error("Not connected to database");

package/dist/{mysql-CDUKJMNN.js → mysql-265M3KBD.js}

@@ -1,11 +1,13 @@
 import {
   MissingDatabaseError,
   extractAffectedRows,
+  getMySQLFamilyHealthCheck,
   isTiDBVersion,
   parseQueryResults,
   requireDatabaseInDSN,
   withReadOnlyTransaction
-} from "./chunk-DUCNPMNW.js";
+} from "./chunk-NIILHXTG.js";
+import "./chunk-FU2ZJE4E.js";
 import {
   quoteIdentifier
 } from "./chunk-JFWX35TB.js";
@@ -343,6 +345,16 @@ var MySQLConnector = class _MySQLConnector {
       return null;
     }
   }
+  async getHealthCheck() {
+    if (!this.pool) {
+      throw new Error("Not connected to database");
+    }
+    const pool = this.pool;
+    return getMySQLFamilyHealthCheck(async (sql) => {
+      const [rows] = await pool.query(sql);
+      return rows;
+    });
+  }
   async getStoredProcedures(schema, routineType) {
     if (!this.pool) {
       throw new Error("Not connected to database");

package/dist/{postgres-YAYHDXVD.js → postgres-5ZOFYV6X.js}

@@ -1,3 +1,6 @@
+import {
+  toNullableNumber
+} from "./chunk-FU2ZJE4E.js";
 import {
   quoteIdentifier
 } from "./chunk-JFWX35TB.js";
@@ -383,6 +386,64 @@ var PostgresConnector = class _PostgresConnector {
       client.release();
     }
   }
+  async getHealthCheck() {
+    if (!this.pool) {
+      throw new Error("Not connected to database");
+    }
+    const client = await this.pool.connect();
+    try {
+      const [connectionsResult, maxConnectionsResult, bufferCacheResult] = await Promise.all([
+        client.query(`
+          SELECT
+            count(*) AS total,
+            count(*) FILTER (WHERE state = 'active') AS active,
+            count(*) FILTER (WHERE state = 'idle') AS idle,
+            count(*) FILTER (WHERE state = 'idle in transaction') AS idle_in_transaction,
+            count(*) FILTER (WHERE state = 'idle in transaction (aborted)') AS idle_in_transaction_aborted,
+            max(EXTRACT(EPOCH FROM (now() - state_change)))
+              FILTER (WHERE state = 'idle in transaction') AS longest_idle_in_transaction_seconds,
+            max(EXTRACT(EPOCH FROM (now() - query_start)))
+              FILTER (WHERE state = 'active') AS longest_active_query_seconds
+          FROM pg_stat_activity
+          WHERE pid <> pg_backend_pid()
+        `),
+        client.query(`SHOW max_connections`),
+        client.query(
+          `
+          SELECT
+            blks_hit,
+            blks_read,
+            CASE WHEN (blks_hit + blks_read) = 0 THEN NULL
+                 ELSE round(100.0 * blks_hit / (blks_hit + blks_read), 2)
+            END AS hit_ratio_pct
+          FROM pg_stat_database
+          WHERE datname = current_database()
+        `
+        )
+      ]);
+      const conn = connectionsResult.rows[0];
+      const cache = bufferCacheResult.rows[0];
+      return {
+        connections: {
+          total: Number(conn.total),
+          active: Number(conn.active),
+          idle: Number(conn.idle),
+          idleInTransaction: Number(conn.idle_in_transaction),
+          idleInTransactionAborted: Number(conn.idle_in_transaction_aborted),
+          maxConnections: Number(maxConnectionsResult.rows[0].max_connections),
+          longestIdleInTransactionSeconds: toNullableNumber(conn.longest_idle_in_transaction_seconds),
+          longestActiveQuerySeconds: toNullableNumber(conn.longest_active_query_seconds)
+        },
+        bufferCache: {
+          hitRatioPct: toNullableNumber(cache.hit_ratio_pct),
+          blocksHit: Number(cache.blks_hit),
+          blocksRead: Number(cache.blks_read)
+        }
+      };
+    } finally {
+      client.release();
+    }
+  }
   async getStoredProcedures(schema, routineType) {
     if (!this.pool) {
       throw new Error("Not connected to database");

package/dist/{registry-ZU6ZFNQ2.js → registry-JYRRNC3E.js}

@@ -2,7 +2,7 @@ import {
   ToolRegistry,
   getToolRegistry,
   initializeToolRegistry
-} from "./chunk-MQR6VX5F.js";
+} from "./chunk-GSSLHJB6.js";
 import "./chunk-WVVMH6FJ.js";
 import "./chunk-JEZZN2YZ.js";
 export {

package/dist/{sqlserver-COKW7RIK.js → sqlserver-PSAZRH7G.js}

@@ -3,10 +3,14 @@ import {
   sqlServerDynamicSqlPattern,
   sqlServerPassThroughKeywords,
   sqlServerPassThroughPattern
-} from "./chunk-JO7YQPBQ.js";
+} from "./chunk-EPOKWSFC.js";
 import {
   isDriverNotInstalled
 } from "./chunk-WVVMH6FJ.js";
+import {
+  computeHitRatioPct,
+  toNullableNumber
+} from "./chunk-FU2ZJE4E.js";
 import {
   SQLRowLimiter,
   closeQuietly
@@ -372,6 +376,81 @@ var _SQLServerConnector = class _SQLServerConnector {
       return null;
     }
   }
+  async getHealthCheck() {
+    if (!this.connection) {
+      throw new Error("Not connected to SQL Server database");
+    }
+    const notes = [];
+    const result = {};
+    try {
+      const [connResult, maxConnResult] = await Promise.all([
+        this.connection.request().query(`
+          SELECT
+            COUNT(*) AS total,
+            SUM(CASE WHEN r.session_id IS NOT NULL THEN 1 ELSE 0 END) AS active,
+            SUM(CASE WHEN r.session_id IS NULL THEN 1 ELSE 0 END) AS idle,
+            SUM(CASE WHEN r.session_id IS NULL AND t.session_id IS NOT NULL THEN 1 ELSE 0 END) AS idle_in_transaction,
+            MAX(CASE WHEN r.session_id IS NULL AND t.session_id IS NOT NULL
+                  THEN DATEDIFF(SECOND, s.last_request_end_time, SYSDATETIME()) ELSE NULL END) AS longest_idle_in_transaction_seconds,
+            MAX(CASE WHEN r.session_id IS NOT NULL
+                  THEN DATEDIFF(SECOND, r.start_time, SYSDATETIME()) ELSE NULL END) AS longest_active_query_seconds
+          FROM sys.dm_exec_sessions s
+          LEFT JOIN sys.dm_exec_requests r ON r.session_id = s.session_id
+          LEFT JOIN (SELECT DISTINCT session_id FROM sys.dm_tran_session_transactions) t ON t.session_id = s.session_id
+          WHERE s.is_user_process = 1 AND s.session_id <> @@SPID
+        `),
+        this.connection.request().query(`
+          SELECT CAST(value_in_use AS INT) AS max_connections
+          FROM sys.configurations
+          WHERE name = 'user connections'
+        `)
+      ]);
+      const conn = connResult.recordset[0];
+      const maxConnections = maxConnResult.recordset.length > 0 && maxConnResult.recordset[0].max_connections > 0 ? maxConnResult.recordset[0].max_connections : null;
+      result.connections = {
+        total: conn.total ?? 0,
+        active: conn.active ?? 0,
+        idle: conn.idle ?? 0,
+        idleInTransaction: conn.idle_in_transaction ?? 0,
+        // SQL Server has no equivalent of Postgres's "idle in transaction
+        // (aborted)" state - a failed statement doesn't leave the session's
+        // transaction in a distinct aborted-but-open state the way Postgres does.
+        maxConnections,
+        longestIdleInTransactionSeconds: toNullableNumber(conn.longest_idle_in_transaction_seconds),
+        longestActiveQuerySeconds: toNullableNumber(conn.longest_active_query_seconds)
+      };
+    } catch {
+      notes.push(
+        "Connection pool metrics unavailable: connecting user lacks the VIEW SERVER STATE permission (VIEW DATABASE STATE on Azure SQL Database)."
+      );
+    }
+    try {
+      const bufferResult = await this.connection.request().query(`
+        SELECT counter_name, CAST(cntr_value AS BIGINT) AS cntr_value
+        FROM sys.dm_os_performance_counters
+        WHERE object_name LIKE '%Buffer Manager%'
+          AND counter_name IN ('Page lookups/sec', 'Page reads/sec')
+      `);
+      const counters = Object.fromEntries(
+        bufferResult.recordset.map((row) => [row.counter_name.trim(), Number(row.cntr_value)])
+      );
+      const pageLookups = counters["Page lookups/sec"] ?? 0;
+      const pageReads = counters["Page reads/sec"] ?? 0;
+      result.bufferCache = {
+        hitRatioPct: computeHitRatioPct(pageLookups, pageReads),
+        blocksHit: pageLookups - pageReads,
+        blocksRead: pageReads
+      };
+    } catch {
+      notes.push(
+        "Buffer cache metrics unavailable: connecting user lacks the VIEW SERVER STATE permission (VIEW DATABASE STATE on Azure SQL Database)."
+      );
+    }
+    if (notes.length > 0) {
+      result.notes = notes;
+    }
+    return result;
+  }
   async getStoredProcedures(schema, routineType) {
     if (!this.connection) {
       throw new Error("Not connected to SQL Server database");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebase/dbhub",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "mcpName": "io.github.bytebase/dbhub",
   "description": "Minimal, token-efficient Database MCP Server for PostgreSQL, MySQL, SQL Server, SQLite, MariaDB",
   "repository": {

package/dist/chunk-DUCNPMNW.js

@@ -1,113 +0,0 @@
-import {
-  obfuscateDSNPassword
-} from "./chunk-JEZZN2YZ.js";
-
-// src/utils/dsn-database.ts
-var MissingDatabaseError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "MissingDatabaseError";
-  }
-};
-function requireDatabaseInDSN(database, dsn, label) {
-  if (database) {
-    return;
-  }
-  throw new MissingDatabaseError(
-    `${label} DSN must name a database.
-Provided: ${obfuscateDSNPassword(dsn)}
-Add the database to the DSN, e.g. ...:3306/mydb
-To work with several databases, define one [[sources]] entry per database in a TOML config file: https://dbhub.ai/config/toml`
-  );
-}
-
-// src/utils/multi-statement-result-parser.ts
-function isMetadataObject(element) {
-  if (!element || typeof element !== "object" || Array.isArray(element)) {
-    return false;
-  }
-  return "affectedRows" in element || "insertId" in element || "fieldCount" in element || "warningStatus" in element;
-}
-function isMultiStatementResult(results) {
-  if (!Array.isArray(results) || results.length === 0) {
-    return false;
-  }
-  const firstElement = results[0];
-  return isMetadataObject(firstElement) || Array.isArray(firstElement);
-}
-function extractRowsFromMultiStatement(results) {
-  if (!Array.isArray(results)) {
-    return [];
-  }
-  const allRows = [];
-  for (const result of results) {
-    if (Array.isArray(result)) {
-      allRows.push(...result);
-    }
-  }
-  return allRows;
-}
-function extractAffectedRows(results) {
-  if (isMetadataObject(results)) {
-    return results.affectedRows || 0;
-  }
-  if (!Array.isArray(results)) {
-    return 0;
-  }
-  if (isMultiStatementResult(results)) {
-    let totalAffected = 0;
-    for (const result of results) {
-      if (isMetadataObject(result)) {
-        totalAffected += result.affectedRows || 0;
-      } else if (Array.isArray(result)) {
-        totalAffected += result.length;
-      }
-    }
-    return totalAffected;
-  }
-  return results.length;
-}
-function parseQueryResults(results) {
-  if (!Array.isArray(results)) {
-    return [];
-  }
-  if (isMultiStatementResult(results)) {
-    return extractRowsFromMultiStatement(results);
-  }
-  return results;
-}
-
-// src/utils/readonly-transaction.ts
-async function withReadOnlyTransaction(conn, readonly, supportsReadOnlyTransaction, execute) {
-  if (!readonly) {
-    return execute();
-  }
-  try {
-    await conn.query(
-      supportsReadOnlyTransaction ? "START TRANSACTION READ ONLY" : "START TRANSACTION"
-    );
-    const result = await execute();
-    await conn.query(supportsReadOnlyTransaction ? "COMMIT" : "ROLLBACK");
-    return result;
-  } catch (error) {
-    try {
-      await conn.query("ROLLBACK");
-    } catch {
-    }
-    throw error;
-  }
-}
-
-// src/utils/server-flavor.ts
-function isTiDBVersion(version) {
-  return typeof version === "string" && /tidb/i.test(version);
-}
-
-export {
-  MissingDatabaseError,
-  requireDatabaseInDSN,
-  extractAffectedRows,
-  parseQueryResults,
-  withReadOnlyTransaction,
-  isTiDBVersion
-};