chatgpt-apps

ChatGPT Apps

概要

ドキュメントを優先し、例を基に進めるワークフローで ChatGPT Apps SDK の実装をスキャフォールドし、現在の Apps SDK と MCP Apps ブリッジのパターンに沿ったコードを生成します。

このスキルを使用すると、次のものを作成できます。

• 主要なアプリのアーキタイプ分類とリポジトリ構成の決定
• ツールの計画（名前、スキーマ、アノテーション、出力）
• 上流の開始点に関する推奨事項（公式の例、ext-apps の例、またはローカルのフォールバック用スキャフォールド）
• MCP サーバーのスキャフォールド（リソース登録、ツールハンドラー、メタデータ）
• ウィジェットのスキャフォールド（まず MCP Apps ブリッジ、次に window.openai の互換性／拡張機能）
• 依存関係を抑えたフォールバック向けの、再利用可能な Node + @modelcontextprotocol/ext-apps スターター用スキャフォールド
• 最小限の動作するリポジトリ要件に対する検証レポート
• ローカル開発とコネクターのセットアップ手順
• アプリの機能を関係者に説明する短い要約（依頼された場合）

必須のドキュメント優先ワークフロー

ChatGPT Apps SDK アプリを作成または変更する際は、必ず最初に $openai-docs を使用してください。

1. $openai-docs を呼び出します（推奨）。または、OpenAI のドキュメント MCP サーバーを直接呼び出します。
2. コードを書く前に、Apps SDK の最新ドキュメントを取得します。特に、次の基本ページを取得してください。
   • apps-sdk/build/mcp-server
   • apps-sdk/build/chatgpt-ui
   • apps-sdk/build/examples
   • apps-sdk/plan/tools
   • apps-sdk/reference
3. 新しいアプリをスキャフォールドする場合や、初回実装を生成する場合は、apps-sdk/quickstart を取得し、ゼロからスキャフォールドを作成する前に公式の例のリポジトリ／ページを確認してください。
4. タスクに ChatGPT でのローカルテスト、ホスティング、または一般公開が含まれる場合は、デプロイ／提出に関するドキュメントを取得してください。
   • apps-sdk/deploy
   • apps-sdk/deploy/submission
   • apps-sdk/app-submission-guidelines
5. 設計上の選択や生成したスキャフォールドについて説明する際は、使用したドキュメントの URL を記載してください。
6. 現在のドキュメントのガイダンスと古いリポジトリのパターンが異なる場合は、現在のドキュメントを優先し、互換性エイリアスを明示してください。
7. ドキュメント検索がタイムアウトするか、適切な結果が返らない場合は、Apps SDK の正規ページを URL から直接取得して続行してください。検索の失敗をスキャフォールド作成の妨げにしないでください。

$openai-docs を利用できない場合は、次を使用してください。

• mcp__openaiDeveloperDocs__search_openai_docs
• mcp__openaiDeveloperDocs__fetch_openai_doc

推奨されるドキュメント検索クエリと簡潔なチェックリストについては、references/apps-sdk-docs-workflow.md を読んでください。 例やスキャフォールドを選ぶ前に、依頼を少数の対応可能なアプリ形態に分類する方法については、references/app-archetypes.md を読んでください。 リポジトリの生成またはレビューにあたり、出力が安定した「動作するアプリ」の要件に収まるようにするには、references/repo-contract-and-validation.md を読んでください。 アプリがコネクター型、データ専用、同期指向である場合、または企業のナレッジやディープリサーチとの連携を想定している場合は、references/search-fetch-standard.md を読んでください。 新規アプリを作成する場合や、上流の例を応用するかローカルのフォールバック用スキャフォールドを使うかを判断する場合は、references/upstream-example-workflow.md を読んでください。 タスクで ChatGPT 固有のウィジェット動作が必要な場合、またはラッパー固有の app.* ヘルパーを使用するリポジトリの例を扱う場合は、references/window-openai-patterns.md を読んでください。

プロンプトの指針

生成されるひな形を最新のドキュメントに基づいたものにするため、このスキルと $openai-docs を明示的に組み合わせたプロンプトを使用してください。

推奨するプロンプトのパターン：

• Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <use case> with a <TS/Python> MCP server and <React/vanilla> widget.
• Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use case>.
• Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.
• Use $chatgpt-apps with $openai-docs to plan tools first, then generate the MCP server and widget code.

コードを作成する前に、次の入力を確認するか、推測してください。

