mcp-a2ui-vega

一个MCP应用，其UI是A2UI，图表是Vega-Lite。

向Claude请求售票仪表盘，它就会出现在对话中：指标、图表、最新订单表格、以及一个可以放置CSV的地方。然后请求更改——将销售图改为折线图，并以绿色显示今日销售额，添加一个购买时间热力图——仪表盘会在原地编辑，而不是从头重绘。将CSV放入其中，或从脚本追加行，每个图表都会自动更新。

仪表盘不是模型生成的图片。它是一个组件树，由代理从类型化目录中组合而成，由Google自己的A2UI渲染器（@a2ui/react）绘制，并绑定到一个数据集，该数据集会向它推送更改。

它由什么组成

无需API密钥。 此仓库中没有模型。代理是任何连接的MCP宿主；服务器存储行并组合JSON；渲染器是确定性的。唯一涉及的凭据是部署Worker所需的Cloudflare凭据。

Related MCP server: vegalite-viewer

用A2UI自己的术语来说

Google的A2UI and MCP Apps文章指出了两种协议组合的三种方式。此仓库是模式3：MCP应用中的A2UI——MCP应用包携带自己的A2UI渲染器，这使得从未听说过A2UI的宿主（如今天的Claude）也能显示代理组合的UI。

它是真正的A2UI，而不是模仿。渲染器是@a2ui/react驱动@a2ui/web_core的MessageProcessor——Google的包，未修改。线格式是A2UI v0.9消息：createSurface、updateComponents、updateDataModel。目录扩展了A2UI自己的基本目录而不是替换它，所以Column、Card和ChoicePicker是它们的，而VegaChart是我们的，在同一个目录id下。

它还实现了模式1：基于MCP的A2UI作为第二条路径——同一个仪表盘以application/a2ui+json格式在a2ui://dashboard/ticket_sales提供，因此拥有自己的A2UI渲染器的宿主（Flutter、Angular、原生客户端）可以完全不用iframe来绘制它。该负载是可移植的工件；MCP应用是其他人看到它的方式。

仪表盘如何保持实时

agent ──render_dashboard──▶ server ──A2UI messages in _meta──▶ view

                     ┌──────── change stream (SSE) ────────┐
server ──────────────┘  "ticket_sales moved"               ▼
   ▲                                                      view
   └── get_dataset_rows, through the host's tool proxy ──── │
                                                            │
                                          updateDataModel ──┘  every chart,
                                                               tile and table
                                                               re-renders

四个决策完成了大部分工作：

行永远不会经过模型。 render_dashboard返回布局和行数。视图自己使用get_dataset_rows获取行，该工具的_meta.ui.visibility为["app"]，因此它永远不会出现在代理的工具列表中。一万两千个订单属于图表，而不是上下文窗口。

仪表盘是组件，而不是图像。 更改一个图表就是一次update_dashboard，指定一个id。用户的筛选器、排序顺序和滚动位置都会保留，因为没有触及任何其他内容。

更新必须在从未见过仪表盘的视图中渲染。 宿主可以自由地为每个工具结果打开一个新视图，而不是将其路由到正在运行的视图，而纯updateComponents的负载在那里没有可更新的内容——A2UI会以surface not found拒绝它，用户会在请求更改的地方得到一个空白面板。因此，服务器会记住组合的树，并且每次更新都以两种形式传输：_meta['a2ui/messages']从头重建整个表面，_meta['a2ui/patch']只携带增量。视图应用适合它已持有的任何形式，因此服务器永远不必猜测它在与哪个视图对话。

服务器说何时，宿主仍然携带什么。 MCP没有服务器到视图的通道，因此视图保持一个直接到Worker的更改流——这是应用资源在csp.connectDomains中允许的唯一一件事。下来的是通知，而不是数据：行仍然通过宿主的工具代理获取，因此每个字节的数据都是可审计的。空闲的仪表盘根本不发出请求，更改大约在一秒内到达。

任何图表，包括目录从未命名的图表

VegaChart将整个Vega-Lite规范作为属性。热力图、箱线图、分面小倍数——它们都不在目录中，但都能工作，因为目录的边界是组件类型，而不是图表类型。

