webmcp

WebMCP

手順

ステップ 1：ブラウザーとの統合箇所を特定する

1. ワークスペースを調べて、ブラウザーのエントリーポイント、UI ハンドラー、および既存のアプリ状態管理やフォーム処理のレイヤーを確認します。
2. Node ランタイムを利用できる場合は、node scripts/find-webmcp-targets.mjs . を実行して、フロントエンドと思われるファイルと既存の WebMCP マーカーを一覧表示します。
3. Node ランタイムを利用できない場合は、最も近い package.json、HTML エントリーポイント、およびフレームワークのブートストラップファイルを手動で調べて、ブラウザーアプリの境界を特定します。
4. ワークスペースに複数のフロントエンドアプリがある場合は、アクティブなルート、コンポーネント、またはユーザーが指定した機能の領域を含むアプリを優先します。
5. 一覧を確認しても有力なフロントエンドの候補が複数残る場合は、作業を中断し、どのアプリに WebMCP を統合するかユーザーに尋ねます。
6. プロジェクトがブラウザー向け Web アプリでない場合は、作業を中断し、このスキルが適用されないことを説明します。

ステップ 2：WebMCP の形式を選択する

1. コードを書く前に、references/webmcp-reference.md を読みます。
2. 機能を HTML フォームのフローとして表現できる場合、またはエージェントが呼び出す送信処理が必要な場合は、references/declarative-api.md を読みます。
3. ネイティブ機能の利用可否、Chrome のプレビュー設定、またはドラフト版とプレビュー版の挙動が重要な場合は、references/compatibility.md を読みます。
4. 登録、スキーマのシリアル化、またはエージェント主導のフォーム実行に失敗した場合は、references/troubleshooting.md を読みます。
5. 統合がセキュアなウィンドウのブラウジングコンテキストで実行されることを確認します。
6. 機能をサーバー、ワーカー、または表示可能なブラウジングコンテキストのないヘッドレス環境で実行する必要がある場合は、作業を中断し、プラットフォーム上の制約を説明します。
7. 既存の JavaScript ロジックをツールでラップする場合、動的な登録が必要な場合、または実行のキャンセルに対応する必要がある場合は、命令型 API を選択します。
8. ユーザーフローをフォーム送信にそのまま対応させられ、エージェントの操作中もページ上の人間向けフォームを同期できる場合は、宣言型 API を選択します。
9. ツール名、説明、パラメーターは具体的かつ肯定的な表現にし、相互に重複するバリエーションより、単一機能に絞ったツールを優先します。 ステップ 3：ツールの登録を実装する
10. 命令型 API を使用する場合は、assets/model-context-registry.template.ts を読み、ワークスペースのフレームワーク、状態モデル、ファイル構成に合わせて調整します。
11. 特徴検出パターン const modelContext = document.modelContext || navigator.modelContext; を使ってモデルコンテキストを解決し、その存在を確認してから後続の登録を行います。document.modelContext（現在のサーフェス）を優先し、navigator.modelContext は Chrome 146～149 の旧ビルド向けのフォールバックとしてのみ残します。
12. 命令型ツールは、安定した name（ASCII の英数字、_、-、. のいずれかからなる 1～128 文字）、肯定的な description、オブジェクト形式の inputSchema、および execute コールバックを使い、try／catch 内で modelContext.registerTool() を await して登録します。Chrome 151 以降では、この呼び出しはフレームツリー全体でツールが利用可能になると解決する Promise<void> を返します。await を使用すれば、同期的に登録していた旧ビルドでも同じコードを利用できます。
13. 状態を変更しないツールに限り、annotations.readOnlyHint を true に設定します。
14. Chrome 154.0.8017.0 以降では、旅行の予約、資金の送金、購入、データの削除など、重大な結果を伴う、取り消し不能な、または現実世界での操作を行うツールに annotations.consequentialHint を true に設定します。これにより、エージェントは実行前にユーザーの明示的な確認を求めるようになります。
15. Chrome 156.0.8067.0 以降では、Chrome DevTools の AI 支援など、検査、診断、テストフレームワーク、開発者向けツールを特に目的とするツールに限り、annotations.debugging を true に設定します。これにより、汎用エージェントやエンドユーザー向けエージェントが開発者向けツールを識別し、除外できるようになります。
16. ツールの出力に信頼できないソースのデータが含まれる可能性がある場合は、annotations.untrustedContentHint を true に設定します。
17. スキーマが厳密であっても、ツールの実装内でビジネスルールを検証し、エージェントが入力を修正して再試行できるよう、内容の分かるエラーを返します。
18. UI とアプリケーションの状態にツールの効果が反映されてから、ツールの結果を返します。
19. Chrome 153 以降では、常に存在する { signal } を execute の第 2 引数として受け取り、fetch() など、キャンセル可能な処理に渡します。この実行シグナルは登録シグナルとは別に扱います。
20. ツールの利用可否がルート、選択状態、またはページの状態に依存する場合は、有効な間だけツールを登録し、registerTool() に渡したシグナルを持つ AbortController を中断して、古くなったツールの登録を解除します。Chrome 148 への移行期間中は、中断する前にオプショナルチェーンを使って modelContext.unregisterTool?.() も呼び出します。
21. 宣言型ツールでは、対象の <form> に toolname と tooldescription を指定し、フォームコントロールでパラメーターの範囲を定義します。
22. 宣言型フィールドのパラメーターを明確に説明するには、ラベルまたは toolparamdescription を使用します。
23. エージェントがフォームに入力した後、ページを自動的に送信する必要がある場合に限り、toolautosubmit を使用します。 ステップ 4：エージェント主導の UX を安全に組み込む
24. ページがエージェントによる呼び出しに対応していても、通常の人間による操作経路を維持します。
25. ツールで明示的な確認やユーザー向けのステップが必要な場合は、アプリケーションの可視 UI と既存の認可チェックを経由させます。現在の execute(input, { signal }) コントラクトでは、クライアントコールバックを利用できません。
26. 宣言型の送信処理をカスタマイズする場合は、respondWith() の前に preventDefault() を呼び出し、エージェントから呼び出された送信に対して構造化された検証エラーを返します。
27. toolactivated、toolcancel、agentInvoked などのプレビュー専用イベントや WebMCP フォームの疑似クラスは、互換性を考慮した UI ロジックの中でのみ使用します。toolactivated と toolcancel については、references/declarative-api.md を読み、古いビルド向けに window にフォールバックする前に、document.modelContext 上の on* プロパティを機能検出します。
28. annotations.consequentialHint が true の場合でも、破壊的な操作や機密性の高い操作には、可視のユーザー確認と既存の認可チェックを必ず適用します。このアノテーションはエージェントに情報を伝えるものであり、アプリケーションのセキュリティを強制するものではありません。
29. UI の状態を同期し、人間の入力とツール呼び出しのどちらによって変更が生じた場合も、同じページに正確に反映されるようにします。

