Visual MCP

一个模型上下文协议服务器，为LLM提供结构化的视觉层：它描述存在什么，并返回一个干净、精确的SVG图表——而不是ASCII艺术。

什么是Visual MCP？

让任何LLM“画出架构图”，你会得到这样的结果：

+----------+      +---------+      +------------+
|  React   |----->| NestJS  |----->| PostgreSQL |
+----------+      +---------+      +------------+
                       |
                       +-----> Redis?

框线绘制字符对于空间信息来说是一种糟糕的媒介。对齐会断裂，箭头无法到达，之后无法编辑，而且模型会把推理能力浪费在字符计数上。

显而易见的修复方案——“让模型编写SVG”——更糟糕。那样它必须手动计算viewBox、路径数据、箭头多边形、文本基线和边框交点，全部没有反馈，而且一旦用户要求做一个小改动，又得从头再来。

Visual MCP将几何计算从模型的任务中移除。 模型处理的是一个场景图：

{
  "title": "Service architecture",
  "elements": [
    { "id": "frontend", "type": "node",     "label": "React" },
    { "id": "backend",  "type": "node",     "label": "NestJS" },
    { "id": "db",       "type": "database", "label": "PostgreSQL" },
    { "id": "cache",    "type": "database", "label": "Redis" },

    { "id": "c1", "type": "connection", "from": "frontend", "to": "backend" },
    { "id": "c2", "type": "connection", "from": "backend",  "to": "db" },
    { "id": "c3", "type": "connection", "from": "backend",  "to": "cache" }
  ]
}

注意没有什么：没有坐标，没有尺寸，没有线条端点，没有箭头，没有SVG。服务器计算所有内容——根据标签计算节点大小，根据连接图计算位置，计算与边框相交的边、箭头标记、文本换行，以及一个不会裁剪的viewBox。

而且因为场景是一个带有稳定ID的图，对话的下一轮就是一行编辑，而不是重绘：

“把Redis放在后端上面，PostgreSQL放在它下面。” → update_element × 2，其他一切不变。

“现在把所有基础设施放在一个叫AWS的框里。” → group_elements，并且没有元素移动。

Related MCP server: Mermaid MCP Server

架构

ChatGPT
   │  tool call: render_diagram / update_element / …
   ▼
MCP server            src/mcp/         (transport, tools, error shaping)
   │
   ▼
Scene graph           src/scene/       (Zod schemas, validation, store, mutations)
   │
   ├─▶ layout         src/layout/      (sizes and positions for elements with no coordinates)
   ├─▶ semantic       src/semantic/    (node/connection/axis/… ▸ primitives)
   │
   ▼
SvgNode tree          src/renderer/    (closed, allow-listed representation of an SVG document)
   │
   ├─▶ toSvgString()  ─────────────────▶  SVG returned by the MCP tools
   └─▶ <SceneRenderer> ────────────────▶  React, for the interactive UI

五个理念支撑着这一切

1. 场景图是产物，SVG只是一种输出格式。 模型发送的所有内容都被验证为Scene并存储。渲染是该场景的一个纯函数，因此同一个图表可以在以后以不同的主题或由不同的后端重新渲染，而无需模型参与。

2. 语义元素编译为基本图元。 database变成一条路径、一个椭圆和两个文本块。connection变成一条带标记的路径。渲染器只看到这十个基本图元——这使其保持小巧，并且意味着以后添加neuron、decisionTree或functionPlot只需要在src/semantic/中增加一个扩展文件，而无需更改模式联合、布局引擎或渲染器。

3. 一个几何管线，两个后端。 渲染器的实际输出是一个SvgNode树，而不是字符串。serialize()将其转换为MCP工具的标记；<SceneRenderer>将其映射为UI的React元素。没有第二个实现会导致漂移，项目中也没有dangerouslySetInnerHTML。

4. 错误是为模型编写的，而不是为日志文件。

{
  "success": false,
  "error": {
    "code": "ELEMENT_NOT_FOUND",
    "message": "Connection 'c1' points to 'router-2' (to), which does not exist in the scene.",
    "path": "c1.to",
    "hint": "Existing elements you can connect: pc, switch, router-1, server."
  }
}

一个用于分支的代码，一个指出问题的句子，以及一个包含答案的提示。绝无堆栈跟踪。

