@bytebase/dbhub 0.22.6 → 0.23.0

package/README.md

@@ -80,6 +80,10 @@ docker run --rm --init \
 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.
+
 **Demo Mode:**
 
 ```bash

package/dist/{chunk-WPXPKRDU.js → chunk-COEDRFSK.js}

@@ -68,7 +68,8 @@ function findDefaultSSHKey() {
   }
   return void 0;
 }
-function parseSSHConfig(hostAlias, configPath) {
+function parseSSHConfig(hostAlias, configPath, options = {}) {
+  const { requireUser = true } = options;
   const sshConfigPath = resolveSymlink(configPath);
   if (!isFile(sshConfigPath)) {
     return null;
@@ -77,7 +78,7 @@ function parseSSHConfig(hostAlias, configPath) {
     const configContent = readFileSync(sshConfigPath, "utf8");
     const config = SSHConfig.parse(configContent);
     const hostConfig = config.compute(hostAlias);
-    if (!hostConfig || !hostConfig.HostName && !hostConfig.User) {
+    if (!hostConfig || !hostConfig.HostName && !hostConfig.User && !hostConfig.Port && !hostConfig.IdentityFile && !hostConfig.ProxyJump) {
       return null;
     }
     const sshConfig = {};
@@ -111,10 +112,10 @@ function parseSSHConfig(hostAlias, configPath) {
     if (hostConfig.ProxyCommand) {
       console.error("Warning: ProxyCommand in SSH config is not supported by DBHub. Use ProxyJump instead.");
     }
-    if (!sshConfig.host || !sshConfig.username) {
+    if (!sshConfig.host || requireUser && !sshConfig.username) {
       return null;
     }
-    return sshConfig;
+    return requireUser ? sshConfig : sshConfig;
   } catch (error) {
     console.error(`Error parsing SSH config: ${error instanceof Error ? error.message : String(error)}`);
     return null;
@@ -193,6 +194,45 @@ function parseJumpHosts(proxyJump) {
   }
   return proxyJump.split(",").map((s) => s.trim()).filter((s) => s.length > 0).map(parseJumpHost);
 }
+function resolveJumpHosts(proxyJump, configPath, visited = /* @__PURE__ */ new Set()) {
+  if (!proxyJump || proxyJump.trim() === "" || proxyJump.toLowerCase() === "none") {
+    return [];
+  }
+  const resolved = [];
+  for (const token of proxyJump.split(",").map((s) => s.trim()).filter((s) => s.length > 0)) {
+    const hop = parseJumpHost(token);
+    if (!looksLikeSSHAlias(hop.host)) {
+      resolved.push(hop);
+      continue;
+    }
+    if (visited.has(hop.host)) {
+      throw new Error(`Cycle detected in SSH ProxyJump chain at alias "${hop.host}"`);
+    }
+    const aliasConfig = parseSSHConfig(hop.host, configPath, { requireUser: false });
+    if (!aliasConfig) {
+      resolved.push(hop);
+      continue;
+    }
+    if (aliasConfig.proxyJump) {
+      resolved.push(...resolveJumpHosts(aliasConfig.proxyJump, configPath, new Set(visited).add(hop.host)));
+    }
+    resolved.push({
+      host: aliasConfig.host,
+      // An explicit `:port` on the token wins; otherwise use the alias's Port (default 22).
+      port: tokenHasExplicitPort(token) ? hop.port : aliasConfig.port ?? 22,
+      // An explicit `user@` on the token wins; otherwise the alias's User.
+      username: hop.username ?? aliasConfig.username,
+      privateKey: aliasConfig.privateKey,
+      passphrase: aliasConfig.passphrase
+    });
+  }
+  return resolved;
+}
+function tokenHasExplicitPort(token) {
+  const atIndex = token.indexOf("@");
+  const hostPart = atIndex !== -1 ? token.slice(atIndex + 1) : token;
+  return hostPart.startsWith("[") ? /\]:\d+$/.test(hostPart) : /:\d+$/.test(hostPart);
+}
 
 // src/utils/ssh-tunnel.ts
 var SSHTunnel = class {
@@ -215,29 +255,8 @@ var SSHTunnel = class {
     }
     this.isConnected = true;
     try {
-      const jumpHosts = config.proxyJump ? parseJumpHosts(config.proxyJump) : [];
-      let privateKeyBuffer;
-      if (config.privateKey) {
-        try {
-          const resolvedKeyPath = resolveSymlink(config.privateKey);
-          privateKeyBuffer = readFileSync2(resolvedKeyPath);
-        } catch {
-          try {
-            const decoded = Buffer.from(config.privateKey, "base64");
-            const text = decoded.toString("utf8");
-            if (text.includes("PRIVATE KEY")) {
-              privateKeyBuffer = decoded;
-            } else {
-              throw new Error(`SSH key is neither a valid file path nor a base64-encoded private key`);
-            }
-          } catch (decodeError) {
-            if (decodeError instanceof Error && decodeError.message.includes("neither a valid file path")) {
-              throw decodeError;
-            }
-            throw new Error(`SSH key is neither a valid file path nor a base64-encoded private key`);
-          }
-        }
-      }
+      const jumpHosts = config.resolvedJumpHosts ?? (config.proxyJump ? parseJumpHosts(config.proxyJump) : []);
+      const privateKeyBuffer = config.privateKey ? this.loadPrivateKey(config.privateKey) : void 0;
       if (!config.password && !privateKeyBuffer) {
         throw new Error("Either password or privateKey must be provided for SSH authentication");
       }
@@ -248,6 +267,30 @@ var SSHTunnel = class {
       throw error;
     }
   }
+  /**
+   * Load an SSH private key, supporting both a file path (with symlink resolution)
+   * and base64-encoded key content.
+   */
+  loadPrivateKey(key) {
+    try {
+      const resolvedKeyPath = resolveSymlink(key);
+      return readFileSync2(resolvedKeyPath);
+    } catch {
+      try {
+        const decoded = Buffer.from(key, "base64");
+        const text = decoded.toString("utf8");
+        if (text.includes("PRIVATE KEY")) {
+          return decoded;
+        }
+        throw new Error("SSH key is neither a valid file path nor a base64-encoded private key");
+      } catch (decodeError) {
+        if (decodeError instanceof Error && decodeError.message.includes("neither a valid file path")) {
+          throw decodeError;
+        }
+        throw new Error("SSH key is neither a valid file path nor a base64-encoded private key");
+      }
+    }
+  }
   /**
    * Establish a chain of SSH connections through jump hosts.
    * @returns The final SSH client connected to the target host
@@ -257,6 +300,9 @@ var SSHTunnel = class {
     for (let i = 0; i < jumpHosts.length; i++) {
       const jumpHost = jumpHosts[i];
       const nextHost = i + 1 < jumpHosts.length ? jumpHosts[i + 1] : { host: targetConfig.host, port: targetConfig.port || 22 };
+      const hopPrivateKey = jumpHost.privateKey ? this.loadPrivateKey(jumpHost.privateKey) : privateKey;
+      const hopPassword = targetConfig.password;
+      const hopPassphrase = jumpHost.passphrase ?? targetConfig.passphrase;
       let client = null;
       let forwardStream;
       try {
@@ -266,9 +312,9 @@ var SSHTunnel = class {
             port: jumpHost.port,
             username: jumpHost.username || targetConfig.username
           },
-          targetConfig.password,
-          privateKey,
-          targetConfig.passphrase,
+          hopPassword,
+          hopPrivateKey,
+          hopPassphrase,
           previousStream,
           `jump host ${i + 1}`,
           targetConfig.keepaliveInterval,
@@ -1367,6 +1413,30 @@ function validateSourceConfig(source, configPath) {
       );
     }
   }
+  if (source.charset !== void 0) {
+    if (source.type !== "mysql" && source.type !== "mariadb") {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has 'charset' but it is only supported for MySQL and MariaDB sources.`
+      );
+    }
+    if (typeof source.charset !== "string" || source.charset.trim() === "") {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has invalid charset '${source.charset}'. Must be a non-empty string naming a character set (e.g. "utf8mb4").`
+      );
+    }
+  }
+  if (source.collation !== void 0) {
+    if (source.type !== "mysql" && source.type !== "mariadb") {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has 'collation' but it is only supported for MySQL and MariaDB sources.`
+      );
+    }
+    if (typeof source.collation !== "string" || source.collation.trim() === "") {
+      throw new Error(
+        `Configuration file ${configPath}: source '${source.id}' has invalid collation '${source.collation}'. Must be a non-empty string naming a collation (e.g. "utf8mb4_0900_ai_ci").`
+      );
+    }
+  }
   if (source.readonly !== void 0) {
     throw new Error(
       `Configuration file ${configPath}: source '${source.id}' has 'readonly' field, but readonly must be configured per-tool, not per-source. Move 'readonly' to [[tools]] configuration instead.`
@@ -1735,13 +1805,23 @@ var ConnectorManager = class {
     console.error(`  - ${sourceId}: ${redactDSN(dsn)}`);
     let actualDSN = dsn;
     if (source.ssh_host) {
+      const sshConfigPath = getDefaultSSHConfigPath();
       let resolvedSSHConfig = null;
       if (looksLikeSSHAlias(source.ssh_host)) {
-        const sshConfigPath = getDefaultSSHConfigPath();
         console.error(`  Resolving SSH config for host '${source.ssh_host}' from: ${sshConfigPath}`);
         resolvedSSHConfig = parseSSHConfig(source.ssh_host, sshConfigPath);
       }
       const username = source.ssh_user || resolvedSSHConfig?.username;
+      const proxyJump = source.ssh_proxy_jump || resolvedSSHConfig?.proxyJump;
+      let resolvedJumpHosts;
+      try {
+        resolvedJumpHosts = proxyJump ? resolveJumpHosts(proxyJump, sshConfigPath) : void 0;
+      } catch (error) {
+        if (error && typeof error === "object") {
+          error[TUNNEL_ERROR_MARKER] = true;
+        }
+        throw error;
+      }
       const sshConfig = {
         host: resolvedSSHConfig?.host || source.ssh_host,
         port: source.ssh_port || resolvedSSHConfig?.port || 22,
@@ -1749,7 +1829,8 @@ var ConnectorManager = class {
         password: source.ssh_password,
         privateKey: source.ssh_key || resolvedSSHConfig?.privateKey,
         passphrase: source.ssh_passphrase,
-        proxyJump: source.ssh_proxy_jump || resolvedSSHConfig?.proxyJump,
+        proxyJump,
+        resolvedJumpHosts,
         keepaliveInterval: source.ssh_keepalive_interval,
         keepaliveCountMax: source.ssh_keepalive_count_max
       };
@@ -1808,6 +1889,12 @@ var ConnectorManager = class {
     if (source.timezone) {
       config.timezone = source.timezone;
     }
+    if (source.charset) {
+      config.charset = source.charset;
+    }
+    if (source.collation) {
+      config.collation = source.collation;
+    }
     await connector.connect(actualDSN, source.init_script, config);
     this.connectors.set(sourceId, connector);
     if (!this.sourceIds.includes(sourceId)) {

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   resolveSourceConfigs,
   resolveTomlConfigPath,
   resolveTransport
-} from "./chunk-WPXPKRDU.js";
+} from "./chunk-COEDRFSK.js";
 import {
   loadConnectors
 } from "./chunk-WVVMH6FJ.js";
@@ -126,12 +126,16 @@ var mutatingPatternWithReplace = new RegExp(
   `\\b(?:${mutatingKeywords.join("|")}|replace\\s+(?:(?:low_priority|delayed)\\s+)?into)\\b`,
   "i"
 );
+var mutatingPatternSqlServer = new RegExp(
+  `\\b(?:${[...mutatingKeywords, "execute", "exec", "sp_executesql", "xp_cmdshell"].join("|")})\\b`,
+  "i"
+);
 var mutatingPatterns = {
   postgres: mutatingPattern,
   mysql: mutatingPatternWithReplace,
   mariadb: mutatingPatternWithReplace,
   sqlite: mutatingPatternWithReplace,
-  sqlserver: mutatingPattern
+  sqlserver: mutatingPatternSqlServer
 };
 var selectIntoPattern = /\bselect\b[\s\S]+\binto\b/i;
 var sqliteReadOnlyArgPragmas = /* @__PURE__ */ new Set([
@@ -1672,7 +1676,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-IPRZ55YC.js");
+    const { initializeToolRegistry: initializeToolRegistry2 } = await import("./registry-ZME64VB2.js");
     initializeToolRegistry2({
       sources: sourceConfigsData.sources,
       tools: sourceConfigsData.tools
@@ -1827,10 +1831,10 @@ See documentation for more details on configuring database connections.
 // src/index.ts
 var connectorModules = [
   { load: () => import("./postgres-BKBCGDZS.js"), name: "PostgreSQL", driver: "pg" },
-  { load: () => import("./sqlserver-47APXMSF.js"), name: "SQL Server", driver: "mssql" },
+  { load: () => import("./sqlserver-65AGCEJX.js"), name: "SQL Server", driver: "mssql" },
   { load: () => import("./sqlite-CQ4LCBB6.js"), name: "SQLite", driver: "node:sqlite" },
-  { load: () => import("./mysql-EK6TCER5.js"), name: "MySQL", driver: "mysql2" },
-  { load: () => import("./mariadb-JPEKVFEW.js"), name: "MariaDB", driver: "mariadb" }
+  { load: () => import("./mysql-MZWCPISB.js"), name: "MySQL", driver: "mysql2" },
+  { load: () => import("./mariadb-SPFBL46R.js"), name: "MariaDB", driver: "mariadb" }
 ];
 loadConnectors(connectorModules).then(() => main()).catch((error) => {
   console.error("Fatal error:", error);

package/dist/{mariadb-JPEKVFEW.js → mariadb-SPFBL46R.js}

@@ -50,7 +50,14 @@ Expected: ${expectedFormat}`
         // Controls how the driver interprets DATETIME values ("Z", "local", or "±HH:MM").
         ...config?.timezone !== void 0 && {
           timezone: config.timezone
-        }
+        },
+        // Connection character set (e.g. "utf8mb4") / collation (e.g.
+        // "utf8mb4_general_ci"). The mariadb driver exposes both as distinct
+        // options, but a configured collation is authoritative (it implies its
+        // character set) and the driver ignores `collation` when `charset` is also
+        // passed. So forward the collation when present, otherwise the charset
+        // (which uses that character set's default collation).
+        ...config?.collation !== void 0 ? { collation: config.collation } : config?.charset !== void 0 ? { charset: config.charset } : {}
       };
       url.forEachSearchParam((value, key) => {
         if (key === "sslmode") {

package/dist/{mysql-EK6TCER5.js → mysql-MZWCPISB.js}

@@ -21,6 +21,8 @@ var MySQLDSNParser = class {
   async parse(dsn, config) {
     const connectionTimeoutSeconds = config?.connectionTimeoutSeconds;
     const timezone = config?.timezone;
+    const charset = config?.charset;
+    const collation = config?.collation;
     if (!this.isValidDSN(dsn)) {
       const obfuscatedDSN = obfuscateDSNPassword(dsn);
       const expectedFormat = this.getSampleDSN();
@@ -61,6 +63,10 @@ Expected: ${expectedFormat}`
       if (timezone !== void 0) {
         config2.timezone = timezone;
       }
+      const charsetOrCollation = collation ?? charset;
+      if (charsetOrCollation !== void 0) {
+        config2.charset = charsetOrCollation;
+      }
       if (url.password && url.password.includes("X-Amz-Credential")) {
         config2.authPlugins = {
           mysql_clear_password: () => () => {

package/dist/{registry-IPRZ55YC.js → registry-ZME64VB2.js}

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

package/dist/{sqlserver-47APXMSF.js → sqlserver-65AGCEJX.js}

@@ -469,6 +469,9 @@ var _SQLServerConnector = class _SQLServerConnector {
       if (options.maxRows) {
         processedSQL = SQLRowLimiter.applyMaxRowsForSQLServer(sqlQuery, options.maxRows);
       }
+      if (options.readonly) {
+        return await this.executeReadOnly(processedSQL, parameters);
+      }
       const request = this.connection.request();
       const messages = [];
       request.on(
@@ -525,6 +528,97 @@ var _SQLServerConnector = class _SQLServerConnector {
       throw new Error(`Failed to execute query: ${error.message}`);
     }
   }
+  /**
+   * Execute a query inside a transaction that always rolls back, preventing
+   * any modifications from persisting. SQL Server has no native READ ONLY
+   * transaction mode, so this is the defense-in-depth backstop behind the
+   * keyword classifier.
+   *
+   * Because the rollback guard is application-level (not engine-enforced),
+   * we reject dangerous keywords in the stripped SQL before opening the
+   * transaction:
+   * - COMMIT/ROLLBACK: would end the outer transaction, letting writes persist
+   * - EXEC/EXECUTE/sp_executesql/xp_cmdshell: dynamic SQL can carry hidden
+   *   COMMIT/ROLLBACK inside string literals that stripCommentsAndStrings removes
+   */
+  async executeReadOnly(processedSQL, parameters) {
+    const cleaned = stripCommentsAndStrings(processedSQL, "sqlserver").toLowerCase();
+    if (/\b(?:commit|rollback)\b/.test(cleaned)) {
+      throw new Error(
+        "Read-only mode: transaction control statements (COMMIT, ROLLBACK) are not allowed"
+      );
+    }
+    if (/\b(?:exec|execute|sp_executesql|xp_cmdshell)\b/.test(cleaned)) {
+      throw new Error(
+        "Read-only mode: dynamic SQL execution (EXEC, EXECUTE, sp_executesql, xp_cmdshell) is not allowed"
+      );
+    }
+    const transaction = new sql.Transaction(this.connection);
+    await transaction.begin();
+    const request = new sql.Request(transaction);
+    const messages = [];
+    request.on(
+      "info",
+      (info) => {
+        messages.push({
+          text: info.message,
+          severity: info.class !== void 0 ? String(info.class) : void 0,
+          code: info.number,
+          line: info.lineNumber
+        });
+      }
+    );
+    if (parameters && parameters.length > 0) {
+      parameters.forEach((param, index) => {
+        const paramName = `p${index + 1}`;
+        if (typeof param === "string") {
+          request.input(paramName, sql.VarChar, param);
+        } else if (typeof param === "number") {
+          if (Number.isInteger(param)) {
+            request.input(paramName, sql.Int, param);
+          } else {
+            request.input(paramName, sql.Float, param);
+          }
+        } else if (typeof param === "boolean") {
+          request.input(paramName, sql.Bit, param);
+        } else if (param === null || param === void 0) {
+          request.input(paramName, sql.VarChar, param);
+        } else if (Array.isArray(param)) {
+          request.input(paramName, sql.VarChar, JSON.stringify(param));
+        } else {
+          request.input(paramName, sql.VarChar, JSON.stringify(param));
+        }
+      });
+    }
+    let result;
+    let queryFailed = false;
+    try {
+      result = await request.query(processedSQL);
+    } catch (error) {
+      queryFailed = true;
+      console.error(`[SQL Server executeReadOnly] ERROR: ${error.message}`);
+      console.error(`[SQL Server executeReadOnly] SQL: ${processedSQL}`);
+      if (parameters && parameters.length > 0) {
+        console.error(`[SQL Server executeReadOnly] Parameters: ${JSON.stringify(parameters)}`);
+      }
+      throw error;
+    } finally {
+      try {
+        await transaction.rollback();
+      } catch (rollbackError) {
+        if (!queryFailed) {
+          throw new Error(
+            `Read-only rollback failed \u2014 data may have been modified: ${rollbackError.message}`
+          );
+        }
+      }
+    }
+    return {
+      rows: result.recordset || [],
+      rowCount: result.rowsAffected[0] || 0,
+      ...messages.length > 0 ? { messages } : {}
+    };
+  }
   /**
    * Return the estimated execution plan for a query using SHOWPLAN_XML.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytebase/dbhub",
-  "version": "0.22.6",
+  "version": "0.23.0",
   "mcpName": "io.github.bytebase/dbhub",
   "description": "Minimal, token-efficient Database MCP Server for PostgreSQL, MySQL, SQL Server, SQLite, MariaDB",
   "repository": {
@@ -21,6 +21,8 @@
     "build": "pnpm run generate:api-types && tsup && cd frontend && pnpm run build",
     "build:backend": "pnpm run generate:api-types && tsup",
     "build:frontend": "cd frontend && pnpm run build",
+    "build:mcpb": "pnpm run build:backend && node scripts/build-mcpb.mjs",
+    "test:mcpb": "node scripts/smoke-test-mcpb.mjs",
     "start": "node dist/index.js",
     "dev": "concurrently --kill-others \"pnpm run dev:backend\" \"pnpm run dev:frontend\"",
     "dev:backend": "NODE_ENV=development tsx src/index.ts --transport=http",
@@ -58,6 +60,7 @@
     "pg": "^8.13.3"
   },
   "devDependencies": {
+    "@anthropic-ai/mcpb": "^2.1.2",
     "@testcontainers/mariadb": "^11.0.3",
     "@testcontainers/mssqlserver": "^11.0.3",
     "@testcontainers/mysql": "^11.0.3",