add-webmcp

WebMCP を追加する

Web アプリですでに実装されている機能を、保守されるファーストパーティの WebMCP ツールにします。対象のコードベースとそのテストを変更し、ホスト型プロキシやサードパーティのランタイムは導入しないでください。

互換性：バンドルされている Stagehand バリデーターには Node.js 22.18 以降が必要です。検証には、ローカルの Chrome／Chromium、または一般公開されているプレビュー用の BROWSERBASE_API_KEY が必要です。

作業中は詳しく説明してください。最終報告だけでなく、各手順で判明したことをその都度報告してください。

ライブ URL からスタンドアロンの初期化スクリプトを生成する場合は、代わりに webmcp-gen を使用してください。このスキルはソースコードを起点に、ツールをアプリケーションへ統合します。

1. アプリケーションの境界を確認する

対象リポジトリの指示、パッケージマニフェスト、フレームワーク設定、現在の git ステータスを確認してください。無関係な変更は保持してください。

ADD_WEBMCP_SKILL_DIR をこのファイルが含まれるディレクトリに設定し、範囲を限定したスキャナーを実行してください。

node "$ADD_WEBMCP_SKILL_DIR/scripts/scan-codebase.mjs" "$TARGET_REPO"

スキャナーの結果は手がかりとして扱い、確定事項とは見なさないでください。モノレポの場合は、実際のブラウザーアプリと、そのアプリが呼び出すサーバーパッケージを特定してから編集してください。

2. 機能の一覧を作成する

各候補について、ユーザーに見えるエントリーポイントから、クライアントハンドラー、バリデーションスキーマ、サーバー境界、認可チェック、副作用、返される状態までをたどってください。次を確認します。

• ルートと画面；
• フォームとその送信ハンドラー；
• サーバーアクション、API ハンドラー、RPC プロシージャ、サービスクライアント；
• Zod、Valibot、Yup、Joi、JSON Schema、または同等のバリデーター；
• 認証、認可、CSRF、冪等性、レート制限、監査フック。

search_catalog や save_draft のような、ユーザーのタスク全体を完了できるツールを優先してください。エンドポイントごとに機械的にツールを作成しないでください。内部専用／管理者専用の操作、認証の回避、データベースへの直接アクセス、シークレットを扱う操作、UI で現在のユーザーに許可されていない機能は除外してください。

選定した各ツールについて、ソースファイル、既存のバリデーションと認可の境界、副作用、リスク分類、確認動作、安全なフィクスチャ入力を記録してください。詳細な一覧とフレームワークのパターンについては、references/implementation-and-validation.md を参照してください。

3. ツールの契約を設計する

• 安定した動詞と名詞の組み合わせで名前を付け、ユーザーに見える効果、前提条件、重要な対象外事項を説明します。
• アプリケーションに既存のバリデーターまたはドメイン型から JSON Schema を導きます。より緩い契約を別途作らないでください。additionalProperties: false でオブジェクトスキーマを閉じ、実行時のパーサーでも未知のフィールドを拒否するようにします。実行時のパーサーが寛容なままでは、探索用スキーマを閉じても契約は閉じていません。
• コンパクトで JSON にシリアライズ可能なドメイン結果を返します。DOM ノード、認証情報、Cookie、トークン、HTML ドキュメント全体は返さないでください。
• UI と同じクライアント／サービスの境界を呼び出し、既存の検証、認可、可観測性、ビジネスルールが引き続き適用されるようにします。
• ハンドラー内でも再度検証します。エージェントが提供する入力は信頼できません。
• リクエストを結果としてそのまま返さないでください。アプリケーション自身の状態から処理結果を読み取ります。状態が非同期に更新される場合（React やほとんどのリアクティブストアでは、次の行ですぐに変更が反映されるとは限りません）は、状態が確定するまでポーリングしてから読み取り、実際の状態を報告します。そのまま返すと、何も行われていないのにテストが成功してしまいます。

アノテーションは慎重に割り当ててください。

リスク	ツールの設計	アノテーションと確認の動作
読み取り専用	状態を変更しない	readOnlyHint: true を登録します。出力にページ上のテキストやユーザーが制御できるテキストが含まれる場合は、untrustedContentHint: true も追加します
元に戻せる変更	下書き、設定、カートの編集	readOnlyHint: false を登録し、認証と冪等性を維持します。テストには破棄可能な状態のみを使用します
重大または取り消し不能	購入、送信、公開、削除、権限の変更	可能な場合はプレビュー／準備と確定を分けます。宣言的な toolautosubmit は追加しません。最終操作はアプリケーション本来の確認コントロールを通じて行います

