build-webmcp-tools

WebMCP ツール開発ワークフロー（build-webmcp-tools）

WebMCP を使うと、ウェブページは document.modelContext 上で、クライアント側の機能を構造化されたツールとしてブラウザー内の AI エージェントに公開できます。これにより、エージェントが DOM をスクレイピングしたりクリックしたりする必要がなくなります。このスキルでは、開発者をツールのライフサイクルにおける適切な段階へ導き、その段階の詳細なルールとコードを収録したリファレンスファイルを案内します。

重要な原則：WebMCP は、ユーザーの認証済みセッション内で、ブラウザータブのクライアント側にある document.modelContext 上で動作します。対応するのはツールのみです（リソースやプロンプトには対応していません）。stdio／SSE を介するバックエンドの MCP サーバーではなく、ツールは入力やクリックをシミュレートするのではなく、アプリケーションのロジック（状態ストア、API、クライアントルーター）を直接実行します。

このスキルの使い方

1. 開発者の依頼に合致する行をルーターで確認し、その段階に進みます。
2. 回答する前に、「最初に読む」列に記載されたファイルを読みます。パスはこのスキルのディレクトリからの相対パスです。このファイルはそれらの内容を要約したものにすぎません。詳細なルール、例、コードパターンはリファレンスに記載されているため、この要約だけをもとに回答しないでください。
3. 依頼で、渡されていない成果物（トランスクリプト、schema.json、ソースファイル）が参照されている場合、ワークスペースにあればそれを読み、なければ提供を求めてください。そのうえで、リファレンスファイルにあるその段階の主要なルールをどのように適用するかを説明します（監査の場合は、検証手順も含めます）。不足している成果物を決して捏造しないでください。
4. 作成するものすべてに必須事項を適用します。
5. 監査、schema.json、または実装を完了する前に、references/audit-checklist.mdに照らして出力を確認します。

---

絶対に守るべき事項

• 予算：ツール名とパラメーター名は 30 文字以下、ツールの説明は 500 文字以下、パラメーターの説明は 150 文字以下、出力は 1,500 文字（約 400 トークン）以下とし、ページ分割します。→ tool-design.md
• 説明：「何をするか＋いつ使うか」（ツールが何をするか、いつ選ぶべきか）を記述します。inputSchema のパラメーターを繰り返してはいけません。実装に関する専門用語（Redux、Pinia、Express、REST、GraphQL、gRPC）は使いません。→ tool-design.md
• 命名と形状：動作を表す動詞を使います。フォームやウィザードを開くツールには initiate_* を使い、即時実行するツールには book_*／create_* を使います。モデルに値の計算（相対日付、単位変換など）をさせてはいけません。ユーザーの表現を受け取り、アプリ内で解決します。ただし、標準コードへの曖昧さのない検索は問題ありません。不透明な ID より名前を優先します。推奨事項：ライフサイクルと注釈を共有するエンティティは、多態的なバッチ処理ツールに統合し、信頼できるコンテンツとユーザー作成コンテンツは別々のツールに保ちます。→ tool-design.md
• 注釈：すべてのヒントは既定で false とし、明示的に指定する場合にのみ設定します（true の場合のみ指定し、: false は決して宣言しません）。readOnlyHint: true は純粋なクエリにのみ設定します。consequentialHint: true は、重大かつ取り消せない現実世界のアクション（支払い、予約、削除）にのみ設定します。画面遷移、タブ切り替え、initiate_* による引き継ぎでは readOnlyHint: true を宣言せず（省略します）、consequentialHint も不要です。これにより、ツール内の未保存の作業を保護します。通常の変更を伴うツールでは注釈を省略します。ユーザーまたは第三者が作成したテキストを含む出力には、自分のデータベースから取得したものであっても untrustedContentHint: true を設定します。→ annotations.md
• エラーをエージェントに伝える：React の useWebMCP は Error をスローします（→ isError: true）。ネイティブの registerTool は { error, code, retryable } を解決します。拒否すると、汎用の DOMException: UnknownError に変換されるためです。宣言的フォームでは、event.respondWith を通じて構造化されたフィールドエラーを解決します。→ error-handling.md
• UI の同期：ツールが返る前に、状態と DOM の更新を待ちます。
• クロスオリジン：ツールは既定で同一オリジンです（Permissions Policy の tools、既定値は self）。委譲する場合は、<iframe allow="tools"> と registerTool(tool, { exposedTo: ['https://trusted.origin'] }) を併用します。オリジンの分離が必要です（Origin-Agent-Cluster: ?0 は WebMCP を無効にします）。→ vanilla-patterns.md
• コーディングの前に設計する：すべてのツールで、Stage 5～6 のスキーマ、評価、コードに進む前に、Stage 2～4（開始時の状態、ロールプレイ、バリエーション、口調、確認の質問、自律性の境界に関する批評）を実施します。実装の簡潔さと会話の簡潔さは別のものです。Stage 2～6 は、各目標のロールプレイ後に開発者の批評を挟む Interactive Mode か、各目標の Stage 2～4 を個別に進めて自己批評し、Stage 5～6 で統合とコード作成まで中断せずに行う Autonomous Mode で実施します。1 つのツールについて設計を省略するよう求められた場合に限り、以下の Explicit Fast Path に従って Stage 2～4 を省略できます。→ conversational-design.md

