Applications ChatGPT

Aperçu

Générez des implémentations du SDK Applications ChatGPT en utilisant un workflow orienté documentation d'abord, exemples d'abord, puis générez du code qui suit les patterns actuels du SDK Applications et du pont MCP Applications.

Utilisez cette skill pour produire :

Une classification d'archétype d'app principal et une décision de forme de repo
Un plan d'outils (noms, schémas, annotations, outputs)
Une recommandation de point de départ en amont (exemple officiel, exemple ext-apps, ou scaffold de fallback local)
Un scaffold de serveur MCP (enregistrement de ressources, handlers d'outils, métadonnées)
Un scaffold de widget (pont MCP Apps d'abord, compatibilité window.openai et extensions en second)
Un scaffold de démarrage réutilisable Node + @modelcontextprotocol/ext-apps pour les fallbacks à faibles dépendances
Un rapport de validation contre le contrat de repo minimal fonctionnel
Des étapes de configuration de dev local et de connecteur
Un résumé court pour les parties prenantes de ce que l'app fait (si demandé)

Workflow Obligatoire Documentation D'abord

Utilisez $openai-docs d'abord chaque fois que vous construisez ou modifiez une app du SDK Applications ChatGPT.

Appelez $openai-docs (préféré) ou appelez directement le serveur MCP des docs OpenAI.
Récupérez les docs actuelles du SDK Applications avant d'écrire du code, en particulier (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 du scaffolding d'une nouvelle app ou de la génération d'une implémentation de première passe, et vérifiez le repo d'exemples officiel/page avant d'inventer un scaffold de zéro.
Récupérez les docs de déploiement/soumission lorsque la tâche inclut les tests local ChatGPT, l'hébergement ou le lancement public :
- apps-sdk/deploy
- apps-sdk/deploy/submission
- apps-sdk/app-submission-guidelines
Citez les URLs des docs que vous avez utilisées lorsque vous expliquez les choix de conception ou les scaffolds générés.
Préférez les conseils de docs actuels aux patterns de repo plus anciens lorsqu'ils diffèrent, et appelez les alias de compatibilité explicitement.
Si la recherche de doc expire ou retourne de mauvaises correspondances, récupérez les pages canoniques du SDK Applications directement par URL et continuez ; ne laissez pas l'échec de la recherche bloquer le scaffolding.

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 doc suggérées et une checklist compacte. Lisez references/app-archetypes.md pour classifier la demande dans un petit nombre de formes d'app supportées avant de choisir des exemples ou des scaffolds. Lisez references/repo-contract-and-validation.md lors de la génération ou révision d'un repo afin que la sortie reste à l'intérieur d'un contrat "app fonctionnelle" stable. Lisez references/search-fetch-standard.md lorsque l'app est de type connecteur, données uniquement, orientée sync, ou destinée à bien fonctionner avec la connaissance d'entreprise ou la recherche approfondie. Lisez references/upstream-example-workflow.md lors du démarrage d'une app greenfield ou lorsque vous décidez d'adapter un exemple en amont ou d'utiliser le scaffold de fallback local. Lisez references/window-openai-patterns.md lorsque la tâche a besoin d'un comportement de widget spécifique à ChatGPT ou lors de la traduction de repo examples utilisant des helpers app.* spécifiques à wrapper.

Orientation des Prompts

Utilisez des prompts qui appairent explicitement cette skill avec $openai-docs afin que le scaffold résultant soit ancré dans la docs actuelle.

Patterns de prompts préférés :

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.

Lors de la réponse, demandez ou déduisez ces entrées avant de coder :

Cas d'usage et flux utilisateur principaux
Outils lecture seule vs mutants
Cible démo vs production
Utilisation privée/interne vs soumission d'annuaire public
Langage backend et stack UI
Exigences d'authentification
Domaines d'API externes pour les listes de allowlist CSP
Cible d'hébergement et approche de dev local
Propriété de l'organisation/préparation à la vérification (pour les tâches de soumission)

Classifier L'App Avant De Choisir Du Code

Avant de choisir des exemples, une forme de repo ou des scaffolds, classifiez la demande dans un archétype principal et énoncez-le.

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

Déduisez l'archétype sauf si un détail manquant est véritablement bloquant. Utilisez l'archétype pour choisir :

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

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

Ordre de Point de Départ Par Défaut

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

Exemples OpenAI officiels lorsqu'un exemple proche correspond déjà à la stack demandée ou au pattern d'interaction.
Exemples @modelcontextprotocol/ext-apps version-matched lorsque l'utilisateur a besoin d'une baseline MCP Apps plus bas niveau ou plus portable.
scripts/scaffold_node_ext_apps.mjs uniquement lorsqu'aucun exemple proche ne correspond, que l'utilisateur veut un tiny démarrage Node + vanilla, ou que l'accès réseau/la récupération d'exemples est indésirable.

Ne générez pas un grand scaffold personnalisé de zéro si un exemple en amont proche existe déjà. Copiez le plus petit exemple correspondant, supprimez le code démo non lié, puis patchez-le aux docs actuels et à la demande utilisateur.

Workflow De Construction

0. Classifier L'Archétype De L'App

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

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

1. Planifier Les Outils Avant Le Code

Définissez la surface d'outil à partir des intentions utilisateur.

Utilisez un job par outil.
Écrivez des descriptions d'outils qui commencent par des signaux de comportement "Use this when...".
Rendez les entrées explicites et machine-friendly (enums, champs obligatoires, limites).
Décidez si chaque outil est données uniquement, rendu uniquement, ou les deux.
Définissez les annotations avec précision (readOnlyHint, destructiveHint, openWorldHint ; ajoutez idempotentHint quand c'est vrai).
Si l'app est de type connecteur, données uniquement, sync-orientée, ou destinée à la connaissance d'entreprise ou recherche approfondie, privilégiez les formes standard search et fetch au lieu d'inventer des équivalents lecture seule personnalisés.
Pour les apps éducationnelles/démo, préférez un concept par outil afin que le modèle puisse choisir le bon exemple clairement.
Groupez les outils démo par objectif d'apprentissage : données dans le widget, actions widget de retour dans la conversation ou les outils, signaux d'environnement host/layout, et comportement de lifecycle/streaming.

Lisez references/search-fetch-standard.md lorsque search et fetch peuvent être pertinentes.

2. Choisir Une Architecture D'App

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

Utilisez un pattern démo minimal pour les prototypes rapides, ateliers, ou preuves de concept.
Utilisez un pattern données/rendu découplé pour la UX production afin que le widget ne se rerend pas à chaque appel d'outil.

Préférez le pattern découplé pour les apps non triviales :

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

2a. Démarrer À Partir D'Un Exemple En Amont Lorsqu'il Correspond

Privilegiez les exemples en amont pour le travail greenfield lorsqu'ils sont proches de l'app demandée.

Vérifiez d'abord les exemples officiels OpenAI pour les apps facing ChatGPT, les patterns UI polis, les composants React, les flux de téléchargement de fichiers, les flux modaux, ou les apps ressemblant aux exemples de docs.
Utilisez les exemples @modelcontextprotocol/ext-apps lorsque la demande est plus proche du raw wiring MCP Apps bridge/server, ou lorsque les patterns de packages version-matched importent plus que le polish spécifique à ChatGPT.
Choisissez le plus petit exemple correspondant et copiez uniquement les fichiers pertinents ; ne transplantez pas une app showcase entière inchangée.
Après avoir copié, réconciliez l'exemple avec les docs actuels que vous avez récupérés : noms/descriptions d'outils, annotations, _meta.ui.*, CSP, versioning URI, et instructions de run local.
Énoncez quel exemple vous avez choisi et pourquoi en une phrase.

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

2b. Utiliser Le Script De Démarrage Lorsqu'Un Fallback À Faible Dépendance Aide

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

Exécutez-le uniquement après avoir récupéré les docs actuels, puis réconciliez les fichiers générés avec les docs que vous avez récupérés.
Si vous choisissez le script au lieu d'un exemple en amont, dites pourquoi le fallback est meilleur pour cette demande.
Passez-le lorsqu'un exemple officiel proche existe, lorsque l'utilisateur a déjà une structure d'app existante, lorsqu'ils ont besoin d'une stack non-Node, lorsqu'ils veulent explicitement React d'abord, ou lorsqu'ils ne veulent qu'un plan/révision au lieu de code.
Le script génère un serveur minimal @modelcontextprotocol/ext-apps plus un widget HTML vanilla qui utilise le pont MCP Apps par défaut.
Le widget généré maintient la messagerie de suivi sur le pont ui/message standard et utilise seulement window.openai pour les signaux host optionnels/extensions.
Après l'avoir exécuté, patchez la sortie générée pour correspondre aux docs actuels et à la demande utilisateur : ajustez les noms/descriptions d'outils, les annotations, les métadonnées de ressource, le versioning URI, et les instructions README/run.

3. Scaffolder Le Serveur MCP

Générez un serveur qui :

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

Gardez structuredContent concis. Déplacez les payloads larges ou sensibles widget uniquement vers _meta.

4. Scaffolder La UI Du Widget

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

Écoutez ui/notifications/tool-result (JSON-RPC sur postMessage)
Rendez à partir de structuredContent
Utilisez tools/call pour les appels d'outils initiés par composant
Utilisez ui/update-model-context uniquement lorsque 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 seul chemin d'intégration pour les nouvelles apps.

Garde-fous De Surface API

Certains exemples enveloppent le pont avec un objet app (par exemple, @modelcontextprotocol/ext-apps/react) et exposent les noms helpers comme app.sendMessage(), app.callServerTool(), app.openLink(), ou les méthodes host getter.
Traitez ces wrappers comme détails d'implémentation ou couches de commodité, pas comme l'API publique canonique à enseigner par défaut.
Pour les conseils facing ChatGPT, préférez la surface documentée actuelle : window.openai.callTool(...), window.openai.sendFollowUpMessage(...), window.openai.openExternal(...), window.openai.requestDisplayMode(...), et les globales 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 helpers wrapper à partir d'exemples de repo, mappez-les vers les primitives documentées window.openai ou MCP Apps bridge et appelez que le wrapper n'est pas la surface API normative.
Utilisez references/window-openai-patterns.md pour le mapping wrapper-vers-canonique et pour les patterns d'extraction helper React.

5. Ajouter Métadonnées De Ressource Et Sécurité

Définissez les métadonnées de ressource délibérément sur la ressource/template widget :

_meta.ui.csp avec connectDomains et resourceDomains exacts
_meta.ui.domain pour les déploiements soumission-ready
_meta.ui.prefersBorder (ou alias compatibilité OpenAI lorsque nécessaire)
Optional openai/widgetDescription pour réduire la narration redondante

Évitez frameDomains sauf si l'intégration iframe est core au produit.

5a. Appliquer Un Contrat De Repo Minimal Fonctionnel

Chaque repo généré doit satisfaire un petit contrat stable avant de le considérer comme terminé.

La forme du repo correspond à l'archétype choisi.
Le serveur MCP et les outils sont câblés à un endpoint /mcp atteignable.
Les outils ont des descriptions claires, des annotations précises, et des métadonnées UI où nécessaire.
Les apps de type connecteur, données uniquement, sync-orientées, et style connaissance d'entreprise utilisent les formes standard search et fetch lorsque pertinent.
Le widget utilise correctement le pont MCP Apps lorsqu'une UI existe.
Le repo inclut assez de scripts ou de commandes pour qu'un utilisateur puisse l'exécuter et le vérifier localement.
La réponse dit explicitement quelle validation a été exécutée et ce qui ne l'a pas été.

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

6. Valider La Boucle Locale

Validez contre le contrat de repo minimal fonctionnel, pas seulement "des fichiers ont-ils été créés".

Exécutez d'abord les vérifications les moins coûteuses :
- revue statique du contrat
- vérifications de syntaxe ou compilations lorsque faisable
- vérification de santé /mcp locale lorsque faisable
Puis passez aux vérifications d'exécution :
- vérifiez les descripteurs d'outil et le rendu widget dans MCP Inspector
- testez l'app dans ChatGPT en mode développeur 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 de widget après les événements host et les appels d'outil de suivi
Si vous livrez uniquement un scaffold et n'installez pas les dépendances, exécutez toujours les vérifications à bas 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. Connecter Et Tester Dans ChatGPT (Mode Développeur)

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

Exécutez le serveur MCP localement sur http://localhost:<port>/mcp
Exposez le serveur local avec un tunnel public HTTPS (par exemple ngrok http <port>)
Utilisez l'URL du tunnel HTTPS plus le chemin /mcp lors de la connexion à partir de ChatGPT
Dans ChatGPT, activez le Mode Développeur sous Paramètres → Apps & Connecteurs → Paramètres avancés
Dans les paramètres de l'app ChatGPT, créez une nouvelle app pour le serveur MCP distant et collez l'URL MCP publique
Dites aux utilisateurs de rafraîchir l'app après les modifications d'outil/métadonnées MCP afin que ChatGPT recharge les descripteurs les plus récents

Remarque : Certains docs/screenshots utilisent toujours l'ancienne terminologie "connecteur". Préférez le wording de produit actuel ("app") tout en reconnaissant les deux labels dans les instructions étape par étape.

8. Planifier L'Hébergement Et Le Déploiement En Production

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

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

9. Préparer La Soumission Et Publier (Apps Publiques Uniquement)

Incluez uniquement ces étapes lorsque l'utilisateur envisage un listing d'annuaire public.

Utilisez apps-sdk/deploy/submission pour le flux de soumission et apps-sdk/app-submission-guidelines pour les exigences de révision
Gardez les apps privées/internes en mode Développeur au lieu de les soumettre
Confirmez les prérequis de vérification organisationnelle et de rôle Propriétaire avant le travail de soumission
Assurez-vous que le serveur MCP utilise un endpoint production public (pas localhost/testing URLs) et a la CSP submission-ready configurée
Préparez les artifacts de soumission : métadonnées de l'app, logo/screenshots, URL de politique de confidentialité, contact d'support, prompts/réponses de test, infos de localisation
Si l'auth est requise, incluez les credentials démo safe pour révision et testez le chemin de connexion end-to-end
Soumettez pour révision dans le dashboard Platform, surveillez l'état de révision, et publiez uniquement après approbation

Orientation De L'État Interactif

Lisez references/interactive-state-sync-patterns.md lorsque l'app a un état widget long-lived, des interactions répétées, ou des appels d'outils initiés par composant (par exemple, jeux, boards, cartes, dashboards, éditeurs).

Utilisez-le pour choisir les patterns pour :

Snapshots d'état plus tokens d'événement monotones (stateVersion, resetCount, etc.)
Handlers idempotents retry-safe
Partitionnement structuredContent vs _meta
Flux de mise à jour du pont MCP Apps d'abord avec compatibilité window.openai optionnelle
Architecture d'outil données/rendu découplée pour les apps interactives plus complexes

Attentes De Sortie

Lorsque vous utilisez cette skill pour scaffolder du code, produisez la sortie dans cet ordre sauf si l'utilisateur demande autrement :

Pour les demandes de scaffold directes, ne vous arrêtez pas au plan : donnez le plan court, puis créez les fichiers immédiatement.

Archétype principal de l'app choisi et pourquoi
Plan d'outil et choix d'architecture (minimal vs découplé)
Point de départ en amont choisi (exemple officiel, exemple ext-apps, ou scaffold de fallback local) et pourquoi
Pages/URLs des docs utilisées à partir de $openai-docs
Arborescence de fichiers à créer ou modifier
Implémentation (serveur + widget)
Validation effectuée contre le contrat de repo minimal fonctionnel
Instructions de run/test local (incluant tunnel + configuration d'app ChatGPT en mode Développeur)
Conseils de déploiement/hébergement (si demandé ou implicite)
Checklist de préparation à la 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 dans un petit nombre de formes d'app supportées
references/apps-sdk-docs-workflow.md pour les requêtes de docs, les cibles de page, et la checklist de génération de code
references/interactive-state-sync-patterns.md pour les patterns réutilisables pour les apps widget avec état ou hautement interactives
references/repo-contract-and-validation.md pour le contrat de repo minimal fonctionnel et l'échelle de validation légère
references/search-fetch-standard.md pour quand et comment privilégier les outils standards search et fetch
references/upstream-example-workflow.md pour choisir entre les exemples officiels, les exemples ext-apps, et le scaffold de fallback local
references/window-openai-patterns.md pour les extensions spécifiques à ChatGPT, la traduction API wrapper, et les patterns helpers React
scripts/scaffold_node_ext_apps.mjs pour un scaffold de démarrage minimal Node + @modelcontextprotocol/ext-apps de fallback