Files
dbx/docs/content/docs/mcp.cn.mdx
T

277 lines
19 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: MCP 集成
description: 通过 Model Context Protocol 让 AI 编程助手在 DBX 权限策略内读取元数据、查询数据和使用有状态会话。
---
<Callout type="info">把 AI 助手连接到 DBX,即可查看数据库结构、查询数据,并在 DBX 中打开结果。</Callout>
## 什么是 MCP?
MCP(Model Context Protocol)是让 AI 客户端调用外部工具的开放协议。DBX MCP 可以让 AI 助手使用 DBX 中已经配置好的数据库连接。
```text
AI 助手 → DBX MCP → 你的数据库 → 返回结果
↘ DBX 桌面端(打开或展示结果)
```
## 快速开始
<Steps>
<Step>
### 安装 MCP Server
```bash
npm install -g @dbx-app/mcp-server
```
npm 会自动安装当前平台需要的依赖。不要使用 `--no-optional`。
</Step>
<Step>
### 配置 AI 助手
在项目目录创建 `.mcp.json`:
```json
{
"mcpServers": {
"dbx": {
"command": "npx",
"args": ["-y", "@dbx-app/mcp-server"]
}
}
}
```
如果使用全局安装,可将 `command` 改为 `dbx-mcp-server`。连接 allowlist 和执行权限统一在 **DBX 设置 → MCP** 中管理,常规客户端配置不需要权限环境变量。Windows 便携版请将 `DBX_DATA_DIR` 设置为 `DBX.exe` 同级的 `data` 目录。
</Step>
<Step>
### 开始使用
在 AI 助手中直接使用自然语言:
- "列出我的数据库连接"
- "查看 local-pg 上有哪些表"
- "查看 users 表的结构"
- "查询最近 7 天的订单数量"
- "打开 orders 表"(需要 DBX 运行中)
</Step>
</Steps>
## 支持的 AI 助手
| AI 助手 | 配置方式 |
| --- | --- |
| Claude Code | `.mcp.json` |
| Cursor | `.cursor/mcp.json` |
| Windsurf | MCP 配置 |
| VS Code + Copilot | MCP 扩展/配置 |
| DeepSeek Harness | `$DSH_HOME/profiles/<profile>/cordis.patch.yml` |
### DeepSeek Harness
DeepSeek Harness 通过 Cordis 插件条目加载 MCP Server,不读取 `mcpServers` JSON。安装 `@dbx-app/mcp-server` 后,为 `web` profile 将以下条目合并到 `$DSH_HOME/profiles/web/cordis.patch.yml`:未设置 `DSH_HOME` 时默认为 `~/.dsh`。
```yaml
- insert:
- id: mcp-dbx
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: dbx
transport: stdio
command: dbx-mcp-server
```
保留最外层的 `- insert:`,不要覆盖文件中已有的 patch 条目。使用其他 DSH profile 时,将路径中的 `web` 替换为对应 profile 名称。DSH 进程的 `PATH` 必须能找到 `dbx-mcp-server`;必要时请改用可执行文件的绝对路径。
运行 `dsh web --dump-config` 检查组合后的配置,再重启 DSH 或等待热加载应用该 patch。模型侧工具名为 `mcp__dbx__<tool>`。请保持 `serverName: dbx` 稳定,避免工具名和权限规则发生变化。连接访问范围和执行模式仍统一在 **DBX 设置 → MCP** 中管理。
## 工具列表
DBX MCP 当前提供 17 个工具:
| 工具 | 说明 |
| --- | --- |
| `dbx_list_connections` | 列出当前 MCP 会话可见的连接 |
| `dbx_list_databases` | 列出连接中可通过 MCP 访问的数据库,并遵守该连接的数据库范围 |
| `dbx_add_connection` | 添加连接到 DBX 存储 |
| `dbx_duplicate_connection` | 复制一个连接及其完整配置 |
| `dbx_remove_connection` | 从 DBX 存储删除连接 |
| `dbx_list_tables` | 列出表、视图或集合 |
| `dbx_describe_table` | 返回列定义和表元数据 |
| `dbx_list_routines` | 列出 Schema 中的存储过程和函数,支持可选的 `routine_type` 过滤(PROCEDURE 或 FUNCTION) |
| `dbx_get_routine_source` | 按名称返回存储过程或函数的源码,重载场景可用可选的 `signature` 区分 |
| `dbx_get_schema_context` | 返回适合 AI 使用的紧凑 Schema 上下文 |
| `dbx_execute_query` | 执行 SQL 或支持的 MongoDB shell 命令,最多返回 100 行 |
| `dbx_open_session` | 为 SQL 连接打开固定后端连接的有状态查询会话 |
| `dbx_close_session` | 关闭会话并释放固定连接资源 |
| `dbx_execute_redis_command` | 执行 Redis 命令 |
| `dbx_send_message` | 向支持的消息队列 Topic 或队列发送消息 |
| `dbx_open_table` | 在运行中的 DBX 桌面端打开表 |
| `dbx_execute_and_show` | 执行查询并在 DBX 中展示结果 |
启用连接作用域后,修改连接和桌面 UI 工具会被隐藏。
## 有状态查询会话
普通 `dbx_execute_query` 调用彼此独立。需要保持数据库 Session 状态时,先调用 `dbx_open_session`,再把返回的 `sessionId` 传给后续 `dbx_execute_query`:
- `USE` 或数据库上下文切换
- 临时表
- Session 变量和设置
- 需要固定连接的显式事务或多步诊断
会话只支持 SQL 连接,并固定到一个连接和数据库。未知、已关闭或过期的 `sessionId` 会失败,不会静默退化为普通查询。完成后应调用 `dbx_close_session`;空闲 30 分钟的会话会被回收,同时最多允许 32 个并发会话。
<Callout type="warn">有状态会话不会放宽 SQL 策略。`USE` 只有在会话中才有意义,但写入、DDL、生产保护、连接只读和数据库权限仍按每次请求重新检查。</Callout>
## 数据库访问
### DBX Desktop 原生 Streamable HTTP
Desktop 可以选择直接托管 Streamable HTTP MCP 服务。该服务**默认关闭**;在 **设置 → MCP → HTTP 服务**启用后,默认仅监听 `127.0.0.1:5225/mcp`。监听服务由 Desktop 进程管理,会生成本地 Bearer Token,页面提供可复制的客户端配置;服务异常退出时会由 Desktop 自动重新拉起。
本机 MCP 客户端的接入步骤:
1. 打开 **设置 → MCP → HTTP 服务**,开启 **Streamable HTTP 服务**。除非确实需要让其他设备访问,否则保持默认本机回环地址。
2. 点击 **保存并启动服务**。修改地址、端口或路径后保存,会通过重启服务来应用新配置。
3. 将页面展示的服务地址和 Bearer Token 复制到 MCP 客户端。
不同客户端的字段名称可能不同,但核心配置如下:
```json
{
"type": "http",
"url": "http://127.0.0.1:5225/mcp",
"headers": {
"Authorization": "Bearer <DBX Desktop 页面展示的 Token>"
}
}
```
本机客户端建议保留默认回环监听。绑定到局域网地址时,必须开启 **允许远程访问**,并填写精确的允许 `Host`;浏览器客户端还必须填写精确的 `Origin`。客户端通过非默认端口访问时,允许的 Host 应写成 `host:port`。轮换 Token 会立即使旧凭证失效。
### 本地连接
这是默认模式。MCP 使用 DBX 中保存的连接配置。原生可执行的连接不要求 DBX 桌面端保持运行;需要 Desktop bridge 或已安装 Agent/驱动的连接仍依赖对应运行时。
常见的本地数据库文件路径:
| 平台 | 默认路径 |
| --- | --- |
| macOS | `~/Library/Application Support/com.dbx.app/dbx.db` |
| Linux | `~/.local/share/com.dbx.app/dbx.db` |
| Windows | `%APPDATA%\com.dbx.app\dbx.db` |
`DBX_DATA_DIR` 必须指向包含 `dbx.db` 的目录,而不是数据库文件本身。Windows 便携版通常是 `DBX.exe` 同级的 `data` 目录。
原生 SQL、独立 Redis 和 MongoDB 等路径可以由 MCP 直接执行。SSH、集群、厂商专用、外部驱动以及 Agent/JDBC 连接是否可用,取决于连接配置和本机已安装的 DBX 组件;不要从“DBX 支持该数据库”推断 MCP 原生包已经内置全部运行时。
DuckDB 使用独立的 DBX DuckDB 驱动。通过本地 MCP 查询 DuckDB 前,需要先在 **DBX Driver Manager** 中安装该驱动。MCP 二进制只包含 sidecar 客户端,不会内置 DuckDB 引擎。
### Agent/JDBC 数据库
Oracle、金仓KingbaseES 和虚谷需要匹配的 DBX 原生 Agent,但不需要 JRE。达梦、DB2、Hive、Trino、Snowflake、SAP HANA 等 JDBC Agent 数据库需要匹配的 Agent、JDBC 驱动和 JRE。请先在 DBX 中安装所需组件,再使用 MCP。
### DBX Web / Docker 模式
设置 `DBX_WEB_URL` 后,MCP 会使用部署的 DBX Web 后端,而不是读取本机连接。如果 Web 登录启用了密码保护,还要设置 `DBX_WEB_PASSWORD`,值为 Web 登录页使用的密码。
DBX Web 请求遵循标准系统代理环境变量:https 地址读取 `HTTPS_PROXY`/`https_proxy`,http 地址读取 `HTTP_PROXY`/`http_proxy`,`ALL_PROXY`/`all_proxy` 作为兜底,`NO_PROXY`/`no_proxy`(逗号分隔的主机列表,例如 `localhost,127.0.0.1,.internal.example`)作为绕过列表。代理值为空或未设置时直连(不走代理)。支持 HTTP、HTTPS 与 SOCKS5 代理(`http://127.0.0.1:7890` 或 `socks5://127.0.0.1:1080`);需要认证的代理使用标准 `user:password@host:port` URL 形式,例如 `http://admin:admin123@127.0.0.1:7890`。如需为每次 DBX Web 请求附加自定义请求头(例如网关前的令牌认证),将 `DBX_WEB_HEADERS` 设置为 JSON 对象,键为请求头名称、值为字符串,例如 `{"Authorization":"Bearer <token>"}`。目标为自签名 HTTPS 时,证书验证默认开启:设置 `DBX_WEB_INSECURE_SKIP_VERIFY=1` 可跳过验证,或设置 `DBX_WEB_CA_CERT` 指向 PEM/DER CA 文件以信任私有 CA。同样的变量在 DBX CLI 的 Web 模式下同样生效。
DBX Web 和 Docker 同样需要独立 DuckDB 驱动。首次启动后可通过 Driver Manager 安装;Docker 会把驱动保存到 `/app/data/agents`,挂载 `/app/data` 数据卷后升级容器不会丢失。
### DBX Web 原生 Streamable HTTP
DBX Web 也可以直接托管 MCP。只有配置 `DBX_WEB_MCP_TOKEN` 或 `DBX_WEB_MCP_TOKEN_FILE` 后才会启用。它复用现有 Web 监听器和 `/mcp` 路径,因此 Docker 和反向代理部署不需要额外暴露第二个端口。将 `DBX_WEB_MCP_ALLOWED_HOSTS` 配置为客户端在 `Host` 请求头中发送的公网访问地址;如有端口映射,必须包含映射后的端口。生产环境请使用 `DBX_WEB_MCP_TOKEN_FILE` 或部署平台的 Secret 管理能力,不要把真实 Token 提交到 Compose 文件中。
例如容器映射为 `4225:4224` 时,MCP 地址为 `http://localhost:4225/mcp`:
```yaml
environment:
DBX_WEB_MCP_TOKEN: replace-with-a-long-random-secret
DBX_WEB_MCP_ALLOWED_HOSTS: localhost:4225
ports:
- "4225:4224"
```
客户端必须携带 `Authorization: Bearer <DBX_WEB_MCP_TOKEN>`。浏览器客户端还需要在 `DBX_WEB_MCP_ALLOWED_ORIGINS` 中填写精确 Origin,例如 `https://mcp.example.com`;原生客户端通常不会发送 `Origin` 请求头。若反向代理添加了公网路径前缀,请设置 `DBX_PUBLIC_BASE_PATH=/dbx`,此时原生端点为 `/dbx/mcp`。原生 HTTP 与现有的 `DBX_WEB_URL` stdio 适配方式可以同时使用:两者共享 DBX 连接和 MCP 策略,后者仍适合只支持 stdio 的客户端。
### 桌面 UI 工具
`dbx_open_table` 和 `dbx_execute_and_show` 要求 DBX 桌面端正在运行,并且在 Web 模式或连接作用域隐藏 UI 工具时不可用。其他工具是否需要 Desktop 取决于该连接是原生执行还是 bridge/Agent 路径。
## 安全和环境变量
DBX 在 **设置 → MCP** 中保存一份权威策略,并在每次请求时重新读取:
| 权限模式 | 允许的操作 |
| --- | --- |
| 只读 | 查询和元数据读取 |
| 数据读写 | 普通插入、带有效过滤条件的更新/删除、范围明确的 MongoDB 修改和普通 Redis 写入 |
| 完全访问 | 额外允许大范围更新/删除、DDL、`TRUNCATE`、MongoDB 破坏性操作和 Redis `FLUSH*` |
`WHERE TRUE`、`WHERE 1 = 1`、`_id: {$exists: true}` 或不透明 MongoDB 过滤器仍按高风险处理。连接自身只读、生产库保护、数据库账号权限和 MCP 连接 allowlist 在任何模式下都是权限上限。
对于已暴露给 MCP 的连接,**设置 → MCP** 可以设置连接默认执行权限:继承全局、只读、安全写入或高风险写入。选择指定数据库后,还可为单个数据库设置执行权限。执行权限按范围由小到大回退:**单库设置 → 连接默认 → 全局默认**;例如全局和连接默认均为“数据读写”时,可为单个数据库设置“完全访问”。连接自身只读、生产库保护、数据库范围和数据库账号权限仍是独立的硬性限制,不能被单库设置绕过。
同一页面还可只暴露选定的 MCP 工具。这项限制在服务端的每一次调用中都会强制执行,不只是客户端的展示偏好;即使客户端缓存了旧工具列表,也会在服务端 allowlist 更新后被拒绝。
### 按顺序配置授权范围
在 **设置 → MCP** 中建议按以下顺序定义最终权限范围:
1. 选择 MCP 可见的是**所有连接**(包括以后新增的连接),还是仅**指定连接**。
2. 为每个已暴露连接选择**全部数据库**、**仅指定数据库**或**不允许访问**。指定数据库名按精确名称匹配;可先调用 `dbx_list_databases` 获取当前允许使用的名称,并为选中的数据库按需设置执行权限。
3. 为每个连接设置默认执行权限。未配置单库覆盖、或选择全部数据库时,该默认值就是连接内数据库的执行权限。
4. 仅选择客户端实际需要的 MCP 工具,再设置全局默认执行权限模式。
执行权限由最具体的设置决定,但已允许的工具仍不能绕过隐藏连接、数据库范围、连接只读、生产库保护或数据库账号本身的权限。请求未被选中数据库时,服务会返回 `DATABASE_OUT_OF_SCOPE`;配置单库执行权限时,跨库 SQL 和 MongoDB 聚合写入会被拒绝,避免绕过数据库级限制。
升级时,未带执行策略版本的已保存连接规则继续使用旧的权限上限语义,不会放大全局权限。只有当前设置页面保存的规则会标记为范围覆盖语义;编辑旧规则时,系统会先固化其实际生效的权限上限,再启用新的覆盖行为。
新版 Server 不允许 `DBX_MCP_ALLOW_WRITES` 或 `DBX_MCP_ALLOW_DANGEROUS_SQL` 放宽 DBX 中央策略。为兼容升级,在中央策略首次保存前,旧配置中的 `DBX_MCP_ALLOW_WRITES=0`(或 `false`)仍会保持 MCP 只读;策略保存后仅以中央策略为准,并忽略旧权限变量。旧连接 scope 变量只能进一步收窄 DBX allowlist。
| 变量 | 用途 |
| --- | --- |
| `DBX_DATA_DIR` | 覆盖本地 DBX 数据目录 |
| `DBX_WEB_URL` | 使用 DBX Web/Docker 后端 |
| `DBX_WEB_PASSWORD` | 登录 DBX Web |
| `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` | DBX Web 请求的标准系统代理变量;空值表示不走代理。认证格式 `http://user:pass@host:port` |
| `NO_PROXY` | 上述代理的标准绕过列表(逗号分隔主机) |
| `DBX_WEB_HEADERS` | DBX Web 请求附加的请求头 JSON 对象,例如 `{"Authorization":"Bearer token"}` |
| `DBX_WEB_INSECURE_SKIP_VERIFY` | `1`/`true` 时跳过 TLS 证书验证(用于自签名 DBX Web 后端;默认验证) |
| `DBX_WEB_CA_CERT` | DBX Web TLS 验证时信任的 PEM/DER CA 文件 |
| `DBX_WEB_MCP_TOKEN` | 使用该 Bearer Token 启用原生 Web Streamable HTTP MCP |
| `DBX_WEB_MCP_TOKEN_FILE` | 从文件读取原生 Web MCP Token;不能与 `DBX_WEB_MCP_TOKEN` 同时设置 |
| `DBX_WEB_MCP_ALLOWED_HOSTS` | 原生 Web MCP 必填:允许的公网 Host authority,逗号分隔 |
| `DBX_WEB_MCP_ALLOWED_ORIGINS` | 原生 Web MCP 的浏览器 Origin allowlist,逗号分隔 |
| `DBX_MCP_ALLOW_WRITES` | 仅用于升级兼容:`0`/`false` 使尚未配置的策略保持只读 |
| `DBX_MCP_SCOPE_CONNECTION_ID` | 兼容旧配置:限制为一个连接 ID |
| `DBX_MCP_SCOPE_CONNECTION_IDS` | 兼容旧配置:限制为多个连接 ID |
| `DBX_MCP_SCOPE_CONNECTION_NAME` | 限制为一个连接名称 |
| `DBX_MCP_SCOPE_DATABASE` | 限制为一个数据库 |
| `DBX_MCP_DEBUG_SQL` | 临时诊断时输出 SQL |
## 常见问题
<Accordions>
<Accordion title="npm 没有安装当前平台包">不要使用 `--no-optional`,重新安装 `@dbx-app/mcp-server`,并用 `node -p 'process.platform + "-" + process.arch'` 检查平台。Alpine Linux 默认使用 musl,目前不在 Linux 发布包支持范围内。</Accordion>
<Accordion title="找不到 dbx.db">将 `DBX_DATA_DIR` 设置为包含 `dbx.db` 的目录。Windows 便携版通常是 `DBX.exe` 旁边的 `data` 目录。</Accordion>
<Accordion title="提示 DBX 未运行">只有 `dbx_open_table` 和 `dbx_execute_and_show` 需要桌面端运行;本地查询工具可以在 DBX 关闭时执行。</Accordion>
<Accordion title="Desktop HTTP 客户端提示 ERR_CONNECTION_REFUSED">进入 **设置 → MCP → HTTP 服务**,确认服务已开启并点击 **保存并启动服务**。客户端应使用页面展示的地址、路径和当前 Bearer Token。默认的 `127.0.0.1` 只接受同一台电脑上的连接。</Accordion>
<Accordion title="Desktop 提示 HTTP 地址已被占用">已有其他进程监听了所选地址和端口。请在 **设置 → MCP → HTTP 服务** 中改用未被占用的端口,再保存配置以重启服务。不要让两个 DBX Desktop 实例使用相同 HTTP 端点。</Accordion>
<Accordion title="请求返回 DATABASE_OUT_OF_SCOPE">该连接虽然已暴露给 MCP,但请求的数据库不在它的 MCP 数据库范围内。请在 **设置 → MCP** 中添加精确的数据库名称,或在合适时将该连接设为全部数据库。指定范围时,应先调用 `dbx_list_databases`,再使用返回的名称。</Accordion>
<Accordion title="之前可见的工具现在被拒绝">该工具已不在 **设置 → MCP** 的选中范围内,或当前权限策略不允许它。修改工具 allowlist 后请刷新 MCP 客户端的工具列表;服务端同样会拒绝缓存的旧工具调用。</Accordion>
<Accordion title="Docker 或反向代理下 MCP 请求失败">请使用公网访问地址,包括映射后的端口和 `DBX_PUBLIC_BASE_PATH` 前缀。`DBX_WEB_MCP_ALLOWED_HOSTS` 必须与实际 `Host` authority 精确一致;浏览器客户端还必须在 `DBX_WEB_MCP_ALLOWED_ORIGINS` 中配置精确 Origin。</Accordion>
<Accordion title="Agent/JDBC 数据库无法启动">在 DBX Driver Manager 中安装或更新匹配的 Agent、JDBC 驱动和 JRE。厂商专有驱动不会随 MCP 原生包发布。</Accordion>
<Accordion title="DuckDB 连接无法启动">在 DBX Driver Manager 中安装或更新 DuckDB 驱动。本地 MCP、DBX Web 和 Docker 都通过独立驱动运行 DuckDB,不会内置 DuckDB 引擎。</Accordion>
<Accordion title="出现 better-sqlite3 或 Node ABI 错误">MCP 不需要 `better-sqlite3`。请先升级 `@dbx-app/mcp-server`;如果错误来自 `@dbx-app/cli`,请按照 CLI 的安装要求处理,因为它们是两个独立的包。</Accordion>
</Accordions>
## 系统要求
- Node.js 18.18.0 或更高版本
- 已安装 DBX,并至少配置一个数据库连接
- Agent/JDBC 数据库需要匹配的 Agent、驱动和 JRE
- 使用两个桌面 UI 工具时,需要保持 DBX 桌面端运行