---

ルーター

開発者の依頼内容	移動先	最初に読むもの	まだ行わないこと
「このプロジェクトに WebMCP を追加して」（ワークスペース内のローカルコードで、URL はない）	Stage 1	プロジェクトの package.json、ルート、主要コンポーネント、conversational-design.md	アプリの機能を尋ねること、Stage 1 より前にコードやスキーマを書くこと
中断せずに一連のスターターツールを作りたい（「設計段階を自律的に進めて」「スターターツールを生成して」）	Autonomous Mode (Stages 1–6) — アプリを調査し、目標ごとに自己批評を行いながら Stages 2–4 を実施し、スキーマ＋評価＋コードを提供	プロジェクトファイル、フレームワークファイル（下記）、conversational-design.md、evals-format.md	Stages 2–4 のロールプレイ／バリエーションを省略すること、質問のために早々に中断すること
特定のツールのアイデアが 1 つある（「フライトを検索するツール」）	その目標に対する Stage 2 または 3	conversational-design.md、use-case-template.md	無関係なポートフォリオを発案すること、コードを書くこと
目標はすでに定義されている	Stage 2	conversational-design.md	目標を再度考案すること
目標＋開始状態	Stage 3	use-case-template.md、conversational-design.md	批評のループを省略すること
強化する対象となるハッピーパスのトランスクリプト	Stage 4	conversational-design.md	—
承認済みのロールプレイ → スキーマと評価	Stage 5	tool-design.md、annotations.md、evals-format.md	モデル化されていない目標向けのツールを考案すること
既存の schema.json → evals.json	Stage 5 (evals)	evals-format.md	Stages 1–4 を強制すること
schema.json／evals.json を作成し終えたところ（「次は何をすればいい？」）	Stage 5 eval gate	evals-format.md	尋ねずに Stage 6 を開始すること
既存のスキーマ、ツール仕様、またはフレームワークコードで実装する名前付きツールがある（例：「list_items と move_items の React useWebMCP ツールを書いて」）	Stage 6	フレームワークファイル（下記）、error-handling.md	会話設計をやり直すこと
ツールを追加したり、ユーザージャーニーを分析したりするための URL またはドメイン（例：example.com、https://...）	chrome-devtools MCP でサイトを探索した後、Stage 1	live-site-discovery.md（最初に読むのは conversational-design.md ではありません）	サイトの説明をユーザーに求めること、chrome-devtools MCP を呼び出す代わりに read_url_content を使ったり推測したりすること、フロントエンドコードを書くこと
既存ツールへのフィードバック、レビュー、監査（ライブサイトまたはローカルコード）	Audit	audit-checklist.md、agent-security.md、error-handling.md	Stage 1 のアイデア出しを最初からやり直すこと
テスト、DevTools、chrome-devtools-mcp によるライブ探索、Lighthouse、ページの準備状況	—	testing-and-debugging.md	圧縮された JS バンドルをスクレイピングすること
概念に関する質問	—	予算／命名／説明：tool-design.md、アノテーション：annotations.md、プロンプトインジェクション、スポットライティング：agent-security.md、エラー：error-handling.md	—
1 つのツールについて設計を省略したい（「ロールプレイを省略してコードを書くだけにできる？」「設計を省略してコードをください」）	明示的なファストパス（下記）— 省略する設計に伴うリスクを述べる 1 文から必ず始めて、その後スキーマ＋評価＋コードを提供	tool-design.md、annotations.md、フレームワークファイル	コードの作成を拒否すること
バックエンド MCP（stdio／SSE サーバー、Node/Python）	対象外	—	サーバーで document.modelContext を使用すること
フレームワークファイル：React → react-patterns.md、Angular → angular-patterns.md、Vanilla JS、Vue、Svelte → vanilla-patterns.md、宣言的 HTML フォーム → declarative-patterns.md。すべてのファイルは references/ にあります。

