第14章 通过 MCP 将 drawDB 接入 AI 工具
第14章 通过 MCP 将 drawDB 接入 AI 工具 配置只读 drawDB MCP 服务器,使 Claude Desktop、Cursor、Cline、Goose、Windsurf 及兼容客户端能够查看云端的数据库架构。 drawDB 的模型上下文协议(MCP)服务器为兼容的 AI 编码工具提供对存储在你 drawDB Pro 云工作区中数据库架构的只读访问权限。 它以 Node.js 子进程形式在本地运行,使用你的 API 密钥对 drawDB API 进行身份验证,并暴露出用于图表、表、字段、关系、枚举和 PostgreSQL 复合类型的专用工具。 设计上是只读的 MCP 无法创建、修改、导出、恢复或删除图表。它不暴露注释、主题领域、画布布局、SQL 导出或 DBML 导出功能。 开始之前 你需要:
* 一个包含云存储的 drawDB 计划,以及至少一个基于云的图表。 * 在运行 MCP 客户端的计算机上安装 Node.js 20 或更高版本。 * 一个能够启动本地 stdio 服务器的 MCP 客户端。 * 一个 drawDB API 密钥。请先参考“创建和管理 API 密钥”。
发布的 npm 软件包是 `@drawdb/mcp`。它默认连接到 `https://api.drawdb.app`。 配置你的 MCP 客户端 使用以下配置添加一个本地 stdio 服务器: { "mcpServers": { "drawdb": { "command": "npx", "args": ["-y", "@drawdb/mcp"], "env": { "DRAWDB_API_KEY": "ddb_your_key_here" } } } } 将 `ddb_your_key_here` 替换为你创建密钥时显示的令牌。将该密钥保留在 drawDB 服务器条目的 env 对象中。 Claude Desktop、Cursor、Cline、Goose、Windsurf 以及其他能够启动本地 MCP 进程的客户端可以使用相同的命令、参数和环境变量。界面或配置文件位置因客户端而异;请查找添加本地或 stdio MCP 服务器选项。 重启或重新加载客户端(使用其正常的 MCP 服务器工作流),然后确认名为 drawdb 的服务器及其工具可用。 暂不支持仅网页端客户端 当前软件包使用本地 stdio 传输。由于 drawDB 尚未暴露这些客户端所需的托管 HTTP 和 OAuth 传输,因此无法直接连接到仅网页端的 ChatGPT 或 claude.ai 会话。 测试连接 在你的 MCP 客户端中尝试此提示:
列出我的 drawDB 图表,然后总结名为“Orders”的图表的架构。
代理应先调用 `list_diagrams`,选择返回的图表 ID,并在架构工具中重用该 ID。 若要独立于 MCP 客户端测试 API,请将你的密钥放入环境变量并运行: ```bash curl --fail-with-body \ -H "X-API-Key: $DRAWDB_API_KEY" \ https://api.drawdb.app/api/v1/diagrams ``` 可用工具 | 工具 | 必需参数 | 返回内容 | | :--- | :--- | :--- | | list_diagrams | 无 | 密钥所有者团队归属范围内可见的图表 ID、名称、数据库方言及更新时间 | | get_schema_summary | diagram_id | 方言、计数和表名 | | list_tables | diagram_id | 表名、注释和字段数 | | describe_table | diagram_id, table_name | 列、约束、默认值、注释、枚举值和索引 | | list_relationships | diagram_id | 外键、基数、引用操作和复合列映射 | | describe_relationship | diagram_id, from_table, to_table | 两个表之间指定方向的关系 | | list_enums | diagram_id | 用户定义的枚举名称和值 | | list_custom_types | diagram_id | PostgreSQL 复合类型及其字段 | | search_tables | diagram_id, query | 匹配的表名、列名和注释 | 传递给 `describe_table` 的表名不区分大小写,但必须完整匹配表名。关系查找具有方向性:`from_table` 和 `to_table` 必须遵循 `list_relationships` 报告的方向。 `search_tables` 在多个列或注释匹配查询时,可能会多次返回相同的表。 API 密钥可见范围 MCP 进程以创建密钥的用户身份运行。它不受 drawDB 编辑器中当前选择的工作区限制。
* `list_diagrams` 搜索该用户所有团队归属中的云图表元数据。在当前版本中,它可能包含那些后续因“仅限邀请”或“无访问权限”规则而被拒绝架构请求的图表。 * 每次架构请求都会执行新的访问检查。 * 明确撤销的访问权限、退出团队、密钥过期或密钥删除将阻止后续访问。 * 本地浏览器中的图表不会自动上传,MCP 也无法发现它们。 为每个设备或客户端使用单独的密钥,以便在不中断其他连接的情况下撤销其中一个连接。 连接到自托管后端 `DRAWDB_BASE_URL` 是可选的。仅在你针对另一个 drawDB API 部署进行开发时才设置它: { "mcpServers": { "drawdb-local": { "command": "npx", "args": ["-y", "@drawdb/mcp"], "env": { "DRAWDB_API_KEY": "ddb_your_key_here", "DRAWDB_BASE_URL": "http://localhost:4000" } } } } MCP 故障排除 | 症状 | 检查事项 | | :--- | :--- | | 启动前设置 DRAWDB_API_KEY 环境变量 | 客户端未传递密钥。确认 env 位于 drawDB 服务器条目内。 | | 找不到 npx 或 Node | 安装 Node.js 20+,并确保桌面客户端能通过其进程 PATH 访问它。 | | 401 缺少 api key | DRAWDB_API_KEY 未到达进程。 | | 401 api key 格式无效 | 值必须以 ddb_ 开头;编辑器会话令牌将不起作用。 | | 401 api key 无效或已过期 | 密钥已过期、被删除、复制错误或完整值丢失。创建替换密钥。 | | 402 云存储需要 Pro 计划 | 账户不再有云存储权限。检查计划或试用状态。 | | 未返回图表 | 确认图表已保存到云端,且密钥所有者仍属于其工作区。 | | 400 无效 diagramId | 调用 list_diagrams 并使用其 UUID,而不是图表名称。 | | 403 非你的图表 | 摘要可以列出,但密钥所有者未通过图表当前的架构访问检查。 | | 404 未找到图表 | 图表已被删除或 ID 不正确。 | | 未找到表 | 调用 list_tables 并传递完整的表名。 | | 从 A 到 B 没有关系 | 反向查找不匹配。使用 list_relationships 返回的方向。 | | 缺少最近的编辑 | 等待 drawDB 云端保存完成,然后再次查询图表。 | 如果密钥可能已泄露,请立即轮换它。 在 GitHub 上编辑 最后更新于 创建和管理 drawDB API 密钥 创建、重命名、轮换、使失效或撤销 drawDB Pro API 密钥,用于 MCP 客户端和其他集成。 故障排除 drawDB Pro 解决 drawDB Pro 中常见的登录、云保存、工作区、邀请、共享、协作、AI、计费、API 密钥和 MCP 问题。