@zz1996/dbhub-dameng 0.1.7 → 1.2.5-dameng.621

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,
@@ -10,31 +12,41 @@ import {
   loadTomlConfig,
   mapArgumentsToArray,
   resolveAllowedHosts,
+  resolveAuthTokens,
   resolveHost,
   resolvePort,
   resolveSourceConfigs,
   resolveTomlConfigPath,
   resolveTransport
-} from "./chunk-2A2QF3CS.js";
+} from "./chunk-HGU7ILEZ.js";
 import {
   loadConnectors
 } from "./chunk-WVVMH6FJ.js";
 import {
   quoteQualifiedIdentifier
-} from "./chunk-IPK7BYBL.js";
+} from "./chunk-JFWX35TB.js";
 import {
-  ConnectorRegistry,
   getDatabaseTypeFromDSN,
   getDefaultPortForType,
-  parseConnectionInfoFromDSN,
+  parseConnectionInfoFromDSN
+} from "./chunk-3RJRH3CN.js";
+import {
+  allowedKeywords,
+  getFirstKeyword,
+  hasEscapeHatchFunction,
+  isReadOnlySQL,
+  sqlServerDynamicSqlPattern
+} from "./chunk-HDPZAIDL.js";
+import {
+  ConnectorRegistry,
   splitSQLStatements,
   stripCommentsAndStrings
-} from "./chunk-SQA2ISDE.js";
+} from "./chunk-2JL4KCP5.js";
 
 // src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer, createMcpHandler } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { toNodeHandler } from "@modelcontextprotocol/node";
 import express from "express";
 import http from "http";
 import path from "path";
@@ -95,98 +107,51 @@ function createToolSuccessResponse(data, meta = {}) {
   };
 }
 