登録では、現在の WebMCP のヒント名 readOnlyHint と untrustedContentHint を使用します。Stagehand v4 は検出したアノテーションを readOnly、untrustedContent、また宣言型フォームでは autosubmit に正規化します。これらはブラウザーやエージェントへのヒントであり、セキュリティを強制するものではありません。権限、検証、確認、冪等性、リプレイ攻撃対策はアプリケーション側で適用する必要があります。

4. アプリケーションに統合する

ブラウザーが公開するランタイムのモデルコンテキストを使用します。

const modelContext = navigator.modelContext || document.modelContext;

両方のアクセサーを保持してください。現在の Chrome では、document.modelContext はネイティブの ModelContext として公開されますが、navigator.modelContext は undefined です。そのため、フォールバックは単なる防御的処理ではなく、不可欠です。この機能はブラウザーから提供され、すべてのページで利用できるため、アプリケーションにポリフィルは含まれません。

アプリケーションの準備ができた後、クライアント専用のルートまたはプロバイダーから命令型ツールを登録します。registerTool は Promise を返し、名前ごとに冪等です。再登録すると前の定義が置き換えられ、重複は発生しません。また、登録解除用のハンドルはありません。そのため、アンマウントやホットリロードの際にクリーンアップしなくても安全です。既存のフォームがタスクそのものを正確に表し、ユーザーに見える確認手順を維持することが重要な場合は、宣言型フォーム属性を使用します。

ツールの実行処理で、サーバーのビジネスロジックを重複させないでください。スモークテストを通すために CSRF、同一オリジン、認証、確認のチェックを弱めないでください。ブラウザーのコードにシークレットを埋め込まないでください。

5. 実装を検証する

対象に合わせたテスト、型チェック、本番ビルドを実行します。その後、期待するすべてのツールを含む小さな webmcp.e2e.json を作成します。ツールの検出は必須です。呼び出しはテストケースごとにオプトインで指定し、合成データまたは破棄可能なデータを使用する必要があります。

バリデーターの依存関係を一度インストールします。

pnpm --dir "$ADD_WEBMCP_SKILL_DIR" install --frozen-lockfile

Stagehand が起動するローカルブラウザーで localhost を検証します。

node "$ADD_WEBMCP_SKILL_DIR/scripts/validate-stagehand.mjs" \
  --url http://localhost:3000 \
  --config "$TARGET_REPO/webmcp.e2e.json" \
  --local

ローカル実行はデフォルトでヘッドありのため、検証中にブラウザーを表示できます。CI または無人実行の場合は --headless を渡してください。

ツールが 0 件と報告された場合、コードを疑う前にホストを確認してください。開発サーバーは通常 localhost のみにバインドするため、--url http://127.0.0.1:PORT では何も見つからず、http://localhost:PORT では動作することがあります。この失敗は、ツールがまったく登録されていない場合と同じように見えます。

--browserbase は、一般からアクセス可能なデプロイ済みプレビューでのみ使用してください。バリデーターは、Stagehand v4 の実際の page.tools()、tool.invoke()、invocation.result() の経路を使用します。--allow-consequential を明示的に指定しない限り、重大な影響を伴う呼び出しは拒否します。

注入した init スクリプトはバリデーター自体のテストには便利ですが、対象アプリが独自のツールを提供している証拠にはなりません。アプリケーションの最終確認は、--init-script を指定せずに実行する必要があります。

6. ツールが実際に機能したことを敵対的に検証する

ステップ 5 で確認できるのは、各ツールが検出可能であり、実行処理が動いたことです。ツールが主張どおりに動作したことまでは証明できません。また、設定のテストに合格しても、契約が適切である証拠にはなりません。このステップはステップ 5 が合格した後、最後に実行し、webmcp.e2e.json に記述するのではなく、稼働中のページに対して自分でテストしてください。作者が想定していなかった入力を試すことが目的です。

永続的なブラウザーセッションでページを操作し、実際の状態に対するテストを積み重ねてください。最も手軽な方法は browse CLI です。グローバルインストールは 1 回だけで済み、コマンド間でセッションが維持されます。