5. 每个突变都是原子的。 被拒绝的编辑会使存储的场景保持字节完全不变。没有这一点，一次错误的调用就会破坏对话剩余部分的图表。

与最初草拟布局的偏差

• src/layout/ 是一个独立的模块，与src/semantic/分开。定位和含义到形状的扩展是不同的任务，这种分离使得以后替换为Dagre或ELK只需要更改一个文件（src/layout/flow.ts）——它的FlowItem in / centres out接口特意设计成这些库所暴露的形状。

• SvgNode位于渲染器及其输出之间（上面的理念3），这使得React视图可以在没有第二个渲染器且没有不安全的HTML注入的情况下存在。

• src/mcp/widget.ts 是一个无依赖的纯查看器，与src/ui/中的React应用分开。ChatGPT的iframe资源必须是一个自包含的HTML字符串，没有可能过时或运行时缺失的构建步骤；React应用是本地游乐场。它们共享相同的行为（缩放/平移/适应/复制/导出）和相同的允许列表。

• 自动适应默认开启，因此width/height作为提示而不是硬画布。这消除了最常见的失败模式——模型选择了一个太小的画布并裁剪了自己的图表。

安装

git clone <this repo>
cd visual-mcp
npm install

需要Node 20+（在Node 22/26上开发）。

开发

npm run dev:http      # MCP server over Streamable HTTP on http://localhost:3333/mcp
npm run dev:stdio     # MCP server over stdio (Claude Desktop, MCP Inspector, tunnels)
npm run dev:ui        # React playground on http://localhost:5180
npm test              # 128 tests
npm run typecheck
npm run build         # server → dist/
npm run build:ui      # playground → dist-ui/
npm run examples      # render the reference scenes → examples/out/index.html

针对运行中的服务器进行快速端到端检查：

npm run dev:http &
npx tsx scripts/smoke-mcp.ts

它重放整个目标对话——构建一个没有坐标的图表，检查它，移动两个节点，将所有内容包裹在一个框中——并在每一步断言结果。

可用的MCP工具

每个工具描述都说明了它的功能、何时使用、何时不使用以及每个属性的含义，因为另一个模型会读取这些描述并自行决定。只读工具带有readOnlyHint: true，破坏性工具带有destructiveHint: true，宿主使用这些来决定哪些需要确认。

场景模式

interface Scene {
  id?: string;
  title?: string;
  subtitle?: string;
  width?: number;          // hint; autoFit grows the canvas so nothing is clipped
  height?: number;
  autoFit?: boolean;       // default true
  background?: string;
  theme?: "dark" | "light" | "blueprint" | "paper";
  themeOverrides?: Partial<Theme>;
  layout?: "auto" | "layered" | "horizontal" | "vertical" | "grid" | "manual";
  direction?: "right" | "down" | "left" | "up";
  gap?: number;
  padding?: number;
  legend?: boolean;
  elements: VisualElement[];
}

每个元素都有id和type。ID是稳定的，是对话式编辑的工作方式。

基本图元——渲染器可以绘制的内容

circle · ellipse · rectangle · line · arrow · text · polygon · polyline · path · group

语义元素——模型实际应该使用的内容

布局

layout: "auto"（默认）在有连接时从连接图构建一个分层流，否则构建一行。具有显式x/y的元素永远不会被移动，因此模型可以微调一个节点而不干扰其他节点。direction控制流的增长方向。

数据框

一个axis声明从数据单位到像素的映射；任何带有frame: "<axis id>"的内容都放置在数据坐标中，y向上增长，正如它应该的那样：

{ "id": "plot",  "type": "axis",    "x": 90, "y": 70, "width": 620, "height": 420,
  "xRange": [0, 10], "yRange": [0, 10], "xLabel": "Feature 1", "yLabel": "Feature 2" },
{ "id": "class-a", "type": "cluster", "frame": "plot", "x": 3.4, "y": 6.6,
  "count": 40, "spread": 0.8, "label": "Class A", "hull": true, "seed": 7 }

主题

四个内置主题（dark、light、blueprint、paper），每个都是一个完整的调色板加上一个不需要外部字体的字体堆栈。元素引用令牌——primary、surface、muted、danger——而不是硬编码的颜色，因此整个图表可以在不触及几何的情况下重新样式化。themeOverrides更改任何令牌。

