mcp-a2ui-vega

UI が A2UI、チャートが Vega-Lite の MCP App。

Claude にチケット販売ダッシュボードを頼むと、会話の中に表示されます。メトリクス、チャート、最新注文のテーブル、CSV をドロップする場所。そして変更を頼むと — 売上を折れ線チャートにして、今日の売上を緑で表示して、購入時間のヒートマップを追加して — ダッシュボードはゼロから描き直されるのではなく、その場で編集されます。CSV をドロップするか、スクリプトから行を追加すると、すべてのチャートが自動で更新されます。

このダッシュボードはモデルが生成した画像ではありません。エージェントが型付きカタログから構成したコンポーネントツリーであり、Google 自身の A2UI レンダラー（@a2ui/react）で描画され、変更をプッシュするデータセットにバインドされています。

構成要素

API キーは不要。 このリポジトリにはモデルはありません。エージェントは接続する MCP ホスト次第です。サーバーは行を保存し JSON を構成し、レンダラーは決定的です。関わる資格情報は、Worker をデプロイするために必要な Cloudflare のものだけです。

Related MCP server: vegalite-viewer

A2UI の言葉で言うと

Google の A2UI と MCP Apps の投稿では、2 つのプロトコルが構成される 3 つの方法が挙げられています。このリポジトリは パターン 3: MCP Apps 内の A2UI です — MCP App バンドルは独自の A2UI レンダラーを内蔵しており、これにより A2UI を知らないホスト（今日の Claude）でもエージェント構成の UI を表示できます。

これは本物の A2UI であり、模倣ではありません。レンダラーは @a2ui/react が @a2ui/web_core の MessageProcessor を駆動しています — Google のパッケージをそのまま使用。ワイヤーフォーマットは A2UI v0.9 メッセージ: createSurface、updateComponents、updateDataModel。カタログは A2UI 自身の基本カタログを置き換えるのではなく拡張しているため、Column、Card、ChoicePicker は彼らのもので、VegaChart は私たちのもので、1 つのカタログ ID の下にあります。

また、パターン 1: MCP 上の A2UI を第 2 のパスとして実装しています — 同じダッシュボードが a2ui://dashboard/ticket_sales で application/a2ui+json として提供されるため、独自の A2UI レンダラー（Flutter、Angular、ネイティブクライアント）を持つホストは iframe なしで描画できます。そのペイロードがポータブルな成果物であり、MCP App は他のすべての人がそれを見るための方法です。

ダッシュボードがライブであり続ける仕組み

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

4 つの決定が大部分の仕事を担っています:

行はモデルを経由しません。 render_dashboard はレイアウトと行数を返します。ビューは get_dataset_rows で自分で行を取得します。このツールの _meta.ui.visibility は ["app"] なので、エージェントのツールリストには決して表示されません。1 万 2 千件の注文はチャートに属するものであり、コンテキストウィンドウに属するものではありません。

ダッシュボードはコンポーネントであり、画像ではありません。 1 つのチャートを変更するのは、1 つの ID を指定した 1 回の update_dashboard です。ユーザーのフィルター、並べ替え順、スクロール位置は、他の何も触れられていないため、維持されます。

更新は、ダッシュボードを見たことがないビューでもレンダリングできなければなりません。 ホストはツール結果ごとに新しいビューを開くことができ、実行中のビューにルーティングする必要はありません。純粋な updateComponents のペイロードには、そこで更新するものは何もありません — A2UI は surface not found で拒否し、ユーザーは変更を求めた場所に空白のパネルが表示されます。そこでサーバーは構成済みツリーを記憶し、すべての更新は 2 つの形式で送信されます: _meta['a2ui/messages'] はサーフェス全体をゼロから再構築し、_meta['a2ui/patch'] は差分のみを運びます。ビューは自分が保持しているものに合う方を適用するため、サーバーは自分がどのビューと話しているかを推測する必要はありません。

サーバーが「いつ」を伝え、ホストは依然として「何を」運びます。 MCP にはサーバー→ビューのチャネルがないため、ビューは Worker への変更ストリームを直接開いたままにします — これはアプリリソースが csp.connectDomains で許可する唯一のものです。そこに流れてくるのは通知であり、データではありません。行は依然としてホストのツールプロキシを通じて取得されるため、すべてのデータバイトは監査可能なままです。アイドル状態のダッシュボードはリクエストを一切行わず、変更は約 1 秒で届きます。

カタログが名付けたことのないチャートも含む、あらゆるチャート

VegaChart はプロパティとして Vega-Lite 仕様全体を受け取ります。ヒートマップ、箱ひげ図、ファセット化されたスモールマルチプル — どれもカタログにはありませんが、すべて機能します。カタログの境界は コンポーネントの種類 であり、チャートの種類 ではないからです。

ユーザーが気に入った場合、save_widget は名前を付けて保存し、render_dashboard({widgets: ["sales_by_hour_heatmap"]}) は後の会話でそれを呼び戻します — ライブデータセットにバインドされたままなので、他のすべてと同様に更新されます。

データ

data/ticket_sales.csv は、12 のブロードウェイショーにわたるチケット注文ごとの 1 行です。ショー、劇場、ハウスサイズ、週ごとの収容率、価格帯は 実際の もので、Broadway weekly grosses データセット（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 でデプロイに向け、ダッシュボードが動くのを見てください — 各追記から 1 秒以内に、サーバーが通知するからです。

実行

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 をデプロイする場合は、その 1 行を変更し、/plugin marketplace update mcp-a2ui-vega を実行してください。

Claude Web またはデスクトップ: 設定 → コネクタ → カスタムコネクタを追加 で、https://your-worker.workers.dev/mcp を貼り付けます。OAuth もキーもありません。次にスキルを追加します: skills/a2ui-dashboards フォルダーを zip 化し — フォルダー自体が zip のルートにある必要があります — 設定 → 機能 → スキルの下にアップロードします。

スキルはどちらの場合も任意です: サーバーは MCP ハンドシェイクで使用手順を送信します。フォローアップを良くするのはこれです — すべてを再描画するのではなく 1 つのコンポーネントを編集し、気に入ったチャートを記憶します。

その後、チケット販売ダッシュボードを頼んでください。

デプロイ

ホストする必要があるのは Worker だけです。GitHub Pages はスタンドアロンデモを提供します。

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

これにより、KV 名前空間がまだ存在しなければ作成され、その ID が wrangler.toml に書き込まれ、アプリとシードデータがバンドルされ、デプロイされます。

または、2 つのリポジトリシークレットを追加して main にプッシュします — ワークフロー が名前空間の作成を含めてすべてを行い、シークレットが不足している間は失敗せず警告付きでデプロイをスキップします:

同じワークフローは、設定 → Pages でソースを GitHub Actions にして Pages が有効になると、スタンドアロンデモを 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

ローカルワーカーではなくデプロイに対して同じスイートを実行するには:

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 Apps ホスト、約 120 行、アプリとコードを意図的に共有しないため、プロトコルの間違いが両方で気づかれずに通過することはありません。型チェッカーではチェックできないことを検証します: ダッシュボードが描画されること、再構成が他のタイルを乱さずに 1 つのタイルを着色すること、追記された行が要求なしに届くこと、フィルターがメトリクスとテーブルを一緒に動かすこと、保存されたウィジェットが戻ってくること。

tools/push-latency.mjs はアーキテクチャが主張することを測定します: アイドル状態のダッシュボードは 一切 リクエストを行わず、変更は正確に 1 回のフェッチで約 0.5 秒で届きます。

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

ライセンス

MIT。