---name: webmcpdescription: Implements and debugs browser WebMCP integrations in JavaScript or TypeScript web apps. Use when exposing imperative tools through document.modelContext (with a navigator.modelContext fallback), annotating HTML forms for declarative tools, handling agent-invoked form flows, or validating WebMCP behavior in the current Chrome preview. Don't use for server-side MCP servers, REST tool backends, or non-browser providers.license: MITmetadata: author: webmaxruversion: 1.8---

WebMCP

Procedures

Step 1: Identify the browser integration surface

1. Inspect the workspace for browser entry points, UI handlers, and any existing app state or form handling layer.
2. Execute node scripts/find-webmcp-targets.mjs . to inventory likely frontend files and existing WebMCP markers when a Node runtime is available.
3. If a Node runtime is unavailable, inspect the nearest package.json, HTML entry point, and framework bootstrap files manually to identify the browser app boundary.
4. If the workspace contains multiple frontend apps, prefer the app that contains the active route, component, or user-requested feature surface.
5. If the inventory still leaves multiple plausible frontend targets, stop and ask the user which app should receive the WebMCP integration.
6. If the project is not a browser web app, stop and explain that this skill does not apply.

Step 2: Choose the WebMCP shape

1. Read references/webmcp-reference.md before writing code.
2. Read references/declarative-api.md when the feature can be expressed as an HTML form flow or needs agent-invoked submit handling.
3. Read references/compatibility.md when native availability, Chrome preview setup, or draft-versus-preview behavior matters.
4. Read references/troubleshooting.md when registration, schema serialization, or agent-driven form execution fails.
5. Verify that the integration runs in a secure window browsing context.
6. If the feature must run on the server, in a worker, or headlessly without a visible browsing context, stop and explain the platform limitation.
7. Choose the imperative API when the tool wraps existing JavaScript logic, requires dynamic registration, or must handle execution cancellation.
8. Choose the declarative API when the user flow already maps cleanly to a form submission and the page can keep the human-visible form in sync with agent activity.
9. Keep tool names, descriptions, and parameters explicit and positive, and prefer atomic tools over overlapping variants.

Step 3: Implement tool registration

1. Read assets/model-context-registry.template.ts and adapt it to the framework, state model, and file layout in the workspace when using the imperative API.
2. Resolve the model context with the feature-detection pattern const modelContext = document.modelContext || navigator.modelContext; and guard subsequent registration on its presence. Prefer document.modelContext (the current surface) and keep navigator.modelContext only as a fallback for older Chrome 146–149 builds.
3. Register imperative tools by awaiting modelContext.registerTool() inside a try/catch, using a stable name (1–128 ASCII alphanumeric/_/-/. characters), a positive description, an object inputSchema, and an execute callback. On Chrome 151+ the call returns a Promise<void> that resolves when the tool is available across the frame tree; await keeps the same code working on older builds that registered synchronously.
4. Set annotations.readOnlyHint to true only for tools that do not modify state.
5. On Chrome 154.0.8017.0+, set annotations.consequentialHint to true for tools that perform high-stakes, irreversible, or real-world actions such as booking travel, transferring funds, making purchases, or deleting data. This signals the agent to obtain explicit user confirmation before execution.
6. On Chrome 156.0.8067.0+, set annotations.debugging to true only for tools intended specifically for inspection, diagnostics, testing frameworks, or developer tooling such as Chrome DevTools AI assistance. This lets general-purpose and end-user agents identify and filter out developer-focused tools.
7. Set annotations.untrustedContentHint to true when the tool's output may contain data from untrusted sources.
8. Validate business rules inside the tool implementation even when the schema is strict, and return descriptive errors that help the agent retry with corrected input.
9. Return tool results only after the UI and application state reflect the tool's effect.
10. On Chrome 153+, accept the always-present { signal } as the second execute argument and pass it to cancellable work such as fetch(). Treat this execution signal separately from the registration signal.
11. If tool availability depends on route, selection, or page state, register tools only while they are valid and unregister stale tools by aborting the AbortController whose signal was passed to registerTool(); during the Chrome 148 transition window, also call modelContext.unregisterTool?.() with optional chaining before aborting.
12. For declarative tools, annotate the target <form> with toolname and tooldescription, and let form controls define the parameter surface.
13. Use labels or toolparamdescription to produce clear parameter descriptions for declarative fields.
14. Use toolautosubmit only when the page should submit automatically after the agent populates the form.

