/add-webmcp

name: add-webmcp
description: Analyze an existing web application, identify safe user-visible capabilities across routes, forms, server actions, handlers, and schemas, then implement first-party WebMCP tools and validate discovery and invocation with Stagehand. Use when the user asks to make a codebase agent-ready, expose website features as WebMCP tools, or add WebMCP directly to an app rather than generating a standalone injection script from a URL.
compatibility: "Requires Node.js 22.18 or newer. Validation needs Chrome/Chromium locally or BROWSERBASE_API_KEY for a publicly reachable preview."
license: MIT
allowed-tools: Bash Read Grep Edit Write

Add WebMCP

Turn capabilities already implemented by a web app into maintained, first-party WebMCP tools. Modify the target codebase and its tests; do not introduce a hosted proxy or third-party runtime.

Compatibility: the bundled Stagehand validator requires Node.js 22.18 or newer. Validation needs Chrome/Chromium locally or `BROWSERBASE_API_KEY` for a publicly reachable preview.

Be verbose as you work: report what each step found as you go, not only in the final report.

Use `webmcp-gen` instead when the requested output is a standalone init script derived from a live URL. This skill starts from source code and integrates tools into the application.

1. Establish the application boundary

Read the target repository's instructions, package manifests, framework configuration, and current git status. Preserve unrelated changes.

Set `ADD_WEBMCP_SKILL_DIR` to the directory containing this file and run the bounded scanner:

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

Treat scanner results as leads, not conclusions. In a monorepo, identify the actual browser app and the server packages it calls before editing.

2. Build a capability inventory

Trace each candidate from its user-visible entry point through the client handler, validation schema, server boundary, authorization checks, side effect, and returned state. Look at:

• routes and screens;
• forms and their submit handlers;
• server actions, API handlers, RPC procedures, and service clients;
• Zod, Valibot, Yup, Joi, JSON Schema, or equivalent validators;
• authentication, authorization, CSRF, idempotency, rate limits, and audit hooks.

Prefer complete user tasks such as `search_catalog` or `save_draft`, not a mechanical tool per endpoint. Exclude internal/admin-only operations, authentication bypasses, raw database access, secret-bearing operations, and capabilities the UI does not grant the current user.

For each selected tool, record its source files, existing validation and authorization boundary, side effects, risk class, confirmation behavior, and a safe fixture input. Read [references/implementation-and-validation.md](references/implementation-and-validation.md) for the detailed inventory and framework patterns.

3. Design the tool contract

• Use a stable verb-noun name and describe the user-visible effect, prerequisites, and important exclusions.
• Derive JSON Schema from the application's existing validator or domain type. Do not invent a second, looser contract. Close object schemas with `additionalProperties: false` and make the execute-time parser reject unknown fields too; a closed discovery schema backed by a permissive runtime parser is not a closed contract.
• Return compact JSON-serializable domain results. Do not return DOM nodes, credentials, cookies, tokens, or entire HTML documents.
• Call the same client/service boundary as the UI so existing validation, authorization, observability, and business rules remain authoritative.
• Validate again inside the handler. Agent-provided input is untrusted.
• Never echo the request back as the result. Read the outcome from the application's own state, and where that state is updated asynchronously (React and most reactive stores do not reflect a change on the next line), poll until it settles before reading, then report whatever is actually true. Echoing turns a silent no-op into a passing test.

Assign annotations deliberately:

| Risk | Tool design | Annotation and confirmation behavior | | --- | --- | --- | | Read-only | No state mutation | Register `readOnlyHint: true`; add `untrustedContentHint: true` when output includes page or user-controlled text | | Reversible mutation | Drafts, preferences, cart edits | Register `readOnlyHint: false`; preserve auth/idempotency; test only with disposable state | | Consequential or irreversible | Purchase, send, publish, delete, permission changes | Split preview/prepare from commit where possible; do not add declarative `toolautosubmit`; keep the final action behind the app's real confirmation control |

Registration uses the current WebMCP hint names `readOnlyHint` and `untrustedContentHint`. Stagehand v4 normalizes discovered annotations to `readOnly`, `untrustedContent`, and, for declarative forms, `autosubmit`. These are hints to the browser or agent, not security enforcement. The application must enforce permissions, validation, confirmation, idempotency, and replay protection.

4. Integrate with the application

Use the runtime model context exposed by the browser:

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

Keep both accessors: current Chrome exposes `document.modelContext` as a native `ModelContext` while `navigator.modelContext` is `undefined`, so the fallback is load-bearing rather than defensive. The surface is browser-provided and present on any page, so the application ships no polyfill.

Register imperative tools from a client-only root/provider after the application is ready. `registerTool` returns a promise and is idempotent by name — re-registering replaces the previous definition rather than duplicating it, and there is no unregister handle — so remounting and hot reload are safe without teardown. Use declarative form attributes when an existing form already represents