ステップ 5：動作を検証する

1. 重複名の防止と、ルートや状態の変更時のクリーンアップを含め、登録と登録解除のライフサイクルをテストします。
2. 無効または不完全な入力をテストし、ツールが暗黙に失敗するのではなく、修正を促すエラーを返すことを確認します。
3. 宣言型ツールでは、生成されたパラメーターの説明、必須フィールド、送信動作、およびカスタムの respondWith() 処理を検証します。
4. 対象環境が現在の Chrome プレビューである場合は、実行時の失敗をアプリケーションのバグと判断する前に、references/compatibility.md で必要なバージョンとフラグの状態を確認します。
5. executeTool() に渡されたシグナルを中断して実行のキャンセルをテストし、ツールの登録解除に頼らず、長時間実行される処理が停止することを確認します。
6. Model Context Tool Inspector または同等のプレビュー用ツールは、検証の補助としてのみ使用し、実行時の依存関係にはしないでください。
7. まず、登録済みツールの一覧を調べ、プレビュー用ツールが利用できる場合は代表的な引数でツールを手動実行して、決定論的な実行を検証します。
8. 決定論的な実行が正しいことを確認した後、説明とパラメーターの形式がエージェントを適切なツールへ誘導することを検証し、自然言語によるルーティングを確認します。
9. 影響の大きい操作、取り消せない操作、または現実世界に作用する命令的なツールでは、annotations.consequentialHint: true が宣言されていることを確認します。また、アプリケーションの確認および認可フローが引き続き適用されることも確認します。
10. 検査、診断、テスト、または開発者向けツール専用のツールでは、annotations.debugging: true が宣言されていることを確認します。ユーザー向けのツールでは、この設定を未指定または false にします。
11. 編集後に、ワークスペースのビルド、型チェック、またはテストを実行します。

エラー処理

• document.modelContext と navigator.modelContext の両方が存在しない場合は、安全なブラウザーウィンドウのコンテキストでコードが実行されていることを確認し、references/compatibility.md のプレビュー要件を確認してください。
• navigator.modelContext だけが存在する場合は、ページが古い Chrome 146–149 のプレビュービルドで実行されています。document.modelContext || navigator.modelContext のフォールバックは維持しつつ、非推奨期間が終了したら navigator.modelContext を削除する計画を立ててください。
• registerTool() は try／catch の中で await してください。Chrome 151.0.7922.0 以降では、失敗時にリジェクトされる Promise<void> を返します。それ以前のビルドでは同期的に返され、例外がスローされていました。同じ await と try／catch で両方を捕捉できるため、以下のエラーチェックは、失敗が同期的な例外として発生する場合と、Promise のリジェクションとして発生する場合のどちらにも適用されます。
• registerTool() が InvalidStateError をスローする場合は、名前の重複、空の name または description の値、128 文字を超えるツール名、または使用できない文字を含むツール名がないか確認してください（使用できるのは ASCII の英数字、_、-、. のみです）。
• registerTool() が NotAllowedError をスローする場合は、tools Permissions Policy の機能が拒否されていないか確認してください。クロスオリジンの iframe では、埋め込み元のドキュメントに allow="tools" が必要です。
• registerTool() が TypeError または JSON シリアル化エラーをスローする場合は、シリアル化できない値や循環参照を含む inputSchema を、プレーンな JSON 互換オブジェクトに置き換えてください。
• 古いデモや記事で provideContext、clearContext、toolparamtitle に言及している場合は、これらのインターフェースは現在の実装では廃止されているものとして扱ってください。
• 宣言型の実行でページが正しく更新されない場合は、ツールの契約を変更する前に references/declarative-api.md と references/troubleshooting.md を確認してください。