-// src/utils/allowed-keywords.ts
-var allowedKeywords = {
-  postgres: ["select", "with", "explain", "show"],
-  mysql: ["select", "with", "explain", "show", "describe", "desc"],
-  mariadb: ["select", "with", "explain", "show", "describe", "desc"],
-  sqlite: ["select", "with", "explain", "pragma"],
-  // SQL Server has no native EXPLAIN statement; the connector translates a
-  // leading `EXPLAIN` into a SET SHOWPLAN_XML request (see SQLServerConnector).
-  sqlserver: ["select", "with", "explain"],
-  dameng: ["select", "with", "explain", "describe", "desc"]
+// src/utils/sql-access-policy.ts
+var CLASS_SEVERITY = {
+  read: 0,
+  dml: 1,
+  ddl: 2,
+  admin: 3,
+  unknown: 4
 };
-var mutatingKeywords = [
-  "insert",
-  "update",
-  "delete",
-  "drop",
-  "alter",
-  "create",
-  "truncate",
-  "merge",
-  "grant",
-  "revoke",
-  "rename"
-];
-var mutatingPattern = new RegExp(
-  `\\b(?:${mutatingKeywords.join("|")})\\b`,
-  "i"
-);
-var mutatingPatternWithReplace = new RegExp(
-  `\\b(?:${mutatingKeywords.join("|")}|replace\\s+(?:(?:low_priority|delayed)\\s+)?into)\\b`,
-  "i"
-);
-var mutatingPatterns = {
-  postgres: mutatingPattern,
-  mysql: mutatingPatternWithReplace,
-  mariadb: mutatingPatternWithReplace,
-  sqlite: mutatingPatternWithReplace,
-  sqlserver: mutatingPattern,
-  dameng: mutatingPattern
-};
-var selectIntoPattern = /\bselect\b[\s\S]+\binto\b/i;
-var sqliteReadOnlyArgPragmas = /* @__PURE__ */ new Set([
-  "table_info",
-  "index_info",
-  "index_list",
-  "foreign_key_list"
-]);
-var sqlitePragmaParenPattern = /^pragma\s+(?:[a-z0-9_]+\.)?([a-z0-9_]+)\s*\(/;
-var explainAnalyzePattern = /^explain\s+(?:\([^)]*\banalyze\b(?!\s*(?:=\s*)?(?:false|off|0)\b)[^)]*\)|\banalyze\b(?!\s*(?:=\s*)?(?:false|off|0)\b)(?:\s+verbose\b)?)/i;
-function isReadOnlySQL(sql, connectorType) {
-  return checkReadOnly(
-    stripCommentsAndStrings(sql, connectorType).trim().toLowerCase(),
-    connectorType
-  );
+var ddlPattern = /\b(?:create|alter|drop|truncate|rename)\b/i;
+var dmlPattern = /\b(?:insert|update|delete|merge|replace\s+(?:(?:low_priority|delayed)\s+)?into)\b/i;
+var grantRevokePattern = /\b(?:grant|revoke)\b/i;
+function isAdminStatement(stripped, connectorType) {
+  if (grantRevokePattern.test(stripped)) return true;
+  if (hasEscapeHatchFunction(stripped, connectorType)) return true;
+  return connectorType === "sqlserver" && sqlServerDynamicSqlPattern.test(stripped);
 }
-function checkReadOnly(cleanedSQL, connectorType) {
-  if (!cleanedSQL) {
-    return false;
-  }
-  const firstWord = cleanedSQL.match(/\S+/)?.[0] ?? "";
-  const keywordList = allowedKeywords[connectorType] || [];
-  if (!keywordList.includes(firstWord)) {
-    return false;
-  }
-  if (firstWord === "with") {
-    const pattern = mutatingPatterns[connectorType] ?? mutatingPattern;
-    if (pattern.test(cleanedSQL)) {
-      return false;
-    }
-  }
-  if (firstWord === "pragma" && connectorType === "sqlite") {
-    if (cleanedSQL.includes("=")) {
-      return false;
-    }
-    const parenMatch = cleanedSQL.match(sqlitePragmaParenPattern);
-    if (parenMatch && !sqliteReadOnlyArgPragmas.has(parenMatch[1])) {
-      return false;
-    }
-  }
-  if ((firstWord === "select" || firstWord === "with") && selectIntoPattern.test(cleanedSQL)) {
-    return false;
-  }
-  if (firstWord === "explain") {
-    const m = explainAnalyzePattern.exec(cleanedSQL);
-    if (m) {
-      const afterExplain = cleanedSQL.slice(m[0].length).trim();
-      if (afterExplain && !checkReadOnly(afterExplain, connectorType)) {
-        return false;
-      }
+function policyFromReadonly(readonly) {
+  const write = readonly === true ? "deny" : "allow";
+  return { read: "allow", dml: write, ddl: write, admin: write, unknown: write };
+}
+function isReadOnlyPolicy(policy) {
+  return policy.dml === "deny" && policy.ddl === "deny" && policy.admin === "deny" && policy.unknown === "deny";
+}
+function classifyStatement(sql, connectorType) {
+  if (isReadOnlySQL(sql, connectorType)) {
+    return "read";
+  }
+  const stripped = stripCommentsAndStrings(sql, connectorType);
+  if (isAdminStatement(stripped, connectorType)) return "admin";
+  if (ddlPattern.test(stripped)) return "ddl";
+  if (dmlPattern.test(stripped)) return "dml";
+  return "unknown";
+}
+function classifySQL(sql, connectorType) {
+  let strictest = "read";
+  for (const statement of splitSQLStatements(sql, connectorType)) {
+    const cls = classifyStatement(statement, connectorType);
+    if (CLASS_SEVERITY[cls] > CLASS_SEVERITY[strictest]) {
+      strictest = cls;
     }
   }
-  return true;
+  return strictest;
+}
+function sqlVerdict(policy, sql, connectorType) {
+  return policy[classifySQL(sql, connectorType)];
 }
 
 // src/requests/store.ts
@@ -240,18 +205,41 @@ var RequestStore = class {
 var requestStore = new RequestStore();
 
 // src/utils/client-identifier.ts
-function getClientIdentifier(extra) {
-  const userAgent = extra?.requestInfo?.headers?.["user-agent"];
+function getClientIdentifier(ctx) {
+  const userAgent = ctx?.http?.req?.headers.get("user-agent");
   if (userAgent) {
     return userAgent;
   }
   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 toStatementsPayload(resultSets) {
+  return resultSets.map((set) => ({
+    sql: set.sql,
+    rows: set.rows,
+    count: set.rowCount,
+    // Only present when a max_rows cap actually cut off rows, so consumers
+    // can tell a capped result from a table with exactly max_rows rows
+    // (and complete results don't pay the extra tokens).
+    ...set.truncated ? { truncated: true } : {}
+  }));
+}
+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"}`;
 }
@@ -287,10 +275,7 @@ function tryClassifyConnectionError(error, rawSourceId, displaySourceId) {
 var executeSqlSchema = {
   sql: z.string().describe("SQL to execute (multiple statements separated by ;)")
 };
-function areAllStatementsReadOnly(sql, connectorType) {
-  const statements = splitSQLStatements(sql, connectorType);
-  return statements.every((statement) => isReadOnlySQL(statement, connectorType));
-}
+var executeSqlInputSchema = z.object(executeSqlSchema);
 function createExecuteSqlToolHandler(sourceId) {
   return async (args, extra) => {
     const { sql } = args;
@@ -305,20 +290,19 @@ function createExecuteSqlToolHandler(sourceId) {
       const actualSourceId = connector.getId();
       const registry = getToolRegistry();
       const toolConfig = registry.getBuiltinToolConfig(BUILTIN_TOOL_EXECUTE_SQL, actualSourceId);
-      const isReadonly = toolConfig?.readonly === true;
-      if (isReadonly && !areAllStatementsReadOnly(sql, connector.id)) {
+      const policy = policyFromReadonly(toolConfig?.readonly);
+      if (sqlVerdict(policy, sql, connector.id) === "deny") {
         errorMessage = `Read-only mode is enabled. Only the following SQL operations are allowed: ${allowedKeywords[connector.id]?.join(", ") || "none"}`;
         success = false;
         return createToolErrorResponse(errorMessage, "READONLY_VIOLATION");
       }
       const executeOptions = {
-        readonly: toolConfig?.readonly,
+        readonly: isReadOnlyPolicy(policy),
         maxRows: toolConfig?.max_rows
       };
       result = await connector.executeSQL(sql, executeOptions);
       const responseData = {
-        rows: result.rows,
-        count: result.rowCount,
+        statements: toStatementsPayload(result.resultSets),
         source_id: effectiveSourceId,
         ...result.messages && result.messages.length > 0 ? { messages: result.messages } : {}
       };
@@ -355,6 +339,7 @@ var searchDatabaseObjectsSchema = {
   detail_level: z2.enum(["names", "summary", "full"]).default("names").describe("Detail: names (minimal), summary (metadata), full (all)"),
   limit: z2.number().int().positive().max(1e3).default(100).describe("Max results")
 };
+var searchDatabaseObjectsInputSchema = z2.object(searchDatabaseObjectsSchema);
 function likePatternToRegex(pattern) {
   const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/%/g, ".*").replace(/_/g, ".");
   return new RegExp(`^${escaped}$`, "i");
@@ -375,9 +360,10 @@ async function getTableRowCount(connector, tableName, schemaName) {
     }
     const qualifiedTable = quoteQualifiedIdentifier(tableName, schemaName, connector.id);
     const countQuery = `SELECT COUNT(*) as count FROM ${qualifiedTable}`;
-    const result = await connector.executeSQL(countQuery, { maxRows: 1 });
-    if (result.rows && result.rows.length > 0) {
-      return Number(result.rows[0].count || result.rows[0].COUNT || 0);
+    const result = await connector.executeSQL(countQuery, { maxRows: 1, readonly: true });
+    const rows = result.resultSets[0]?.rows;
+    if (rows && rows.length > 0) {
+      return Number(rows[0].count || rows[0].COUNT || 0);
     }
   } catch (error) {
     return null;
@@ -431,25 +417,23 @@ async function searchTables(connector, pattern, schemaFilter, detailLevel, limit
   for (const schemaName of schemasToSearch) {
     if (results.length >= limit) break;
     try {
-      const searchableConnector = connector;
-      const matched = searchableConnector.searchTables ? await searchableConnector.searchTables(pattern, schemaName, limit - results.length) : (await connector.getTables(schemaName)).filter((table) => regex.test(table)).map((name) => ({ name, schema: schemaName }));
-      for (const tableMatch of matched) {
+      const tables = await connector.getTables(schemaName);
+      const matched = tables.filter((table) => regex.test(table));
+      for (const tableName of matched) {
         if (results.length >= limit) break;
-        const tableName = tableMatch.name;
-        const matchedSchema = tableMatch.schema;
         if (detailLevel === "names") {
           results.push({
             name: tableName,
-            schema: matchedSchema
+            schema: schemaName
           });
         } else if (detailLevel === "summary") {
           try {
-            const columns = await connector.getTableSchema(tableName, matchedSchema);
-            const rowCount = await getTableRowCount(connector, tableName, matchedSchema);
-            const comment = await getTableComment(connector, tableName, matchedSchema);
+            const columns = await connector.getTableSchema(tableName, schemaName);
+            const rowCount = await getTableRowCount(connector, tableName, schemaName);
+            const comment = await getTableComment(connector, tableName, schemaName);
             results.push({
               name: tableName,
-              schema: matchedSchema,
+              schema: schemaName,
               column_count: columns.length,
               row_count: rowCount,
               ...comment ? { comment } : {}
@@ -457,20 +441,20 @@ async function searchTables(connector, pattern, schemaFilter, detailLevel, limit
           } catch (error) {
             results.push({
               name: tableName,
-              schema: matchedSchema,
+              schema: schemaName,
               column_count: null,
               row_count: null
             });
           }
         } else {
           try {
-            const columns = await connector.getTableSchema(tableName, matchedSchema);
-            const indexes = await connector.getTableIndexes(tableName, matchedSchema);
-            const rowCount = await getTableRowCount(connector, tableName, matchedSchema);
-            const comment = await getTableComment(connector, tableName, matchedSchema);
+            const columns = await connector.getTableSchema(tableName, schemaName);
+            const indexes = await connector.getTableIndexes(tableName, schemaName);
+            const rowCount = await getTableRowCount(connector, tableName, schemaName);
+            const comment = await getTableComment(connector, tableName, schemaName);
             results.push({
               name: tableName,
-              schema: matchedSchema,
+              schema: schemaName,
               column_count: columns.length,
               row_count: rowCount,
               ...comment ? { comment } : {},
@@ -491,7 +475,7 @@ async function searchTables(connector, pattern, schemaFilter, detailLevel, limit
           } catch (error) {
             results.push({
               name: tableName,
-              schema: matchedSchema,
+              schema: schemaName,
               error: `Unable to fetch full details: ${error.message}`
             });
           }
@@ -510,7 +494,7 @@ async function searchViews(connector, pattern, schemaFilter, detailLevel, limit)
   if (schemaFilter) {
     schemasToSearch = [schemaFilter];
   } else {
-    schemasToSearch = await connector.getSchemas();
+    schemasToSearch = await resolveDefaultSchemas(connector);
   }
   for (const schemaName of schemasToSearch) {
     if (results.length >= limit) break;
@@ -586,36 +570,6 @@ async function searchColumns(connector, pattern, schemaFilter, tableFilter, deta
   for (const schemaName of schemasToSearch) {
     if (results.length >= limit) break;
     try {
-      const searchableConnector = connector;
-      if (searchableConnector.searchColumns) {
-        const matchedColumns = await searchableConnector.searchColumns(
-          pattern,
-          schemaName,
-          tableFilter,
-          limit - results.length
-        );
-        for (const column of matchedColumns) {
-          if (results.length >= limit) break;
-          if (detailLevel === "names") {
-            results.push({
-              name: column.name,
-              table: column.table,
-              schema: column.schema
-            });
-          } else {
-            results.push({
-              name: column.name,
-              table: column.table,
-              schema: column.schema,
-              type: column.type,
-              nullable: column.nullable,
-              default: column.default,
-              ...column.description ? { description: column.description } : {}
-            });
-          }
-        }
-        continue;
-      }
       let tablesToSearch;
       if (tableFilter) {
         tablesToSearch = [tableFilter];
@@ -791,10 +745,10 @@ function createSearchDatabaseObjectsToolHandler(sourceId) {
         }
       }
       if (schema) {
-        const exists = connector.schemaExists ? await connector.schemaExists(schema) : (await connector.getSchemas()).includes(schema);
-        if (!exists) {
+        const schemas = await connector.getSchemas();
+        if (!schemas.includes(schema)) {
           success = false;
-          errorMessage = `Schema '${schema}' does not exist`;
+          errorMessage = `Schema '${schema}' does not exist. Available schemas: ${schemas.join(", ")}`;
           return createToolErrorResponse(errorMessage, "SCHEMA_NOT_FOUND");
         }
       }
@@ -861,15 +815,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.resultSets[0].rows,
+        count: result.resultSets[0].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 "";
@@ -879,17 +969,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({
@@ -901,24 +991,32 @@ 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 maxRowsNote = executeOptions.maxRows ? ` (limited to ${executeOptions.maxRows} rows; capped results carry "truncated": true)` : "";
   const description = isSingleSource ? `${userDescPrefix}Execute SQL queries on the ${dbType} database${readonlyNote}${maxRowsNote}` : `${userDescPrefix}Execute SQL queries on the '${sourceId}' ${dbType} database${readonlyNote}${maxRowsNote}`;
-  const isReadonly = executeOptions.readonly === true;
+  const isReadonly = isReadOnlyPolicy(policyFromReadonly(executeOptions.readonly));
   const annotations = {
     title,
     readOnlyHint: isReadonly,
@@ -931,25 +1029,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).` : `${userDescPrefix}Show the execution plan for a SQL statement on the '${sourceId}' ${dbType} database without running it (always read-only).`;
+  const annotations = {
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false
+  };
   return {
-    name: toolName,
+    name,
     description,
-    title
+    schema: explainSqlSchema,
+    annotations
+  };
+}
+function getHealthCheckMetadata(sourceId) {
+  const { dbType, isSingleSource, name, title, userDescPrefix } = resolveBuiltinToolNaming(
+    sourceId,
+    "health_check",
+    "Health Check"
+  );
+  const description = isSingleSource ? `${userDescPrefix}Report connection pool and buffer cache health metrics for the ${dbType} database (read-only).` : `${userDescPrefix}Report connection pool and buffer cache health metrics for the '${sourceId}' ${dbType} database (read-only).`;
+  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,
+    description,
+    schema: healthCheckSchema,
+    annotations
   };
 }
 function customParamsToToolParams(params) {
@@ -986,13 +1121,13 @@ function buildSearchObjectsTool(sourceId) {
         name: "object_type",
         type: "string",
         required: true,
-        description: "Object type to search: schema, table, view, column, procedure, function, index"
+        description: "Object type to search"
       },
       {
         name: "pattern",
         type: "string",
         required: false,
-        description: "LIKE pattern (% = any chars, _ = one char). Default: %"
+        description: "LIKE pattern (% = any chars, _ = one char)"
       },
       {
         name: "schema",
@@ -1016,13 +1151,23 @@ function buildSearchObjectsTool(sourceId) {
         name: "limit",
         type: "integer",
         required: false,
-        description: "Max results (default: 100, max: 1000)"
+        description: "Max results"
       }
     ],
     readonly: true
     // 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,
@@ -1041,6 +1186,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);
     }
@@ -1048,7 +1195,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 {};
@@ -1058,26 +1205,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),
@@ -1094,9 +1241,17 @@ function buildZodSchemaFromParameters(parameters) {
   }
   return schemaShape;
 }
+var customToolInputSchemas = /* @__PURE__ */ new WeakMap();
+function getCustomToolInputSchema(toolConfig) {
+  let schema = customToolInputSchemas.get(toolConfig);
+  if (!schema) {
+    schema = z6.object(buildZodSchemaFromParameters(toolConfig.parameters));
+    customToolInputSchemas.set(toolConfig, schema);
+  }
+  return schema;
+}
 function createCustomToolHandler(toolConfig) {
-  const zodSchemaShape = buildZodSchemaFromParameters(toolConfig.parameters);
-  const zodSchema = z4.object(zodSchemaShape);
+  const zodSchema = getCustomToolInputSchema(toolConfig);
   return async (args, extra) => {
     const startTime = Date.now();
     let success = true;
@@ -1106,12 +1261,12 @@ function createCustomToolHandler(toolConfig) {
       const validatedArgs = zodSchema.parse(args);
       await ConnectorManager.ensureConnected(toolConfig.source);
       const connector = ConnectorManager.getCurrentConnector(toolConfig.source);
+      const policy = policyFromReadonly(toolConfig.readonly);
       const executeOptions = {
-        readonly: toolConfig.readonly,
+        readonly: isReadOnlyPolicy(policy),
         maxRows: toolConfig.max_rows
       };
-      const isReadonly = executeOptions.readonly === true;
-      if (isReadonly && !isReadOnlySQL(toolConfig.statement, connector.id)) {
+      if (sqlVerdict(policy, toolConfig.statement, connector.id) === "deny") {
         errorMessage = createReadonlyViolationMessage(toolConfig.name, toolConfig.source, connector.id);
         success = false;
         return createToolErrorResponse(errorMessage, "READONLY_VIOLATION");
@@ -1126,8 +1281,7 @@ function createCustomToolHandler(toolConfig) {
         paramValues
       );
       const responseData = {
-        rows: result.rows,
-        count: result.rowCount,
+        statements: toStatementsPayload(result.resultSets),
         source_id: toolConfig.source
       };
       return createToolSuccessResponse(responseData);
@@ -1136,7 +1290,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 {
@@ -1176,6 +1330,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);
       }
@@ -1188,7 +1346,7 @@ function registerExecuteSqlTool(server, sourceId) {
     metadata.name,
     {
       description: metadata.description,
-      inputSchema: metadata.schema,
+      inputSchema: executeSqlInputSchema,
       annotations: metadata.annotations
     },
     createExecuteSqlToolHandler(sourceId)
@@ -1200,7 +1358,7 @@ function registerSearchObjectsTool(server, sourceId) {
     metadata.name,
     {
       description: metadata.description,
-      inputSchema: searchDatabaseObjectsSchema,
+      inputSchema: searchDatabaseObjectsInputSchema,
       annotations: {
         title: metadata.title,
         readOnlyHint: true,
@@ -1212,16 +1370,39 @@ 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;
-  const isReadOnly = isReadOnlySQL(toolConfig.statement, dbType);
-  const zodSchema = buildZodSchemaFromParameters(toolConfig.parameters);
+  const isReadOnly = classifySQL(toolConfig.statement, dbType) === "read";
   server.registerTool(
     toolConfig.name,
     {
       description: toolConfig.description,
-      inputSchema: zodSchema,
+      inputSchema: getCustomToolInputSchema(toolConfig),
       annotations: {
         title: `${toolConfig.name} (${dbType})`,
         readOnlyHint: isReadOnly,
@@ -1654,6 +1835,32 @@ function validateOrigin(originHeader, hostHeader, allowedHosts) {
   return { ok: true };
 }
 
+// src/utils/auth-token.ts
+import { timingSafeEqual } from "node:crypto";
+var BEARER_PREFIX = "Bearer ";
+function constantTimeEqual(a, b) {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+function validateAuthToken(authorizationHeader, tokens) {
+  if (tokens.length === 0) return { ok: true };
+  if (!authorizationHeader || !authorizationHeader.startsWith(BEARER_PREFIX)) {
+    return {
+      ok: false,
+      status: 401,
+      message: "Missing or malformed Authorization header. Expected: Bearer <token>"
+    };
+  }
+  const presented = authorizationHeader.slice(BEARER_PREFIX.length);
+  const matches = tokens.some((token) => constantTimeEqual(presented, token));
+  if (!matches) {
+    return { ok: false, status: 401, message: "Invalid bearer token" };
+  }
+  return { ok: true };
+}
+
 // src/server.ts
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = path.dirname(__filename);
@@ -1661,6 +1868,8 @@ var packageJsonPath = path.join(__dirname, "..", "package.json");
 var packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
 var SERVER_NAME = "DBHub MCP Server";
 var SERVER_VERSION = packageJson.version;
+var TOOLS_LIST_CACHE_TTL_MS = 3e5;
+var logMcpError = (scope) => (error) => console.error(`MCP ${scope} error:`, error);
 function generateBanner(version, modes = []) {
   const modeText = modes.length > 0 ? ` [${modes.join(" | ")}]` : "";
   return `
@@ -1706,7 +1915,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-XSX2VZTD.js");
+    const { initializeToolRegistry: initializeToolRegistry2 } = await import("./registry-WVSFVS35.js");
     initializeToolRegistry2({
       sources: sourceConfigsData.sources,
       tools: sourceConfigsData.tools
@@ -1717,10 +1926,18 @@ See documentation for more details on configuring database connections.
       initialTools: sourceConfigsData.tools
     });
     const createServer = () => {
-      const server = new McpServer({
-        name: SERVER_NAME,
-        version: SERVER_VERSION
-      });
+      const server = new McpServer(
+        {
+          name: SERVER_NAME,
+          version: SERVER_VERSION
+        },
+        {
+          // `private` keeps caching client-side (no shared/proxy caches).
+          cacheHints: {
+            "tools/list": { ttlMs: TOOLS_LIST_CACHE_TTL_MS, cacheScope: "private" }
+          }
+        }
+      );
       registerTools(server);
       return server;
     };
@@ -1728,6 +1945,7 @@ See documentation for more details on configuring database connections.
     const port = transportData.type === "http" ? resolvePort().port : null;
     const host = transportData.type === "http" ? resolveHost().host : null;
     const allowedHosts = transportData.type === "http" ? buildAllowedHosts(resolveAllowedHosts().hosts, host ?? void 0, getSelfHosts()) : /* @__PURE__ */ new Set();
+    const { tokens: authTokens, source: authTokenSource } = resolveAuthTokens();
     const activeModes = [];
     const modeDescriptions = [];
     const isDemo = isDemoMode();
@@ -1762,44 +1980,33 @@ See documentation for more details on configuring database connections.
         }
         res.header("Access-Control-Allow-Origin", origin || "http://localhost");
         res.header("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-        res.header("Access-Control-Allow-Headers", "Content-Type, Mcp-Session-Id");
+        res.header("Access-Control-Allow-Headers", "Content-Type, Authorization, Mcp-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name");
         res.header("Access-Control-Allow-Credentials", "true");
         if (req.method === "OPTIONS") {
           return res.sendStatus(200);
         }
         next();
       });
-      const frontendPath = path.join(__dirname, "public");
-      app.use(express.static(frontendPath));
       app.get("/healthz", (req, res) => {
         res.status(200).send("OK");
       });
+      app.use((req, res, next) => {
+        const result = validateAuthToken(req.headers.authorization, authTokens);
+        if (!result.ok) {
+          res.header("WWW-Authenticate", "Bearer");
+          return res.status(result.status).json({ error: "Unauthorized", message: result.message });
+        }
+        next();
+      });
+      const frontendPath = path.join(__dirname, "public");
+      app.use(express.static(frontendPath));
       app.get("/api/sources", listSources);
       app.get("/api/sources/:sourceId", getSource);
       app.get("/api/requests", listRequests);
-      app.get("/mcp", (req, res) => {
-        res.status(405).json({
-          error: "Method Not Allowed",
-          message: "SSE streaming is not supported in stateless mode. Use POST requests with JSON responses."
-        });
-      });
-      app.post("/mcp", async (req, res) => {
-        try {
-          const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: void 0,
-            // Disable session management for stateless mode
-            enableJsonResponse: true
-            // Use JSON responses (SSE not supported in stateless mode)
-          });
-          const server = createServer();
-          await server.connect(transport);
-          await transport.handleRequest(req, res, req.body);
-        } catch (error) {
-          console.error("Error handling request:", error);
-          if (!res.headersSent) {
-            res.status(500).json({ error: "Internal server error" });
-          }
-        }
+      const mcpHandler = createMcpHandler(createServer, { onerror: logMcpError("handler") });
+      const mcpNodeHandler = toNodeHandler(mcpHandler, { onerror: logMcpError("adapter") });
+      app.all("/mcp", (req, res) => {
+        void mcpNodeHandler(req, res, req.body);
       });
       if (process.env.NODE_ENV !== "development") {
         app.get("*", (req, res) => {
@@ -1824,6 +2031,11 @@ See documentation for more details on configuring database connections.
         } else {
           console.error(`Allowed hosts: ${[...allowedHosts].join(", ")} (set --allowed-hosts to serve other hostnames)`);
         }
+        if (authTokens.length > 0) {
+          console.error(`Auth: bearer token required (${authTokens.length} token(s) configured via ${authTokenSource})`);
+        } else {
+          console.error("Auth: disabled (set --auth-token or DBHUB_AUTH_TOKEN to require a bearer token)");
+        }
         if (process.env.NODE_ENV === "development") {
           console.error("Development mode detected!");
           console.error("   Workbench dev server (with HMR): http://localhost:5173");
@@ -1835,16 +2047,14 @@ See documentation for more details on configuring database connections.
         console.error(`MCP server endpoint at http://${userHost}:${boundPort}/mcp`);
       });
     } else {
-      const server = createServer();
-      const transport = new StdioServerTransport();
-      await server.connect(transport);
+      const stdioHandle = serveStdio(createServer, { onerror: logMcpError("stdio") });
       console.error("MCP server running on stdio");
       let isShuttingDown = false;
       const shutdown = async () => {
         if (isShuttingDown) return;
         isShuttingDown = true;
         console.error("Shutting down...");
-        await transport.close();
+        await stdioHandle.close();
         await connectorManager.disconnect();
         process.exit(0);
       };
@@ -1860,12 +2070,12 @@ See documentation for more details on configuring database connections.
 
 // src/index.ts
 var connectorModules = [
-  { load: () => import("./postgres-VFNLBWMF.js"), name: "PostgreSQL", driver: "pg" },
-  { load: () => import("./sqlserver-OE4SFH4B.js"), name: "SQL Server", driver: "mssql" },
-  { load: () => import("./sqlite-IOUAYHGE.js"), name: "SQLite", driver: "node:sqlite" },
-  { load: () => import("./mysql-A43SL7UM.js"), name: "MySQL", driver: "mysql2" },
-  { load: () => import("./mariadb-7F72IRB4.js"), name: "MariaDB", driver: "mariadb" },
-  { load: () => import("./dameng-5KYI5JBK.js"), name: "Dameng", driver: "dmdb" }
+  { load: () => import("./postgres-C24SBQ4I.js"), name: "PostgreSQL", driver: "pg" },
+  { load: () => import("./sqlserver-KZPPK67Q.js"), name: "SQL Server", driver: "mssql" },
+  { load: () => import("./dameng-NKF7NZKE.js"), name: "Dameng", driver: "dmdb" },
+  { load: () => import("./sqlite-7BNGDMBZ.js"), name: "SQLite", driver: "node:sqlite" },
+  { load: () => import("./mysql-TESH7KKV.js"), name: "MySQL", driver: "mysql2" },
+  { load: () => import("./mariadb-MMC6WMEG.js"), name: "MariaDB", driver: "mariadb" }
 ];
 loadConnectors(connectorModules).then(() => main()).catch((error) => {
   console.error("Fatal error:", error);