内容
# @drawdb/mcp
一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为 AI 代理提供**只读**访问您的 [drawDB](https://drawdb.app) 图表的能力 —— 这样它们可以在帮助您编写查询、迁移或应用程序代码时，检查您的数据库模式（表、列、关系、枚举、自定义类型）。
它通过 **stdio** 传输在本地运行，该传输适用于 Claude Desktop、Cursor、Cline、Goose、Windsurf 以及任何其他启动本地 MCP 子进程的客户端。
## 要求
- **Node.js ≥ 20**
- 一个 **drawDB API 密钥**（以 `ddb_` 开头）。从 drawDB **个人资料模态框 → API 密钥**选项卡中创建一个。`/api/v1` 上不接受纯 JWT。
您不需要提前安装任何东西 —— 以下配置将使用 `npx` 按需启动服务器。
## 快速入门
将服务器添加到您的 MCP 客户端配置中。对于 **Claude Desktop**（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"drawdb": {
"command": "npx",
"args": ["-y", "@drawdb/mcp"],
"env": {
"DRAWDB_API_KEY": "ddb_xxx"
}
}
}
}
```
**Cursor**（`~/.cursor/mcp.json` 或项目中的 `.cursor/mcp.json`）使用相同的结构。编辑后重启客户端，然后询问代理一些问题，例如 *"列出我的 drawDB 图表"* 以确认连接。
连接后，典型的流程是：代理调用 `list_diagrams` 以查找图表的 ID，然后将该 `diagram_id` 传递给以下任意架构工具。
## 工具
所有工具都是只读的 —— 服务器无法修改图表。
| 工具 | 参数 | 返回值 |
| --- | --- | --- |
| `list_diagrams` | — | 密钥可见的每个图表的 id / 名称 / 数据库 / updatedAt |
| `get_schema_summary` | `diagram_id` | 方言 + 计数 + 表列表 |
| `list_tables` | `diagram_id` | 每个表的名称 + 评论 + 字段计数 |
| `describe_table` | `diagram_id`, `table_name` | 完整的列定义、索引、注释 |
| `list_relationships` | `diagram_id` | 每个外键及其基数 + ON UPDATE/DELETE |
| `describe_relationship` | `diagram_id`, `from_table`, `to_table` | 过滤的关系信息 |
| `list_enums` | `diagram_id` | 用户定义的枚举 |
| `list_custom_types` | `diagram_id` | Postgres 复合类型 |
| `search_tables` | `diagram_id`, `query` | 表/列名称 + 注释中的子字符串匹配 |
表和关系查找不区分大小写。
## 配置
服务器完全通过环境变量配置（在客户端配置的 `env` 块中设置，或在本地运行时在 shell 中导出）：
| 变量 | 是否必需 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `DRAWDB_API_KEY` | 是 | — | 您的 drawDB API 密钥（`ddb_…`）。 |
| `DRAWDB_BASE_URL` | 否 | `https://api.drawdb.app` | 覆盖以指向自托管或本地后端（例如 `http://localhost:4000`）。 |
## 认证模型
- API 密钥从 drawDB **个人资料模态框 → API 密钥**选项卡中生成。
- 密钥继承用户的计划和访问权限，并列出用户所属的所有团队的图表 —— 没有工作区范围，因此代理可以看到所有图表。
- 按设计只读；服务器不公开任何修改工具。
- 吊销密钥会立即使持有它的每个代理失效。
## 开发
```bash
npm install
npm run dev # 从源代码运行，并使用 tsx（如果存在，则读取 .env）
npm run typecheck # tsc --noEmit
npm run build # 编译到 dist/
npm start # 运行编译后的 dist/stdio.js
```
复制 `.env.example` 到 `.env` 并添加您的密钥，以针对实时后端运行，或将 `DRAWDB_BASE_URL` 指向本地 drawDB 服务器。
要在本地构建内测试 MCP 客户端，请在配置中将 `command`/`args` 替换为绝对节点调用：
```json
{
"command": "node",
"args": ["/absolute/path/to/drawdb-mcp/dist/stdio.js"],
"env": { "DRAWDB_API_KEY": "ddb_xxx" }
}
```
## 架构
服务器是 drawDB 后端只读 API 的一层薄薄的封装：
- `src/stdio.ts` — 入口点（`drawdb-mcp` 二进制文件）；读取环境变量，连接 stdio。
- `src/server.ts` — 构建 `McpServer` 并注册工具。
- `src/tools.ts` — 九个工具处理程序及其响应塑形。
- `src/api.ts` — `DrawDBClient`，一个 HTTP 包装器，封装 `GET /api/v1/diagrams` 和 `GET /api/v1/diagrams/:id/schema`，使用 `X-API-Key` 头进行身份验证。
- `src/types.ts` — 后端返回的图表模式形状。
## 许可证
MIT —— 请参阅 [LICENSE](./LICENSE)。
