drawarch

DrawArch MCP

将架构提示词和参考图像转换为便于移植、原生可编辑的 Draw.io 文件。
MCP 主机负责视觉推理。DrawArch 负责确定性渲染、资源嵌入、验证和交付。

快速开始 · 查看工作流 · 架构 · 参与贡献

---

查看哪些内容仍可编辑

这不是将截图粘贴到图表中。容器、标签、图标、形状、连接线端点、端口和路径点仍是相互独立的原生 mxCell 对象。资源嵌入在 .drawio 文件中，因此生成结果便于移植，也可离线编辑。

重要

DrawArch 不会调用其他大模型，也不需要第二个大模型 API 密钥。ChatGPT、Claude、Codex、Cursor 或其他具备视觉能力的 MCP 主机会分析请求或图像，并提供场景图。

DrawArch 能为你提供什么

	功能	含义
🧩	原生可编辑性	在 diagrams.net 中移动对象、修改样式、重命名、重新连接或删除单个对象。
🎯	参考图重建	使用绝对几何位置、图层、z 顺序、端口和路径点重建随附的架构图像。
🌐	真实世界资源	使用内置图标、兼容 Iconify 的图标、用户图像或经批准的 HTTPS 图像来源。
📦	可移植成果	生成的 .drawio 文件通过 MCP 直接返回，且所有图像资源均已嵌入。
🔐	知情批准渲染	不可变的计划修订版本和绑定修订版本的批准令牌可防止渲染过期或未经审核的内容。
✅	内置验证	在接受输出前检查 Draw.io 结构、引用、资源安全性和结构覆盖情况。

参考图像复刻

将架构图像附加到 MCP 主机，并提出以下要求：

使用 DrawArch 复刻此图像。保留其布局、标签、图标、分组和连接线走向。确保每个可见对象都可编辑，并在适当情况下使用真实图标。

随后，主机和 DrawArch 会按照可审查的四步流程操作：

1. 准备 — 主机视觉模型调用 prepare_reference_recreation，并提供经过类型校验的绝对场景图。
2. 审查并批准 — 用户或主机策略审查布局和在线资源来源；批准与该特定版本绑定。
3. 创建 — create_reference_drawio 安全解析并嵌入资源、渲染原生单元格、验证文件，并返回 .drawio 资源。
4. 比较并修订 — compare_reference_recreation 衡量结构覆盖度；主机调整计划，并在需要时重复操作。

flowchart LR
    A[Prompt or<br/>reference image] --> B[Vision-capable<br/>MCP host]
    B -->|typed scene graph| C{DrawArch MCP}
    C --> D[Plan revision<br/>& approval]
    D --> E[Safe asset<br/>resolver]
    E --> F[Native Draw.io<br/>renderer]
    F --> G[Validation &<br/>comparison]
    G -->|portable resource| H[Editable<br/>.drawio file]
    G -. revise .-> B

简单来说：你现有的 AI 分析图像；DrawArch 则将分析结果转换为受控、经过验证且可编辑的文件。完整契约见 examples/reference-recreation.json。

为什么不直接生成图像？

要求	DrawArch	扁平图像生成
编辑单个组件	✅	❌
重新连接并调整连接线走向	✅	❌
保留明确的 ID 和层级结构	✅	❌
生成后离线使用	✅	通常可以
自动验证结构	✅	❌
使用真实的嵌入式图标进行复刻	✅	不稳定
按照可审查的计划迭代	✅	❌
保证输出与原图像素完全一致	不保证 — 由主机引导迭代	不保证

DrawArch 的目标是高保真、可编辑的重建，而非不透明的像素级副本。主机视觉模型可以检查结果、更新几何形状或样式，并渲染另一个不可变版本。

快速开始

需要 Node.js 20+ 或 Docker。

通过 npm 运行

npx -y [email protected]

DrawArch 默认使用 stdio。诊断信息会写入 stderr，为 MCP 消息保留 stdout。

将其添加到本地 MCP 主机

{
  "mcpServers": {
    "drawarch": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "DRAWARCH_OUTPUT_DIR": "/absolute/path/to/diagrams",
        "DRAWARCH_ONLINE_ASSETS": "false"
      }
    }
  }
}

对于无法直接解析 npx 的 Windows 主机，请将 command 设为 npx.cmd。你也可以使用源代码检出，并配置绝对路径 dist/src/index.js。

从源代码运行

git clone https://github.com/Ajey95/drawarch-mcp.git
cd drawarch-mcp
npm ci
npm test
npm run build

然后配置主机：

{
  "mcpServers": {
    "drawarch": {
      "command": "node",
      "args": ["/absolute/path/to/drawarch-mcp/dist/src/index.js"],
      "env": {
        "DRAWARCH_OUTPUT_DIR": "/absolute/path/to/diagrams"
      }
    }
  }
}

运行已发布的容器

docker run --rm -p 3000:3000 \
  -e DRAWARCH_API_KEY=replace-with-a-long-random-secret \
  -e DRAWARCH_APPROVAL_SECRET=replace-with-another-random-secret \
  -e DRAWARCH_ALLOWED_HOSTS=localhost,127.0.0.1 \
  -e DRAWARCH_ALLOWED_ORIGINS=localhost,127.0.0.1 \
  -v drawarch-data:/data \
  ghcr.io/ajey95/drawarch-mcp:0.2.0

该容器在 http://localhost:3000/mcp 上运行 Streamable HTTP。其公开健康检查接口为 GET /health；MCP 和文件下载需要配置的 bearer token。

