Archform

@archform/mcp

一个 MCP 服务，可让 AI 助手渲染和验证以代码编写的图表：Mermaid、PlantUML、C4-PlantUML、Graphviz、D2、Structurizr、BPMN 和 Excalidraw。

它可通过 stdio 在 Claude Desktop、Claude Code、Cursor 和 VS Code 中运行，也可在 ChatGPT 开发者模式下作为远程 Streamable HTTP 端点运行。

示例

助手可以像下面这样编写图表源代码 D2：

direction: right
user: User {shape: person}
ai: AI assistant
mcp: Archform MCP
kroki: Kroki {shape: cylinder}
user -> ai: "draw our architecture"
ai -> mcp: render_diagram
mcp -> kroki: diagram source
kroki -> mcp: SVG / PNG
mcp -> ai: image + share link

render_diagram 会将其转换为图像和分享链接。下方图像即为该链接的内容：

**试试看：**连接 Archform 后，向助手提问：

绘制一个 URL 缩短器的 C4 上下文图。

或者 “将 schema.prisma 转换为 ER 图”，或 “绘制我们登录流程的时序图”。

**隐私：**渲染由 Kroki 完成。默认情况下，图表源代码会发送到公开的 kroki.io 服务。如果图表描述了任何你不会粘贴到公开网站上的内容，请自托管 Kroki 并设置 KROKI_URL。

工具

所有工具均为只读（readOnlyHint: true、openWorldHint: true）。

工具	输入	结果
list_formats	无	所有受支持的格式及其别名、输出、文档链接和最简有效示例
render_diagram	format、source（≤ 100 KB）、output（默认 svg，或 png）	SVG 作为嵌入的 image/svg+xml 资源，或 PNG 作为图像内容，并附带可分享的 kroki.io 链接。源代码无效时，会返回 isError: true 以及解析器消息和行号
validate_diagram	format、source	{ valid, errors: [{ line?, message }] }。无效图表属于正常结果，而非工具错误

格式

格式	别名	输出
mermaid		svg、png
plantuml		svg、png
c4plantuml		svg、png
graphviz	dot	svg、png
d2		svg
structurizr		svg、png
bpmn		svg
excalidraw		svg

在本地使用（stdio）

需要 Node.js 22 或更高版本。

Claude Desktop：添加到 claude_desktop_config.json：

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

Claude Code：

claude mcp add archform -- npx -y @archform/mcp

Cursor：添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

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

VS Code：添加到 .vscode/mcp.json：

{
  "servers": {
    "archform": { "type": "stdio", "command": "npx", "args": ["-y", "@archform/mcp"] }
  }
}

要使用自己的 Kroki，请在服务条目中添加 "env": { "KROKI_URL": "https://kroki.internal.example.com" }。

远程运行（Streamable HTTP）

npx -y @archform/mcp --http --port 3000

• POST /mcp：MCP 流量（无状态）
• GET /health：健康检查

默认情况下，服务绑定到 127.0.0.1，并拒绝 Host 或 Origin 不是 localhost 的请求（防止 DNS 重绑定）。要将其公开访问，例如用于 ChatGPT 开发者模式，请绑定到所有网络接口并指定公开主机名：

HOST=0.0.0.0 ALLOWED_HOSTS=mcp.example.com TRUST_PROXY=1 RATE_LIMIT_PER_CLIENT=0 PORT=8080 npx -y @archform/mcp --http

然后，在 ChatGPT 中将 https://mcp.example.com/mcp 添加为连接器（Settings → Connectors，开发者模式），无需身份验证。请在 HTTPS 后运行服务。

限制

HTTP 端点将请求正文限制为 512 KB，并统计工具调用，而不是 HTTP 请求。会话的 initialize 和 tools/list 请求不计入统计。

• 总体：RATE_LIMIT（默认每分钟 120 次）限制所有客户端的工具调用总数。请根据 Kroki 后端的承载能力设置。默认值对公共 kroki.io 较为友好；如果使用可自托管的 Kroki，可调高此值。
• 每个客户端：RATE_LIMIT_PER_CLIENT（默认每分钟 60 次）可防止单个客户端耗尽全部额度。ChatGPT 从 OpenAI 的服务器调用你的服务，因此所有 ChatGPT 用户会共用少数几个 IP 地址，并共同受此限制。在主要服务于 ChatGPT 的部署中，设置 RATE_LIMIT_PER_CLIENT=0（如上例所示），或将其设为与 RATE_LIMIT 相同的值，这样 ChatGPT 用户便可使用全部总体额度。
• **位于代理之后：**大多数主机（Render、Fly.io、Railway、Cloud Run）会在应用前设置代理，因此每个请求看起来都来自代理的地址。设置 TRUST_PROXY=1（服务器前方的代理数量），使限流器使用代理添加到 X-Forwarded-For 中的地址。客户端直接连接时，请勿设置此项。客户端可以在该标头中填写任意内容，因此除非设置了 TRUST_PROXY，否则会忽略该标头。

当单次工具调用超出限制时，模型会收到一个包含 isError: true 的普通工具结果，以及类似 "Rate limit reached: … Retry in 42s." 的消息，因此可以告知用户等待。HTTP 429 只会显示为通用连接器故障。批量请求或格式错误的请求超出限制时，会返回 429 和 Retry-After。

计数器保存在内存中，因此每个实例都会单独执行自己的限制。

配置

标志 / 变量	默认值	含义
--http	关闭	使用 Streamable HTTP 而非 stdio 提供服务
--port、PORT	3000	HTTP 端口
--host、HOST	127.0.0.1	HTTP 绑定地址
ALLOWED_HOSTS		公共绑定时允许的逗号分隔 Host 值
RATE_LIMIT	120	所有客户端每分钟的工具调用次数；0 表示禁用
RATE_LIMIT_PER_CLIENT	60	每个客户端 IP 每分钟的工具调用次数；0 表示禁用
TRUST_PROXY	0	受信任的反向代理数量（true = 1），其 X-Forwarded-For 条目将被信任
KROKI_URL	https://kroki.io	用于渲染和分享链接的 Kroki 服务

自托管 Kroki

Kroki 提供 Docker 镜像。核心镜像支持 PlantUML、C4-PlantUML、Graphviz、D2 和 Structurizr；Mermaid、BPMN 和 Excalidraw 则各自需要一个配套容器：

# docker-compose.yml
services:
  kroki:
    image: yuzutech/kroki
    ports: ["8000:8000"]
    environment:
      KROKI_MERMAID_HOST: mermaid
      KROKI_BPMN_HOST: bpmn
      KROKI_EXCALIDRAW_HOST: excalidraw
  mermaid:
    image: yuzutech/kroki-mermaid
  bpmn:
    image: yuzutech/kroki-bpmn
  excalidraw:
    image: yuzutech/kroki-excalidraw

docker compose up -d
KROKI_URL=http://localhost:8000 npx -y @archform/mcp

生成的可分享链接会指向你的 Kroki 实例，因此只有能够访问该实例的人才能打开链接。详情请参阅 Kroki 安装文档。

开发

pnpm install
pnpm test                      # unit + in-process integration tests (Kroki stubbed)
KROKI_LIVE=1 pnpm test         # also run the live tests against KROKI_URL
pnpm build
npx @modelcontextprotocol/inspector node dist/index.js           # stdio
node dist/index.js --http      # then point the Inspector at http://127.0.0.1:3000/mcp

许可证

MIT