用 Excalidraw…

当需要通过 MCP 工具或 REST API 在实时 Excalidraw 画布上程序化创建、迭代优化和导出图表时使用。

适用场景

解决思路

1. 先按顺序检测连接模式：运行 `mcp-cli tools | grep excalidraw`，若出现 `excalidraw/batch_create_elements` 等工具则用 MCP 模式；否则运行 `curl -s http://localhost:3000/health`，若返回 `{"status":"ok"}` 则用 REST API 模式；两者都失败则引导用户安装：`git clone https://github.com/yctimlin/mcp_excalidraw && cd mcp_excalidraw`，`npm ci && npm run build`，`HOST=0.0.0.0 PORT=3000 npm run canvas`，浏览器打开 `http://localhost:3000`，并可选执行 `claude mcp add excalidraw -s user -e EXPRESS_SERVER_URL=http://localhost:3000 -- node /path/to/mcp_excalidraw/dist/index.js`。
2. 在浏览器中打开画布 URL（截图和图片导出必需）。
3. MCP 模式下先调用 `read_diagram_guide` 加载设计最佳实践；REST 模式下阅读 `references/cheatsheet.md` 获取设计指南。
4. 写任何 JSON 之前先规划坐标网格：Tier 1（y=50-130）客户端应用，Tier 2（y=200-280）网关/边缘，Tier 3（y=350-440）服务（每个约 180px 间隔），Tier 4（y=510-590）数据存储，侧面板放在 x < 0（左侧）或 x > 主图右边界 + 80（右侧），绝不要把侧面板放在与主图相同的 x 范围。
5. 可选：MCP 用 `clear_canvas`，REST 用 `curl -X DELETE http://localhost:3000/api/elements/clear` 清空画布。
6. 用一次批量调用同时创建形状和箭头：MCP 用 `batch_create_elements`，REST 用 `POST http://localhost:3000/api/elements/batch` 并传 `{"elements": [...]}`（大 payload 用 `@file.json`）。
7. 给形状分配自定义 `id`（如 `"id": "auth-svc"`）以便后续引用。
8. 按文本长度设置形状尺寸：宽度用 `max(160, labelTextLength * 9)` 像素，高度单行 60px、两行 80px、三行 100px。
9. MCP 模式下用 `text` 字段标注形状，用 `startElementId` / `endElementId` 绑定箭头；REST 模式下必须用 `"label": {"text": "..."}` 标注形状（不能用 `"text"`），用 `"start": {"id": "..."}` / `"end": {"id": "..."}` 绑定箭头。
10. REST 模式注意：`fontFamily` 必须是字符串（如 `"1"`）或完全省略，不能传数字；更新形状标签时在 `PUT /api/elements/:id` 的 body 中包含完整 `label` 以确保正确渲染。
11. 箭头绑定后服务器会自动路由；未绑定的箭头需手动指定 `x`、`y`、`points` 坐标。
12. 复杂图中避免直线箭头交叉：用曲线箭头（加中间 waypoint 并设 `roundness: {"type": 2}`，如 `"points": [[0,0],[50,-40],[200,0]]`）或折线箭头（`"points": [[0,0],[0,-50],[200,-50],[200,0]]` 加 `"elbowed": true`）。
13. 箭头路由选择：扇出箭头（一源多目标）用曲线箭头并垂直分散 waypoint；跨泳道箭头（连到侧面板）用折线箭头先上、再横、再下绕过主图；服务间水平箭头用带轻微垂直偏移的曲线箭头。
14. 规则：若箭头会穿过无关元素，就加 waypoint 绕开，绝不接受交叉箭头。
15. 用 `set_viewport` 加 `scrollToContent: true` 自动适配全部元素；也可用 `scrollToElementId` 居中某元素，或用 `zoom`/`offsetX`/`offsetY` 手动控制。
16. 每批元素添加后必须运行质量检查：截图（MCP 用 `get_canvas_screenshot`，REST 用 `POST /api/export/image` 返回 `{"data": "<base64>"}` 保存为 PNG 再读回）并逐项核对——文本是否截断、元素是否重叠、箭头是否穿过无关元素、箭头标签是否与形状重叠、元素间距是否至少 40px、字号是否 >= 16（正文）/ >= 20（标题）。
17. 发现任何问题时：停止添加新元素，先修复（调整尺寸、重新定位、删除重建），重新截图验证，全部检查通过后才进入下一轮迭代。
18. 背景区域在所有边留 50px 内边距；层间垂直间距 60px，同级水平间距 40px；侧面板距主图至少 80px；箭头标签保持 1-2 个词。
19. 诚实评估截图：看到任何问题就说「我看到 [问题]，正在修复」，绝不说「看起来很好」除非全部检查通过。
20. 修改已有图时：先用 `describe_scene` 了解现状，按 id/类型/标签文本（而非 x/y 坐标）定位目标，用 `update_element` 移动/缩放/改色，用 `delete_element` 删除，截图验证；若更新失败，用 `get_element` 检查 id 是否存在、用 `unlock_elements` 检查是否被锁定。
21. 文件 I/O：用 `export_scene` 导出 .excalidraw（可指定 `filePath`），用 `import_scene` 加 `mode: "replace"` 或 `"merge"` 导入，用 `export_to_image` 加 `format: "png"` 或 `"svg"` 导出图片（需浏览器打开）；CLI 导出 `node scripts/export-elements.cjs --out diagram.elements.json`，CLI 导入 `node scripts/import-elements.cjs --in diagram.elements.json --mode batch|sync`。
22. 快照：风险操作前用 `snapshot_scene` 加名称保存，改动后用 `describe_scene` / `get_canvas_screenshot` 评估，需要时用 `restore_snapshot` 回滚。
23. 复制：用 `duplicate_elements` 传 `elementIds` 和可选 `offsetX`/`offsetY`（默认 20,20）创建重复模式。
24. 箭头/线条的 `points` 字段接受元组格式 `[[0,0],[100,50]]` 或对象格式 `[{"x":0,"y":0},{"x":100,"y":50}]`，都会自动归一化为元组。
25. 分享：用 `export_to_excalidraw_url` 上传加密场景并返回可分享 URL，任何人可在 excalidraw.com 打开查看和编辑。

适用边界 · 注意事项

• 没有运行画布服务器（`EXPRESS_SERVER_URL`，默认 `http://localhost:3000`）时无法使用。
• 需要截图或图片导出时必须打开浏览器，纯无头环境不支持。
• REST API 模式下 `get_canvas_screenshot`、`read_diagram_guide`、`export_to_excalidraw_url` 不可用，需改用 MCP 模式或替代方案。