drawio-mcp 无 MCP 零安装方案:用 Claude Project 指令让 AI 直接生成 draw.io 图表链接

原创2026-10-11 22:38:212,225 阅读
文章标签:MCP 服务AI 技能AI 插件人工智能

drawio-mcp 无 MCP 零安装方案:用 Claude Project 指令让 AI 直接生成 draw.io 图表链接

导读

drawio-mcp 项目为 AI 助手接入 draw.io 提供了四种方式,其中 project-instructions 目录承载的是一套完全不需要安装 MCP 服务器的替代方案:把一段精心编写的指令粘贴进 Claude Project 设置,Claude 就能在对话中直接生成可点击的 draw.io 图表链接。本文将以该方案的核心文档为主体,完整讲解其安装步骤、底层 URL 编码原理、Python 生成脚本、格式选择规则与"HTML artifact 交付链接"的设计动机,并结合仓库源码(mcp-tool-server/src/index.js、shared/xml-reference.md、shared/mermaid-elk.js 等)佐证其技术细节。读完本文,你将掌握这套零安装方案的全部配置内容与运行机制,并能判断它相比 MCP 服务器方案的优势与边界。

方案定位:为什么可以"不需要 MCP"

仓库主 README 将四种接入方式并列对比,Project Instructions 是其中唯一"零安装"的一条:

维度 MCP App Server MCP Tool Server Assistant Plugins Project Instructions
工作方式 对话内嵌渲染图表 浏览器打开图表 生成 .drawio 文件 Claude 用 Python 生成 draw.io URL
输出形式 对话内交互视图 新标签页编辑器 .drawio / PNG/SVG/PDF / URL 可点击的 draw.io 链接
是否需要安装 否(托管于 mcp.draw.io) 是(npm 包) 一行命令装插件 否——只需粘贴指令
支持格式 仅 XML XML / CSV / Mermaid 仅 XML XML / CSV / Mermaid 全支持
适用场景 对话内联预览 本地桌面工作流 本地开发工作流 快速上手、无需安装

原文档(project-instructions/README.md)给出的定位是:这是一条不需要安装 MCP 服务器的替代路径,不使用任何 MCP 工具,而是通过向 Claude Project 添加指令,让 Claude 使用 Python 代码执行来生成 draw.io URL。