• ユースケースと主なユーザーフロー
• 読み取り専用ツールか、変更を行うツールか
• デモ向けか、本番向けか
• 非公開／社内利用か、公開ディレクトリへの申請か
• バックエンドの言語と UI スタック
• 認証要件
• CSP 許可リストに含める外部 API のドメイン
• ホスティング先とローカル開発の方法
• 組織の所有権確認／検証の準備状況（申請タスクの場合）

コードを選ぶ前にアプリを分類する

例、リポジトリの構成、ひな形を選ぶ前に、依頼を主要なアーキタイプのいずれか 1 つに分類し、明示してください。

• tool-only
• vanilla-widget
• react-widget
• interactive-decoupled
• submission-ready

不足している情報が本当に妨げになる場合を除き、アーキタイプは推測してください。次の選択にアーキタイプを活用してください。

• UI が必要かどうか
• server/ + web/ の分割構成を維持するかどうか
• 公式の OpenAI の例、ext-apps の例、ローカルの代替ひな形のどれを優先するか
• 最も重要な検証項目
• search と fetch をデフォルトの読み取り専用ツールとして使うかどうか

判断基準については references/app-archetypes.md をお読みください。

デフォルトの出発点の優先順位

新規アプリの場合は、次の順に出発点を選んでください。

1. 公式の OpenAI の例：依頼されたスタックやインタラクションパターンに合う例がすでにある場合。
2. バージョンが一致する @modelcontextprotocol/ext-apps の例：より低レベル、または移植性の高い MCP Apps のベースが必要な場合。
3. scripts/scaffold_node_ext_apps.mjs：適切な例が見つからない場合、ユーザーが最小限の Node + vanilla のスターターを希望する場合、またはネットワークへのアクセスや例の取得が望ましくない場合に限ります。

上流に適切な例がすでにある場合は、大規模なカスタムひな形をゼロから生成しないでください。 最も小さく適合する例をコピーし、無関係なデモコードを削除してから、最新のドキュメントとユーザーの依頼に合わせて修正してください。

構築ワークフロー

0. アプリのアーキタイプを分類する

ツールを計画したり、出発点を選んだりする前に、主要なアーキタイプを 1 つ選んでください。

• 複数を混在させるのではなく、主要なアーキタイプを 1 つ選んでください。
• 依頼の範囲が広い場合は、要件を満たせる最小のアーキタイプを推測してください。
• ユーザーが公開リリース、ディレクトリへの申請、またはレビューに対応したデプロイを求めた場合に限り、submission-ready に引き上げてください。
• 必要に応じてユーザーが早い段階で修正できるよう、回答では選択したアーキタイプを明示してください。

1. コードを書く前にツールを計画する

ユーザーの意図に基づいて、ツールの範囲を定義します。

• 1つのツールにつき、1つの役割を持たせます。
• ツールの説明は、「Use this when...」という行動の目安から始めます。
• 入力は明示的で、機械が扱いやすい形式にします（列挙型、必須フィールド、範囲など）。
• 各ツールがデータ専用、レンダリング専用、またはその両方のいずれかを決定します。
• アノテーション（readOnlyHint、destructiveHint、openWorldHint）を正確に設定します（該当する場合はidempotentHintを追加します）。
• アプリがコネクターのような性質を持つ場合、データ専用の場合、同期を中心とする場合、または社内ナレッジや深い調査を目的とする場合は、独自の読み取り専用ツールを考案するのではなく、標準のsearchツールとfetchツールをデフォルトで使用します。
• 教育用／デモ用アプリでは、モデルが適切な例を選びやすいよう、ツール1つにつき概念を1つにすることを優先します。
• デモ用ツールは学習目標ごとにグループ化します。ウィジェットへのデータの受け渡し、ウィジェットの操作から会話やツールへの連携、ホスト／レイアウト環境のシグナル、ライフサイクル／ストリーミングの動作に分けます。

searchとfetchが関連する可能性がある場合は、references/search-fetch-standard.mdを読んでください。

2. アプリのアーキテクチャを選ぶ

目的に合った最もシンプルな構成を選びます。

• 迅速なプロトタイプ、ワークショップ、または概念実証には、最小限のデモパターンを使用します。
• ウィジェットがツール呼び出しのたびに再レンダリングされないよう、本番環境のUXにはデータ／レンダリング分離パターンを使用します。

複雑なアプリでは、データ／レンダリング分離パターンを優先します。

• データツールは、再利用可能なstructuredContentを返します。
• レンダリングツールには、_meta.ui.resourceUriと、任意の_meta["openai/outputTemplate"]を設定します。
• レンダリングツールの説明には、前提条件を記載します（例：「先にsearchを呼び出してください」）。

