AIGUI

@ai-gui/mcp

让你的编码 Agent 绘图。 一个 MCP 服务，也是 Claude Code 和 Codex 的 AIGUI 插件引擎，可将图表、示意图、数学公式、3D 场景、分子、轨道、仪表板和分步基础设施拓扑转换为 PNG，供 Agent 检查；也可在浏览器中生成实时页面。

在线演示 · 源代码 · 所有软件包

安装

Claude Code — 此插件还附带技能，告诉 Agent 何时图片比文字更合适：

/plugin marketplace add liliang-cn/aigui
/plugin install aigui@aigui

Codex：

codex plugin marketplace add liliang-cn/aigui
codex plugin add aigui@aigui

任何 MCP 客户端 — 通过 stdio 运行 aigui-mcp：

npm install -g @ai-gui/[email protected]
claude mcp add aigui -- aigui-mcp

需要 Node.js 18.11+。首次绘图时会下载一个无头浏览器（约 100 MB，仅需下载一次）；所有内容都在本地运行，无需账户或 API 密钥。

可绘制内容

包含 21 种区块类型：ECharts 图表（也支持 3D）、Mermaid、KaTeX、仪表板和数据墙、3D 场景、由 SMILES 生成的分子、轨道和碰撞、可播放步骤的拓扑、知识图谱、几何图形、函数图像、光学、力学、带标注的图形、蜡烛图、表格等。其中 9 种可直接渲染为 PNG；所有类型都能绘制在页面中。

工具

工具	功能
aigui_guide	列出区块，或返回所列区块的精确语法——编写区块前请先阅读。
aigui_render	将 Markdown 字符串中的区块绘制为 PNG，返回给 Agent 并保存到磁盘。
aigui_open	将整个答案作为实时页面打开：图表可悬停查看，3D 内容可旋转，拓扑和数据墙可播放。
aigui_edit	通过查找并替换修改页面的一部分，无需再次发送整个答案。
aigui_export	将页面保存为 PNG、PDF、单个自包含 HTML 文件，或录制为 GIF / WebM。
aigui_topology	根据 docker-compose 文件或 Kubernetes 清单绘制系统。
aigui_feedback	读取用户对页面区块留下的评论。

可信之处

• 数值来自你的文件。 传入 data: {"sales": "/abs/path/sales.csv"}，并在图表中写入 {"$data":"sales","column":"revenue"}——也可使用 pick、sum、count、max、min、avg。数值直接从文件读取，不由模型重新输入；结果还会标明每个区块所依据的文件。
• 每幅图都会经过检查。 无头浏览器会检查标签重叠、文字被截断或小于 9 px、对比度不足以及图表拥挤等问题，并在你看到内容前提示 Agent 修正。
• 拓扑基于真实配置。 aigui_topology 读取实际部署的配置，而非模型记忆中的内容。
• 本地运行。 图片保存到 ~/.cache/aigui/images，页面保存到 ~/.cache/aigui/pages，并在 pages/index.html 中按时间倒序列出。页面不会从网络加载任何内容。

自定义区块

在 3 个文件中添加自己的区块类型——无需构建，也无需分叉：

npx @ai-gui/cli plugin new ticket   # writes ~/.config/aigui/plugins/ticket/

文件	说明
aigui.json	名称、围栏、一行描述，以及是否可以渲染为 PNG
plugin.js	一个用于注册 AIGuiPlugin 的普通浏览器脚本：(globalThis.__aiguiPacks ??= {}).ticket = (theme, still) => [...]。其 HTML 会像其他插件的 HTML 一样经过净化。
spec.md	模型编写此区块时遵循的规则

之后，它会以 [custom] 的形式出现在 aigui_guide 中，并在页面、PNG 和导出内容中绘制。会话开始时安装的区块也会列在工具描述中：在一次实测中，启用该功能的 9 个会话里，Agent 在 9 个会话中都使用了自定义区块；未启用时，9 个会话中只有 5 个使用了。损坏的文件夹会被跳过并说明原因；与内置区块重名时会被拒绝。

页面评论

会话运行期间，页面会通过 127.0.0.1（由系统选择的端口）提供，并带有一个 评论 按钮：选择区块，说明需要更改的内容，然后发送。Agent 会通过 aigui_feedback 读取评论并编辑页面。只有 pages 目录会被提供。

配置

变量	作用
AIGUI_OUT_DIR	图片和页面的保存位置。默认值为 ~/.cache/aigui（遵循 XDG_CACHE_HOME）。
AIGUI_NO_OPEN=1	写入页面，但不打开。
AIGUI_OPEN_IMAGES=1	也在图片查看器中打开 aigui_render 生成的 PNG——插件会设置此项，因为终端无法显示图片。
AIGUI_PLUGIN_DIR	自定义区块的存放位置。默认值为 ~/.config/aigui/plugins。
AIGUI_NO_BROWSER_DOWNLOAD=1	跳过无头浏览器下载；使用已安装的 Chrome 或 Edge 绘制。
AIGUI_BROWSER_CHANNEL	指定浏览器：chromium、chrome 或 msedge。

程序化使用

import { createServer, callTool, renderToContent, writePage } from "@ai-gui/mcp"

createServer() 返回未连接的 McpServer，供使用自有传输方式的宿主使用；callTool(name, args) 可直接运行一个工具。

许可证

MIT © Liang Li