该方案的核心优势(原文档列出):

  • 无需安装——在 Claude.ai 中开箱即用,立即生效;
  • 无需桌面应用——完全在浏览器内完成;
  • 使用简单——只需把指令加入 Claude Project;
  • 隐私友好——生成的 URL 使用哈希片段(#create=...),该片段只停留在浏览器中,永远不会被发送到任何服务器。

从仓库结构看(AGENTS.md),project-instructions/ 目录正是"Claude Project 指令(无需 MCP、无需安装)"的专属模块,与 mcp-app-server/(App 服务器)、mcp-tool-server/(stdio 工具服务器)、plugins/(各助手插件)并列,构成项目的第四条交付通道。

安装步骤:两条内容,粘贴即用

原文档的安装流程只有四步,核心动作是把两份文本粘贴进 Claude Project:

  1. 打开你的 Claude Project 设置;
  2. 将 claude-project-instructions.txt 的完整内容加入项目指令;
  3. 同时加入 shared/xml-reference.md 的内容——这是覆盖边缘路由、容器、图层、标签、元数据、深色模式等主题的 XML 生成参考;
  4. 之后让 Claude 创建图表,它便会生成可点击的 draw.io URL。

其中 claude-project-instructions.txt 就是发给 Claude 的"技能说明书"本体,而 shared/xml-reference.md 是项目层级的单一事实来源(single source of truth)。这一点在 AGENTS.md 中有明确说明:shared/ 下两份参考文件(xml-reference.md 与 mermaid-reference.md)被每一种交付机制消费——App 服务器的 create_diagram、Tool 服务器的 open_drawio_xml、Claude Code 插件以及这里的 Project Instructions——因此只需维护这一份文件,改动会自动传播到所有消费者。此外 mcp-tool-server/src/index.js 也印证了这一机制:工具服务器在启动时读取同一份 shared/xml-reference.md 并附加到 open_drawio_xml 的工具描述中,指令方案与 MCP 方案共享完全相同的 XML 生成规范。

工作原理:四步闭环

原文档给出的工作流程是一个四步闭环:

  1. Claude 生成图表代码(Mermaid、XML 或 CSV);
  2. Claude 执行 Python 代码,对图表进行压缩与编码;
  3. 脚本输出一个完整 HTML 页面,URL 以可点击按钮的形式内嵌其中;
  4. Claude 将 HTML 作为 artifact(工件)呈现,用户点击按钮即可打开 draw.io。

这条流程的关键在于:图表的"压缩 + 编码 + 拼 URL"全部由 Python 代码完成,Claude 的文本生成过程完全不触碰 URL 本身。为什么必须这样设计?原文档给出了明确的理由,下一节详述。

URL 的编码机制:deflateRaw + Base64 + #create 哈希

claude-project-instructions.txt 中的 Python 脚本揭示了 draw.io URL 的标准编码管线:

  1. 对图表源码做 quote(diagram_code, safe=''),即百分号编码;
  2. 用 zlib.compressobj(9, zlib.DEFLATED, -15) 做原始 deflate 压缩(-15 表示不带 zlib 头、使用原始 deflate 流);
  3. 对压缩结果做 Base64 编码;
  4. 组装 JSON 载荷 {"type": ..., "compressed": true, "data": ...},再次百分号编码后拼进 #create= 哈希片段。

这条管线与仓库中 MCP 工具服务器的服务端实现逐位一致:在 mcp-tool-server/src/index.js 中,compressData() 使用 pako.deflateRaw() 对 encodeURIComponent(data) 的结果做压缩并转为 Base64;generateDrawioUrl() 则组装 { type, compressed: true, data } 对象,用 #create= 前缀拼出完整 URL。区别仅在于服务端还额外处理了 lightbox、dark、border、edit 等查询参数,以及针对 Mermaid 类型追加 version 字段(见下文"进阶一致性"一节)。因此,指令方案中 Python 脚本产出的 URL 与 MCP 服务器产出的 URL 属于同一协议格式,可以被 draw.io 编辑器同等解析。

为什么 URL 放在 #create= 哈希里是隐私友好的

原文档强调生成的 URL 使用哈希片段(hash fragment)承载数据。哈希片段位于 URL 的 # 之后,按 Web 规范不会随 HTTP 请求发送到服务器,只会留在浏览器端。因此包含整个图表载荷的 #create=... 部分不会泄露给任何中间服务器——这正是该方案"隐私友好"的技术根基。

Python 生成脚本逐段解析(完整可复制)

以下是 claude-project-instructions.txt 中要求 Claude 执行的完整 Python 脚本。它负责把图表代码压缩、编码、拼装 URL,并输出一张内嵌"Open in draw.io"按钮的 HTML 页面:

import json, zlib, base64
from urllib.parse import quote

# Set these variables:
diagram_type = "mermaid"  # "mermaid", "xml", or "csv"
diagram_code = """graph TD
    A[Start] --> B[End]"""

# Generate compressed URL
encoded = quote(diagram_code, safe='')
c = zlib.compressobj(9, zlib.DEFLATED, -15)
raw_deflate = c.compress(encoded.encode('utf-8')) + c.flush()
data = base64.b64encode(raw_deflate).decode()

payload = json.dumps({"type": diagram_type, "compressed": true, "data": data})
url = f"https://app.diagrams.net/?pv=0&grid=0#create={quote(payload, safe='')}"

# Output as HTML page
print(f"""<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
  body {{
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    margin: 0;
    background: #f8f9fa;
  }}
  .card {{
    text-align: center;
    background: white;
    border-radius: 12px;
    padding: 40px;
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
  }}
  .card h2 {{
    margin: 0 0 8px;
    color: #1a1a1a;
  }}
  .card p {{
    margin: 0 0 24px;
    color: #666;
  }}
  .btn {{
    display: inline-block;
    padding: 14px 32px;
    background: #4285f4;
    color: white;
    text-decoration: none;
    border-radius: 8px;
    font-size: 16px;
    font-weight: 500;
    transition: background 0.2s;
  }}
  .btn:hover {{
    background: #3367d6;
  }}
</style>
</head>
<body>
  <div class="card">
    <h2>Diagram Ready</h2>
    <p>Click below to open your diagram in draw.io</p>
    <a class="btn" href="{url}" target="_blank" rel="noopener noreferrer">
      Open in draw.io
    </a>
  </div>
</body>
</html>""")

逐段要点:

  • 编码管线(quote → deflateRaw → base64):顺序与 MCP 服务器 compressData() 完全一致;compressobj(9, ...) 的 9 是最高压缩级别,-15 是关键——它选择原始 deflate 格式(即 deflateRaw),与 draw.io 官方工具链的解码端严格对应。
  • 载荷结构:{"type": diagram_type, "compressed": true, "data": data} 中的 compressed: true 是 draw.io 判断"数据已被压缩"的解码开关,字段名不可改动。
  • URL 查询参数:pv=0&grid=0 会关闭演示模式与网格,与服务端 generateDrawioUrl() 在非 lightbox 分支下设置的参数一致。
  • HTML 输出:脚本用 f-string 模板输出一张居中卡片页,把 url 变量直接插值进 <a href> 中——URL 由程序生成,不经过 Claude 的文本生成,从而保证链接字节级正确。

格式选择:三种输入格式与适用场景

claude-project-instructions.txt 为 Claude 定义了格式选择策略:

格式 最佳用途
Mermaid 流程图、时序图、ER 图、Gantt 图、状态图、类图
CSV 层级数据(组织架构图)、从电子表格批量导入
XML 复杂布局、精确坐标定位、自定义样式、图标、形状

原文档给出三条决策建议(见 AGENTS.md 的 Best Practices 与工具服务器 README 中的 Quick Decision Guide):默认优先用 Mermaid——它稳定覆盖大多数图表类型;需要精确坐标与定制样式时用 XML;尽量对关键图表避免 CSV——CSV 依赖 draw.io 服务端处理,可能偶发失败,组织架构图建议改用 Mermaid。

三种格式的示例代码

Mermaid(流程图)——方向关键字 TD 表示自上而下,--> 为箭头,-->|Yes| 为带标签的边:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

XML(draw.io 原生格式)——<mxGraphModel> 为根元素,<root> 内 id="0" 与 id="1" 分别代表根与默认图层,<mxCell> 描述顶点,<mxGeometry> 给出坐标与尺寸:

<mxGraphModel adaptiveColors="auto">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Box" style="rounded=1;fillColor=#d5e8d4;" vertex="1" parent="1">
      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>

CSV(层级数据)——以 # 开头的行是 draw.io 的导入指令:# label: 定义节点文本模板,# style: 定义默认样式,# connect: 定义父子连线规则(invert: true 表示箭头从经理指向下属),# layout: auto 开启自动布局:

# label: %name%
# style: rounded=1;whiteSpace=wrap;html=1;
# connect: {"from":"manager","to":"name","invert":true}
# layout: auto
name,manager
CEO,
CTO,CEO
CFO,CEO

XML 生成的关键规则:良构性与转义

指令中对 XML 生成有一条 CRITICAL 级约束:输出必须是良构(well-formed)的 XML,具体包括:

  • 严禁包含任何 XML 注释(<!-- -->)——注释浪费 token、可能引发解析错误,在图表 XML 中毫无意义;
  • 属性值中的特殊字符必须转义:& → &amp;,< → &lt;,> → &gt;," → &quot;。

这一约束在共享参考 shared/xml-reference.md 中被再次强调,并补充了第三条:每个 mxCell 的 id 必须唯一。之所以对"良构性"如此执念,从源码侧可以得到印证:工具服务器对 XML 的后续处理(归一化、ELK 布局、libavoid 布线)全部建立在对 XML 的解析之上——shared/mx-xml.js 的注释明确指出,解析器是一个针对 <mxCell>/<mxGeometry> 的小而精确的遍历,"LLM 被要求输出带转义属性值的良构 XML",任何意外情况都会让该页保持原样跳过处理。也就是说,良构 XML 是后续一切服务器端增强(布局、布线、修复)能正确生效的前提。

除良构性外,shared/xml-reference.md 还为 XML 生成提供了完整的风格与结构规范,例如:

  • 常用样式:圆角矩形 rounded=1;whiteSpace=wrap;html=1;、决策菱形 rhombus;、数据库圆柱 shape=cylinder3;、文档形状 shape=mxgraph.flowchart.document;;
  • HTML 标签:value 中含 <b>、<br> 等标签时必须在样式中加 html=1,否则标签会按字面文本显示;换行应使用 &#xa; 或 &lt;br&gt;,绝不能用 \n;
  • 容器体系:子元素通过 parent="<containerId>" 归属容器并使用相对坐标;不可见分组用 group;(含 pointerEvents=0),带标题栏用 swimlane;startSize=30;,任意形状加 container=1;pointerEvents=0; 也可充当容器;
  • 图层与标签:额外图层是 parent="0" 的 mxCell,可用 visible="0" 默认隐藏;标签需用 <object> 包裹 mxCell,通过 tags="critical v2" 空格分隔多标签;
  • 深色模式:<mxGraphModel adaptiveColors="auto"> 开启自动适配;未显式指定的颜色随明暗主题自动反转(明色反色并旋转色相 180°),需要精确双色时用 light-dark(lightColor,darkColor) 函数。

这些细节都是"复制进 Claude Project 的 xml-reference.md"所携带的能力,指令方案因此在 XML 图表质量上与 MCP 方案保持同一水准。

为什么必须用 HTML artifact 交付链接(关键设计决策)

原文档用了整整一节强调一个反直觉的约束:绝不要在你的聊天回复里重新输入、复述或复制生成的 URL。

原因是深刻的工程现实:生成的 URL 内含压缩后的 Base64 数据,而 LLM 在逐 token 复现 Base64 字符串时会静默损坏它——哪怕只有一个字符改变,整条链接也会彻底失效。Base64 是一种对单个字符错误极其敏感的表达方式,而 LLM 的文本生成本质上是概率性的 token 序列,逐字符精确复制长 Base64 串超出了其可靠边界。

解决方案正是本文反复强调的"HTML artifact 交付"流程:

  1. 执行 Python 脚本;
  2. 脚本输出一个内嵌了正确链接的完整 HTML 页面;
  3. Claude 将脚本输出作为 artifact 呈现(链接因由脚本生成而保证正确);
  4. 在聊天文字中,只需告诉用户点击 artifact 里的按钮。

也就是说,URL 从不经过 Claude 的文本生成管线,artifact 本身就是链接的交付机制。这与 MCP 工具服务器的浏览器打开逻辑形成有趣的对照:服务端在 openBrowser() 中处理 Windows 上 # 片段丢失、URL 超长(超过 Win32 INTERNET_MAX_URL_LENGTH 2083 字符)等问题时,同样选择了"临时 HTML 重定向页"(buildRedirectHtml())来绕过 shell 的 URL 长度限制——两种方案不约而同地借助"HTML 承载链接"来规避环境对长 URL 的处理缺陷,只是指令方案更进一步,把这个思想用于规避 LLM 自身的 Base64 复现误差。

进阶:与 MCP 服务器方案的底层一致性

虽然指令方案不运行任何服务器,但它产出的图表协议与 MCP 工具服务器高度同源,理解这一点有助于排查异常:

  • 压缩与载荷协议一致:见上文,Python 的 zlib 原始 deflate + Base64 与服务器 pako.deflateRaw + Base64 是同一格式(mcp-tool-server/src/index.js)。
  • Mermaid 版本一致性:服务端在生成 Mermaid URL 时会向载荷追加 version: "12"(MERMAID_DEFAULTS_VERSION),确保 draw.io 以 Mermaid 12 的默认配置(ELK 布局、redux-color 主题)转换并"记住"该版本;指令脚本未设置此字段,绘制结果将按 draw.io 当时的默认处理——若追求与 MCP 方案一致的渲染效果,可在脚本的 payload 中为 type == "mermaid" 的情况追加 "version": "12"。
  • ELK 布局选择:shared/xml-reference.md 描述的 postLayout: "elk" 对应服务端 elk-pass.js 的服务端 ELK 重排;对 Mermaid 流程图,shared/mermaid-elk.js 的 withElkLayout() 展示了标准做法——在源码前插入 YAML frontmatter config: { layout: elk },draw.io 转换时便会启用分层 ELK 布局。指令方案若需要复杂流程图(约 ≥20 节点、≥3 个判断菱形、存在回边或 ≥3 个端点)更整洁的排布,可以在生成的 Mermaid 源码顶部自行加入该 frontmatter。
  • 模型归一化:MCP 服务器会对每个 XML 图表先做归一化(shared/normalize-model.js),把边归到其端点的最近公共祖先、为缺失几何的边补上 relative 几何、把容器撑大到容纳溢出的子元素——这些修复对应桌面 CLI 的 --normalize。指令方案的 XML 若要被编辑器平滑编辑,建议遵循同一规则:两端在同一容器内的边,parent 应设为该容器(详见 xml-reference.md 的"边归属于同时容纳两个端点的最内层容器"规则),避免后续自动布局把边排到错误坐标帧。

最佳实践与常见问题

综合原文档与仓库 AGENTS.md 的 Best Practices 与 Troubleshooting 表格,指令方案的使用要点可归纳为:

  1. 默认 Mermaid:流程图、时序图、ER 图、Gantt 图等用它最可靠;
  2. XML 用于精确控制:需要精确坐标、自定义颜色或复杂布局时使用;
  3. 避免对关键图表用 CSV:CSV 处理可能失败,组织架构图优先 Mermaid;
  4. 发送前校验语法:确保 Mermaid/XML/CSV 语法正确、转义到位;
  5. 链接一律走 artifact:绝不把 URL 复制进聊天文本。

常见问题对照:

现象 成因 对策
生成的 XML 中出现注释 <!-- --> 混入输出 移除全部 XML 注释(严格禁止)
CSV 图表报 "URI malformed" 样式属性里用了 %column% 占位符 改用硬编码颜色
CSV 转换失败("Service nicht verfügbar") draw.io CSV 服务端不可用 稍后重试,或改用 Mermaid
打开后是空白图 Mermaid/XML 语法无效 检查语法与转义
链接失效 URL 被 LLM 重新复述导致 Base64 损坏 必须用 HTML artifact 交付链接

小结

project-instructions/README.md 描述的是 drawio-mcp 家族中最轻量的一条接入路径:不装 MCP、不开桌面应用、不碰服务器,只靠两段粘贴进 Claude Project 的文本,就让 Claude 借 Python 代码执行产出协议正确的 draw.io 链接。它的技术内核——deflateRaw 压缩、Base64 编码、#create= 哈希承载、HTML artifact 交付——与仓库中 MCP 服务器共享同一套规范,因此既可以作为零安装的快速体验入口,也可以作为理解整个 drawio-mcp 编码管线的最小样例。当你需要"立刻、零依赖、隐私友好"地让 AI 出图时,这套 Project Instructions 就是首选。

登录后查看全文
drawio-mcp