drawio-mcp 无 MCP 零安装方案:用 Claude Project 指令让 AI 直接生成 draw.io 图表链接
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:
- 打开你的 Claude Project 设置;
- 将 claude-project-instructions.txt 的完整内容加入项目指令;
- 同时加入 shared/xml-reference.md 的内容——这是覆盖边缘路由、容器、图层、标签、元数据、深色模式等主题的 XML 生成参考;
- 之后让 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 生成规范。
工作原理:四步闭环
原文档给出的工作流程是一个四步闭环:
- Claude 生成图表代码(Mermaid、XML 或 CSV);
- Claude 执行 Python 代码,对图表进行压缩与编码;
- 脚本输出一个完整 HTML 页面,URL 以可点击按钮的形式内嵌其中;
- Claude 将 HTML 作为 artifact(工件)呈现,用户点击按钮即可打开 draw.io。
这条流程的关键在于:图表的"压缩 + 编码 + 拼 URL"全部由 Python 代码完成,Claude 的文本生成过程完全不触碰 URL 本身。为什么必须这样设计?原文档给出了明确的理由,下一节详述。
URL 的编码机制:deflateRaw + Base64 + #create 哈希
claude-project-instructions.txt 中的 Python 脚本揭示了 draw.io URL 的标准编码管线:
- 对图表源码做
quote(diagram_code, safe=''),即百分号编码; - 用
zlib.compressobj(9, zlib.DEFLATED, -15)做原始 deflate 压缩(-15表示不带 zlib 头、使用原始 deflate 流); - 对压缩结果做 Base64 编码;
- 组装 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 中毫无意义; - 属性值中的特殊字符必须转义:
&→&,<→<,>→>,"→"。
这一约束在共享参考 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,否则标签会按字面文本显示;换行应使用
或<br>,绝不能用\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 交付"流程:
- 执行 Python 脚本;
- 脚本输出一个内嵌了正确链接的完整 HTML 页面;
- Claude 将脚本输出作为 artifact 呈现(链接因由脚本生成而保证正确);
- 在聊天文字中,只需告诉用户点击 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 frontmatterconfig: { 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 表格,指令方案的使用要点可归纳为:
- 默认 Mermaid:流程图、时序图、ER 图、Gantt 图等用它最可靠;
- XML 用于精确控制:需要精确坐标、自定义颜色或复杂布局时使用;
- 避免对关键图表用 CSV:CSV 处理可能失败,组织架构图优先 Mermaid;
- 发送前校验语法:确保 Mermaid/XML/CSV 语法正确、转义到位;
- 链接一律走 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 就是首选。