# Crear un proyecto de BeamCue a partir de tu servicio Versión de las instrucciones: 1.2 Sigue este flujo en un asistente de desarrollo con acceso al repositorio del servicio y a la aplicación en ejecución. Formula preguntas y redacta el proyecto en el idioma solicitado explícitamente por el usuario; si no lo indica, utiliza español, el idioma de este documento. Llama «escena» a cada unidad de presentación y conserva los nombres de herramientas MCP y campos internos como `stepId`. El resultado es un proyecto de BeamCue privado y editable, con pantallas reales, títulos, descripciones y un enlace a Studio. Guía la atención con objetivos de clic relevantes, subtítulos y un énfasis visual adecuado; no te limites a una secuencia de capturas sin explicar. La narración es opcional. Este documento no concede acceso adicional al servicio. Respeta las instrucciones del usuario y las reglas del repositorio. ## 1. Examinar el servicio y preguntar solo por los datos que faltan Lee las instrucciones del repositorio y revisa entradas, rutas, documentación y pantallas reales. Averigua el nombre, las funciones disponibles y la URL local o desplegada cuando puedas hacerlo de forma segura; no preguntes por datos que puedes descubrir. Comprueba si el entorno permite manejar y capturar el navegador o la aplicación nativa y si BeamCue MCP está disponible. Agrupa de forma breve únicamente las preguntas pendientes: - Propósito: presentación del producto, incorporación, guía de funciones, historia comercial u otro objetivo. - Público y lo que debe comprender o conseguir. - Número de escenas y funciones o pantallas imprescindibles. - Idioma del proyecto solo si las preferencias lingüísticas no están claras. - Si debe generarse narración; pregunta por la voz únicamente si se desea narración. - URL o pasos de acceso solo si la inspección no los ha resuelto. Reutiliza las respuestas y preferencias ya proporcionadas. No repitas preguntas contestadas. Espera las respuestas obligatorias pendientes: el paso del tiempo no equivale a una respuesta. Si el usuario delega las decisiones, elige cinco escenas, el idioma solicitado (en su defecto, español) y sin narración, e informa de esos valores. No añadas una aprobación independiente del guion gráfico salvo que se solicite. ## 2. Conectar BeamCue MCP Añade este servidor remoto Streamable HTTP a la configuración MCP del asistente: https://beamcue.com/mcp Utiliza la interfaz de conexión admitida por el host MCP y descubre sus capacidades instaladas en lugar de inventar comandos específicos de cada cliente. Incluir una URL en el prompt no instala ni autoriza la conexión. Si no puedes configurarla, pide al usuario que añada la URL en su asistente y retoma esta conversación. El host y el navegador del usuario gestionan OAuth: - Servidor de autorización: https://beamcue.com/o - Metadatos del recurso protegido: https://beamcue.com/.well-known/oauth-protected-resource/mcp - Metadatos del servidor de autorización: https://beamcue.com/.well-known/oauth-authorization-server/o - Ámbitos: `projects:read projects:write` - Flujo Authorization Code con S256 PKCE; el host proporciona la URL de retorno y los valores PKCE. Descubre las herramientas actuales y sus esquemas antes de invocarlas. El host puede añadir prefijos a sus nombres. Llama a `get_connection_status` y exige `mcpConnectionStatus=connected` antes de modificar proyectos. Si falta la conexión o ha caducado, utiliza `begin_oauth` o `get_reconnect_url` para que el host reinicie OAuth. La sesión web y OAuth MCP son distintas: iniciar sesión en BeamCue no repara una autorización MCP caducada. Nunca pidas contraseñas, tokens ni secretos PKCE en el chat ni los incluyas en prompts, capturas o registros. ## 3. Planificar las escenas y recoger pantallas reales Ordena las escenas según el propósito y el número solicitado. En cada una define la idea que debe entenderse, la ruta o navegación, el estado requerido, el elemento objetivo si existe, el título, una descripción breve y el plan de atención: qué señalar, explicar y mostrar como resultado, y qué efectos se aplican por MCP o requieren Studio. Para una introducción de cinco escenas delegada, cubre entrada, espacio principal, acción esencial, resultado y otra función útil o siguiente paso. Adáptalo a lo que existe, sin inventar funciones para llenar huecos. Opera el servicio real, preferiblemente con una cuenta de prueba autorizada. Usa la captura disponible del navegador o aplicación nativa, o capturas auténticas aportadas por el usuario, respetando las reglas del repositorio. En BeamCue, las capturas de Playwright sirven solo como referencia comparativa, no como material de origen del proyecto. No uses imágenes generadas, maquetas HTML, datos de ejemplo o fragmentos de código como prueba del servicio en funcionamiento. Las importaciones MCP son imágenes estáticas con `producer=mcp.client`; no las describas como grabaciones de la extensión ni las etiquetes `chrome.tabs.captureVisibleTab`. Mantén una ventana de visualización coherente, espera al estado cargado y examina cada imagen antes de subirla. Excluye secretos y entradas sensibles de imágenes, solicitudes, registros y pruebas. Iniciar sesión, pagar, cambiar permisos u otras operaciones importantes requieren la autorización existente del usuario. Si falta acceso, captura o una pantalla necesaria, pide la acción concreta o una captura auténtica y espera. No omitas escenas imprescindibles en silencio ni declares completo un proyecto parcial. Mide las coordenadas desde la esquina superior izquierda de la imagen exacta que se subirá, en píxeles de imagen, no CSS. Si no hay objetivo de interacción, usa el centro con `labelMode=caption_only` y omite `clickLabel`. No inventes un clic. Escribe un título corto y una descripción diferente, sin repetir la misma frase en varias etiquetas. ### Guiar al espectador por una tarea real Elige la presentación según el propósito y el público; no pidas configurar cada efecto ni aprobar otro guion gráfico. Aplica los ajustes MCP compatibles durante la creación. Con acceso autorizado a Studio, realiza también los retoques exclusivos mediante controles visibles, guarda y previsualiza. En caso contrario, enumera los retoques pendientes por escena. No digas que aplicaste un efecto solo porque lo planeaste. No modifiques el JSON del proyecto ni uses API no documentadas para eludir límites de MCP. | Elemento | Cómo dirige la atención | Cómo aplicarlo actualmente | | --- | --- | --- | | Objetivo y etiqueta de acción | Señala el control exacto. Prefiere «Seleccionar un período» a «Haz clic aquí». | `add_screen` / `update_screen`: `clickXPixel`, `clickYPixel`, `clickLabel` medidos y `labelMode=both` o `hotspot_only`. | | Subtítulo | Explica la utilidad de la acción o el cambio en una frase corta, comprensible sin sonido. | `description` con `labelMode=caption_only` o `both`; también sirve como texto de la narración opcional. | | Énfasis del puntero | Facilita encontrar la siguiente acción en una interfaz densa con un puntero destacado coherente. | `update_project` con `pointerMode=highlighted`; usa `standard` si distrae o tapa controles pequeños. | | Efecto de clic y resaltado | Refuerza acciones reales; evita pulsos inexplicables en vistas generales o resultados. | `presentation.clickEffectVisible=false`, `hotspotRadius`, `hotspotAnchor`. | | Disposición de textos | Evita cubrir objetivo, resultado, navegación u otras etiquetas; usa contraste legible, tipografía coherente y líneas cortas. | `presentation.captionLayout`: `placement`, `point` (`x`, `y`: 0–1). | | Zoom | Acerca brevemente controles o resultados pequeños pero esenciales, conservando contexto alrededor. | `presentation.zoomEnabled=true`, `presentation.zoomScale=1.16` (1.12–1.20). | | Duración y transiciones | Da tiempo para encontrar la acción y leer el resultado. Corte para cambios claros, fundido cruzado para un enlace tranquilo; deslizamiento o transformación solo si explican continuidad. | `presentation.durationMs`, `transition` (`cut`, `crossfade`, `slide`, `morph`), `slideDirection`, `transitionAnchor`. | | Marco de salida | Establece contexto de navegador o aplicación sin reducir innecesariamente el contenido. | `update_project` con `windowFrame=browser`, `app` o `none`; usa `none` si la captura ya contiene marco. | | Voz y pausa opcionales | Explica el resultado durante la reproducción y deja una breve pausa al terminar de hablar. | `set_narration` / `generate_voiceover`, solo bajo petición. `endPaddingMs` admite 0–10000; empezar con 400–800ms si resulta útil. | `labelMode` controla el texto explicativo. `caption_only` no oculta el clic: usa `presentation.clickEffectVisible=false` en escenas sin acción y verifica la vista previa. Dentro del número solicitado, sigue **orientar → actuar → confirmar → continuar**. Por ejemplo, para un servicio de informes que realmente tenga estas funciones: | Escena | Captura y énfasis | Texto de ejemplo | | --- | --- | --- | | 1. Orientar | Espacio real completo; solo subtítulo, sin pulso de acción, con contexto. | «Consulta los informes de tu equipo en un solo lugar». | | 2. Actuar | Filtro de fechas antes de usarlo; posición medida, `both`, puntero destacado y posible zoom moderado en Studio. | «Seleccionar un período»; «Limita el informe al período que quieras comparar». | | 3. Confirmar | Resultado filtrado real; solo subtítulo y foco en el cambio, no en pulsar otra vez el filtro. | «El gráfico muestra ahora únicamente el período seleccionado». | | 4. Actuar de nuevo | Control de exportación real antes de una exportación autorizada, señalado con una etiqueta corta. | «Exportar el informe»; «Prepara esta vista para tu equipo». | | 5. Continuar | Estado final real o destino útil, con la siguiente acción clara. | Describe el resultado observado, no un éxito supuesto por pulsar el botón. | Adapta el ejemplo sin inventar controles ni afirmar exportaciones no observadas. Una imagen `add_screen` es un estado estático, no una grabación antes/después. Para mostrar cambios, captura el resultado como otra escena prevista. Respeta el número solicitado; con pocas escenas, prioriza la acción principal y su resultado. Usa un énfasis dominante por momento: no tapes objetivos ni acumules zoom, grandes efectos de clic y texto móvil solo para añadir movimiento. En un servicio de solo lectura, destaca resultados útiles sin fabricar clics. ## 4. Crear y completar el proyecto Guarda en la conversación un registro de reanudación: ID del proyecto, URL Studio, ID y orden de escenas terminadas, revisión actual y claves de idempotencia por operación. No incluyas Base64, URL firmadas, credenciales ni contenido sensible de pantallas. Usa una clave única para cada nueva modificación lógica, conservando entrada y clave al reintentar la misma. Crea un proyecto nuevo solo ante una nueva solicitud. Estos JSON ilustran argumentos de herramientas, no evidencias del servicio. Sustituye los marcadores por valores inspeccionados. `canvas` representa la ventana CSS; `output` configura dimensiones y fps del vídeo cuando se especifica. `surface` es `browser` para sitios o `screen` para aplicaciones nativas. Define `locale` según el idioma del resultado. ```json {"tool":"create_project","arguments":{"title":"Presentación del servicio","surface":"browser","locale":"es-ES","sourceUrl":"https://your-service.example/","canvas":{"width":1440,"height":900},"idempotencyKey":""}} ``` Conserva `projectId` y `studioUrl`. Desactiva la voz si no se ha solicitado: ```json {"tool":"set_narration","arguments":{"projectId":"","enabled":false,"idempotencyKey":""}} ``` En recorridos guiados, aplica explícitamente un puntero destacado y un marco adecuado a la captura: ```json {"tool":"update_project","arguments":{"projectId":"","pointerMode":"highlighted","windowFrame":"none","idempotencyKey":""}} ``` Añade pantallas en orden con la imagen real y sus coordenadas en píxeles. `description` aporta el subtítulo y, si está activa, la narración. Usa `labelMode=caption_only` en escenas descriptivas y `both` con un objetivo real. Ajusta `narrationEnabled` a la respuesta del usuario. ```json {"tool":"add_screen","arguments":{"projectId":"","title":"Tu espacio de trabajo principal","description":"Explica el flujo de trabajo real que se ve aquí.","clickXPixel":720,"clickYPixel":450,"labelMode":"caption_only","narrationEnabled":false,"imageFile":{"name":"workspace.png","mimeType":"image/png","dataBase64":""},"idempotencyKey":""}} ``` En escenas de acción usa una diana real y ambas capas de texto. Estas coordenadas son ejemplos: mídelo en la imagen inspeccionada. El título puede aparecer en la burbuja del objetivo y debe ser corto. Igualar `title` y `clickLabel` evita una segunda etiqueta repetida; el subtítulo añade el beneficio. ```json {"tool":"add_screen","arguments":{"projectId":"","title":"Seleccionar un período","clickLabel":"Seleccionar un período","description":"Limita el informe al período que quieras comparar.","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","narrationEnabled":false,"imageFile":{"name":"date-filter.png","mimeType":"image/png","dataBase64":""},"idempotencyKey":""}} ``` Corrige el objetivo o las palabras en la escena existente: ```json {"tool":"update_screen","arguments":{"projectId":"","stepId":"","title":"Seleccionar un período","clickLabel":"Seleccionar un período","description":"Compara los resultados del período seleccionado.","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}}}}} ``` Envía los ajustes dentro de `presentation` en `add_screen`, `update_screen` o `add_screens_batch.screens[]`. Las actualizaciones conservan los ajustes omitidos y el estilo de subtítulo existente. `captionLayout` requiere `placement` y `point`. ### Límites de imágenes y solicitudes - Formatos decodificados: PNG, WebP, JPEG. Cada lado, como máximo 8192px; imagen total, 64 megapíxeles. - Imagen integrada: máximo 4MiB tras decodificar Base64. Base64 añade aproximadamente un tercio de tamaño; la solicitud HTTP MCP completa debe caber en 8MiB. - `add_screens_batch` acepta de forma atómica 1–20 pantallas integradas, sujetas al mismo límite global. Prefiere `add_screen` secuencial para prever tamaños y reanudar fácilmente; no envíes veinte imágenes grandes juntas. - Para imágenes mayores, `prepare_image_upload` admite hasta 15MiB. Proporciona `name`, `mimeType`, `byteLength`, `sha256`, `width`, `height`, `projectId` y una nueva `idempotencyKey`. Envía por PUT los bytes exactos a `uploadUrl` con las cabeceras devueltas. La URL firmada caduca a los diez minutos y es de un solo uso. Después llama a `add_screen` con `uploadId` en lugar de `imageFile`. - MIME, longitud, SHA-256 y dimensiones declaradas deben coincidir con la imagen real. Detecta MIME mediante bytes decodificados, no por el nombre: una captura guardada como `.png` puede contener JPEG. No registres Base64, secretos de URL firmadas ni bytes de imagen. Si se supera un límite, recaptura una ventana adecuada o redimensiona de forma coherente y recalcula dimensiones, hash y coordenadas. Usa `update_screen` para corregir y `reorder_screens` para ordenar, en vez de crear duplicados. Consulta los campos obligatorios del esquema actual. Cuando exista, revisa `displayPreview.display` en la respuesta para detectar texto visible duplicado entre título, etiqueta y subtítulo. ## 5. Narración opcional Solo si se ha solicitado, actívala con `set_narration`, configura idioma y voz compatibles y habilita las escenas correspondientes. Si no hay preferencia, usa la voz predeterminada admitida; no inventes identificadores. Tras finalizar las descripciones, llama a `generate_voiceover` con `operation=generate-stale` y verifica el estado con `get_narration_status`. Informa por separado de fallos o trabajos pendientes y conserva el proyecto para corregirlo en Studio. ## 6. Recuperar y reanudar - Tras un fallo de conexión o respuesta incierta, reconecta si hace falta y consulta el proyecto existente con `get_project`. Reintenta la misma modificación con la entrada y clave originales, sin crear otro proyecto a ciegas. - `expectedRevision` es opcional; omítelo en tareas secuenciales simples. Si lo usas y hay conflicto, lee el error estructurado, actualiza el estado y emplea la revisión de reintento devuelta con la misma entrada lógica y clave. Conserva las ediciones del usuario; si contradicen lo solicitado, pregunta en vez de sobrescribirlas. - Si caduca una subida firmada, prepara otra con una clave de subida nueva. Para sustituir `uploadId` en un alta fallida, comprueba primero que la operación anterior no creó una escena y usa una nueva clave de alta. - Si falta acceso o una captura imprescindible, deja una pregunta breve que identifique la escena y acción necesarias. Mantén lo terminado y el enlace Studio para continuar sin empezar de nuevo. ## 7. Validar y entregar Con `get_project`, compara cantidad, orden, títulos, descripciones y estado de narración reales con la solicitud, y corrige diferencias. Revisa cada plan de atención: objetivo preciso, textos de acción y resultado distintos, modo de etiqueta adecuado, puntero y marco aplicados. Valida el proyecto canónico: ```json {"tool":"get_project","arguments":{"projectId":""}} ``` ```json {"tool":"validate_project","arguments":{"projectId":"","idempotencyKey":""}} ``` Usa `studioUrl` o `nextAction.url` de una acción `open_studio` devueltos, nunca una URL inventada. Con una sesión de navegador autorizada, inspecciona la lista real de escenas y la vista previa de Studio. Reproduce entre escenas para comprobar que el clic apunta al control correcto, los resultados muestran cambios reales, los subtítulos son legibles y no tapan objetivos y el zoom no corta UI esencial. Revisa tanto escritorio como vista previa pequeña, tiempos de lectura con y sin voz, avisos de transición y persistencia de los retoques exclusivos de Studio después de guardar y recargar. Reduce textos saturados o simplifica efectos antes de declararlo listo. Sin acceso a Studio, informa de la validación MCP por separado y pide revisar el proyecto enlazado; no afirmes haberlo comprobado visualmente. Finaliza con título, escenas terminadas/solicitadas, lista breve, señales visuales aplicadas, estado de narración, enlace Studio y acciones pendientes. Distingue ajustes MCP aplicados, retoques Studio verificados visualmente y pendientes por escena. Solo declara completo el proyecto cuando existan todas las pantallas y descripciones requeridas. `validate_project` valida y prepara la edición en Studio. No publica, genera voces ni renderiza MP4. MCP no expone una herramienta de renderizado de vídeo. Mantén los proyectos privados; el usuario puede previsualizar, editar, renderizar MP4 y elegir compartir en Studio. Una validación correcta no demuestra que exista un enlace público o un archivo de vídeo.