本地和远程主机

主机类型	推荐传输方式	说明
Claude Desktop / Claude Code	stdio 或远程 HTTP	本地 stdio 最简单；远程连接器可以使用 /mcp。
Codex / Cursor / VS Code	stdio 或远程 HTTP	对每位开发者分别生成输出时使用本地 stdio；也可以使用共享的、经过身份验证的服务。
ChatGPT	远程 Streamable HTTP	ChatGPT 无法启动本地 stdio 进程；请先将容器部署在 HTTPS 后面。
CI 和团队服务	Streamable HTTP	设置 bearer 身份验证、稳定的批准密钥、精确的主机/来源允许列表、TLS 和持久化输出卷。

DrawArch 目前提供可部署的服务端和公开容器，不提供托管的托管端点。运营方需自行提供 HTTPS 域名和基础设施。

MCP 工具

架构图生成

工具	用途
list_themes	列出六种内置视觉主题。
list_assets	搜索捆绑的真实图标目录。
resolve_asset	解析捆绑资源或选择加入的在线 SVG，并提供来源信息。
create_drawio	生成使用确定性主题的架构图。
validate_drawio	验证生成的架构文件。

参考图复刻

工具	用途
prepare_reference_recreation	存储绝对可编辑的场景图，并可选择批准其来源。
update_reference_plan	创建不可变的新版本，并使先前的批准失效。
get_reference_plan	读取最新的场景图版本以供审阅。
create_reference_drawio	渲染已批准的计划，并返回可移植的 .drawio 文件。
validate_reference_drawio	验证原生结构、引用和嵌入图像的安全性。
compare_reference_recreation	评估结构覆盖情况，并报告缺失的可编辑元素。

资源与安全模型

参考计划支持以下资源模式：

模式	来源	是否需要服务端主动启用？
bundled	原始 MIT 许可的 DrawArch SVG 图标库	否
online	兼容 Iconify 的图标查询	是
data	用户提供的 SVG、PNG、JPEG 或 WebP 数据 URI	否
remote	明确批准的 HTTPS 图像 URL	是

远程图像处理会拒绝包含 URL 凭据、使用非 HTTPS 协议或自定义端口的 URL，以及解析到私有或保留 DNS 地址、存在不安全重定向、字节数或像素尺寸超限、含有活动 SVG 内容的图像。嵌入前会解码并重新编码光栅图像。在线资源会保留提供方和许可信息；用户仍有责任核实第三方许可条款。

HTTP 部署还支持 Bearer 身份验证、主机验证、来源验证、安全输出路径、原子写入，以及与版本绑定的 HMAC 批准令牌。部署指南和漏洞报告方式请参阅 SECURITY.md。

环境变量

变量	默认值	含义
DRAWARCH_TRANSPORT	stdio	选择 stdio 或 http。
DRAWARCH_OUTPUT_DIR	.drawarch-output	受限的输出和计划存储目录。
DRAWARCH_ONLINE_ASSETS	false	启用需主动开启的在线和远程图像来源。
DRAWARCH_ICONIFY_BASE_URL	Iconify API	兼容 Iconify 的 HTTPS 提供方基础 URL。
HOST	127.0.0.1	HTTP 绑定主机。
PORT	3000	HTTP 监听端口。
DRAWARCH_API_KEY	未设置	/mcp 和 /files 的 Bearer 令牌；向互联网开放时必须设置。
DRAWARCH_APPROVAL_SECRET	每个进程随机生成	用于批准的 HMAC 密钥；共享部署时请设置稳定的密钥。
DRAWARCH_ALLOWED_HOSTS	本地主机	以逗号分隔的允许 Host 值。
DRAWARCH_ALLOWED_ORIGINS	本地来源	以逗号分隔的允许 Origin 主机。
DRAWARCH_PUBLIC_BASE_URL	监听器 URL	服务报告的公共基础 URL。

开发

npm ci
npm test                    # 83 tests at the 0.2.0 release
npm run build
npm run sample
npm audit --audit-level=high
npm pack --dry-run

CI 矩阵会在 Windows 和 Linux 上验证 Node 20 和 22，并构建生产环境 Docker 镜像。组件边界和安全流程请参阅 docs/ARCHITECTURE.md。

项目状态

渠道	状态
源代码	在 GitHub 上公开
发布版本	v0.2.0
容器	ghcr.io/ajey95/drawarch-mcp:0.2.0
npm	[email protected]
官方 MCP 注册表	io.github.Ajey95/[email protected]
托管远程服务	目前未提供

路线图

• 扩充精选架构素材目录和提供方元数据。
• 添加预览渲染功能，缩短由宿主引导的可视化对比周期。
• 添加像素级对比，作为结构评分的补充。
• 为更多 MCP 宿主和社区目录添加安装指南。
• 为常见容器平台提供可重复的部署方案。

欢迎提出想法并提交针对性 Pull Request。开始进行大规模行为或契约变更前，请先创建一个 issue。

贡献

请阅读 CONTRIBUTING.md，遵循 CODE_OF_CONDUCT.md，并确保不要将生成的输出、凭据和未获授权的第三方素材提交到代码库。

如有安全问题，请遵循 SECURITY.md 中的私下报告流程，而不要创建公开 issue。

许可证

DrawArch 源代码和捆绑素材采用 MIT 许可证。第三方素材保留其原始提供方的许可证和署名要求。

---

为架构设计而打造，让成果易于理解、方便移植，并由你随意编辑。