本地运行

作为库，完全没有MCP

import { renderScene } from "visual-mcp";

const svg = renderScene({
  title: "Request flow",
  elements: [
    { id: "client", type: "computer", label: "Client" },
    { id: "api", type: "server", label: "API" },
    { id: "c", type: "connection", from: "client", to: "api", label: "HTTPS" },
  ],
});

作为HTTP服务器

npm run dev:http

服务器是无状态的：每个请求获得自己的McpServer和传输，场景存储是唯一共享的状态。这就是为什么它在负载均衡器后面或服务器无服务器平台上安全，因为一个对话的两轮可能不会到达同一个进程。

作为stdio服务器（MCP Inspector、Claude Desktop、Cursor）

npx @modelcontextprotocol/inspector npx tsx src/mcp/stdio.ts

{
  "mcpServers": {
    "visual-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/visual-mcp/dist/mcp/stdio.js"]
    }
  }
}

连接到ChatGPT

ChatGPT通过公共HTTPS端点的Streamable HTTP访问远程MCP服务器，因此服务器需要可以从互联网访问。两种方式：

A. 使用隧道快速测试

npm run dev:http                  # http://localhost:3333/mcp
npx localtunnel --port 3333       # or: ngrok http 3333, or cloudflared tunnel

B. 在VPS上使用Docker部署

docker-compose.yml 运行两个容器：MCP 服务器在 4000 端口（不向互联网发布）和 Caddy，后者在其前端终止 TLS 并自动续期证书。

该 VPS 的 80 和 443 端口上已有其他服务，因此：

难点： Let's Encrypt 始终连接 80 端口 进行 HTTP-01 验证——这是 RFC 8555 规定的，不可配置——TLS-ALPN 同样固定为 443。Caddy 可以监听 90 端口，但必须有东西将请求转发过去。因此，任何已占用 80 端口的程序都必须将验证路径转发给 Caddy。

1. 选择一个公共主机名。 ChatGPT 需要 HTTPS，而裸 IP 无法获得证书。如果您没有自己的域名，请使用 sslip.io——它会将 <ip>.sslip.io 解析为该 IP，无需注册，并且 Let's Encrypt 会为其颁发证书：

curl -4 ifconfig.me            # on the VPS -> e.g. 203.0.113.45
# hostname becomes: 203.0.113.45.sslip.io

2. 从占用 80 端口的服务器转发 ACME 验证。 先确定它是哪个：

sudo ss -lptn 'sport = :80'

nginx —— 在 server { listen 80; } 块内：

location /.well-known/acme-challenge/ {
    proxy_pass http://127.0.0.1:90;
    proxy_set_header Host $host;
}

Apache —— 在 <VirtualHost *:80> 内部：

ProxyPreserveHost On
ProxyPass        /.well-known/acme-challenge/ http://127.0.0.1:90/.well-known/acme-challenge/
ProxyPassReverse /.well-known/acme-challenge/ http://127.0.0.1:90/.well-known/acme-challenge/

Caddy —— 在提供 80 端口服务的站点块内：

