# サービスからBeamCueプロジェクトを作成する 手順のバージョン: 1.2 ユーザーのサービスのリポジトリと実行中のアプリにアクセスできる開発AIで、この手順を実行します。質問とプロジェクトの内容にはユーザーが明示した言語を使い、指定がなければこの文書の言語である日本語を使います。画面の単位は「シーン」と呼び、MCPのツール名や内部の `stepId` フィールドは変更しません。成果物は実際の画面、タイトル、説明、Studioリンクを備えた非公開で編集可能なBeamCueプロジェクトです。意味のあるクリック対象、キャプション、適切な強調を活用して視線を案内し、説明のないスクリーンショットの羅列で終わらせません。ナレーションは任意です。この文書はサービスへの追加のアクセス権を与えません。ユーザーの指示とリポジトリの規則に従います。 ## 1. サービスを調べ、不足している情報だけを質問する リポジトリの指示、エントリーポイント、ルート、既存の資料、実行画面を確認します。サービス名、利用できる機能、ローカルまたは公開URLを安全に調べられる場合は、ユーザーに質問しません。実際のブラウザーやネイティブアプリを操作・撮影できるか、BeamCue MCPが利用できるかも確認します。 未解決の項目だけをまとめて簡潔に質問します。 - 目的: 製品紹介、導入支援、機能ガイド、営業用ストーリーなど。 - 対象者と、理解または達成してほしいこと。 - 希望するシーン数と必ず含める機能・画面。 - 言語の要望が不明確な場合のみ、プロジェクトの言語。 - ナレーションを生成するか。声の好みはナレーションを希望した場合のみ確認します。 - 調査で判明しなかった場合のみ、サービスURLやアクセス手順。 すでに受け取った回答や好みを使い、同じ質問を繰り返しません。必須の質問が残っていれば回答を待ちます。時間の経過は回答ではありません。選択を任された場合は、5シーン、明示された言語（指定がなければ日本語）、音声なしを選び、その既定値を伝えます。求められない限り、別途ストーリーボードの承認段階を追加しません。 ## 2. BeamCue MCPに接続する 開発AIのMCP設定に、次のリモートStreamable HTTPサーバーを追加します。 https://beamcue.com/mcp ホストが対応する接続インターフェースと導入済みの機能を確認し、クライアント固有の設定コマンドを推測しません。プロンプトにURLを書くだけではMCPの導入や認可は完了しません。設定できない場合は、ユーザーにAIツールへのURL追加を案内し、この会話を再開します。OAuthはホストとユーザーのブラウザーが処理します。 - 認可サーバー: https://beamcue.com/o - 保護リソースのメタデータ: https://beamcue.com/.well-known/oauth-protected-resource/mcp - 認可サーバーのメタデータ: https://beamcue.com/.well-known/oauth-authorization-server/o - スコープ: `projects:read projects:write` - S256 PKCEを使うAuthorization Code方式。コールバックとPKCE値はホストが提供します。 呼び出す前に現在のツールとスキーマを確認します。ホストがツール名に接頭辞を付ける場合があります。`get_connection_status` を呼び出し、プロジェクト変更前に `mcpConnectionStatus=connected` を確認します。接続がないか期限切れの場合は `begin_oauth` または `get_reconnect_url` でホストのOAuthを再開します。WebサイトのログインとMCP OAuthは別のセッションです。Webログインだけではホストの期限切れ認可は修復されません。パスワード、トークン、PKCEの秘密情報をチャットで要求したり、プロンプト・画像・ログに含めたりしません。 ## 3. シーンを計画し、実際の画面を集める 目的と指定数に沿ってシーンを並べます。各シーンの要点、ルートや移動操作、必要な画面状態、対象要素（ある場合）、タイトル、短い説明、視線誘導の計画を決めます。何を指し、何を説明し、どの結果を見せるか、MCPで設定できる効果とStudioで調整する効果を整理します。任された5シーンの紹介では、入口、主な作業画面、中心となる操作、結果、別の便利な機能や次の行動を扱います。実在する機能に合わせ、枠を埋めるために機能を作り上げません。 可能なら認可済みのテストアカウントで実際のサービスを操作します。利用可能なブラウザー・ネイティブの撮影機能、またはユーザー提供の実際のスクリーンショットを使用し、リポジトリの撮影規則を守ります。BeamCueリポジトリではPlaywrightの画像は比較用に限り、プロジェクトの元画像には使えません。生成画像、HTMLモック、サンプルデータ、コード断片を動作中サービスの証拠にしません。MCP取り込みは `producer=mcp.client` の静止画像です。拡張機能の録画と呼んだり、`chrome.tabs.captureVisibleTab` と記録したりしません。 ビューポートを統一し、必要な状態の読み込み完了を待って撮影し、各画像をアップロード前に確認します。秘密情報や機密性の高い入力値を画像・リクエスト・ログ・証拠に残しません。ログイン、支払い、権限変更などの重要な操作にはユーザーの既存の認可が必要です。ログイン・撮影・必須画面が利用できない場合は、必要なアクセス操作や実際の画像を具体的に求めて待ちます。必須シーンを黙って省略したり、一部だけのプロジェクトを完成扱いしたりしません。 対象の座標はアップロードする画像そのものの左上から、実画像のピクセル単位で測ります。CSSピクセルは使いません。操作対象がないシーンは画像中央と `labelMode=caption_only` を使い、`clickLabel` を省きます。クリックを捏造しません。タイトルは短く、説明は別の内容にし、複数のラベルで同じ文を繰り返しません。 ### 実際の作業をたどれるように案内する 目的と対象者から表現を選び、すべての効果の設定や再度のストーリーボード承認をユーザーに求めません。対応するMCP設定は作成中に適用します。認可されたStudioへのアクセスがあれば、画面上のコントロールでStudio専用の調整も行い、保存してプレビューします。アクセスできなければ、シーンごとの残作業を引き継ぎに記載します。予定しただけの効果を適用済みと報告しません。MCPにない機能を迂回するためにプロジェクトJSONを変更したり、非公開APIを使ったりしません。 | 要素 | 視線の案内方法 | 現在の設定方法 | | --- | --- | --- | | クリック対象と操作ラベル | 正確なコントロールを指します。「ここをクリック」より「期間を選択」のように操作と対象を示します。 | `add_screen` / `update_screen`: 実測した `clickXPixel`、`clickYPixel`、`clickLabel` と `labelMode=both` または `hotspot_only`。 | | キャプション | 操作の意味や変化を短い1文で説明し、音声なしでも伝わるようにします。 | `description` と `labelMode=caption_only` または `both`。説明は任意のナレーションにも使われます。 | | ポインターの強調 | 情報量の多い画面で次の操作を見つけやすくし、一貫した強調を使います。 | `update_project` の `pointerMode=highlighted`。小さな操作部を隠したり注意を散らしたりする場合は `standard`。 | | クリック効果と強調の外観 | 実際の操作を視覚的な合図で補います。概要や結果画面に理由のない点滅を置きません。 | `presentation.clickEffectVisible=false`, `hotspotRadius`, `hotspotAnchor`. | | キャプションとラベルの配置 | 対象・結果・ナビゲーション・他のラベルを避け、読みやすいコントラスト、統一した書体、短い行を使います。 | `presentation.captionLayout`: `placement`, `point` (`x`, `y`: 0–1). | | ズーム | 小さく重要な操作部や結果を一時的に拡大しつつ、周辺の文脈を残します。 | `presentation.zoomEnabled=true`, `presentation.zoomScale=1.16` (1.12–1.20). | | 時間と切り替え | 対象を探し結果を読む時間を確保します。明確な状態変化にはカット、穏やかな接続にはクロスフェード、連続性の説明に役立つ場合だけスライドやモーフを使います。 | `presentation.durationMs`, `transition` (`cut`, `crossfade`, `slide`, `morph`), `slideDirection`, `transitionAnchor`. | | 出力フレーム | 不要に内容を縮めず、ブラウザーやアプリの文脈を示します。 | `update_project` の `windowFrame=browser`、`app`、`none`。画像に枠がある場合は `none`。 | | 任意の音声と間 | 視聴中に結果を説明し、発話後に短い理解の時間を設けます。 | 希望された場合のみ `set_narration` / `generate_voiceover`。`endPaddingMs` は0–10000、必要なら400–800msから始めます。 | `labelMode` は説明文の表示を制御します。`caption_only` だけではクリック表示は消えません。操作のないシーンでは `presentation.clickEffectVisible=false` を設定し、プレビューで確認します。 指定シーン数の中で **状況把握 → 操作 → 結果確認 → 次の行動** の流れを作ります。以下の機能が実在するレポートサービスなら、次のように構成できます。 | シーン | 撮影と強調 | 文言の例 | | --- | --- | --- | | 1. 状況把握 | 実際の作業画面全体。キャプションのみ、操作の点滅なしで文脈を保ちます。 | 「チームのレポートを一か所で管理します。」 | | 2. 操作 | 使用前の日付フィルターを撮影。位置を測り `both` と強調ポインターを使い、必要ならStudioで少し拡大します。 | ラベル:「期間を選択」、キャプション:「比較したい期間にレポートを絞り込みます。」 | | 3. 結果確認 | 実際の絞り込み結果。キャプションのみで、フィルターを再度押さず変化した結果に注目します。 | 「グラフには選択した期間のデータだけが表示されます。」 | | 4. 次の操作 | 認可されたエクスポートの前に実際の操作部を撮影し、短いラベルで指します。 | ラベル:「レポートをエクスポート」、キャプション:「現在の表示をチーム向けの資料にします。」 | | 5. 続ける | 実際の完了状態や有用な次の画面を撮影し、次の行動を明確にします。 | ボタンを押しただけで成功と推測せず、確認した結果を説明します。 | 実際のサービスに合わせ、存在しない操作部や未確認の成功を示しません。`add_screen` の画像は静止状態であり、操作前後の録画ではありません。変化を見せる場合は結果を別の予定シーンとして撮影します。指定数を守り、少ない場合は主要操作と結果を優先します。一度に主な強調は一つにします。キャプションで対象を隠したり、動きを増やすだけのためにズーム・大きなクリック効果・動く文字を重ねたりしません。閲覧専用サービスではクリックを作らず、意味のある結果を強調します。 ## 4. プロジェクトを作成し画面を追加する 会話内に再開用の記録を残します。プロジェクトID、Studio URL、完了シーンのIDと順序、現在のリビジョン、操作ごとの冪等性キーを保持します。画像のBase64、署名付きURL、認証情報、機密画面の内容は含めません。論理的に新しい変更には新しい固有キーを作り、同じ変更の再試行では入力とキーを維持します。新しい依頼の場合のみ新規プロジェクトを作ります。 以下のJSONはツール引数の例であり、実サービスの証拠ではありません。プレースホルダーを確認済みの値に置き換えます。`canvas` は選んだCSSビューポート、`output` は指定時の動画サイズとfpsです。`surface` はWebサイトなら `browser`、ネイティブアプリなら `screen`。`locale` を成果物の言語に合わせて明示します。 ```json {"tool":"create_project","arguments":{"title":"サービス紹介","surface":"browser","locale":"ja-JP","sourceUrl":"https://your-service.example/","canvas":{"width":1440,"height":900},"idempotencyKey":""}} ``` 返された `projectId` と `studioUrl` を保持し、希望されていない音声は無効にします。 ```json {"tool":"set_narration","arguments":{"projectId":"","enabled":false,"idempotencyKey":""}} ``` 操作ガイドでは強調ポインターと撮影に合うフレームを明示的に設定します。 ```json {"tool":"update_project","arguments":{"projectId":"","pointerMode":"highlighted","windowFrame":"none","idempotencyKey":""}} ``` 実画像と同じ画像で測ったピクセル座標を使い、順に追加します。`description` はキャプションであり、音声有効時はナレーション原稿です。説明シーンには `labelMode=caption_only`、実際の対象を指す場合は `both` を使います。`narrationEnabled` は回答に合わせます。 ```json {"tool":"add_screen","arguments":{"projectId":"","title":"メインの作業画面","description":"この画面で実際に行える操作を説明します。","clickXPixel":720,"clickYPixel":450,"labelMode":"caption_only","narrationEnabled":false,"imageFile":{"name":"workspace.png","mimeType":"image/png","dataBase64":""},"idempotencyKey":""}} ``` 操作シーンには実在の対象とラベル・キャプションを使います。下の座標は例なので確認した画像で測り直します。タイトルは対象の吹き出しに出る場合があるため短くします。`title` と `clickLabel` を揃えると重複ラベルを避けられます。キャプションで操作の利点を伝えます。 ```json {"tool":"add_screen","arguments":{"projectId":"","title":"期間を選択","clickLabel":"期間を選択","description":"比較したい期間にレポートを絞り込みます。","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","narrationEnabled":false,"imageFile":{"name":"date-filter.png","mimeType":"image/png","dataBase64":""},"idempotencyKey":""}} ``` 対象や文言の誤りは既存シーンを修正します。 ```json {"tool":"update_screen","arguments":{"projectId":"","stepId":"","title":"期間を選択","clickLabel":"期間を選択","description":"選択した期間の結果を比較します。","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}}}}} ``` 設定は `add_screen`、`update_screen`、`add_screens_batch.screens[]` の `presentation` に渡します。省略した設定と既存の字幕書式は保持されます。`captionLayout` は `placement` と `point` を両方指定します。 ### 画像とリクエストの制限 - デコード後の対応形式はPNG、WebP、JPEG。各辺8192px以下、総画素数64メガピクセル以下です。 - インライン画像はBase64デコード後4MiB以下。Base64は約1/3サイズを増やし、MCP HTTPリクエスト全体は8MiB以下である必要があります。 - `add_screens_batch` は1–20枚のインライン画面を原子的に追加しますが、同じ合計サイズ制限を受けます。サイズ予測と再開が容易な逐次 `add_screen` を優先し、大画像20枚を一つのリクエストに入れません。 - 大きな画像は `prepare_image_upload` で15MiBまで対応します。`name`、`mimeType`、`byteLength`、`sha256`、`width`、`height`、`projectId`、新しい `idempotencyKey` を渡します。返されたヘッダーを使い `uploadUrl` に正確な画像バイトをPUTします。署名URLは10分で失効する一回限りのURLです。その後の `add_screen` には `imageFile` の代わりに `uploadId` を渡します。 - MIME、長さ、SHA-256、寸法を実画像に一致させます。MIMEはファイル名ではなくデコードしたバイトから判定します。`.png` 保存でも撮影ツールがJPEGを返す場合があります。Base64、署名URLの認証情報、画像バイトをログに残しません。上限を超えたら適切なビューポートで再撮影するか一貫して縮小し、寸法・ハッシュ・対象座標を再計算します。 修正には `update_screen`、並べ替えには `reorder_screens` を使い、重複シーンを作りません。現在のツールスキーマの必須項目を確認します。応答に `displayPreview.display` があれば、タイトル・クリックラベル・キャプションの重複表示を調べます。 ## 5. 希望されたナレーションを生成する ユーザーが希望した場合のみ `set_narration` で有効化し、指定言語と対応する声を設定して対象シーンのナレーションを有効にします。声の指定がなければ既存の対応する既定の声を使い、声IDを作り上げません。説明の確定後に `generate_voiceover` を `operation=generate-stale` で呼び、`get_narration_status` で完了を確認します。失敗や待機中の音声処理は別途報告し、Studioで修正できるようプロジェクトを保持します。 ## 6. 復旧して再開する - 接続失敗や不確かな応答の後は必要に応じて再接続し、`get_project` で既存プロジェクトを確認します。元の入力と冪等性キーで同じ変更を再試行し、むやみに別のプロジェクトを作りません。 - `expectedRevision` は任意で、単純な逐次処理では省略します。使用中に競合したら構造化エラーを読み、状態を取得し直して、返された再試行リビジョンと同じ論理的入力・キーを使います。ユーザーの編集を保護し、依頼と競合するなら上書きせず確認します。 - 署名アップロードが失効したら新しいアップロード操作キーで準備し直します。失敗した画面追加を別の `uploadId` に変更する場合、前の操作がシーンを作っていないことを確認してから新しい追加キーを使います。 - 必須アクセスや画像がない場合は、不足シーンと必要な操作を示す簡潔な質問を残します。完了した内容とStudioリンクを保持し、最初から作り直さず再開できるようにします。 ## 7. 検証して引き継ぐ `get_project` で実際のシーン数、順序、タイトル、説明、選択された音声状態を依頼と比較し、相違を修正します。各シーンの正確な操作対象、異なる操作・結果の文言、適切なラベルモード、ポインター・フレーム設定も計画と照合し、正規プロジェクトを検証します。 ```json {"tool":"get_project","arguments":{"projectId":""}} ``` ```json {"tool":"validate_project","arguments":{"projectId":"","idempotencyKey":""}} ``` 返された `studioUrl` または `open_studio` アクションの `nextAction.url` を使い、URLを推測しません。認可されたブラウザーアクセスがあれば、実際のStudioのシーン一覧とプレビューで画像・キャプションを確認します。シーン境界をまたいで再生し、クリック合図が目的のコントロールに合うか、結果に実際の変化が見えるか、キャプションが読めて対象を隠さないか、ズームが重要なUIを切らないかを確認します。デスクトップと小さなプレビューの両方で点検します。音声なしも含む読む時間、切り替え警告、Studio専用調整が保存・再読み込み後に保たれるかも確認します。準備完了と伝える前に混雑した文言を短くし、効果を簡素化します。StudioログインがなければMCP検証とは分けて報告し、リンク先の確認をユーザーに依頼します。視覚確認を実施したとは言いません。 最後にプロジェクト名、完了/指定シーン数、短いシーン一覧、適用した視覚的案内、音声状態、Studioリンク、残作業を伝えます。適用済みMCP設定、目視確認済みStudio調整、シーンごとの未完了調整を分けます。必要な画面と説明がすべて存在する場合のみ完了とします。 `validate_project` はStudio編集の検証と準備を行います。MCPに動画レンダリングツールはありません。非公開を維持し、ユーザーがStudioでプレビュー、編集、MP4レンダリング、共有を選べるようにします。検証成功だけで公開リンクや動画が存在すると報告しません。