Applications ChatGPT

Aperçu

Échaffaudez les implémentations du SDK Applications ChatGPT avec un flux de travail axé sur la documentation en premier, les exemples en premier, puis générez du code qui suit les motifs actuels du SDK Applications et du pont Applications MCP.

Utilisez cette compétence pour produire :

Une classification d'archétype d'application primaire et une décision de forme de dépôt
Un plan d'outils (noms, schémas, annotations, résultats)
Une recommandation de point de départ en amont (exemple officiel, exemple d'ext-apps, ou scaffold de secours local)
Un scaffold de serveur MCP (enregistrement de ressources, gestionnaires d'outils, métadonnées)
Un scaffold de widget (pont Applications MCP en premier, compatibilité/extensions window.openai en second)
Un scaffold de démarrage Node + @modelcontextprotocol/ext-apps réutilisable pour les secours sans dépendances
Un rapport de validation par rapport au contrat de dépôt minimum fonctionnant
Des étapes de configuration du développement local et du connecteur
Un bref résumé des parties prenantes sur ce que fait l'application (si demandé)

Flux de travail obligatoire axé sur la documentation en premier

Utilisez $openai-docs d'abord chaque fois que vous créez ou modifiez une application du SDK Applications ChatGPT.

Invoquez $openai-docs (préféré) ou appelez directement le serveur MCP de documentation OpenAI.
Récupérez la documentation actuelle du SDK Applications avant d'écrire du code, en particulier les pages de base :
- apps-sdk/build/mcp-server
- apps-sdk/build/chatgpt-ui
- apps-sdk/build/examples
- apps-sdk/plan/tools
- apps-sdk/reference
Récupérez apps-sdk/quickstart lors de l'échafaudage d'une nouvelle application ou de la génération d'une implémentation de première passe, et vérifiez le dépôt/la page des exemples officiels avant d'inventer un scaffold à partir de zéro.
Récupérez la documentation de déploiement/soumission quand la tâche inclut le test local ChatGPT, l'hébergement ou le lancement public :
- apps-sdk/deploy
- apps-sdk/deploy/submission
- apps-sdk/app-submission-guidelines
Citez les URL de documentation que vous avez utilisées quand vous expliquez les choix de conception ou les scaffolds générés.
Préférez les conseils de documentation actuels aux modèles de dépôt plus anciens quand ils diffèrent, et appelez les alias de compatibilité explicitement.
Si la recherche de documents expire ou retourne des correspondances faibles, récupérez les pages du SDK Applications canoniques directement par URL et continuez ; ne laissez pas l'échec de la recherche bloquer l'échafaudage.

Si $openai-docs n'est pas disponible, utilisez :

mcp__openaiDeveloperDocs__search_openai_docs
mcp__openaiDeveloperDocs__fetch_openai_doc

Lisez references/apps-sdk-docs-workflow.md pour les requêtes de documents suggérées et une liste de contrôle compacte. Lisez references/app-archetypes.md pour classifier la demande en un petit nombre de formes d'applications supportées avant de choisir des exemples ou des scaffolds. Lisez references/repo-contract-and-validation.md lors de la génération ou de l'examen d'un dépôt afin que la sortie reste dans un contrat « d'application fonctionnelle » stable. Lisez references/search-fetch-standard.md quand l'application est de type connecteur, données seulement, orientée synchronisation, ou destinée à fonctionner bien avec les connaissances de l'entreprise ou la recherche approfondie. Lisez references/upstream-example-workflow.md quand vous démarrez une application vierge ou quand vous décidez d'adapter un exemple en amont ou d'utiliser le scaffold de secours local. Lisez references/window-openai-patterns.md quand la tâche a besoin d'un comportement de widget spécifique à ChatGPT ou quand vous traduisez des exemples de dépôt qui utilisent des aides app.* spécifiques au wrapper.

Conseils d'invite

Utilisez des invites qui associent explicitement cette compétence à $openai-docs afin que le scaffold résultant soit fondé sur la documentation actuelle.

Modèles d'invite préférés :

Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <cas d'usage> 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 <cas d'usage>.
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.

Quand vous répondez, demandez ou déduisez ces entrées avant de coder :

Cas d'usage et flux d'utilisateur primaires
Outils en lecture seule par rapport aux outils qui mutent
Cible de démonstration par rapport à cible de production
Utilisation privée/interne par rapport à soumission d'annuaire public
Langage backend et pile UI
Exigences d'authentification
Domaines API externes pour les listes blanches CSP
Cible d'hébergement et approche de développement local
Propriété organisationnelle/disponibilité de vérification (pour les tâches de soumission)

Classifiez l'application avant de choisir le code

Avant de choisir des exemples, une forme de dépôt ou des scaffolds, classifiez la demande en un archétype primaire et énoncez-le.

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

Déduisez l'archétype sauf si un détail manquant bloque vraiment. Utilisez l'archétype pour choisir :

si une UI est nécessaire du tout
si vous devez préserver une mise en page divisée server/ + web/
si vous devez préférer les exemples officiels OpenAI, les exemples ext-apps, ou le scaffold de secours local
quels contrôles de validation importent le plus
si search et fetch doivent être la surface d'outil par défaut en lecture seule

Lisez references/app-archetypes.md pour la rubrique de décision.

Ordre du point de départ par défaut

Pour les applications vierges, préférez ces points de départ dans l'ordre :

Exemples officiels OpenAI quand un exemple proche correspond déjà à la pile demandée ou au motif d'interaction.
Exemples @modelcontextprotocol/ext-apps appairés à la version quand l'utilisateur a besoin d'une base MCP Applications plus bas niveau ou plus portable.
scripts/scaffold_node_ext_apps.mjs uniquement quand aucun exemple proche ne convient, l'utilisateur veut un petit démarrage Node + vanilla, ou l'accès réseau/la récupération d'exemple n'est pas souhaitable.

Ne générez pas un grand scaffold personnalisé à partir de zéro si un exemple en amont proche existe déjà. Copiez le plus petit exemple correspondant, supprimez le code de démonstration non lié, puis corrigez-le pour la documentation actuelle et la demande de l'utilisateur.

Flux de travail de construction

0. Classifiez l'archétype de l'application

Choisissez un archétype primaire avant de planifier les outils ou de choisir un point de départ.

Préférez un seul archétype primaire au lieu de mélanger plusieurs.
Si la demande est large, déduisez le plus petit archétype qui peut encore la satisfaire.
Escaladez vers submission-ready uniquement quand l'utilisateur demande un lancement public, une soumission d'annuaire ou un déploiement prêt à l'examen.
Appelez l'archétype choisi dans votre réponse afin que l'utilisateur puisse le corriger tôt si nécessaire.

1. Planifiez les outils avant le code

Définissez la zone de surface de l'outil à partir des intentions de l'utilisateur.

Utilisez un emploi par outil.
Écrivez des descriptions d'outils qui commencent par des indices de comportement « Utilisez ceci quand... ».
Rendez les entrées explicites et conviviales pour les machines (énumérations, champs obligatoires, limites).
Décidez si chaque outil est données seulement, rendu seulement, ou les deux.
Définissez les annotations avec précision (readOnlyHint, destructiveHint, openWorldHint ; ajoutez idempotentHint quand c'est vrai).
Si l'application est de type connecteur, données seulement, orientée synchronisation, ou destinée à la connaissance de l'entreprise ou à la recherche approfondie, utilisez par défaut les formes d'outils search et fetch standard au lieu d'inventer des équivalents en lecture seule personnalisés.
Pour les applications éducatives/démo, préférez un concept par outil afin que le modèle puisse choisir le bon exemple proprement.
Regroupez les outils de démonstration par objectif d'apprentissage : données dans le widget, actions de widget dans la conversation ou outils, signaux d'environnement hôte/mise en page, et comportement de cycle de vie/streaming.

Lisez references/search-fetch-standard.md quand search et fetch peuvent être pertinents.

2. Choisissez une architecture d'application

Choisissez la structure la plus simple qui correspond à l'objectif.

Utilisez un motif de démonstration minimal pour les prototypes rapides, ateliers ou preuves de concept.
Utilisez un motif de données/rendu découplé pour l'UX de production afin que le widget ne se re-rend pas à chaque appel d'outil.

Préférez le motif découplé pour les applications non triviales :

Les outils de données retournent structuredContent réutilisable.
Les outils de rendu attachent _meta.ui.resourceUri et _meta["openai/outputTemplate"] optionnel.
Les descriptions des outils de rendu indiquent les prérequis (par exemple, « Appelez d'abord search »).

2a. Commencez par un exemple en amont quand l'un convient

Préférez les exemples en amont pour le travail vierge quand ils sont proches de l'application demandée.

Vérifiez d'abord les exemples officiels OpenAI pour les applications tournées vers ChatGPT, les motifs d'UI polis, les composants React, les flux de téléchargement de fichiers, les flux modaux, ou les applications qui ressemblent aux exemples de documentation.
Utilisez les exemples @modelcontextprotocol/ext-apps quand la demande est plus proche du câblage du pont/serveur des Applications MCP brutes, ou quand les motifs de paquets appairés à la version importent plus que le brillant spécifique à ChatGPT.
Choisissez le plus petit exemple correspondant et copiez uniquement les fichiers pertinents ; ne transplantez pas une application de showcase entière inchangée.
Après la copie, réconciliez l'exemple avec la documentation actuelle que vous avez récupérée : noms/descriptions d'outils, annotations, _meta.ui.*, CSP, versioning URI, et instructions d'exécution locale.
Indiquez quel exemple vous avez choisi et pourquoi en une phrase.

Lisez references/upstream-example-workflow.md pour la rubrique de sélection et d'adaptation.

2b. Utilisez le script de démarrage quand un secours sans dépendance aide

Utilisez scripts/scaffold_node_ext_apps.mjs uniquement quand l'utilisateur veut un démarreur Node rapide et vierge et qu'un widget HTML vanilla est acceptable, et qu'aucun exemple en amont n'est un meilleur point de départ.

Exécutez-le uniquement après avoir récupéré la documentation actuelle, puis réconciliez les fichiers générés avec la documentation que vous avez récupérée.
Si vous choisissez le script au lieu d'un exemple en amont, dites pourquoi le secours est meilleur pour cette demande.
Ignorez-le quand un exemple officiel proche existe, quand l'utilisateur a déjà une structure d'application existante, quand il a besoin d'une pile non-Node, quand il demande explicitement React en premier, ou quand il veut seulement un plan/examen au lieu du code.
Le script génère un serveur minimal @modelcontextprotocol/ext-apps plus un widget HTML vanilla qui utilise le pont Applications MCP par défaut.
Le widget généré garde la messagerie de suivi sur le pont ui/message standard et n'utilise window.openai que pour les signaux/extensions d'hôte optionnels.
Après l'avoir exécuté, corrigez la sortie générée pour correspondre à la documentation actuelle et à la demande de l'utilisateur : ajustez les noms/descriptions d'outils, les annotations, les métadonnées de ressource, le versioning URI, et les instructions README/exécution.

3. Échaffaudez le serveur MCP

Générez un serveur qui :

Enregistre une ressource/template de widget avec le type MIME UI Applications MCP (text/html;profile=mcp-app) ou la constante SDK (RESOURCE_MIME_TYPE) quand vous utilisez @modelcontextprotocol/ext-apps/server
Enregistre les outils avec des noms, schémas, titres et descriptions clairs
Retourne structuredContent (modèle + widget), content (narration du modèle), et _meta (données de widget seulement) intentionnellement
Garde les gestionnaires idempotents ou documente explicitement le comportement non-idempotent
Inclut les chaînes de statut d'outil (openai/toolInvocation/*) quand utile dans ChatGPT

Gardez structuredContent concis. Déplacez les grandes ou sensibles charges utiles widget seulement vers _meta.

4. Échaffaudez l'UI du widget

Utilisez le pont Applications MCP d'abord pour la portabilité, puis ajoutez les APIs window.openai spécifiques à ChatGPT quand elles améliorent matériellement l'UX.

Écoutez ui/notifications/tool-result (JSON-RPC sur postMessage)
Rendez à partir de structuredContent
Utilisez tools/call pour les appels d'outil initiés par le composant
Utilisez ui/update-model-context uniquement quand l'état UI doit changer ce que le modèle voit

Utilisez window.openai pour la compatibilité et les extensions (téléchargement de fichier, modal, mode d'affichage, etc.), pas comme le seul chemin d'intégration pour les nouvelles applications.

Garde-fous de surface API

Certains exemples enveloppent le pont avec un objet app (par exemple, @modelcontextprotocol/ext-apps/react) et exposent des noms d'aides comme app.sendMessage(), app.callServerTool(), app.openLink(), ou les méthodes getter d'hôte.
Traitez ces wrappers comme des détails d'implémentation ou des couches de commodité, pas comme l'API publique canonique à enseigner par défaut.
Pour les conseils tournés vers ChatGPT, préférez la surface documentée actuelle : window.openai.callTool(...), window.openai.sendFollowUpMessage(...), window.openai.openExternal(...), window.openai.requestDisplayMode(...), et les globals directs comme window.openai.theme, window.openai.locale, window.openai.displayMode, window.openai.toolInput, window.openai.toolOutput, window.openai.toolResponseMetadata, et window.openai.widgetState.
Si vous référencez les aides du wrapper à partir des exemples de dépôt, mapez-les de retour aux primitives window.openai documentées ou au pont Applications MCP et appelez que le wrapper n'est pas la surface API normative.
Utilisez references/window-openai-patterns.md pour le mappage wrapper-to-canonique et pour les motifs d'extraction d'aides React.

5. Ajoutez les métadonnées de ressource et la sécurité

Définissez intentionnellement les métadonnées de ressource sur la ressource/template de widget :

_meta.ui.csp avec connectDomains et resourceDomains exacts
_meta.ui.domain pour les déploiements prêts à la soumission d'application
_meta.ui.prefersBorder (ou alias de compatibilité OpenAI quand nécessaire)
openai/widgetDescription optionnel pour réduire la narration redondante

Évitez frameDomains sauf si les intégrations iframe sont essentielles au produit.

5a. Appliquez un contrat de dépôt minimum fonctionnant

Chaque dépôt généré doit satisfaire un petit contrat stable avant que vous le considériez comme terminé.

La forme du dépôt correspond à l'archétype choisi.
Le serveur MCP et les outils sont câblés à un point d'arrivée /mcp accessible.
Les outils ont des descriptions claires, des annotations précises, et des métadonnées UI où nécessaire.
Les applications de type connecteur, données seulement, orientées synchronisation, et de style connaissances de l'entreprise utilisent les formes d'outils search et fetch standard quand pertinent.
Le widget utilise correctement le pont Applications MCP quand une UI existe.
Le dépôt inclut suffisamment de scripts ou de commandes pour qu'un utilisateur puisse l'exécuter et le vérifier localement.
La réponse dit explicitement quels validations ont été exécutées et lesquelles ne l'ont pas été.

Lisez references/repo-contract-and-validation.md pour la liste de contrôle détaillée et l'échelle de validation.

6. Validez la boucle locale

Validez par rapport au contrat de dépôt minimum fonctionnant, pas seulement « les fichiers ont-ils été créés ».

Exécutez d'abord les contrôles à faible coût :
- examen du contrat statique
- vérifications de syntaxe ou de compilation quand possible
- vérification de santé /mcp local quand possible
Passez ensuite aux vérifications d'exécution :
- vérifiez les descripteurs d'outil et le rendu du widget dans l'inspecteur MCP
- testez l'application en mode développeur ChatGPT via tunneling HTTPS
- exercez les retries et les appels d'outil répétés pour confirmer le comportement idempotent
- vérifiez les mises à jour du widget après les événements d'hôte et les appels d'outil de suivi
Si vous livrez uniquement un scaffold et n'installez pas les dépendances, exécutez toujours des contrôles à faible coût et dites exactement ce que vous n'avez pas exécuté.

Lisez references/repo-contract-and-validation.md pour l'échelle de validation.

7. Connectez et testez dans ChatGPT (mode développeur)

Pour le développement local, incluez des étapes explicites de configuration ChatGPT (pas seulement des commandes de code/exécution).

Exécutez le serveur MCP localement sur http://localhost:<port>/mcp
Exposez le serveur local avec un tunnel HTTPS public (par exemple ngrok http <port>)
Utilisez l'URL du tunnel HTTPS plus le chemin /mcp lors de la connexion depuis ChatGPT
Dans ChatGPT, activez le mode développeur sous Paramètres → Applications et connecteurs → Paramètres avancés
Dans les paramètres de l'application ChatGPT, créez une nouvelle application pour le serveur MCP distant et collez l'URL MCP public
Dites aux utilisateurs de rafraîchir l'application après les modifications des outils/métadonnées MCP afin que ChatGPT recharge les derniers descripteurs

Remarque : Certains documents/captures d'écran utilisent toujours l'ancienne terminologie « connecteur ». Préférez le libellé du produit actuel (« application ») tout en reconnaissant les deux étiquettes quand vous donnez des instructions pas à pas.

8. Planifiez l'hébergement de production et le déploiement

Quand l'utilisateur demande de déployer ou de préparer le lancement, générez des conseils d'hébergement pour le serveur MCP (et les ressources de widget si hébergées séparément).

Hébergez derrière un point d'arrivée HTTPS public stable (pas un tunnel) avec TLS fiable
Préservez le comportement de streaming à faible latence sur /mcp
Configurez les secrets en dehors du dépôt (variables d'environnement / gestionnaire de secrets)
Ajoutez la journalisation, le suivi de la latence des requêtes, et la visibilité des erreurs pour les appels d'outils
Ajoutez l'observabilité basique (CPU, mémoire, volume de requêtes) et un chemin de dépannage
Re-testez le point d'arrivée hébergé en mode développeur ChatGPT avant la soumission

9. Préparez la soumission et publiez (applications publiques uniquement)

Incluez ces étapes uniquement quand l'utilisateur a l'intention un annuaire public.

Utilisez apps-sdk/deploy/submission pour le flux de soumission et apps-sdk/app-submission-guidelines pour les exigences d'examen
Gardez les applications privées/internes en mode développeur au lieu de soumettre
Confirmez la vérification de l'organisation et les prérequis du rôle propriétaire avant les travaux de soumission
Assurez-vous que le serveur MCP utilise un point d'arrivée public de production (pas d'URL localhost/test) et a la CSP prête à la soumission configurée
Préparez les artefacts de soumission : métadonnées d'application, logo/captures d'écran, URL de politique de confidentialité, contact de support, invites/réponses de test, infos de localisation
Si l'authentification est requise, incluez les identifiants de démonstration sûrs pour examen et testez le chemin de connexion de bout en bout
Soumettez pour examen dans le tableau de bord de plateforme, surveillez le statut d'examen, et publiez uniquement après approbation

Conseils d'état interactif

Lisez references/interactive-state-sync-patterns.md quand l'application a un état de widget de longue durée, des interactions répétées, ou des appels d'outil initiés par les composants (par exemple, jeux, tableaux, cartes, tableaux de bord, éditeurs).

Utilisez-le pour choisir des motifs pour :

Instantanés d'état plus tokens d'événement monotoniques (stateVersion, resetCount, etc.)
Gestionnaires idempotents et sûrs pour retry
Partitionnement structuredContent vs _meta
Flux de mise à jour du pont Applications MCP-first avec compatibilité window.openai optionnelle
Architecture d'outil données/rendu découplée pour les applications interactives plus complexes

Attentes de résultat

Quand vous utilisez cette compétence pour échafauder du code, produisez une sortie dans cet ordre sauf si l'utilisateur demande autrement :

Pour les demandes d'échafaudage direct, ne vous arrêtez pas au plan : donnez le bref plan, puis créez les fichiers immédiatement.

Archétype d'application primaire choisi et pourquoi
Plan d'outils et choix d'architecture (minimal vs découplé)
Point de départ en amont choisi (exemple officiel, exemple ext-apps, ou scaffold de secours local) et pourquoi
Pages/URLs de documentation utilisées de $openai-docs
Arborescence de fichiers à créer ou modifier
Implémentation (serveur + widget)
Validation effectuée par rapport au contrat de dépôt minimum fonctionnant
Instructions de test/exécution local (incluant tunnel + configuration d'application ChatGPT en mode développeur)
Conseils de déploiement/hébergement (si demandé ou implicite)
Liste de contrôle de disponibilité pour soumission (pour les demandes de lancement public)
Risques, lacunes, et améliorations de suivi

Références

references/app-archetypes.md pour classifier les demandes en un petit nombre de formes d'application supportées
references/apps-sdk-docs-workflow.md pour les requêtes de documentation, les cibles de pages, et la liste de contrôle de génération de code
references/interactive-state-sync-patterns.md pour les motifs réutilisables pour les applications de widget avec état ou hautement interactives
references/repo-contract-and-validation.md pour le contrat de dépôt minimum fonctionnant et l'échelle de validation légère
references/search-fetch-standard.md pour quand et comment utiliser par défaut les outils search et fetch standard
references/upstream-example-workflow.md pour choisir entre les exemples officiels, les exemples ext-apps, et le scaffold de secours local
references/window-openai-patterns.md pour les extensions spécifiques à ChatGPT, la traduction d'API wrapper, et les motifs d'aides React
scripts/scaffold_node_ext_apps.mjs pour un démarreur de secours minimal Node + @modelcontextprotocol/ext-apps