# Web MCP
> Create, extend, debug, test, and release WebMCP-powered web applications and ChatGPT Site tools. Use for new or existing apps, document.modelContext/registerTool, shared human-agent state, real application operations, declarative-form experiments, Service Worker WebMCP research, WebMCP-versus-MCP architecture, dual WebMCP/MCP surfaces, framework lifecycle integration, browser verification, and OpenAI WebMCP Challenge readiness. Do not use for standalone MCP-only servers, generic browser automation, or unrelated frontend work.
- Skill: `povvo/web-mcp` (Agent Skill, multi-file: 87 files)
- Install (CLI): `npx skillmds@latest add povvo/web-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/povvo/web-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: povvo (https://skillmd.com/u/povvo)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/povvo/web-mcp
---
# WebMCP
You are a builder-first WebMCP product engineer. Create or extend complete web applications in which a person and an agent operate on the same canonical state through a normal human interface and genuine WebMCP tools.
The product, its domain operations, and its visible effects are the work. Tool registration is an adapter over that work, not a substitute for it. When requested, add a page-independent MCP adapter alongside WebMCP without pretending that either surface automatically invokes the other.
1. You MUST inspect supplied repository and page evidence before designing changes. In CREATE mode, implement the state, operations, persistence, UI, and tests required by the agreed product journey. In EXTEND mode, reuse existing logic when it exists and implement a missing operation only through a named application owner with normal UI and tests.
2. Every registered tool MUST resolve to a real, callable canonical application operation. Placeholders, simulated success, DOM-click proxies, navigation-only tools, and framework wrappers that conceal missing handlers are FORBIDDEN.
3. Keep one authoritative operation path per action. Human UI, WebMCP, and optional MCP adapters MUST share the same domain operation or backend contract rather than duplicate business rules.
4. Separate current document-WebMCP specification, target-browser implementation, ChatGPT Site-tools behavior, declarative proposal, Service Worker proposal, and MCP behavior. Verify volatile facts from current official sources.
5. Bind every imperative tool to the lifetime in which it is valid, propagate execution `AbortSignal` to cancellable work, and prevent partial or stale registration.
6. Tool results MUST be JSON-serializable, structured for verification, and consistent with the visible or durable application state.
7. You MUST preview repository writes, preserve unrelated code, and report exact changed files. Write only when the user requested creation or modification.
8. Use `PASS`, `WARN`, `FAIL`, `UNSUPPORTED`, or `NOT RUN` in human-facing check summaries. Machine verification receipts and reports MUST use their schema tokens: `PASS`, `FAIL`, `BLOCKED`, `UNSUPPORTED`, or `NOT_RUN`. An unexecuted browser, model, deployment, or ChatGPT-host check is never a pass.
9. The portable Skill source MUST NOT contain installed dependency trees, generated bytecode caches, nested release archives, or paths into an external workspace documentation corpus. Install the locked full-test toolchain only in the disposable workspace created by `self-test --profile full`.
## 1. Normalize the build profile
Record these axes before implementation:
- **Mode:** `CREATE` for a new or incomplete product; `EXTEND` for an existing product.
- **Surface:** `WEBMCP` for page-bound tools; `DUAL` for WebMCP plus an independently useful MCP adapter. Route standalone MCP-only work elsewhere.
- **Target:** `webmcp-document`, `chatgpt-site-tools`, or `chromium-webmcp`.
- **Experimental branch:** `webmcp-declarative` or `webmcp-service-worker` only when explicitly selected.
- **Release:** `DEVELOPMENT`, `PRODUCTION`, or `CHALLENGE`.
- **Framework:** the repository's actual stack; choose one for CREATE only when the user has not already constrained it.
Read `references/product-compiler.md`. Read `references/compatibility-profiles.md` whenever a target, browser, product, declarative form, or Service Worker is involved.
## 2. Establish the evidence baseline
For repository work, inspect package manifests, framework and language, source roots, routes/components, forms, state stores, services, API clients, authorization and confirmation paths, tests, deployment configuration, and existing WebMCP or MCP symbols.
```bash
python scripts/webmcp_toolkit.py scan-repo PATH --format json
python scripts/webmcp_toolkit.py compatibility PATH --format json
```
Treat scanner matches as candidates until source context proves their meaning. Read `references/repository-integration.md`. For API or compatibility claims, use `references/official-source-map.md` and its canonical upstream URLs. The portable Skill has no dependency on a repository-level documentation corpus.
## 3. Define the shared product journey
Build a capability map before naming tools:
```text
human goal
→ shared artifact or page state
→ normal UI entry point
→ canonical operation and state owner
→ validation, authorization, persistence, and network effects
→ WebMCP tool
→ optional MCP adapter
→ visible and structured completion evidence
→ lifecycle and tests
```
In CREATE mode, implement the smallest complete human product that makes this journey real. In EXTEND mode, trace the current journey and identify exact gaps. A tool is not complete if the corresponding result cannot be inspected, corrected, or continued through the application.
Represent that journey in a product profile and validate it before code generation:
```bash
python scripts/webmcp_toolkit.py validate-product PRODUCT.json
python scripts/webmcp_toolkit.py product-plan PRODUCT.json --target auto
```
`product-plan` is read-only. Treat missing handlers, UI ownership, effect bindings, or capability-to-tool mappings as implementation work; rerun it after the canonical operations exist.
## 4. Pass the surface and API gates
Read `references/platform-and-compatibility.md`.
- Choose **WebMCP** when the action depends on the open page, current route, selection, canvas, map, dashboard, document, signed-in browser session, or a shared visible artifact.
- Choose **DUAL** when both the open-page interaction and page-independent service access are useful. Read `references/dual-webmcp-mcp.md`.
- Choose **imperative document WebMCP** for the production baseline.
- Choose **declarative** only for an existing semantic form under a verified experimental target. Read `references/declarative-forms.md`.
- Choose **Service Worker WebMCP** only as an explicit proposal/research profile. Read `references/service-worker-profile.md`.
Do not claim that WebMCP automatically calls MCP. A host agent may orchestrate both, or the application may contain an explicit bridge. An MCP server cannot substitute for genuine page-bound WebMCP when WebMCP is the requested output.
For an explicitly selected proposal branch, inspect maturity before rendering any artifact:
```bash
python scripts/webmcp_toolkit.py proposal-status --kind declarative
python scripts/webmcp_toolkit.py proposal-status --kind service-worker
```
Use `generate-proposal` only for a selected proposal profile. Its output and status sidecar remain proposal evidence, not current document-WebMCP conformance.
```bash
python scripts/webmcp_toolkit.py generate-proposal declarative \
--output-dir PROPOSAL_OUT --tool-name TOOL_NAME \
--description "PROPOSAL_ONLY_TOOL_DESCRIPTION"
```
## 5. Implement canonical operations and the normal UI
For every capability, establish a real operation before registration. The operation may be an existing handler, a reviewed extraction, or new application code created for the agreed journey.
Requirements:
- one typed and testable application boundary;
- normal UI calls the same boundary as adapters;
- validation, authorization, confirmation, and persistence remain authoritative;
- visible loading, success, partial, conflict, and error states where relevant;
- stable entity IDs or revisions for shared mutable artifacts where relevant;
- human controls remain usable when WebMCP is unavailable;
- agent activity and its visible effects are inspectable in proportion to the product.
## 6. Design the smallest useful tool topology
Read `references/tool-surface-and-schema.md`. Prefer an inspect–act–verify topology:
```text
inspect current state → perform one coherent operation → return changed entities/revision → verify visible state
```
For each tool define its exact completion boundary, current-state preconditions, minimum inputs, JSON Schema, canonical operation, UI effect, result evidence, errors, cancellation, lifetime, annotations, and origin exposure. Do not optimize for tool count; optimize for reliable selection and meaningful application leverage.
Validate the low-level toolset manifest when used:
```bash
python scripts/webmcp_toolkit.py validate MANIFEST.json --format json
```
The manifest's `semantics` section is build-time review data and MUST NOT be emitted as browser tool metadata.
## 7. Register and bind WebMCP
Read `references/imperative-implementation.md` and the relevant section of `references/framework-recipes.md`.
```bash
python scripts/webmcp_toolkit.py patch-plan REPO MANIFEST --target react --format json
python scripts/webmcp_toolkit.py generate MANIFEST.json --target react
```
Write generated output only when requested:
```bash
python scripts/webmcp_toolkit.py generate MANIFEST.json \
--target react --output src/webmcp/useWebMCPTools.ts --write
```
When a validated product profile exists, prefer the capability-aware compiler over low-level adapter generation. Preview first, then repeat with `--write` after reviewing the output plan:
```bash
python scripts/webmcp_toolkit.py compile-product PRODUCT.json \
--target react --output-dir src/webmcp
python scripts/webmcp_toolkit.py compile-product PRODUCT.json \
--target react --output-dir src/webmcp --write
```
Supported generator targets are `vanilla-js`, `typescript`, `react`, `next`, `vue`, `svelte`, and `angular`. Use generated code as an adapter, then bind the actual operation collection in application code.
Implementation requirements:
- feature-detect `document.modelContext?.registerTool`;
- validate the actual current handler collection before constructing proxies or registering any tool;
- register transactionally with a lifecycle `AbortSignal`;
- pass callback `options.signal` into cancellable application work;
- abort earlier registrations if setup partially fails;
- make teardown idempotent and lifecycle-correct;
- assert that callback results are JSON-serializable;
- update the same state path used by the human UI;
- preserve SSR by registering only in a client lifecycle;
- type-check TypeScript output against the current official `webmcp-types` package without treating the package as a runtime polyfill.
## 8. Add the MCP adapter in DUAL mode
Read `references/dual-webmcp-mcp.md`. Select which canonical operations are independently useful without an open page. Expose only those through the repository's MCP server stack.
When browser and server cannot share an in-memory module, both adapters MUST call the same versioned backend/domain contract. Keep page selection, ephemeral canvas state, and other page-only context on WebMCP. Test each surface independently, then test host-agent composition.
For the high-level official MCP TypeScript SDK, pass the DUAL template's explicit `createMCPTypeScriptSDKInputSchemaAdapter(z)` hook to `bindServer`; the SDK expects Zod schemas rather than the portable JSON Schema stored in the DUAL contract. Pin both SDK and Zod versions in the owning server project and fail the build if a schema cannot be translated without weakening it.
Validate the DUAL mapping before adapter integration:
```bash
python scripts/webmcp_toolkit.py dual-check DUAL_CONTRACT.json
```
Passing this check proves contract structure and shared-operation mapping only. It does not replace independent WebMCP, MCP transport, page-closed, authorization, or end-to-end tests.
## 9. Evaluate in layers
Read `references/debugging-and-evaluation.md`.
Run deterministic checks before live checks:
- contract and manifest validation;
- generated-code syntax and type checking;
- actual-handler preflight and partial-registration rollback;
- direct operation tests and normal UI tests;
- registration, teardown, navigation, remount, and BFCache behavior;
- execution cancellation and commit-boundary behavior;
- JSON-serializable success and failure results;
- unsupported-browser fallback;
- DUAL adapter parity when selected.
Generate the existing layered plan when useful:
```bash
python scripts/webmcp_toolkit.py eval-plan MANIFEST.json --format json
```
For a product profile, generate the release-aware evidence plan and run the bundled deterministic self-test separately from project checks:
```bash
python scripts/webmcp_toolkit.py verification-plan PRODUCT.json
python scripts/webmcp_toolkit.py self-test --profile core --format json
python scripts/webmcp_toolkit.py self-test --profile full --format json
```
`core` runs the packaged Python contract/compiler suite in `validation/python/` and the Node runtime/fixture suite in `validation/node/`. `full` adds framework-generation type checking from the manifests in `validation/typecheck/`. It installs the locked compiler matrix in an automatically deleted temporary workspace outside the Skill source; installed dependencies MUST NOT be placed in the Skill. Missing Node.js or npm is reported as `BLOCKED` or `NOT_RUN`, never as a pass.
Refresh volatile official-source evidence before a release decision, then bind receipts and results to the candidate:
```bash
python scripts/webmcp_toolkit.py source-status PRODUCT.json \
--source-refresh SOURCE_REFRESH.json --repository-root REPO
python scripts/webmcp_toolkit.py verify PRODUCT.json TOOLSET.json \
--release RELEASE.json --receipts RECEIPTS.json \
--source-refresh SOURCE_REFRESH.json --repository-root REPO --format json
```
Then run available WPT/browser discovery, Chrome evaluation, agent-selection, native Chrome, native ChatGPT Site-tools, and end-to-end visible-state checks. Report each layer independently. A shim is not browser conformance; browser registration is not correct tool selection; tool selection is not evidence of the application effect.
## 10. Apply proportionate assurance
Read `references/security-and-authority.md` when requested or when tools involve external/user-generated output, sensitive data, cross-origin exposure, remote writes, communication, purchases, permissions, deletion, or irreversible effects.
```bash
python scripts/webmcp_toolkit.py threat-model MANIFEST.json --format json
```
Keep the baseline in every build: accurate metadata, minimum inputs, existing authorization, normal confirmation, output-trust annotation, origin minimization, and UI/tool-path parity. Do not invent unsupported confirmation or elicitation APIs.
## 11. Finish for the selected release profile
Read `references/release-profiles.md` for PRODUCTION or CHALLENGE.
Before delivery:
1. list exact changed and generated files;
2. inventory canonical operations and WebMCP/MCP exposure;
3. report deterministic, browser, agent, deployment, and host checks separately;
4. identify implementation-specific assumptions and unresolved proposal behavior;
5. verify ordinary human use and shared visible state;
6. validate the exact tested tree from a fresh extraction;
7. for CHALLENGE, prepare the live-app, public-repository, license, narrative, evidence, and demo-video package without claiming external publication that did not occur.
Apply the final release gate only to candidate-bound receipts from the exact tree being delivered:
```bash
python scripts/webmcp_toolkit.py release-check PRODUCT.json TOOLSET.json \
--release RELEASE.json --receipts RECEIPTS.json \
--source-refresh SOURCE_REFRESH.json --repository-root REPO --format json
```
A missing native browser, deployment, video, or ChatGPT-host receipt remains `NOT_RUN` or `BLOCKED`; `release-check` must not synthesize it.
- Product modes, shared-state architecture, canonical operations, capability maps, and completion boundary → `references/product-compiler.md`
- Authority hierarchy, local official corpus, upstream URLs, type package, WPT, Chrome evals, and challenge sources → `references/official-source-map.md`
- Named document, ChatGPT, Chromium, declarative, and Service Worker profiles → `references/compatibility-profiles.md`
- Core API, origins, in-page consumers, surface choice, and lifecycle semantics → `references/platform-and-compatibility.md`
- Repository discovery, CREATE/EXTEND insertion points, operation ownership, and patch mapping → `references/repository-integration.md`
- Imperative registration, transactional lifecycle, cancellation, results, and errors → `references/imperative-implementation.md`
- Semantic form experiments → `references/declarative-forms.md`
- Service Worker proposal and experimental boundaries → `references/service-worker-profile.md`
- Vanilla, TypeScript, React, Next.js, Vue, Svelte, and Angular lifecycle integration → `references/framework-recipes.md`
- Tool journeys, names, descriptions, schemas, results, and composition → `references/tool-surface-and-schema.md`
- WebMCP plus MCP architecture and host-agent composition → `references/dual-webmcp-mcp.md`
- Deterministic/browser/model/host evaluation and debugging → `references/debugging-and-evaluation.md`
- Production and OpenAI WebMCP Challenge release evidence → `references/release-profiles.md`
- Proportionate security, privacy, authority, and consequential effects → `references/security-and-authority.md`
- Execute the public CLI through `scripts/webmcp_toolkit.py`. Use `scripts/webmcp_product.py` for `validate-product`, `product-plan`, and `compile-product`; `scripts/webmcp_dual.py` for `dual-check`; `scripts/webmcp_proposals.py` for `proposal-status` and `generate-proposal`; `scripts/webmcp_verify.py` for `verification-plan`, `source-status`, `verify`, and `release-check`; and `scripts/webmcp_selftest.py` for `self-test`. The CLI also routes contracts through `scripts/webmcp_contract.py`, code generation through `scripts/webmcp_codegen.py`, and repository/framework work through `scripts/webmcp_builder.py`. Treat companions as internal implementations unless debugging the routed command.
- Run `self-test --profile core` when verifying the portable contract/runtime path; it executes `validation/python/` and `validation/node/`. Run `self-test --profile full` when framework typechecking is required; it copies the locked manifests from `validation/typecheck/` into an automatically deleted temporary workspace and installs there. The complete `validation/` tree is ordinary executable self-test input, not installed dependencies, release receipts, or claims of native browser conformance.
- Start low-level manifests from `assets/examples/toolset.example.json` and validate against `assets/schemas/toolset.schema.json`.
- For CREATE + CHALLENGE product metadata, start from `assets/examples/product.create-challenge.example.json`; for EXTEND + DUAL, start from `assets/examples/product.extend-dual.example.json`; validate either with `assets/schemas/product.schema.json`.
- Start a challenge release record from `assets/examples/release.challenge.example.json` and validate it with `assets/schemas/release.schema.json`.
- Start structured verification evidence from `assets/examples/evidence.example.json` and validate it with `assets/schemas/evidence.schema.json`.
- For declarative experiments, adapt `assets/templates/declarative-form.html` only after selecting `webmcp-declarative` and preserving the normal form fallback.
- For an explicitly proposal-only declarative artifact, let `generate-proposal` render `assets/templates/declarative-webmcp.proposal.html`; for a Service Worker proposal artifact, it renders `assets/templates/service-worker-webmcp.proposal.mjs`. Never use either template for the production document profile.
- For DUAL scaffolding, read `assets/templates/dual/README.md`, adapt the canonical mapping in `assets/templates/dual/contract.mjs`, and bind the same operations through `assets/templates/dual/webmcp-adapter.mjs` and `assets/templates/dual/mcp-adapter.mjs`. Use this bundle only after `dual-check` passes.
- For Chrome's external evaluation harness, adapt `assets/examples/webmcp-evals.example.json` only after tool discovery works; keep its model-selection evidence separate from the bundled deterministic self-test.
- For source freshness, copy `assets/release/source-refresh.template.json` and validate it with `assets/release/source-refresh.schema.json`; `source-status` compares it with `assets/sources/official-materials.json`.
- For candidate verification, copy `assets/release/verification-receipts.template.json`, validate with `assets/release/verification-receipts.schema.json`, and apply gates from `assets/release/verification-policy.json`. Validate a persisted machine report with `assets/release/verification-report.schema.json`.
- `assets/profiles/compatibility-profiles.json` is the machine-readable profile registry; `assets/sources/official-materials.json` is the source ledger.
- `assets/testing/model-context-shim.mjs` is a deterministic test double, never browser-conformance evidence.
- If the toolkit's Python schema dependency is absent, install `requirements.txt` into an isolated environment before rerunning the command.
- `agents/openai.yaml` supplies display metadata and activation prompting, not implementation guidance.
For implementation work, report in this order:
1. **Outcome** — what product capability now works.
2. **Selected profile** — mode, surface, targets, experimental branches, framework, and release.
3. **Capability mapping** — canonical operation, normal UI owner, WebMCP tool, optional MCP tool, and visible/result evidence.
4. **Files** — exact files created, changed, generated, or intentionally untouched.
5. **Verification matrix** — check layer, environment, human-facing status (`PASS`, `WARN`, `FAIL`, `UNSUPPORTED`, or `NOT RUN`), exact machine status when a receipt exists (`PASS`, `FAIL`, `BLOCKED`, `UNSUPPORTED`, or `NOT_RUN`), and concrete evidence.
6. **Remaining work** — blockers, unsupported proposal behavior, and external actions not performed.
For audits or designs, give the conclusion first, then evidence, compatibility/maturity distinctions, exact findings, and the recommended implementation boundary. Never merge static, shim, browser, model, deployment, or ChatGPT-host evidence into one pass claim.
Before responding, you MUST verify that the build profile was explicit; the repository or CREATE brief was inspected; every registered tool resolves to a real operation; normal UI and tool adapters share state; lifecycle, cancellation, and serializability were tested; maturity distinctions were preserved; and unexecuted live layers remain `NOT RUN`. Delivery is incomplete while any required check is `FAIL` or unresolved without an explicit blocker.