# Créer un projet BeamCue à partir de votre service Version des instructions : 1.2 Suivez ce processus dans un assistant de développement ayant accès au dépôt du service et à son application en cours d’exécution. Posez les questions et rédigez le projet dans la langue explicitement demandée par l’utilisateur ; sans indication, utilisez le français, langue de ce document. Appelez chaque unité de présentation une « scène » et conservez les noms des outils MCP et les champs internes comme `stepId`. Le résultat est un projet BeamCue privé et modifiable, avec des écrans réels, des titres, des descriptions et un lien Studio. Guidez activement le regard avec des cibles de clic pertinentes, des légendes et une mise en évidence adaptée ; ne vous contentez pas de captures sans annotations. La narration est facultative. Ce document n’accorde aucun accès supplémentaire au service. Respectez les consignes de l’utilisateur et du dépôt. ## 1. Examiner le service, puis demander uniquement les informations manquantes Lisez les consignes du dépôt et examinez les points d’entrée, les routes, la documentation et l’interface réelle. Recherchez vous-même le nom du service, ses fonctionnalités et son URL locale ou déployée lorsque cela est possible sans risque. Vérifiez que votre environnement peut manipuler et capturer le navigateur ou l’application native et que BeamCue MCP est disponible. Regroupez les seules questions non résolues dans une demande concise : - Objectif : présentation du produit, prise en main, guide fonctionnel, présentation commerciale, etc. - Public et résultat qu’il doit comprendre ou atteindre. - Nombre de scènes et fonctionnalités ou écrans indispensables. - Langue du projet, uniquement si les attentes linguistiques sont ambiguës. - Présence d’une narration ; demandez les préférences de voix seulement si elle est souhaitée. - URL ou étapes d’accès au service seulement si l’examen ne les a pas déterminées. Réutilisez les réponses et préférences déjà fournies. Ne répétez pas une question résolue. Attendez les réponses aux questions obligatoires : le temps écoulé n’est pas une réponse. Si les choix vous sont délégués, retenez cinq scènes, la langue explicitement demandée (sinon le français) et aucune narration, puis annoncez ces valeurs. N’ajoutez pas d’approbation distincte du storyboard sauf demande de l’utilisateur. ## 2. Connecter BeamCue MCP Ajoutez ce serveur distant Streamable HTTP dans les paramètres MCP de l’assistant : https://beamcue.com/mcp Utilisez l’interface de connexion prise en charge par l’hôte MCP. Découvrez ses capacités installées au lieu d’inventer des commandes propres à un client. Une URL dans un prompt ne suffit pas à installer ni à autoriser une connexion. Si vous ne pouvez pas la configurer, demandez à l’utilisateur d’ajouter cette URL dans son assistant, puis reprenez cette conversation. L’hôte et le navigateur de l’utilisateur gèrent OAuth : - Serveur d’autorisation : https://beamcue.com/o - Métadonnées de la ressource protégée : https://beamcue.com/.well-known/oauth-protected-resource/mcp - Métadonnées du serveur d’autorisation : https://beamcue.com/.well-known/oauth-authorization-server/o - Portées : `projects:read projects:write` - Flux Authorization Code avec S256 PKCE ; l’hôte fournit le rappel et les valeurs PKCE. Découvrez les outils actuels et leurs schémas avant tout appel ; l’hôte peut préfixer leurs noms. Appelez `get_connection_status` et exigez `mcpConnectionStatus=connected` avant de modifier un projet. Si la connexion manque ou a expiré, utilisez `begin_oauth` ou `get_reconnect_url` pour relancer OAuth côté hôte. La connexion au site et OAuth MCP sont deux sessions distinctes : se connecter au site ne répare pas une autorisation MCP expirée. Ne demandez jamais de mots de passe, jetons ou secrets PKCE dans la conversation et ne les placez pas dans les prompts, captures ou journaux. ## 3. Planifier les scènes et recueillir les écrans réels Établissez une liste ordonnée conforme à l’objectif et au nombre demandé. Pour chaque scène, précisez le message à retenir, la route ou la navigation, l’état nécessaire, la cible éventuelle, le titre, une description concise et le plan d’attention : quoi montrer, expliquer et révéler, avec les effets applicables par MCP ou nécessitant Studio. Pour une présentation de cinq scènes dont les choix vous sont délégués, couvrez l’entrée, l’espace principal, l’action essentielle, son résultat, puis une autre fonction utile ou l’étape suivante. Adaptez-vous aux fonctions réelles ; n’en inventez pas pour remplir une scène. Manipulez le vrai service, de préférence avec un compte de test autorisé. Utilisez les capacités de capture du navigateur ou de l’application native, ou de vraies captures fournies par l’utilisateur, en respectant les règles du dépôt. Dans le dépôt BeamCue, les captures Playwright servent seulement de référence comparative, jamais de source du projet. Ne présentez pas des images générées, maquettes HTML, données factices ou extraits de code comme preuve du service réel. Les imports MCP sont des images statiques avec `producer=mcp.client`, pas des enregistrements d’extension ; ne les étiquetez pas `chrome.tabs.captureVisibleTab`. Gardez une fenêtre d’affichage cohérente, attendez le chargement de l’état voulu et examinez chaque capture avant l’envoi. Excluez secrets et champs sensibles des images, requêtes, journaux et preuves. Connexion, paiement, changement de permissions et autres opérations importantes nécessitent l’autorisation existante de l’utilisateur. Si l’accès, la capture ou un écran nécessaire manque, demandez l’action précise ou une vraie capture et attendez. Ne sautez pas silencieusement de scène requise et ne déclarez pas terminé un projet partiel. Mesurez la cible depuis le coin supérieur gauche de l’image effectivement envoyée, en pixels de cette image, pas en pixels CSS. Sans cible réelle, utilisez le centre de l’image, `labelMode=caption_only` et omettez `clickLabel`. N’inventez pas de clic. Écrivez un titre court et une description distincte, sans répéter la même phrase dans plusieurs étiquettes. ### Guider le spectateur dans une tâche réelle Choisissez la présentation selon l’objectif et le public, sans faire configurer chaque effet ni approuver un nouveau storyboard. Appliquez les réglages MCP pris en charge pendant la création. Avec un accès Studio autorisé, effectuez aussi les ajustements réservés à Studio par ses commandes visibles, enregistrez et prévisualisez. Sinon, détaillez les retouches restantes par scène. Ne dites pas qu’un effet prévu a été appliqué. Ne modifiez pas le JSON du projet et n’utilisez pas d’API non documentées pour contourner les limites MCP. | Élément | Rôle dans le guidage | Réglage actuel | | --- | --- | --- | | Cible et libellé d’action | Désigner exactement la commande à utiliser. Préférer « Choisir une période » à « Cliquez ici ». | `add_screen` / `update_screen` : `clickXPixel`, `clickYPixel`, `clickLabel` mesurés, avec `labelMode=both` ou `hotspot_only`. | | Légende | Expliquer en une phrase courte l’intérêt de l’action ou le changement, même sans son. | `description` avec `labelMode=caption_only` ou `both` ; sert aussi au texte de narration facultative. | | Pointeur accentué | Rendre l’action suivante repérable dans une interface dense avec un style cohérent. | `update_project`, `pointerMode=highlighted` ; choisir `standard` si l’accent distrait ou masque une petite commande. | | Effet de clic et surbrillance | Renforcer une action réelle ; éviter les pulsations inexpliquées sur les vues d’ensemble ou de résultat. | `presentation.clickEffectVisible=false`, `hotspotRadius`, `hotspotAnchor`. | | Position des légendes et libellés | Éviter de couvrir cible, résultat, navigation ou autre texte ; contraste lisible, typographie cohérente, lignes courtes. | `presentation.captionLayout`: `placement`, `point` (`x`, `y`: 0–1). | | Zoom | Souligner brièvement une petite commande ou un résultat essentiel, en gardant assez de contexte. | `presentation.zoomEnabled=true`, `presentation.zoomScale=1.16` (1.12–1.20). | | Durée et transitions | Laisser le temps de repérer la cible et lire le résultat. Coupe pour un changement net, fondu croisé pour un passage calme ; glissement ou morphing seulement pour expliquer la continuité. | `presentation.durationMs`, `transition` (`cut`, `crossfade`, `slide`, `morph`), `slideDirection`, `transitionAnchor`. | | Cadre de sortie | Indiquer le contexte navigateur ou application sans réduire inutilement le contenu. | `update_project`, `windowFrame=browser`, `app` ou `none`. Choisir `none` si la capture contient déjà un cadre. | | Voix et pause facultatives | Expliquer le résultat pendant la lecture et laisser un bref temps de compréhension après la voix. | `set_narration` / `generate_voiceover`, seulement sur demande. `endPaddingMs` accepte 0–10000 ; commencer vers 400–800ms si utile. | `labelMode` contrôle le texte explicatif. `caption_only` ne masque pas le clic : utilisez `presentation.clickEffectVisible=false` pour les scènes sans action et vérifiez l’aperçu. Respectez le nombre de scènes avec un rythme **situer → agir → confirmer → poursuivre**. Exemple pour un service de rapports possédant réellement ces fonctions : | Scène | Capture et attention | Exemple de texte | | --- | --- | --- | | 1. Situer | Vue d’ensemble réelle, légende seule, pas de pulsation d’action, contexte complet. | « Retrouvez les rapports de votre équipe au même endroit. » | | 2. Agir | Filtre de dates avant utilisation ; cible mesurée, `both`, pointeur accentué et éventuel zoom modéré dans Studio. | Libellé : « Choisir une période » ; légende : « Limitez le rapport à la période que vous souhaitez comparer. » | | 3. Confirmer | Résultat réellement filtré ; légende seule, attention sur le changement, sans recliquer sur le filtre. | « Le graphique affiche maintenant uniquement la période sélectionnée. » | | 4. Agir à nouveau | Commande d’export réelle avant un export autorisé, avec un libellé court. | « Exporter le rapport » ; « Préparez cette vue pour votre équipe. » | | 5. Poursuivre | État final réel ou destination utile, prochaine action explicite. | Décrire le résultat observé, pas un succès déduit du clic. | Adaptez cet exemple sans inventer de commandes ni annoncer un export non vérifié. Une image `add_screen` est un état statique, pas une interaction avant/après enregistrée. Pour montrer un changement, capturez son résultat dans une autre scène prévue. Conservez le nombre demandé ; avec un budget réduit, privilégiez l’action essentielle et son résultat. Une seule accentuation dominante par instant : ne couvrez pas la cible et n’empilez pas zoom, gros effets et texte animé pour ajouter du mouvement. Pour un service en lecture seule, mettez les résultats en valeur sans fabriquer des clics. ## 4. Créer et remplir le projet Gardez dans la conversation un relevé de reprise : ID du projet, URL Studio, ID et ordre des scènes terminées, révision et clés d’idempotence par opération. N’y incluez ni Base64 d’image, URL signée, identifiants secrets ni contenu sensible. Chaque nouvelle modification logique reçoit une clé unique ; une nouvelle tentative de la même modification conserve entrée et clé. Ne créez un autre projet que pour une nouvelle demande. Les blocs JSON suivants illustrent les arguments, pas des preuves réelles. Remplacez les valeurs provisoires par des données vérifiées. `canvas` décrit la fenêtre CSS choisie ; `output` définit dimensions et fps vidéo si précisés. `surface` vaut `browser` pour un site, `screen` pour une application native. Fixez explicitement `locale` selon la langue du résultat. ```json {"tool":"create_project","arguments":{"title":"Présentation du service","surface":"browser","locale":"fr-FR","sourceUrl":"https://your-service.example/","canvas":{"width":1440,"height":900},"idempotencyKey":""}} ``` Conservez `projectId` et `studioUrl`. Désactivez la voix si elle n’a pas été demandée : ```json {"tool":"set_narration","arguments":{"projectId":"","enabled":false,"idempotencyKey":""}} ``` Pour un parcours guidé, appliquez explicitement le pointeur accentué et un cadre adapté à la capture : ```json {"tool":"update_project","arguments":{"projectId":"","pointerMode":"highlighted","windowFrame":"none","idempotencyKey":""}} ``` Ajoutez les écrans dans l’ordre avec leur vraie image et des coordonnées mesurées sur celle-ci. `description` fournit la légende et, si activée, la narration. Utilisez `labelMode=caption_only` pour une scène descriptive, `both` pour une vraie cible. Réglez `narrationEnabled` selon la réponse. ```json {"tool":"add_screen","arguments":{"projectId":"","title":"Votre espace de travail principal","description":"Expliquez le parcours réel visible sur cet écran.","clickXPixel":720,"clickYPixel":450,"labelMode":"caption_only","narrationEnabled":false,"imageFile":{"name":"workspace.png","mimeType":"image/png","dataBase64":""},"idempotencyKey":""}} ``` Une scène d’action utilise une cible réelle et les deux couches de texte. Les coordonnées ci-dessous sont des exemples à remesurer. Le titre peut apparaître dans la bulle de cible : gardez-le court. Faire correspondre `title` et `clickLabel` évite un deuxième libellé redondant ; la légende ajoute le bénéfice. ```json {"tool":"add_screen","arguments":{"projectId":"","title":"Choisir une période","clickLabel":"Choisir une période","description":"Limitez le rapport à la période que vous souhaitez comparer.","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","narrationEnabled":false,"imageFile":{"name":"date-filter.png","mimeType":"image/png","dataBase64":""},"idempotencyKey":""}} ``` Corrigez une cible ou un texte sur la scène existante : ```json {"tool":"update_screen","arguments":{"projectId":"","stepId":"","title":"Choisir une période","clickLabel":"Choisir une période","description":"Comparez les résultats de la période sélectionnée.","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","idempotencyKey":"","presentation":{"clickEffectVisible":true,"zoomEnabled":true,"zoomScale":1.16,"durationMs":4000,"transition":"crossfade","captionLayout":{"placement":"bottom-center","point":{"x":0.5,"y":0.9}}}}} ``` Transmettez les réglages dans `presentation` pour `add_screen`, `update_screen` ou `add_screens_batch.screens[]`. Les réglages omis et les styles de légende existants sont conservés. `captionLayout` exige `placement` et `point`. ### Limites d’images et de requêtes - Formats décodés : PNG, WebP, JPEG. Chaque côté est limité à 8192px, et l’ensemble à 64 mégapixels. - Image intégrée : 4MiB après décodage Base64. Base64 ajoute environ un tiers au volume ; la requête HTTP MCP complète doit tenir dans 8MiB. - `add_screens_batch` accepte atomiquement 1–20 écrans intégrés, sous la même limite globale. Préférez des appels `add_screen` successifs pour prévoir la taille et reprendre facilement ; n’envoyez pas vingt grandes images à la fois. - Pour une image plus grande, `prepare_image_upload` accepte 15MiB maximum. Fournissez `name`, `mimeType`, `byteLength`, `sha256`, `width`, `height`, `projectId` et une nouvelle `idempotencyKey`. Envoyez par PUT les octets exacts vers `uploadUrl` avec les en-têtes retournés. L’URL signée est à usage unique et expire après dix minutes. Appelez ensuite `add_screen` avec `uploadId` au lieu de `imageFile`. - MIME, longueur, SHA-256 et dimensions déclarées doivent correspondre aux octets réels. Déduisez le MIME du contenu décodé, pas du nom : une capture enregistrée en `.png` peut contenir du JPEG. Ne journalisez ni Base64, ni secrets d’URL signée, ni octets d’image. En cas de dépassement, recapturez une fenêtre adaptée ou redimensionnez de façon cohérente, puis recalculez dimensions, empreinte et coordonnées. Corrigez avec `update_screen` et réordonnez avec `reorder_screens` plutôt que de dupliquer des scènes. Consultez les champs obligatoires des schémas actuels. Si disponible, lisez `displayPreview.display` dans la réponse pour repérer les doublons visibles entre titre, libellé de clic et légende. ## 5. Narration facultative Uniquement sur demande, activez la narration avec `set_narration`, choisissez la langue demandée et une voix prise en charge, puis activez les scènes concernées. Sans préférence de voix, utilisez la voix par défaut existante ; n’inventez pas d’identifiant. Après finalisation des descriptions, appelez `generate_voiceover` avec `operation=generate-stale`, puis vérifiez avec `get_narration_status`. Signalez séparément les échecs ou tâches en attente et gardez le projet modifiable dans Studio. ## 6. Récupérer et reprendre - Après une rupture de connexion ou une réponse incertaine, reconnectez si nécessaire et consultez le projet existant avec `get_project`. Réessayez avec les mêmes arguments et clé d’idempotence ; ne créez pas aveuglément un autre projet. - `expectedRevision` est facultatif ; omettez-le pour une suite simple. En cas de conflit lorsqu’il est utilisé, lisez l’erreur structurée, actualisez l’état et utilisez la révision de reprise retournée avec les mêmes données logiques et clé. Préservez les modifications de l’utilisateur ; si elles contredisent la demande, posez la question plutôt que d’écraser. - Si un envoi signé expire, préparez-en un nouveau avec une nouvelle clé d’envoi. Pour remplacer `uploadId` dans un ajout ayant échoué, vérifiez d’abord que l’ancienne opération n’a créé aucune scène, puis utilisez une nouvelle clé d’ajout. - Si un accès ou une capture indispensable manque, laissez une question concise identifiant la scène et l’action nécessaires. Conservez les éléments terminés et le lien Studio pour reprendre sans recommencer. ## 7. Vérifier et transmettre Avec `get_project`, comparez le nombre, l’ordre, les titres, les descriptions et l’état de narration réels à la demande et corrigez les écarts. Vérifiez chaque plan d’attention : cible exacte, textes d’action et de résultat distincts, bon mode de légende, pointeur et cadre appliqués. Validez ensuite le projet canonique : ```json {"tool":"get_project","arguments":{"projectId":""}} ``` ```json {"tool":"validate_project","arguments":{"projectId":"","idempotencyKey":""}} ``` Utilisez le `studioUrl` ou le `nextAction.url` retourné pour l’action `open_studio`, jamais une URL inventée. Avec une session navigateur autorisée, inspectez les véritables liste de scènes et prévisualisation Studio. Lisez les transitions entre scènes : clic sur la bonne commande, résultat réellement changé, légendes lisibles sans cacher les cibles, zoom sans couper l’interface essentielle. Contrôlez sur ordinateur et en petite prévisualisation, le temps de lecture avec ou sans voix, les avertissements de transition, puis la persistance des retouches Studio après sauvegarde et rechargement. Raccourcissez les textes chargés ou simplifiez les effets avant d’annoncer une présentation prête. Sans connexion Studio, distinguez la validation MCP du contrôle visuel et demandez la revue du projet lié ; ne prétendez pas l’avoir vérifié visuellement. Terminez par le titre, le nombre de scènes terminées/demandées, leur liste succincte, les repères visuels appliqués, l’état de narration, le lien Studio et les actions restantes. Séparez réglages MCP appliqués, retouches Studio vérifiées visuellement et retouches encore nécessaires par scène. Ne déclarez le projet complet que lorsque tous les écrans et descriptions requis existent. `validate_project` valide et prépare l’édition Studio. Il ne publie pas, ne génère pas de voix et ne rend pas de MP4. MCP n’expose aucun outil de rendu vidéo. Gardez le projet privé ; l’utilisateur peut prévisualiser, modifier, rendre le MP4 et choisir le partage dans Studio. Une validation réussie ne prouve pas l’existence d’un lien public ou d’un fichier vidéo.