Skip to main content
Use this guide when you change WorldMonitor’s WebMCP implementation. For host setup, tool schemas, browser-agent workflows, and user-facing limits, see the WebMCP reference. Treat each WebMCP change as a public UI contract change. Tool names, descriptions, schemas, annotations, outputs, visible effects, cancellation policy, security headers, tests, evals, and both language guides must stay aligned.

​
Change checklist

  1. Add or change the canonical name and inventory in src/config/webmcp.ts. Do not create a second name registry.
  2. Define each imperative descriptor and bounded execution path in src/services/webmcp.ts. Reuse an existing human UI path. Do not add a privileged backend shortcut.
  3. Classify the tool as read-only, view-state, cancellation-required, or result-dependent. TypeScript must reject a new imperative tool that has no cancellation policy.
  4. Set accurate readOnlyHint and untrustedContentHint annotations. Keep names, descriptions, parameter descriptions, schemas, outputs, and errors within WEBMCP_TOOL_BUDGETS.
  5. Recheck authentication, entitlement, variant, renderer, mounted state, and capability state at invocation time. Discovery must not grant durable authority.
  6. For a declarative tool, expose attributes only while the real form is connected and usable. Remove them while the form is pending, hidden, resetting, destroyed, or ineligible.
  7. Update docs/webmcp.mdx and docs/zh/webmcp.mdx together. Update both maintenance guides when ownership, verification, or release steps change.
  8. Extend deterministic lifecycle and UI tests. Add direct, ambiguous, wrong-tool, alternate-order, and mid-chain-failure eval cases when tool selection or chaining changes.
  9. If an enrolled route or origin changes, update and test the Vercel, Docker, local Vite, origin-trial, same-origin, and embed-denial headers as one security boundary.
  10. Run the local same-SHA proof, then the production same-SHA smoke. Unit tests and deployment status do not prove production acceptance.

​
Source map

​
Verification ladder

Use Node.js 24. Run focused checks sequentially:
For a browser-visible contract change, also run npm run test:dom and npm run test:e2e:webmcp. A missing browser, origin-trial token, credential, or deployed SHA is a named verification gate. Do not weaken a check to work around it.

​
Release smoke checklist

​
Local, same SHA

Test the exact commit that will ship. This command records its 40-character Git SHA and fails when the checkout is dirty:
The local suite enables Chrome’s WebMCP testing feature and records the SHA in its evidence. It does not prove that a deployment serves that SHA. If the change affects the homepage, run npm run build:pro and inspect /pro/welcome.html. If the change affects conditional registration, inspect every dashboard variant and both eligible and ineligible search_procurement states.

​
Production, same SHA

First confirm in the deployment control plane that the target URL serves the intended SHA. The runner also reads /build-hash.txt from every enrolled dashboard origin.
The headed production suite tests the real origin trial. It verifies the served SHA, security headers, twenty-four-tool inventory and schemas, cold-start invocation, bounded access and sign-in results, read-only catalogs, cancellation behavior, all six dashboard origins, specialized-root redirects, and cross-origin embed denial. Mutation tests that would alter production state remain local. Preserve webmcp-smoke.json, webmcp-cancellation.json, and webmcp-production-matrix.json from test-results/ with the release evidence. Also verify that /embed and /embed.html return tools=(), and that /?mode=agent, preview deployments, documentation, and embed pages do not gain the top-level inventory. Treat the deployment SHA, response headers, inventory, UI behavior, and terminal outcomes as separate assertions. A successful deployment or registration log does not prove acceptance.

​
Compatibility and removal policy

WorldMonitor targets document.modelContext.registerTool() and feature-detects it. It does not ship navigator.modelContext, provideContext, or a draft compatibility shim. If a future browser transition requires a temporary fallback:
  1. Name the exact browser and API gap. Keep the current API as the preferred path.
  2. Preserve same-origin policy, visible UI behavior, authentication and entitlement checks, bounded outputs, privacy rules, and cancellation.
  3. Add contract tests for both paths. Name the removal owner and the Chrome milestone or production verification condition.
  4. Remove the fallback when production verifies the supported current API. Do not leave an undocumented permanent path.
The hosted MCP server remains the supported alternative when WebMCP is unavailable. It is a separate product interface, not a browser fallback. Chrome documents that Chrome 153 can unregister a tool without cancelling in-flight executions. That lifecycle change does not prove that a released browser passes the invocation’s AbortSignal to the page. WorldMonitor’s one-argument callback note is based on recorded Chrome 149–151 evidence. Re-run the production smoke on each browser milestone and update the WebMCP reference from observed results.