2a. 適切な上流のサンプルがある場合は、それをベースにする

新規開発では、依頼されたアプリに近い上流のサンプルをデフォルトで使用します。

• ChatGPT向けのアプリ、洗練されたUIパターン、Reactコンポーネント、ファイルアップロードのフロー、モーダルのフロー、またはドキュメントのサンプルに似たアプリでは、まずOpenAIの公式サンプルを確認します。
• 依頼内容が生のMCP Appsブリッジ／サーバーの接続に近い場合、またはChatGPT固有の洗練度よりもバージョンに合ったパッケージパターンが重要な場合は、@modelcontextprotocol/ext-appsのサンプルを使用します。
• 条件に合う最小のサンプルを選び、関連するファイルだけをコピーします。ショーケースアプリ全体をそのまま移植しないでください。
• コピー後、取得した最新のドキュメントに合わせて、サンプルの内容を調整します。ツール名／説明、アノテーション、_meta.ui.*、CSP、URIのバージョン管理、ローカルでの実行手順を確認してください。
• 選んだサンプルとその理由を、1文で伝えてください。

選定と適応の基準については、references/upstream-example-workflow.mdを読んでください。

2b. 依存関係の少ない代替手段が適切な場合は、スタータースクリプトを使用する

ユーザーが手早く新規のNodeスターターを求めていて、バニラHTMLのウィジェットで問題なく、上流のサンプルより適した出発点がない場合に限り、scripts/scaffold_node_ext_apps.mjsを使用します。

• まず最新のドキュメントを取得し、その後にスクリプトを実行してから、生成されたファイルを取得済みのドキュメントに合わせて調整します。
• 上流のサンプルではなくスクリプトを選んだ場合は、その依頼にこの代替手段がより適している理由を説明します。
• 条件に合う公式サンプルがある場合、ユーザーが既存のアプリ構成を持っている場合、Node以外のスタックが必要な場合、明示的にReactを優先している場合、またはコードではなく計画／レビューのみを求めている場合は、使用しないでください。
• このスクリプトは、最小限の@modelcontextprotocol/ext-appsサーバーと、デフォルトでMCP Appsブリッジを使用するバニラHTMLウィジェットを生成します。
• 生成されるウィジェットは、後続のメッセージ送信に標準のui/messageブリッジを使用し、任意のホストシグナル／拡張機能にのみwindow.openaiを使用します。
• 実行後は、生成された出力を最新のドキュメントとユーザーの依頼に合わせて修正します。ツール名／説明、アノテーション、リソースメタデータ、URIのバージョン管理、README／実行手順を調整してください。

3. MCP サーバーをスキャフォールドする

以下を行うサーバーを生成します。

