chat-apps-ui-sdk

チャットアプリ UI SDK のベストプラクティス

ChatGPT と Claude のチャット画面内にインタラクティブな UI を表示する、美しくレビュー対応可能なアプリを構築するためのリファレンスです。2026 年 1 月時点で、これらのプラットフォームは、Claude、ChatGPT、VS Code、Goose がレンダリングする共通基盤である MCP Apps 標準（@modelcontextprotocol/ext-apps）を共有しています。OpenAI Apps SDK は window.openai ブリッジを追加したスーパーセットであり、MCP-UI（@mcp-ui/server / @mcp-ui/client）はコミュニティによる実装です。このスキルには 8 つのカテゴリにわたる 46 のルールが含まれており、影響の大きいものから順に並んでいます。

基本的な考え方：アプリでは まず MCP ツール、次に UI と考えます。モデルがツールを呼び出し、ツールはデータと UI リソースへのリンクを返します。ホストはそのリソースをサンドボックス化された iframe でレンダリングし、iframe は定義済みのブリッジを介して通信します。この一連の流れの早い段階でミスがあると何もレンダリングされず、後の段階でミスがあると、表示が壊れたり、安全性や完成度に問題が生じたりします。

適用する場面

以下の場合に、このガイドラインを参照してください。

• チャットアプリの MCP ツールと structuredContent / content / _meta の契約を設計するとき
• ツールをコンポーネントに接続するとき（_meta.ui.resourceUri、text/html;profile=mcp-app MIME タイプ、ui:// スキーム）
• iframe コンポーネントとそのブリッジを実装するとき（window.openai、ui/notifications/*、MCP-UI onUIAction）
• 表示モード、ウィジェットの状態、テーマ設定、レスポンシブレイアウトを選択するとき
• チャットアプリのセキュリティを強化するとき（CSP、サンドボックス、シークレット、OAuth）、またはディレクトリへの掲載に備えるとき
• 既存の ChatGPT アプリ / Claude アプリ / MCP-UI のコードをレビューまたはリファクタリングするとき

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	MCP ツールとディスカバリーの設計	重大	tool-
2	UI リソースの接続とテンプレート	重大	wire-
3	ホストとコンポーネント間のデータブリッジ	高	bridge-
4	表示モードとレスポンシブレイアウト	高	display-
5	状態とモデルコンテキスト	高	state-
6	セキュリティとデータ境界	高	sec-
7	ビジュアルデザインと UX の仕上げ	中〜高	design-
8	配布とホスト間の移植性	中	dist-

クイックリファレンス

1. MCP ツールとディスカバリーの設計（重大）

• tool-structured-content-contract - 出力を structuredContent、content、_meta に分ける
• tool-specific-verb-names - ツール名に具体的な動詞を使う
• tool-output-schema-validation - structuredContent の出力スキーマを宣言する
• tool-safety-annotations - readOnlyHint と destructiveHint を正確に設定する
• tool-minimal-scoped-inputs - タスクに必要な最小限の入力をツールに要求する
• tool-feed-widget-in-response - ウィジェットが必要とするすべての情報を 1 回の応答で返す
• tool-honest-descriptions - 正確なツールの説明とステータステキストを書く

2. UI リソースの接続とテンプレート（重大）

• wire-resource-uri-link - 各ツールを resourceUri で UI にリンクする
• wire-mcp-app-mimetype - UI リソースを mcp-app MIME タイプで提供する
• wire-ui-scheme-and-handler - ui:// URI を登録済みリソースに対応させる
• wire-version-uri-cache-key - リソース URI をキャッシュキーとしてバージョン管理する
• wire-inline-self-contained-bundle - コンポーネントのバンドルをリソースにインライン化する
• wire-set-ui-domain - コンポーネントに一意の ui.domain を設定する

3. ホスト–コンポーネント間のデータブリッジ（HIGH）

• bridge-render-from-notifications - 初回描画ではなく、ツールの出力から描画する
• bridge-call-tools-app-visibility - ツールを呼び出す前に、アプリにツールを公開する
• bridge-followup-vs-silent-call - フォローアップメッセージとサイレントなツール呼び出しを使い分ける
• bridge-validate-postmessage-origin - ホストで postMessage の送信元を検証する
• bridge-handle-all-mcpui-actions - MCP-UI のすべての onUIAction タイプを処理する
• bridge-use-host-apis - 再実装せず、ホストブリッジ API を使用する

4. 表示モードとレスポンシブレイアウト（HIGH）

• display-pick-the-right-mode - タスクに適した表示モードを選ぶ
• display-request-mode-with-fallback - 全画面表示をリクエストしつつ、まずインラインで描画する
• display-report-intrinsic-height - 固有の高さを報告し、maxHeight を尊重する
• display-avoid-nested-scroll - インラインカード内のスクロールの入れ子を避ける
• display-respect-theme - ホストのテーマと配色を尊重する
• display-responsive-breakpoints - 小さい画面ではレイアウトを自然に折りたたむ

5. 状態とモデルコンテキスト（HIGH）

• state-separate-three-stores - ウィジェット、サーバー、モデルの状態を分離する
• state-persist-widget-state - setWidgetState を通じて UI の状態を永続化する
• state-no-secrets-in-state - ウィジェットの状態に秘密情報や PII を含めない
• state-update-model-context - ユーザーの決定をモデルコンテキストに反映する
• state-keep-state-small - ウィジェットの状態を小さく、シリアライズ可能に保つ

6. セキュリティとデータ境界（HIGH）

• sec-declare-csp-allowlist - ウィジェットの CSP 許可リストを宣言する
• sec-avoid-frame-domains - ウィジェット内のフレームの入れ子を避ける
• sec-no-secrets-in-payloads - バンドルやペイロードに秘密情報を埋め込まない
• sec-enforce-server-side-auth - サーバー側で認可を強制する
• sec-signal-oauth-challenge - www-authenticate チャレンジで認証を通知する
• sec-minimize-restricted-data - 制限対象データの入力を最小限に抑え、避ける

7. ビジュアルデザインと UX の仕上げ（MEDIUM-HIGH）

• design-inherit-native-typography - ネイティブフォントを継承し、文字サイズを抑える
• design-restrain-brand-color - ブランドカラーはアクセントにとどめる
• design-render-loading-empty-error - 読み込み中、空、エラーの状態を描画する
• design-meet-wcag-contrast - WCAG AA のコントラスト要件を満たし、代替テキストを設定する
• design-limit-actions-hierarchy - アクションを絞り、明確な階層を保つ
• design-respect-reduced-motion - モーションの低減設定を尊重する

8. 配布とホスト間の移植性（中）

• dist-build-on-mcp-apps-standard - 共通の MCP Apps 標準に基づいて構築する
• dist-degrade-without-ui - UI がサポートされていない場合にテキストの代替を返す
• dist-provide-submission-metadata - 正確な提出メタデータを提供する
• dist-feature-detect-host-apis - 使用前にホストの機能を検出する

使用方法

詳しい説明と誤った例・正しい例のコードについては、各リファレンスファイルをお読みください。上から順に確認してください。カテゴリ 1（tool-）とカテゴリ 2（wire-）は、そもそも何かが表示されるかどうかを左右するため、表示やデザインに取りかかる前に解決してください。

• セクションの定義 - カテゴリ構成と影響度
• ルールテンプレート - 新しいルールを追加するためのテンプレート
• AGENTS.md - すべてのルールをまとめた目次

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリの定義と影響度の順序
assets/templates/_template.md	新しいルール用のテンプレート
metadata.json	バージョンとリファレンス URL

関連スキル

• build-mcp-server — このスキルの UI ルールが土台とする MCP サーバーの構成（デプロイモデル、ツールのパターン）を設計するためのエントリーポイントです。