エントリーポイントが不明な場合：どれに該当するかを尋ねます — 1）ユーザーの目標を把握する、2）開始状態をモデル化する、3）会話をロールプレイする、4）バリエーションで堅牢性を高める、5）schema.json/evals.json を生成する、6）フロントエンドコードに実装する、または既存のツールを監査する。

---

明示的なファストパス

開発者が設計を省略するよう求めた場合（「省略できますか？」と尋ねた場合も含む）のみ、単一のツールに対して適用します。途中での確認を挟まずに新規開発やスターターセットを求められた場合は、自律モードを使用します（Stage 1〜4 は引き続き実施します）。

1. 回答の冒頭で、省略する内容を1〜2文で明示します。例：「ロールプレイを省略すると、曖昧なリクエスト、確認の質問、確認が必要な境界をテストできません。」開発者がリスクを理解していると言っていても、毎回必ず行います。
2. 理由がコードの単純さである場合は、その点も正します。コードが簡単でも会話まで簡単とは限りません（例：「状態を1行で更新するのは簡単ですが、『さっき開いたものを保存して』や重複 URL のような状況でエージェントは失敗します」）。
3. ツールスキーマ、少なくとも1件の evals.json ケース、フレームワークコードを提供します。
4. すべての必須事項（予算、What + When、アノテーション、エラー処理）を引き続き適用します。設計について再び主張する必要はありません。

Stage 1：ユーザー目標のポートフォリオ

• アプリを自分で調べ、そのアプリの実際の機能に基づいた、優先順位付きの候補ジャーニーを3つ提案します。各ジャーニーについて、理想的な結果、必要なコンテキスト、自律境界（ユーザーの確認なしにエージェントが行ってはいけないこと）を示します。
• ライブサイト：ツールは、ヘッドレススクレイピングではなく、ページ内で実行されるコード（ファーストパーティコードまたは拡張機能／コンテンツスクリプト）によって document.modelContext に登録する必要があることを説明します。お使いの環境で chrome-devtools MCP（または別のブラウザツール）が利用できる場合は、ジャーニーを提案する前にすぐに呼び出し（navigate_page、take_snapshot、/llms.txt の確認、list_webmcp_tools / document.modelContext.getTools() の確認）、レンダリングされたページを調べます。静的 HTTP フェッチャー（read_url_content、curl）や学習データに基づく推測には決して頼りません。お使いの環境でブラウザツールが利用できない場合に限り、ジャーニーを提案する前にサイトのページを閲覧または調査し、/llms.txt を確認するよう勧めます。
• Stage 2〜6 について、次の2つの進め方を提示します。
  • インタラクティブモード（目標を一度に1つずつ、開発者によるチェックポイントあり）：目標を1つ選び、Stage 2〜4 を進めます。次に進む前に、ユーザー批評ループ（トーン、確認の質問、自律境界）で一時停止します。
  • 自律モード（エンドツーエンド、エージェントによる自己批評）：エージェントが個別の目標ごとに Stage 2〜4（開始状態、ロールプレイ、バリエーション、自己批評）を中断せずに進め、フレームワークファイルを読み、Stage 5（schema.json、evals.json）と Stage 6（フレームワークコード）を提示します。
• 単一のツールのアイデア（例：「フライトを検索するツール」）：ポートフォリオを省略します。そのリクエストを1つのユーザー目標として扱い（理想的な結果、必要なコンテキスト、自律境界を示し）、そのまま Stage 2 または Stage 3 に進みます。

Stage 2：開始状態マトリクス

• 目標の機能状態をモデル化します：アクティブなルート、読み込まれたエンティティ、カート／選択状態、セッションと認証、制約。
• 無関係な診断情報（device_battery、gpu_temp、screen_dpi）は除外します。

ステージ 3：ターンごとのロールプレイ

• すべてのターンを次の 6 要素で記録します：ユーザーの発話、エージェントの意図、エージェントによるツール呼び出し、ツールの応答（ページネーションフィールド page_size と total_count を含む構造化 JSON、1,500 文字以内）、サイトの実装と UI の反応、エージェントの応答。use-case-template.md の形式を使用してください。
• 支払い、予約、または重大な操作では、人間が介在する UI への引き継ぎをモデル化します（例：initiate_booking が status: "requires_user_action" を返し、自律的にユーザーに課金するのではなく、専用の確認 UI に遷移してユーザーが「確認」をクリックする）。
• 批評ループ（エージェントの態度や口調、確認の質問、自律的な確認の境界を評価する）で締めくくります。対話モードでは一時停止し、開発者に批評を求めます。自律モードでは、各目標についてこの 3 つの観点を明示的に自己批評し、続行します。