• MCP Apps UI の MIME タイプ（text/html;profile=mcp-app）または、@modelcontextprotocol/ext-apps/server を使用する場合は SDK 定数（RESOURCE_MIME_TYPE）で、ウィジェットのリソース／テンプレートを登録します
• 明確な名前、スキーマ、タイトル、説明を付けてツールを登録します
• structuredContent（モデル＋ウィジェット）、content（モデルへの説明）、_meta（ウィジェット専用データ）を意図的に返します
• ハンドラーを冪等にするか、非冪等な動作を明示的に文書化します
• ChatGPT で有用な場合は、ツールのステータス文字列（openai/toolInvocation/*）を含めます

structuredContent は簡潔に保ちます。大きなデータや機密性の高いウィジェット専用ペイロードは _meta に移します。

4. ウィジェット UI をスキャフォールドする

まず MCP Apps ブリッジを使って移植性を確保し、そのうえで UX が実質的に向上する場合に ChatGPT 固有の window.openai API を追加します。

• ui/notifications/tool-result（postMessage を介した JSON-RPC）をリッスンします
• structuredContent から描画します
• コンポーネントから開始するツール呼び出しには tools/call を使用します
• UI の状態によってモデルが認識する内容を変える必要がある場合に限り、ui/update-model-context を使用します

新しいアプリでは、互換性や機能拡張（ファイルアップロード、モーダル、表示モードなど）のために window.openai を使用し、唯一の連携経路としては使用しないでください。

API サーフェスのガードレール

• ブリッジを app オブジェクト（例：@modelcontextprotocol/ext-apps/react）でラップし、app.sendMessage()、app.callServerTool()、app.openLink()、ホストの getter メソッドなどのヘルパー名を公開する例もあります。
• これらのラッパーは実装の詳細または利便性を高めるレイヤーとして扱い、標準の公開 API としてデフォルトで案内しないでください。
• ChatGPT 向けのガイダンスでは、現在ドキュメント化されているサーフェスを優先してください。具体的には window.openai.callTool(...)、window.openai.sendFollowUpMessage(...)、window.openai.openExternal(...)、window.openai.requestDisplayMode(...) と、window.openai.theme、window.openai.locale、window.openai.displayMode、window.openai.toolInput、window.openai.toolOutput、window.openai.toolResponseMetadata、window.openai.widgetState などの直接的なグローバルです。
• リポジトリの例にあるラッパーのヘルパーを参照する場合は、対応するドキュメント化済みの window.openai または MCP Apps ブリッジのプリミティブを示し、そのラッパーが規範的な API サーフェスではないことを明記してください。
• ラッパーから標準 API への対応付けと、React ヘルパーの抽出パターンについては、references/window-openai-patterns.md を使用してください。

5. リソースメタデータとセキュリティを追加する

ウィジェットのリソース／テンプレートに、意図を明確にしてリソースメタデータを設定します。

• 正確な connectDomains と resourceDomains を指定した _meta.ui.csp
• アプリの申請に対応したデプロイ用の _meta.ui.domain
• _meta.ui.prefersBorder（または必要に応じて OpenAI 互換エイリアス）
• 冗長な説明を減らすための任意の openai/widgetDescription

iframe の埋め込みが製品の中核機能でない限り、frameDomains は避けてください。

5a. 最小限の動作するリポジトリ要件を満たす

生成するすべてのリポジトリは、完了とみなす前に、簡潔で安定した要件を満たす必要があります。

• リポジトリの構成が、選択したアーキタイプに合致していること。
• MCP サーバーとツールが、到達可能な /mcp エンドポイントに接続されていること。
• ツールに明確な説明、正確なアノテーション、必要に応じた UI メタデータがあること。
• コネクター型、データ専用、同期指向、企業ナレッジ型のアプリでは、該当する場合に標準の search と fetch のツール形状を使用すること。
• UI がある場合、ウィジェットが MCP Apps ブリッジを正しく使用していること。
• ユーザーがローカルで実行して確認するのに十分なスクリプトまたはコマンドがリポジトリに含まれていること。
• 実行した検証と実行していない検証が、応答で明示されていること。

詳細なチェックリストと検証の段階については、references/repo-contract-and-validation.md を参照してください。

6. ローカルループを検証する

「ファイルが作成されたか」だけでなく、最小限の動作可能なリポジトリの要件に照らして検証します。

• 最初に、コストの低いチェックを実行します。
  • 静的な要件の確認
  • 可能であれば、構文チェックまたはコンパイルチェック
  • 可能であれば、ローカルの /mcp ヘルスチェック
• 次に、実行時のチェックに進みます。
  • MCP Inspector でツールの記述子とウィジェットのレンダリングを確認する
  • HTTPS トンネリングを通じて ChatGPT の開発者モードでアプリをテストする
  • 再試行とツール呼び出しの繰り返しを試し、冪等性を確認する
  • ホストのイベントや後続のツール呼び出し後にウィジェットが更新されることを確認する
• スキャフォールドのみを提供し、依存関係をインストールしない場合でも、コストの低いチェックは実行し、実行しなかった項目を正確に伝えます。

検証の段階については references/repo-contract-and-validation.md を参照してください。

7. ChatGPT に接続してテストする（開発者モード）

ローカル開発向けには、コードや実行コマンドだけでなく、ChatGPT の明示的なセットアップ手順を含めます。

• MCP サーバーをローカルで http://localhost:<port>/mcp に起動します
• パブリック HTTPS トンネル（例：ngrok http <port>）でローカルサーバーを公開します
• ChatGPT から接続する際は、トンネルの HTTPS URL に /mcp パスを付けて使用します
• ChatGPT で、設定 → アプリとコネクター → 詳細設定から開発者モードを有効にします
• ChatGPT のアプリ設定でリモート MCP サーバー用の新しいアプリを作成し、パブリック MCP URL を貼り付けます
• MCP のツールやメタデータを変更した場合は、ChatGPT が最新の記述子を再読み込みするよう、アプリを更新するようユーザーに伝えます

注：一部のドキュメントやスクリーンショットでは、以前の「コネクター」という用語が使われています。手順を説明する際は、現在の製品用語である「アプリ」を優先しつつ、両方の呼び方があることにも触れてください。

8. 本番環境のホスティングとデプロイを計画する

ユーザーがデプロイまたは公開準備を求めた場合は、MCP サーバー（および別途ホストする場合はウィジェットのアセット）のホスティングに関するガイダンスを作成します。

• 安定したパブリック HTTPS エンドポイント（トンネルではない）を使用し、信頼性の高い TLS を確保します
• /mcp で低遅延のストリーミング動作を維持します
• シークレットはリポジトリの外（環境変数／シークレットマネージャー）で設定します
• ツール呼び出しのログ、リクエストレイテンシの追跡、エラーの可視化を追加します
• 基本的な可観測性（CPU、メモリ、リクエスト量）とトラブルシューティング手順を用意します
• 提出前に、ホストされたエンドポイントを ChatGPT の開発者モードで再テストします

9. 提出の準備と公開（パブリックアプリのみ）

ユーザーがパブリックディレクトリへの掲載を意図している場合にのみ、これらの手順を含めます。

• 提出の手順には apps-sdk/deploy/submission を、審査要件には apps-sdk/app-submission-guidelines を使用します
• 非公開／内部向けアプリは提出せず、開発者モードのままにします
• 提出作業を始める前に、組織の認証と Owner ロールの前提条件を確認します
• MCP サーバーがパブリックな本番エンドポイント（localhost／テスト用 URL ではない）を使用し、提出要件を満たす CSP が設定されていることを確認します
• 提出用の素材を準備します：アプリのメタデータ、ロゴ／スクリーンショット、プライバシーポリシー URL、サポート連絡先、テスト用プロンプト／応答、ローカライズ情報
• 認証が必要な場合は、審査で使用できるデモ用認証情報を用意し、ログイン手順を最初から最後までテストします
• Platform ダッシュボードで審査に提出し、審査状況を確認して、承認後にのみ公開します

インタラクティブな状態に関するガイダンス

アプリに長期間保持されるウィジェットの状態、インタラクションの繰り返し、またはコンポーネント起点のツール呼び出し（例：ゲーム、ボード、マップ、ダッシュボード、エディター）がある場合は、references/interactive-state-sync-patterns.md を参照してください。

次のパターンを選ぶ際に活用します。

• 状態スナップショットと単調増加するイベントトークン（stateVersion、resetCount など）
• 冪等で再試行に安全なハンドラー
• structuredContent と _meta の使い分け
• MCP Apps のブリッジを優先する更新フローと、任意の window.openai 互換性
• より複雑なインタラクティブアプリ向けの、データツールとレンダリングツールを分離したアーキテクチャ

出力の要件

このスキルを使ってコードをスキャフォールドする場合、ユーザーから別途指示がない限り、次の順序で出力してください。

• 直接スキャフォールドを依頼された場合、計画だけで終わらせないでください。簡潔な計画を提示したら、すぐにファイルを作成してください。

1. 選択した主要なアプリのアーキタイプとその理由
2. ツールの計画とアーキテクチャの選択（最小構成か、疎結合か）
3. 選択した上流の出発点（公式サンプル、ext-apps のサンプル、またはローカルのフォールバックスキャフォールド）とその理由
4. $openai-docs から使用したドキュメントのページ／URL
5. 作成または変更するファイルツリー
6. 実装（サーバー＋ウィジェット）
7. 最小限の動作するリポジトリ要件に対して実施した検証
8. ローカルでの実行／テスト手順（トンネルと ChatGPT Developer Mode アプリの設定を含む）
9. デプロイ／ホスティングのガイダンス（依頼された場合、または暗黙に求められている場合）
10. 提出準備チェックリスト（一般公開の依頼の場合）
11. リスク、未対応事項、今後の改善点

参考資料

• リクエストを少数の対応アプリ形状に分類するための references/app-archetypes.md
• ドキュメントの検索、対象ページ、コード生成チェックリストについての references/apps-sdk-docs-workflow.md
• 状態を持つウィジェットアプリや高度にインタラクティブなウィジェットアプリ向けの再利用可能なパターンについての references/interactive-state-sync-patterns.md
• 最小限の動作するリポジトリ要件と軽量な検証手順についての references/repo-contract-and-validation.md
• 標準の search ツールと fetch ツールをいつ、どのように既定で使用するかについての references/search-fetch-standard.md
• 公式サンプル、ext-apps のサンプル、ローカルのフォールバックスキャフォールドから選択する方法についての references/upstream-example-workflow.md
• ChatGPT 固有の拡張機能、ラッパー API の変換、React ヘルパーパターンについての references/window-openai-patterns.md
• 最小構成の Node + @modelcontextprotocol/ext-apps フォールバック用スタータースキャフォールドである scripts/scaffold_node_ext_apps.mjs