Step 4: Wire agent-driven UX safely

1. Preserve the normal human interaction path even when the page supports agent invocation.
2. When a tool needs explicit confirmation or a user-facing step, route it through the application's visible UI and existing authorization checks; the current execute(input, { signal }) contract does not provide a client callback.
3. When customizing declarative submit handling, call preventDefault() before respondWith() and return structured validation errors for agent-invoked submits.
4. Use preview-only events such as toolactivated, toolcancel, agentInvoked, and WebMCP form pseudo-classes only behind compatibility-aware UI logic. For toolactivated and toolcancel, read references/declarative-api.md and feature-detect their on* properties on document.modelContext before falling back to window for older builds.
5. Keep destructive or sensitive actions gated behind visible user confirmation and existing authorization checks, even when annotations.consequentialHint is true; the annotation informs the agent but does not enforce application security.
6. Keep UI state synchronized so the same page accurately reflects changes caused by human input and tool calls.

Step 5: Validate behavior

1. Test the register and unregister lifecycle, including duplicate-name protection and cleanup on route or state changes.
2. Test invalid or incomplete inputs to confirm the tool returns corrective errors instead of silently failing.
3. For declarative tools, verify generated parameter descriptions, required fields, submit behavior, and any custom respondWith() handling.
4. If the target environment is the current Chrome preview, confirm the required version and flag state from references/compatibility.md before treating runtime failures as application bugs.
5. Test execution cancellation by aborting the signal passed to executeTool() and verify that long-running work stops without relying on tool unregistration.
6. Use the Model Context Tool Inspector or equivalent preview tooling only as a validation aid, not as a runtime dependency.
7. Validate deterministic execution first by inspecting the registered tool set and manually invoking the tool with representative arguments when preview tooling is available.
8. After deterministic execution is correct, validate natural-language routing so descriptions and parameter shapes guide the agent toward the correct tool.
9. Verify that every high-stakes, irreversible, or real-world imperative tool declares annotations.consequentialHint: true and still enforces the application's confirmation and authorization flow.
10. Verify that tools intended specifically for inspection, diagnostics, testing, or developer tooling declare annotations.debugging: true, and that user-facing tools leave it unset or false.
11. Run the workspace build, typecheck, or tests after editing.

Error Handling

• If both document.modelContext and navigator.modelContext are missing, confirm the code is running in a secure browser window context and then check the preview requirements in references/compatibility.md.
• If only navigator.modelContext is present, the page is running on an older Chrome 146–149 preview build; keep the document.modelContext || navigator.modelContext fallback in place but plan to drop navigator.modelContext once the deprecation window closes.
• Await registerTool() inside a try/catch. On Chrome 151.0.7922.0+ it returns a Promise<void> that rejects on failure; older builds returned synchronously and threw. The same await + try/catch catches both, so the error checks below apply whether the failure surfaces as a synchronous throw or a Promise rejection.
• If registerTool() throws InvalidStateError, check for duplicate names, empty name or description values, or tool names that exceed 128 characters or contain disallowed characters (only ASCII alphanumeric, _, -, . are allowed).
• If registerTool() throws NotAllowedError, check whether the tools Permissions Policy feature is denied; cross-origin iframes need allow="tools" from the embedding document.
• If registerTool() throws TypeError or JSON serialization errors, replace non-serializable or circular inputSchema values with plain JSON-compatible objects.
• If an older demo or article references provideContext, clearContext, or toolparamtitle, treat those surfaces as obsolete for current implementations.
• If declarative execution does not update the page correctly, read references/declarative-api.md and references/troubleshooting.md before changing the tool contract.