browse open http://localhost:3000 --session probe --local --headed
browse eval --session probe '(async()=>{const mc=document.modelContext;const t=(await mc.getTools()).find(x=>x.name==="my_tool");try{return "ACCEPTED "+JSON.stringify(await mc.executeTool(t,JSON.stringify({/* probe input */})));}catch(e){return "REJECTED";}})()'
browse screenshot --session probe --path /tmp/effect.png

次の 3 点に気を付けてください。browse open はデフォルトで クラウド ブラウザーを使用しますが、localhost にアクセスできないため、--local が必要です。browse eval が確実に受け付けるのは 1 行のスクリプトのみなので、コマンドごとに 1 つのテストを実行してください。また、executeTool はツールの オブジェクト と引数を JSON 文字列 として受け取ります。通常のオブジェクトを渡すと、「Failed to parse input arguments」というエラーが発生します。

エラーテキストではなく、拒否されたか受け付けられたかを確認してください。WebMCP レイヤーがハンドラーのメッセージを汎用的な呼び出し失敗の文字列に置き換えるため、正確な理由は呼び出し元に届きません。

検証対象には、発見した tool.inputSchema を使ってください。ただし、それを正解の基準にしてはいけません。各ツールに対して、次のテストを行います。

• スキーマの閉鎖性。 スキーマに定義されていないフィールドを追加して呼び出します。§3 を遵守しているツールなら拒否されます。受け付けられる場合、閉じた契約は形だけです。
• 必須フィールド。 required プロパティを省略します。呼び出しは失敗しなければなりません。エラーではなく、null または部分的な結果を伴う Completed ステータスが返るほうが問題です。エージェントが成功したと思い込むためです。
• 型と制約。 スキーマで number とされている箇所に文字列を送り、minimum／maximum の範囲外の値や、enum に含まれない値も送ります。暗黙の型変換や入力値のそのままの返却が起きるなら、ハンドラーで検証が行われていません。
• エラーの誠実さ。 失敗すべきツールが、成功したような形式の本文を返すのではなく、Completed 以外のステータスを報告することを確認します。
• アノテーションの誠実さ。 各ツールの実際の annotations を、ステップ 3 で割り当てたリスクと比較します。読み取り専用の検索ツールが readOnly: false を宣言している場合も、変更を行うツールが readOnly: true を宣言している場合も、検出自体に合格していても欠陥です。
• 安全な拒否。 上記の不正な入力によるテストの後、アプリケーションの状態を再度読み取ります。拒否された呼び出しによって何も残ってはいけません。呼び出しが途中まで実行されて状態が部分的に残っている場合、受け付けられたか拒否されたかだけでは分からない欠陥です。
• 重大な操作のゲート。 これらは決して呼び出さないでください。ツールがリスクを宣言していること、宣言的な toolautosubmit がないこと、そしてアプリケーション独自の確認操作がエージェントと操作の間に設けられていることを確認します。

次に、戻り値ではなく 効果 を検証します。ツールを呼び出した後、アプリケーションを別の方法で確認してください。描画された状態は DOM アサーションで、キャンバスやグラフの場合はスクリーンショットで確認します。何も変更していないのに {saved: true} を返すハンドラーは、ステップ 5 には合格しても、ここでは不合格です。画面から読み取れる DOM がない場合は、ツールにアプリケーションの実際のストアを読み取らせ、実行処理が作り出した値ではなく、実際の状態に基づいた値が返るようにします。

不一致はすべて、アプリケーションまたはツールの契約における欠陥として扱い、その箇所を修正してください。このステップに合格させるために、スキーマを緩めたり、アノテーションの水準を下げたり、テストを削除したりしてはいけません。

7. 結果の報告

検討した機能を列挙し、対象外とした理由を説明してください。実装した各ツールについて、契約、実装コードのパス、リスク／確認の扱い、Stagehand による実際の検出／呼び出し結果、およびステップ 6 のどの敵対的プローブをクリアしたかを報告してください。テストしていない環境やブラウザーのサポートについても明記してください。

比較ベンチマーク、品質監査、またはスコア付き評価を行う場合は、references/quality-rubric.md を参照してください。数値スコアを報告する前に、同文書の認定ゲートを適用してください。診断スコアが高くても、捏造された動作、安全でない結果の境界、または本番環境での検出不足を見過ごしてはいけません。