ステージ 4：バリエーションと適切なエラー処理

基準となるケースに対してストレステストを行います。必須パラメーターが不足している場合（推測せず、質問する）、前提条件違反（対処可能なエラーを示す）、制約が多すぎるクエリ（条件を緩和する案を提示する）、照応表現（「2 番目のもの」）、および機微な操作での人間が介在する UI への引き継ぎ（status: "requires_user_action" を返し、ユーザーが完了する専用の確認 UI を開く。consequentialHint: true を付けるのは、操作自体を確定するツールのみ）。

ステージ 5：ツールの統合と評価

• 承認済みの目標（反復的な段階導入パスまたはポートフォリオ優先パス）に含まれるツールのみを統合し、すべてのツールに tool-design.md と annotations.md を適用します。
• evals-format.md に従って schema.json と evals.json を作成します。
• その後、今すぐ npx webmcp-evals local -t schema.json -e evals.json を実行するか、ステージ 6 に進むかをユーザーに尋ねます。実行する場合は、.env にプロバイダーキー（Gemini の場合は GOOGLE_AI、または OPENAI_API_KEY / ANTHROPIC_API_KEY）が設定されていることを確認し、高速なモデルを提案します。

ステージ 6：アプリケーションの実装

• まずフレームワークのファイルを読みます。React：use-webmcp-tool の useWebMCP を使用します（コンポーネント内で生の registerTool を使用しない）。スキーマリテラルは外に出すか、安定させ、document.modelContext.registerTool をモックしてキャプチャした execute を呼び出す Vitest + React Testing Library のテストを必ず含めます。Angular：provideExperimentalWebMcpTools。Vanilla：AbortController のシグナルを指定して document.modelContext.registerTool を使用します。宣言的：<form toolname tooldescription>。
• testing-and-debugging.md（DevTools の Application > WebMCP ペイン、Lighthouse の「Agentic browsing」）に従って検証し、audit-checklist.md を使ってセルフチェックします。

監査

1. まず references/audit-checklist.md、references/agent-security.md、references/error-handling.md を読んでから（まとめてリクエストできます）、レビュー対象のコードを開いてください。監査基準となるのは必須事項の要約ではなくチェックリストです。このファイルだけに基づく監査は不完全です。
2. ツールを収集します。
   • ローカルのコードベース：登録コード（useWebMCP、registerTool、provideExperimentalWebMcpTools、<form toolname>）を読みます。
   • 稼働中のサイト：list_webmcp_tools（--categoryExperimentalWebmcp を指定した chrome-devtools-mcp）、await document.modelContext.getTools()、または DevTools の Application > WebMCP パネルを使用して、ルート、タブ、UI の状態をまたいで実行時にツールを検出します（references/testing-and-debugging.md を参照）。document.modelContext が undefined の場合、そのブラウザーでは WebMCP が有効になっていません（--enable-features=WebMCP または chrome://flags/#enable-webmcp-testing）。ツールが存在しないと決めつけず、その前提条件を報告してください。稼働中のサイトでは、圧縮された本番用 JS バンドルを決して取得またはスクレイピングしないでください。稼働中のサイトのソースを調べてよいのは、圧縮されていない場合、またはソースマップがある場合に限ります。
3. チェックリストの項目ごとに、該当するツールと具体的な修正方法を添えて、検出事項を報告します。
4. 最後に検証手順を示します。Chrome DevTools の Application > WebMCP パネル（Play アイコン）でツールを確認して手動実行し、Lighthouse の 「Agentic browsing」 監査を実行してください。
5. まだ利用可能なツールがない場合（例：稼働中のサイトにアクセスできない場合）は、コードを求めるだけで終わらせないでください。ツールの収集方法（コンソールで各ルートを開いて await document.modelContext.getTools() を実行する、chrome-devtools-mcp 経由で list_webmcp_tools を実行する、または DevTools の Application > WebMCP パネルを使う）をユーザーに案内し、監査するチェックリストの項目（予算と専門用語、ナビゲーションおよび UGC を含むアノテーション、エラー処理、セキュリティ）を列挙してください。回答の最後には、手順 4 の検証手順（DevTools での手動実行、Lighthouse の「Agentic browsing」）を記載してください。