diag-weaver

图编辑器为核，MCP 为手。用户继续用 Cursor / Claude Code 里已经在用的 Agent；本项目只提供 活画布 + 少量 tools + 简单快照。

用户 ──UI──┐
            ├──► 图编辑器 ──autosave / snapshot──► 版本库
Agent ──MCP┘

不做独立对话 Agent，不内嵌 LLM，不扫整个工作区当第二个大脑。

第一期形态

• 真源：draw.io XML / 画布（官方 embed mode：embed=1&proto=json，autosave，layout，Mermaid descriptor）。

• 编辑器宿主：本机 127.0.0.1 HTTP 页里的 iframe。接口是 EditorHost；第一期是 BrowserHost。以后换成 IDE Webview / MCP Apps 时 不改 MCP 工具名。

• 存储：用户数据目录下的 current.drawio + snapshots/<时间>-<标签>.drawio。默认 Windows %APPDATA%\diag-weaver。进程握手、tools/list、空 diagram_read 不会 mkdir，也不会在 Agent cwd 建 graph-store。

• 工具面刻意少：editor_ensure、diagram_replace、diagram_read、diagram_patch、diagram_snapshot、diagram_restore、diagram_export。

• 多页图安全：diagram_read 的 summary 按页分组（summary.pages，另有跨页平铺的 cells）；diagram_patch 始终只作用于一个页，多页图必须显式传 page（1 起的页号或页名），补丁查找与插入都限定在目标页内，跨页同名 id 不会误伤。指定 id 时按原样写入；该 id 已在目标页存在才会报错，另一页上的同名 id 不占名额。同一批操作里先删掉的 id 可以再加回来。

• 结构化补丁：diagram_patch 支持 add_node / add_edge / set_label / remove_node / remove_edge。删节点会级联删掉其子 cell，以及挂在这些 cell 上的边；删元素请用 remove_* 而不是整图 diagram_replace，以保留用户手工布局。

社区复用：画布用官方 embed.diagrams.net，不自研 mxGraph，不把 lgazo 的 30+ 格子级工具暴露给 Agent。lgazo / 官方 @drawio/mcp 负责「遥控格子 / 打开看看」；这里负责同一张图的本地生命周期（可见、可手改、可快照、不污染工作区）。

Related MCP server: Excalidraw MCP Server

安装与 MCP 配置

用 pnpm（生成物在 dist/，不入库）。测 MCP 时走「构建 + 注册到全局 bin」，pnpm 12 已去掉 pnpm link --global，用 pnpm add -g . 达到同样效果：

pnpm install
pnpm test
pnpm run link

pnpm run link = pnpm build + pnpm add -g .。之后本机任意目录都能调 diag-weaver。卸掉：pnpm run unlink。若命令找不到，先 pnpm setup 并把 pnpm bin -g 加进 PATH。

Cursor MCP 配置（全局注册之后）：

{
  "mcpServers": {
    "diag-weaver": {
      "command": "diag-weaver"
    }
  }
}

不想装全局时，先 pnpm build，再用仓库脚本启动（把路径换成你的绝对路径）：

{
  "mcpServers": {
    "diag-weaver": {
      "command": "pnpm",
      "args": ["--dir", "D:/Projects/diag-weaver", "start"]
    }
  }
}

改源码后跑 pnpm build 即可，全局 bin 是 link 到本仓库的。改了 package.json 的 bin 或依赖再 pnpm run link。开发时可 pnpm dev（tsx 跑源码）。接上浏览器后可用 node scripts/smoke-embed.mjs 走一遍 Mermaid → 活画布。环境变量：

编辑器是懒启动的：进程启动只建立 MCP stdio 通道，不绑端口、不建目录；首次 editor_ensure 或 diagram_replace 才监听本机 HTTP 页、在 stderr 打印编辑器 URL 并打开浏览器。用户在画布上拖节点后，Agent 再 diagram_read 应能看到新位置。

只有 diagram_export 在被明确给出路径时才往工作区写文件：默认导出 .drawio XML；也支持活画布渲染的 png / svg 图片（需要画布已连接，format 可显式指定，缺省按扩展名 .png / .svg 推断），方便把架构图直接插进 README / 文档。

明确不做

• 编辑器内聊天窗口 / 自配 API Key

• Draft / Stage / Commit、游标、graph_nudge_*

• 把 Graph JSON 当真源再 roundtrip

• 第一期绑死某个 IDE 的 Webview

许可

MIT。draw.io 编辑器由 iframe 加载官方 embed 服务，不 vendoring 其源码。