当用户喜欢某个图表时，save_widget按名称保存它，render_dashboard({widgets: ["sales_by_hour_heatmap"]})会在以后的对话中将其带回——仍然绑定到实时数据集，因此它会像其他所有内容一样更新。

数据

data/ticket_sales.csv是十二个百老汇演出中每个票务订单一行。演出、剧院、剧院容量、逐周上座率和价格水平都是真实的，来自Broadway weekly grosses dataset（Playbill，通过TidyTuesday）。单个订单是根据这些数据建模的，因为来源是每周的汇总数据。data/README.md确切说明了哪些部分是哪些。

npm run data:build                    # rebuild, 90 days ending now
npm run data:append -- --watch 10     # a live feed: new orders every 10s

使用--url https://your-worker.workers.dev将其指向部署，并在查看时观察仪表盘移动——每次追加后一秒内，因为服务器会通知它。

运行它

npm install
npm run data:build          # build the dataset (downloads the source CSV once)
npm run build               # catalog → renderer → single-file app → worker
npm run dev -w @mcp-a2ui-vega/server

然后打开http://localhost:8788/app.html单独查看仪表盘，或打开http://localhost:8788/查看连接说明。

在Claude中安装

先部署（见下文）——自定义连接器是从Anthropic的云访问的，而不是从你的机器，所以localhost不行。

Claude Code，直接从此仓库安装：

/plugin marketplace add vpm238/mcp-a2ui-vega
/plugin install a2ui-vega-dashboards@mcp-a2ui-vega

这将同时安装MCP服务器和技能。服务器URL在.claude-plugin/plugin.json中——如果你部署自己的Worker，更改那一行并运行/plugin marketplace update mcp-a2ui-vega。

Claude网页版或桌面版： 设置 → 连接器 → 添加自定义连接器，然后粘贴https://your-worker.workers.dev/mcp。没有OAuth，也没有密钥。然后添加技能：将skills/a2ui-dashboards文件夹压缩——文件夹本身必须在压缩包的根目录——然后在设置 → 功能 → 技能下上传。

无论哪种方式，技能都是可选的：服务器在其MCP握手中发送使用说明。它使后续操作变得更好——编辑一个组件而不是重绘所有内容，并记住你喜欢的图表。

然后请求售票仪表盘。

部署

Worker是唯一需要托管的东西。GitHub Pages承载独立演示。

npx wrangler login
npm run deploy -w @mcp-a2ui-vega/server

如果KV命名空间尚不存在，它会创建它，将其id写入wrangler.toml，打包应用和种子数据，然后部署。

或者添加两个仓库密钥并推送到main——工作流会完成所有操作，包括创建命名空间，并在缺少密钥时跳过部署并发出警告而不是失败：

一旦在设置 → Pages下启用Pages并将源设置为GitHub Actions，同一工作流就会将独立演示发布到GitHub Pages。在此之前，工作流会在警告中说明这一点并保持绿色。

测试

npm test                                       # dataset and catalog checks
npm run dev -w @mcp-a2ui-vega/server           # terminal 1
python3 -m http.server 8479                    # terminal 2, at the repo root
node tools/e2e.mjs                             # a real browser, the real protocol

要针对部署而不是本地worker运行相同的测试套件：

node tools/relay.mjs https://your-worker.workers.dev     # terminal 3
SERVER_URL=http://localhost:8790 node tools/e2e.mjs

中继的存在是因为受限代理后面的浏览器可能无法访问Cloudflare，而Node可以；每个字节仍然来自真实部署。它会缓冲响应，因此不携带更改流——它后面的视图会回退到轮询，这也值得测试。

tools/e2e.mjs驱动tools/harness.html——一个手写的MCP应用宿主，约120行，故意不与应用共享代码，这样协议错误就不会在两者中都被忽视。它检查类型检查器无法检查的事情：仪表盘是否绘制，重新组合是否只改变一个图块而不影响其他图块，追加的行是否自动到达，筛选器是否同时移动指标和表格，以及保存的小部件是否回来。

tools/push-latency.mjs测量架构声称的内容：空闲的仪表盘不发出请求，更改大约在半秒内到达，且恰好一次获取。

node tools/push-latency.mjs https://your-worker.workers.dev

许可证

MIT.