diagramport

diagramport

diagramport 可根据 Mermaid 语法生成 Mermaid 图表。提供图表语法——graph TD; A-->B; 等——即可获得所需格式：语法本身、可分享的 mermaid.ink 链接，或通过你在本机配置的渲染器命令生成的图像。

除渲染之外，其余逻辑都在本地运行且始终可用：系统会先验证语法，再进行其他操作；分享链接直接根据图表文本生成，不会发起任何网络请求。

安装

npx @reneturcios/diagramport generate --mermaid "graph TD; A-->B;" --output-type mermaid

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/diagramport

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

# Validate syntax only (exit 1 with the reason when invalid)
diagramport validate --mermaid "graph TD; A-->B; A-->C; B-->D; C-->D;"

# Return the validated syntax
diagramport generate --mermaid "graph TD; A-->B;" --output-type mermaid

# Build a shareable mermaid.ink link (SVG or PNG)
diagramport generate --mermaid "graph TD; A-->B;" --output-type svg_url
diagramport generate --mermaid "graph TD; A-->B;" --output-type png_url

# Render an image (needs DIAGRAMPORT_RENDERER_COMMAND, see below)
diagramport generate --mermaid "graph TD; A-->B;" --output-type base64
diagramport generate --mermaid "graph TD; A-->B;" --output-type file

diagramport --version

退出代码：成功时为 0；语法无效或渲染失败时为 1（错误信息会指出问题）；用法错误时为 2。

MCP 服务

同一个可执行文件支持两种用途。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/diagramport mcp

MCP 客户端配置：

{
  "mcpServers": {
    "diagramport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/diagramport", "mcp"]
    }
  }
}

工具

工具	输入	返回内容
generate_mermaid_diagram	mermaid（字符串，必填）——mermaid 图表语法；theme（字符串，可选，默认值为 default）；backgroundColor（字符串，可选，默认值为 white）；outputType（字符串，可选，默认值为 base64）——可选值为 base64、svg、mermaid、file、svg_url、png_url	取决于 outputType：mermaid 返回经过验证的语法文本；svg_url / png_url 返回公开的 mermaid.ink 链接；base64 返回经过渲染的 PNG 图像的 base64 编码字符串；svg 返回经过渲染的 SVG 标记；file 将经过渲染的 PNG 图像保存到磁盘并返回其路径。

验证

生成任何输出之前，系统都会在本地检查语法。第一条非空行必须以已知图表类型开头（graph、flowchart、sequenceDiagram、classDiagram、stateDiagram、stateDiagram-v2、erDiagram、journey、userJourney、gantt、pie、gitGraph、mindmap、timeline、quadrantChart、requirementDiagram、C4Context），且引号和括号必须成对（双引号标签中的括号不计入）。语法无效时会报告指出原因的错误，绝不会将其传给渲染器或链接生成器。这是结构合理性检查，并非完整的 Mermaid 解析。

分享链接

对于 svg_url 和 png_url，diagramport 会在本地生成链接：将 UTF-8 图表文本进行 base64url 编码后，附加到 https://mermaid.ink/svg/（SVG）或 https://mermaid.ink/img/（PNG）之后。任何人打开该链接，都可以通过 mermaid.ink 渲染图表；diagramport 本身不会为生成链接发起网络请求。

渲染

diagramport 不捆绑任何渲染器——将图表渲染为图像需要 Mermaid 引擎，通常还需要无头浏览器；这些都由操作方自行配置。base64、svg 和 file 输出类型会通过 DIAGRAMPORT_RENDERER_COMMAND 环境变量指定的本地命令进行渲染。该命令通过 stdin 接收图表文本，并且必须将渲染后的图像字节写入 stdout：

export DIAGRAMPORT_RENDERER_COMMAND="my-mermaid-renderer --format png"
diagramport generate --mermaid "graph TD; A-->B;" --output-type base64

如果没有配置渲染器，这些输出类型会返回指出 DIAGRAMPORT_RENDERER_COMMAND 的错误。系统不会伪造或模拟图像字节。设置了 DIAGRAMPORT_OUTPUT_DIR 时，file 输出会保存到该目录；否则保存到 ./diagrams/，文件名带有时间戳，扩展名为 .png。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, fake renderer only
npm run dev     # run the CLI from source via tsx

许可证

MIT——参见 LICENSE。