dbhawk

DBHawk MCP — Claude Code 插件 + 示例连接器

让 AI 助手能够访问 DBHawk：列出分配给用户的数据源，浏览架构／表／列，运行查询（应用用户的访问控制和列屏蔽），并使用 DBHawk AI 的文本转 SQL／优化／格式化功能。只有在用户的 MCP 层级允许时，才能更改数据或架构——默认层级为只读（参见读取、写入和 MCP 层级）。

这是基于现有 DBHawk REST 接口 /api/v2/mcp/** 的轻量桥接。由 DBHawk 决定运行哪些操作： 每条语句都会根据用户所属组的层级进行分类和检查，无论令牌所有者拥有何种角色。

登录，或使用个人令牌。 将 DBHAWK_TOKEN 留空，服务器就会在首次调用工具时通过浏览器登录 DBHawk：DBHawk 登录页面会打开（密码、LDAP、2FA 或 SSO，具体取决于你的 DBHawk 提供哪些方式），你只需批准一次访问，服务器便会在你的用户配置文件中保存刷新令牌，供下次启动时使用（Windows 上为 %APPDATA%\dbhawk-mcp，macOS 上为 ~/Library/Application Support/dbhawk-mcp，Linux 上为 ~/.config/dbhawk-mcp）。这需要带有 MCP 连接器的 DBHawk 7.0.1；你可以执行哪些操作由你的 MCP 层级决定，与使用令牌时完全相同。请参见 UPGRADE-7.1.0.md。

使用个人令牌时，身份验证分为两步。 DBHAWK_TOKEN 是个人令牌（dbh_<id>.<secret>），不是 JWT——MCP 端点不会直接接受它。服务器首次收到调用时，会通过 POST /api/v2/auth/token/exchange 交换获取一个短期 JWT（在 X-API-Token 标头中发送个人令牌），缓存该 JWT，并在每次 /api/v2/mcp/** 调用中将其作为 Bearer 发送。JWT 的 exp 即将到期时，服务器会提前交换获取新的 JWT；如果调用仍然收到 401，则会重新交换并重试一次——整个过程对你透明。

dbhawk-mcp-plugin/                 <- this folder = a Claude Code "marketplace" (push it to git)
├── .claude-plugin/marketplace.json
└── dbhawk/                        <- the actual plugin (installed by users)
    ├── .claude-plugin/plugin.json
    ├── .mcp.json                  <- declares the "dbhawk" stdio MCP server
    └── mcp-server/
        ├── index.js               <- source
        ├── package.json           <- build tooling (maintainers only)
        └── dist/dbhawk-mcp.mjs    <- COMMITTED self-contained bundle (what users run; no npm install)

dist/ 中的打包文件内置了所有依赖，因此 直接 git clone 即可运行，无需安装——这正是 /plugin install 能够正常工作的原因。

---

面向用户 — 安装

Claude Code（从市场安装）

此仓库发布到 GitHub 后（见下文的 发布），将 Claude Code 指向该仓库并安装：

/plugin marketplace add datasparc/dbhawk-mcp-plugin
/plugin install dbhawk@dbhawk-marketplace

dbhawk 是插件名称，dbhawk-marketplace 是市场名称（来自 marketplace.json）。 然后设置连接（见 配置），并使用 /mcp 检查工具是否已就绪。

想在没有 Git 主机的情况下试用？加载本地文件夹，进行单次会话：

claude --plugin-dir ./dbhawk-mcp-plugin/dbhawk

Claude Desktop（扩展程序，.mcpb）— 推荐

Claude Desktop 会将其作为 桌面扩展程序安装，并提供正规的图形界面设置表单（无需编辑 JSON）。它使用相同的 MCP 服务，只是打包为 .mcpb 文件。

1. 从 Releases 页面下载 dbhawk-<version>.mcpb。
2. 在 Claude Desktop 中，选择 Settings → Extensions → Advanced settings → Install 并选取该文件 （或者直接将 .mcpb 拖到 Extensions 窗口中）。
3. 填写表单——DBHawk Base URL、API Token（可选；会遮蔽内容并存储在操作系统的密钥链中——留空则通过浏览器登录）和 Default Datasource（可选）——然后保存。
4. 不提供令牌时，首次调用 DBHawk 工具会在浏览器中打开 DBHawk 登录页面：登录后点击 Allow；如果 Claude 提示正在等待登录，请重新发送请求。

Claude Desktop 不会自动更新通过文件安装的扩展程序：要升级，请下载较新的 .mcpb 并重新安装。这与 Claude Code 插件相互独立——无需安装市场插件。

Claude Desktop（手动配置，高级）

想手动配置而不使用 .mcpb？使用绝对路径，让 Desktop 指向打包文件。编辑 claude_desktop_config.json （Windows：%APPDATA%\Claude\claude_desktop_config.json， macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "dbhawk": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\...\\dbhawk-mcp-plugin\\dbhawk\\mcp-server\\dist\\dbhawk-mcp.mjs"],
      "env": {
        "DBHAWK_BASE_URL": "https://demo.dbhawk.example.com",
        "DBHAWK_TOKEN": "PASTE_MCP_TOKEN_HERE",
        "DBHAWK_DEFAULT_DATASOURCE": ""
      }
    }
  }
}

完全重启 Claude Desktop（包括系统托盘图标）。

---

配置

该服务需要三个值（令牌所有者需要 ACCESS_TO_DATA）：

设置	必填	含义
基础 URL（DBHAWK_BASE_URL）	是	DBHawk 的基础 URL，例如 https://demo.dbhawk.example.com（末尾不要带 /api）
API 令牌（DBHAWK_TOKEN）	否	留空：首次使用时通过浏览器登录（DBHawk 7.0.1+）。否则使用 MCP 专属个人令牌（dbh_…）：DBHawk → 用户档案 → API 令牌。运行时会将其换成 JWT——请原样粘贴个人令牌，而不是 JWT
默认数据源（DBHAWK_DEFAULT_DATASOURCE）	否	工具调用未提供 datasource 时使用的数据源

Claude Code — 引导式设置对话框（推荐）

该插件在 dbhawk/.claude-plugin/plugin.json 中将这些字段声明为 userConfig，因此启用插件时，Claude Code 会提示你填写这些值——令牌字段为 sensitive，输入时会被屏蔽，并存储在安全存储中（OS 钥匙串 / ~/.claude/.credentials.json），绝不会存入 settings.json 或 git。dbhawk/.mcp.json 通过 ${user_config.dbhawk_token} 等变量接入这些值。

之后如需重新输入或修改这些值，请重新启用插件，或以非交互方式设置：

claude plugin install dbhawk@dbhawk-marketplace \
  --config dbhawk_base_url=https://demo.dbhawk.example.com \
  --config dbhawk_token=dbh_... \
  --config dbhawk_default_datasource=

Claude Desktop — 环境变量

Desktop 不支持插件或 userConfig——请在上文所示的 claude_desktop_config.json 配置块中，将这三个值作为 env 传入。

---

工具

工具	DBHawk 端点
list_datasources	GET /datasources
get_datasource	GET /datasources/{ds}
list_catalogs	GET /datasources/{ds}/catalogs（MSSQL / Snowflake；对于没有目录层级的数据库，结果为空）
list_schemas	GET /datasources/{ds}/schemas
list_objects	GET /datasources/{ds}/schemas/{schema}/objects
list_columns	GET /datasources/{ds}/schemas/{schema}/objects/{object}/columns
get_permissions	GET /permissions（用户的 MCP 层级、允许的操作、行数上限、确认要求）
run_query	POST /datasources/{ds}/query，并设置 readOnly: true（仅读取，即使层级允许写入也一样；行数上限为 200/5000）
explain_plan	POST /datasources/{ds}/explain（在同一连接上构建并读取执行计划；绝不会执行语句；层级需要包含 explain_plan）
list_sessions	GET /datasources/{ds}/sessions（活动的数据库会话；需要 active_sessions）
kill_session	POST /datasources/{ds}/sessions/{id}/kill（结束一个已列出的会话；具有破坏性，需经过 confirm 流程；需要 kill_session）
execute_statement	POST /datasources/{ds}/query（数据 / 架构更改，仅当 MCP 层级允许时可用；需经过 confirm 流程）
text_to_sql	POST /datasources/{ds}/ai/ask
optimize_sql	POST /datasources/{ds}/ai/optimize
format_sql	POST /format-query

读取、写入与 MCP 层级

用户可以执行哪些操作，由 DBHawk 按用户组通过 MCP 层级设置（Admin → MCP Management → MCP Tiers）。 默认层级为只读；更高层级会增加 EXPLAIN、DML（INSERT / UPDATE / DELETE / MERGE）、DDL 和 管理操作。get_permissions 会告知模型其层级允许执行哪些操作。

读取和写入被有意设计为不同的工具。run_query 标记为只读（readOnlyHint），即使层级允许写入，DBHawk 也会拒绝通过它发送的写入操作。execute_statement 标记为具有破坏性（destructiveHint），因此 Claude 等 MCP 客户端会在每次调用前询问用户——请保持此设置，不要将其设为 “始终允许”。如果层级还要求确认，DBHawk 会在首次调用时返回 { confirmationRequired: true, executed: false }，只有在再次调用并传入 confirm: true 时才会执行语句。无论层级如何设置，只读数据源都会拒绝写入。

示例提示词：“我有哪些数据源？” → “显示 Postgres-Demo 中 public 架构的表” → “customers 有哪些列？” → “按状态统计上个月的订单数”（文本转 SQL → 运行）。

---

维护者须知 — 发布与重建

发布市场

cd dbhawk-mcp-plugin
git init && git add . && git commit -m "DBHawk MCP plugin"
git remote add origin [email protected]:datasparc/dbhawk-mcp-plugin.git
git push -u origin main

然后，用户运行上面的两个 /plugin 命令。若要将其列入 Anthropic 精选的 claude-plugins-official 目录，请通过插件目录提交表单提交（需单独审核）；无需经过此流程，你自己的市场即可立即使用。

重新构建打包文件（编辑 index.js 后）

cd dbhawk/mcp-server
npm install        # once, pulls the SDK + esbuild (build-time only)
npm run build      # regenerates dist/dbhawk-mcp.mjs
git add dist/dbhawk-mcp.mjs && git commit -m "rebuild bundle"

有意提交了 dist/dbhawk-mcp.mjs——这是用户运行的产物。不会提交 node_modules/。

测试

cd dbhawk/mcp-server
npm test           # builds the bundle, then runs test/*.test.js
npm run test:only  # runs the tests against the current bundle, without rebuilding

测试会通过 stdio 启动真实的打包文件，使用官方 MCP 客户端与其交互，并将其指向一个会记录每个请求的虚拟 DBHawk HTTP 服务（test/helpers.js），因此无需 DBHawk 实例。测试涵盖工具目录和注释、读写约定（run_query 始终发送 readOnly: true， execute_statement 仅在需要时发送 confirm）、工具到端点的映射、令牌交换（请求头、 JWT 缓存、收到 401 时重新交换一次）和错误报告。CI（.github/workflows/mcp-server.yml） 会在 Node 18/20/22 上运行这些测试；如果已提交的 dist/ 打包文件不是最新版本、mcpb/server 副本与其不一致，或清单、server.json 和 index.js 中的版本不一致，也会导致 CI 失败。

构建并发布桌面扩展（.mcpb）

mcpb/ 文件夹是扩展源代码：mcpb/manifest.json（声明 Desktop 设置表单中显示的 user_config 字段），以及 mcpb/server/dbhawk-mcp.mjs（同一 dist/ 打包文件的副本）。重新构建打包文件后，更新副本，然后打包并发布：

cp dbhawk/mcp-server/dist/dbhawk-mcp.mjs mcpb/server/dbhawk-mcp.mjs   # keep the copy in sync
npx @anthropic-ai/mcpb validate mcpb/manifest.json                   # optional sanity check
npx @anthropic-ai/mcpb pack mcpb dbhawk-<version>.mcpb                # produces the .mcpb

# SBOM of everything inlined into the bundle (all deps are devDependencies, so don't --omit dev)
(cd dbhawk/mcp-server && npm sbom --sbom-format cyclonedx) > dbhawk-mcp-<version>.cdx.json

gh release create v<version> dbhawk-<version>.mcpb dbhawk-mcp-<version>.cdx.json \
  --title "DBHawk <version>" --notes "DBHawk MCP desktop extension"

.cdx.json 是 CycloneDX SBOM，列出了 esbuild 内联到 dist/dbhawk-mcp.mjs 中的确切软件包版本，因此无需解包即可审计该打包文件。与 .mcpb 一样，它会被 git 忽略，仅作为 Release 资源发布。

每次发布时，都要更新 mcpb/manifest.json 中的 version（Desktop 会根据它识别升级）。.mcpb 会被 git 忽略——它作为 Release 资源发布，不会包含在代码树中。确保 mcpb/manifest.json 中的版本 与 dbhawk/.claude-plugin/plugin.json 保持一致，使插件和扩展版本相匹配。

---

故障排查

• token exchange failed: 401/403 — 个人 DBHAWK_TOKEN 错误、已撤销或已过期，用户不在 MCP 访问组中，或者（SSO/SAML 用户）登录重新验证窗口已过期 — 通过身份提供商登录 DBHawk 一次，同一个令牌随后即可再次使用。如有需要，请重新签发。
• DBHawk API 401/403（交换后）— 作用域错误，或用户没有 ACCESS_TO_DATA 权限。
• … needs MCP operation(s) …, which your MCP tier … does not allow — 该语句类型不在用户的 MCP 层级权限范围内（默认层级为只读）。管理员可为用户所属的某个组分配更高层级（DBHawk → Admin → MCP Management → MCP Tiers，然后打开 User Group 对话框 → MCP Tier）。
• … cannot run as a read-only query. Use the execute_statement tool instead. — 写入操作通过 run_query 发送；模型必须改用 execute_statement，由客户端先询问用户。
• Datasource '…' is read-only …（403）— 数据源在 DBHawk 中被标记为只读，因此无论 MCP 层级权限如何，都不会执行写入；读取仍可正常进行。
• confirmationRequired: true, executed: false — 这不是错误：该层级要求写入操作先获得确认。向用户展示语句，待用户批准后，再使用 confirm: true 再次调用 execute_statement。
• Sign in to DBHawk in the browser window that just opened … — 尚未配置令牌，浏览器登录也尚未完成。请登录并点击 Allow，然后重试请求（如果没有弹出窗口，消息中会提供 URL）。要以其他用户身份登录，请删除上方 dbhawk-mcp 文件夹中的 oauth-*.json 文件。
• This DBHawk server does not support signing in from the extension — DBHawk 服务版本早于 MCP 连接器；请配置个人令牌。
• 启动时出现 Missing configuration — 未设置 DBHAWK_BASE_URL。
• 启动时出现 Invalid configuration — DBHAWK_BASE_URL 不是 https:// / http:// URL，包含凭据、查询参数或末尾的 /api；或者 DBHAWK_TOKEN 是 JWT，而不是个人 dbh_… 令牌。
• /mcp 中未列出服务 — 确认 Node ≥ 18，且已安装的插件中存在 dist/dbhawk-mcp.mjs。在 Claude Desktop 中，请使用 node 的完整路径（Desktop 的 PATH 仅包含少量路径）。