handle /.well-known/acme-challenge/* {
    reverse_proxy 127.0.0.1:90
}

使用真正的代理，而不是 301 重定向：Let's Encrypt 仅遵循到 80 和 443 端口的重定向，因此重定向到 :90 会失败。

3. 配置并启动：

cp .env.example .env
# MCP_DOMAIN=203.0.113.45.sslip.io
docker compose up -d --build

如果占用 80 端口的服务器运行在自己的容器内而非主机上，那么 127.0.0.1:90 对其不可达——请在 .env 中设置 MCP_HTTP_BIND=0.0.0.0，并将代理指向 VPS 的内部 IP（或者将两个容器放在同一个 Docker 网络中）。

4. 验证（首次请求可能需要几秒钟，因为证书正在颁发）：

curl https://$MCP_DOMAIN:500/health       # {"status":"ok",...}
docker compose logs caddy | grep -i "certificate obtained"

MCP URL 为 https://<MCP_DOMAIN>:500/mcp，并且是永久性的：restart: unless-stopped 可在重启后保持运行，证书保存在 caddy_data 卷中，因此续期在 docker compose down/up 后仍然存在。只有 docker compose down -v 才会清除它们。请保持验证转发——每 ~60 天的续期与首次颁发同样需要它。

PUBLIC_URL 和 ALLOWED_HOSTS 由 Compose 从 MCP_DOMAIN 和 MCP_HTTPS_PORT 派生。两者都必须包含端口：PUBLIC_URL 是因为 svgUrl 链接否则会指向 443 端口；ALLOWED_HOSTS 是因为 SDK 会将原始 Host 头（在非标准端口上读取 <domain>:500）作为精确字符串进行比较。

如果您无法修改占用 80 端口的服务器，则 HTTP-01 不可用。可行的方案是 DNS-01 验证（需要一个在受支持的 DNS 提供商上的真实域名——sslip.io 没有 API），或者 Cloudflare Tunnel，后者完全不需要入站端口。

不使用 Compose

docker build -t visual-mcp .
docker run -d --name visual-mcp --restart unless-stopped -p 127.0.0.1:4000:4000 \
  -e PUBLIC_URL=https://your-host -e ALLOWED_HOSTS=your-host visual-mcp

然后将任何反向代理指向 http://127.0.0.1:4000。容器以非 root 用户 node 身份运行，带有 /health 健康检查，并且仅包含生产依赖项。托管平台（Fly.io、Railway、Render、Cloud Run）同样适用——它们会注入自己的 PORT，服务器会遵循该端口。

然后在 ChatGPT 中

1. 启用开发者模式。 ChatGPT Business、Enterprise 和 Edu 的网页版可用。管理员在 工作区设置 → 权限与角色 → 连接数据 → 开发者模式 / 创建自定义 MCP 连接器 中启用。

2. 设置 → 连接器 → 创建 / 高级 → 开发者模式 → 添加自定义连接器。

3. 填写：

   • 名称：Visual MCP

   • MCP 服务器 URL：https://<your-host>/mcp

   • 认证：无认证（此服务器不附带认证——请参阅安全）

4. 保存。ChatGPT 会立即调用 tools/list；您应该会看到列出的十个工具。

5. 在新建对话中，启用连接器并请求图表。

该服务器还注册了一个 MCP Apps UI 资源（ui://visual-mcp/scene.html，text/html;profile=mcp-app），通过 _meta.ui.resourceUri 和 ChatGPT 别名 _meta["openai/outputTemplate"] 附加到渲染工具。在支持的地方，图表会显示在带有缩放、平移、适应、复制和导出功能的交互式框架中；在其他地方，工具仍会在 structuredContent 中返回 SVG，因此服务器可以优雅地降级。

示例

npm run examples 将所有五个示例渲染到 examples/out/index.html，而 list_examples 将其提供给模型。

1. 网络图——examples/out/network.svg

域预设和自动从左到右布局。computer → switch → router → server，链接上带有 VLAN 标题。源场景中没有任何坐标。

2. LDA——examples/out/lda.svg

一个 axis 数据框架，两个带种子的 cluster 和软凸包，一条虚线决策边界以及 LDA 方向——全部使用数据坐标，两条线都裁剪到绘图区域。

3. 回归——examples/out/regression.svg

坐标轴，一个 scatter 系列和一条带有 extend: true 的拟合 plotLine，使用浅色主题。

4. 软件架构——examples/out/architecture.svg

React → REST API → { Redis, PostgreSQL }，两个存储位于一个带标签的 group（"数据层"）内，连接路由进入其中。

5. 二叉树——examples/out/tree.svg

七个圆形节点和六条连接；down 方向的层次布局生成了树。

可在 ChatGPT 中尝试的提示词

Draw the architecture where React talks to NestJS, NestJS uses PostgreSQL and also queries Redis.
Now put Redis above the backend and the database below it.
Now put all the infrastructure inside a box called AWS.
Make PostgreSQL bigger and give it a purple border.

Explain Linear Discriminant Analysis visually.
Show me graphically how linear regression works.
Draw a network where a PC in VLAN 20 reaches a server in VLAN 10 through a switch and a router.
Draw a balanced binary tree with 7 nodes.
Explain the TCP three-way handshake as a diagram.
Diagram merge sort on [5, 2, 9, 1].

安全

威胁模型很简单：服务器渲染的所有内容都来自语言模型，而该输出本身可能包含用户从其他地方粘贴的文本。因此，任何源自模型的内容都永远不会被视为代码。

• 封闭模式。 只解析已知的二十四种元素类型。颜色必须匹配十六进制/rgb/hsl/关键字/令牌语法——url(javascript:…) 在验证时会被拒绝。路径数据必须匹配 SVG 路径命令和数字，不能有其他内容。

• 允许列表输出。 渲染器只能发出来自 src/renderer/svgNode.ts 中两个显式列表的标签和属性。没有 on*，没有 href，没有 style，没有 class，没有 <foreignObject>，没有 <script>——模型无法表达它们，序列化器也会丢弃它们。

• 转义。 文本内容和属性值在输出时会进行 XML 转义。

• 项目中没有任何地方使用 dangerouslySetInnerHTML、eval、new Function。React 视图从 SvgNode 树构建元素；ChatGPT 小部件解析 SVG 并逐个节点针对相同的允许列表重新构建它，因此即使服务器被攻破，也无法将脚本注入到那个框架中。

• 有界输入。 元素数量、字符串长度、点数量、路径长度和存储的场景都有上限；场景按最旧优先驱逐。

• 不向模型泄露堆栈跟踪。 每个处理程序都被包装；任何意外情况都会变成带有简短消息的 INTERNAL_ERROR。

tests/security.test.tsx 中的测试对每一项都进行了断言。

按设计不包含的内容： 身份验证。该服务器不暴露任何秘密，也不接触任何外部系统，但公开部署就是一个公开的场景存储。在向除您之外的任何人暴露之前，请将其放在您平台的身份验证之后，或者通过 SDK 的身份验证辅助程序添加 OAuth。设置 ALLOWED_HOSTS 以在可从浏览器访问时启用 DNS 重新绑定保护。

当前限制

• 文本度量是估算的，而非实际测量——服务器上没有字体引擎。对于捆绑的无衬线字体栈，宽度在几个百分点以内，这对于盒子和换行来说足够了，但非常用字体或大量 CJK 字符会导致尺寸略微偏松。

• 布局引擎故意设计得很小。 最长路径分层加居中对齐。没有交叉最小化和重叠解决，因此密集图（大约 25 个以上节点且有许多交叉链接）会产生真实引擎会避免的交叉。接口之所以设计成 Dagre 风格，正是出于这个原因。

• 树形布局不是子节点居中的；父节点位于其层级的中心，而不是其子节点中点的上方。

• render_diagram 的 JSON Schema 约为 50 KB（约 12k 个 token），因为它包含了整个元素词汇表。其他九个工具总计约 5 KB。这是一个刻意的权衡：模型获得每个字段的文档，很少需要修复往返。

• 在具有自动布局的组内，子节点的显式 x/y 会被忽略——布局优先。使用组上的 layout: "manual" 来自己放置子节点。

• 存储是内存中的。 场景不会在重启后保留，并且有多个副本时，场景只存在于创建它的实例上。SceneStore 接口的存在正是为了替换这个类。

• 静态输出。 目前没有动画、3D 或数学表达式解析器——请参阅下文。

路线图

下一步

• 持久化 SceneStore（首先是 SQLite）——接口已经就位。

• 撤销/重做。每个变更已记录为 SceneMutation；这只是存储逆操作的问题。

• 在 src/layout/flow.ts 后端使用 Dagre 或 ELK 处理密集图，以小引擎作为默认选项。

• 子节点居中的树形布局。

数学——axis 数据框架是基础；以下每一项都是 src/semantic/ 中的一个扩展器，无需更改渲染器： functionPlot ({ "expression": "x^2", "domain": [-5, 5] })、vector、matrix、plane、distribution、projection、decisionBoundary 和 regressionLine 作为 plotLine 的命名别名。

图表词汇——neuron、neuralNetwork、decisionTree、sequenceDiagram、stateMachine、gantt、swimlane。

动画——在连接上使用 { "animation": { "type": "flow", "duration": 1200 } }，以 SVG SMIL 或 CSS 形式发出，使其保持声明式且无需运行时。数据包沿链接移动，请求穿过管道，算法在结构中逐步执行。

其他渲染器——解析管道最终生成与后端无关的树。具有 kind: "3d" 和 { "type": "sphere", "position": [0, 1, 0] } 的 Scene 会选择 Three.js 后端而不是 SVG 后端；Canvas 后端可用于非常大的散点图。MCP 层无需更改。

许可

MIT