WebMCP Kit

View saved version →

---
name: implement
description: Add WebMCP tools to a website codebase so browser agents can act through the site's own logic instead of scraping the page. Use when asked to make a site agent-ready, add WebMCP or document.modelContext tools, or implement site tools with @nekuda/webmcp-sdk.
argument-hint: "[request] [--non-interactive | --no-interactive-loop]"
---

# WebMCP Kit — implement

## Mission
- WebMCP hands a browser agent typed tools (via the `@nekuda/webmcp-sdk` SDK) so it answers from the site's own content and acts through the site's own logic. User and agent share the visible page — every tool produces a visible effect.
- Tools answer "what will a visitor ask, and ask for, here?" — journeys, never REST-endpoint wrappers.
- In every human-facing run, the plan you present in Phase D is approved by the developer **before any file is written**. That gate is the product, not a formality.

## Hard rules
- **Local only.** Never send customer code, routes, or schemas to any external or unauthenticated tool/API. The tool-selection rubric is this skill's text — there is no hosted scanner.
- **Client-reachable wiring only.** `execute` may use the app's own client data layer, same-origin routes, or client-safe actions — never server-only imports, secrets, third-party endpoints, or DOM-scraping when a data path exists.
- **Flag, don't fake.** A journey with no safe client path is listed as *needs developer wiring* — never invented data or a dead call. A guidance-only stub does not "cover" a must-have.
- **Irreversible/cost-bearing writes need a boundary.** A payment, cancellation, or delete must not complete in one agent call. The generated tool stops at a reversible handoff — creates the repo-native pending state (checkout session, pending order, prepared cancellation) and hands the final step to the app's own payment/confirm UI, or uses a prepare→confirm two-call shape. A consequence sentence in the description is not a boundary.
- **Authorization is the server's job.** Registration gating on auth/role is UX, not security. Only wrap a privileged mutation whose route independently enforces authn/authz server-side; an endpoint that trusts a hidden client button is *needs developer wiring*, not a tool.
- **Nothing before approval.** No branch, file, or dependency until the developer approves the plan, except in explicit `--non-interactive` mode. This skill reads with Read/Grep/Glob during A–C — plus one read-only exception: the Phase-F baseline capture (the repo's own typecheck/build, `references/verify.md`) may run as a background task before approval, because it writes nothing to the tree; after approval it requests the write, package-manager, and browser permissions it needs through the normal permission prompts — nothing is pre-authorized.
- **SDK only.** Generated code imports `defineTool` / `registerTools` from the SDK under its resolved name (the installed package's declared name — `references/sdk.md`); never the raw `modelContext` surface, never a bundled polyfill/shadow. The SDK pins the spec, resolves whichever surface the browser exposes, and no-ops when unsupported.

## Session flow (A–F)

**A — Understand the repo** (cheap-first). Stack ID from manifests (`package.json`, `composer.json`, …): framework, rendering mode (SPA/SSR/MPA/static), router, language, package manager, and whether a JS bundler/dependency install even exists (a PHP/static MPA may have none — see `references/codegen.md`). Read high-signal sources before app code: README, `openapi.yml`/swagger, route manifests (`app/`, `pages/`, routes files), sitemap, nav, homepage CTAs. Map the visitor surface — routes→pages, forms, data-layer calls, auth boundaries — recording for each: file, what it does, client-reachable or server-only. **Inventory any existing `@nekuda/webmcp-sdk` usage — including its legacy aliases `@agentlane/webmcp` and `@nekuda/webmcp`, the same SDK** (`defineTool` names and `stableKey`s) so a re-run preserves identity instead of churning it. No stack is privileged (Next.js is not pre-decided); read deeper only where a candidate tool's wiring stays ambiguous.

**B — Select journeys/tools.** Load `references/journeys.md`. Match the repo to a category by `applies_when` → primary (+ secondary with the hybrid downgrade). **No match → tell the customer; never draft against the nearest category.** Simulate a concrete visitor on concrete pages: the questions they ask and actions they request are the spec. Instantiate the matched template's must-haves to this repo's real domain objects, content, and CTAs (a "book a demo" site gets `book_demo`, not `request_quote`). `ask_site` wherever the site has visitor-facing content to answer from — one instance; if there is genuinely none (e.g. an auth-only internal dashboard that matches no category), don't fabricate a content bundle, say so. Stay in the category's count band and global 3–10; thin-content sites get `ask_site` and stop. Fix availability, context, response, and annotations per tool.

**C — Pick the wiring.** Load `references/wiring.md`. For each tool take the highest safe rung (client data layer > same-origin route > client action > content bundle) and name the concrete path. Confidence rule: a tool is **decided** only if its journey is a category must-have AND a rung-1/2 path exists with corroborating evidence (route + handler + UI element agree). Anything else — ambiguous semantics, competing flows, great-to-haves, uncertain category — is **needs your input** with a specific question and a stated default.

**D — Review the plan (hard gate).** Load `references/plan-template.md`. Open every human-facing review with a short summary, identical in substance across entry modes, of what the skill will do and which tools it will create; on the loop path, it is the `_chat.ndjson` handoff (Propose, `references/interactive.md`) shown in the Explorer's conversation panel — the terminal message just points the developer to the Explorer. Then present the plan in the selected review surface **before touching any file**; tool descriptions ship verbatim (description is the product). Edits → revise → re-present. Proceed only on explicit approval. In `--non-interactive` mode, use the stated defaults and Degrade path instead.

**E — Generate.** Load `references/codegen.md`. Load `references/sdk.md` for the exact SDK surface and wiring. Add the SDK dependency the way `references/sdk.md` prescribes; emit the two-module shape as **separate files** — side-effect-free tool modules (`defineTool` at module scope, never inside a component/effect) plus one entry module per registration scope. `stableKey` is `domain.action`, authored once and **never changed on re-runs** (reuse any inventoried in Phase A; never a copy of the wire `name`) — `name` may change freely. Each `description` states what it does, **when to use it**, and what it returns; `inputSchema` sets `additionalProperties: false`. `execute` runs the Phase-C path verbatim and **throws on failure or missing anchors/data** (never succeed-on-missing) — a read that finds nothing is not a failure: it still returns, with the empty result plus an explicit note field saying the site has no matching content, never a bare empty array. Match the repo's language, lint/format config, and file conventions. **If an approved call path proves unusable or the implementation must deviate from the approved plan** (different endpoint, changed behavior or coverage), stop and re-present the change — never silently substitute under a stale approval. Start Phase F's static checks (typecheck/lint/build) after this first write, not only once every file is written — preferably a watch-mode typechecker as a background task (`references/verify.md`), so per-file checks are incremental — a turn-budget cutoff should still land at least one static pass.

**F — Verify.** Load `references/verify.md`. Run the ladder: static → boot → registration on declared pages/auth states → read-only invocation → state-changing only on seeded/dev data with consent. Every tool ends **verified**, **failed**, or **could-not-verify**. Failed blocks the PR (fix or drop — never ship known-broken); could-not-verify ships flagged.

**PR.** Branch `webmcp/tools-v0`; conventional commit; open a PR (approved plan + per-tool verification table as the body) via `gh` when available, else commit on the branch and hand over. Restate could-not-verify items and needs-developer-wiring journeys in the summary.

## Entry and review mode
- Headless intent must be explicit: the `--non-interactive` flag in the invocation or an equally explicit standing instruction in the request text (for example, "proceed without approval" or "non-interactive") counts as that flag. Never infer it from the environment (no TTY sniffing or "seems headless"). A request to reopen or continue an existing run (a `.webmcp/` folder with state) → see **Resume**. A request with neither loads `references/interactive.md` and runs D–F as an interactive browser loop over the git-tracked state folder `.webmcp/` — UI phases propose → build → review → verify → done: approval starts `verify`, and `done` starts only after the PR exists. If the loop is not already running, the agent may offer to start it. Codex uses bundled hooks only when `/hooks` lists them; their automatic run binding is same-task only, with manual replay as the fallback. Claude Code may use Monitor where supported. In every path the skill remains the workflow authority.
- Developer declines the browser loop → continue as `--no-interactive-loop` with chat-only review.
- Bun unavailable (the Startup preflight in `references/interactive.md`) → offer install or chat-only review per that preflight; never infer either choice, and never read missing Bun as non-interactive intent.
- `--no-interactive-loop` → human, chat-only: show the Phase-D summary and plan in chat, then wait for explicit approval. Do not start the browser loop.
- `--non-interactive` → explicit headless: skip the browser loop and use the gate-free Degrade path below.
- If nobody answers the gate and no explicit non-interactive intent was given, stop; inference may never skip the gate.

## Resume
- In the same agent task/session, validate `.webmcp/.run.json` v1 for this canonical workspace and call its run-aware `/healthz?capability=...&run_id=...`. If live, reprint `/?capability=...&run_id=...`, restore that task's available Codex-hook or Claude-Monitor wake path from `references/interactive.md` (otherwise use same-task manual replay), then scan valid current-run envelopes without a handled ack in numeric `order`.
- In the same task, a valid run with a dead server may use `server.ts <workspace> --resume`; use only its printed URL/runtime metadata, restore the same task's delivery, reconcile partial effects, and continue. Runtime metadata absent/invalid means there is no safely resumable identity.
- A fresh task does not inherit the old run's automatic hook binding. It may reconcile current unacked envelopes manually. For continued automatic browser interaction, explicitly rotate per `references/interactive.md`: shut down a live old server or abandon dead runtime metadata, then use normal `server.ts <workspace>` without `--resume` and establish the new task's own run/session. Socket delivery and hook claims are hints; matching journal envelopes plus `_ack.ndjson` remain the truth.

## Degrade paths
- No category match → say so; do not force a weak fit.
- Most must-haves unwireable → **proposal-only** is a legitimate terminal outcome: deliver the reviewed plan, no code, and say why. That is benchmark signal, not failure.
- Explicit `--non-interactive` → proceed automatically: record the plan verbatim as the PR body/summary, implement each needs-your-input item on its stated default, and restate each in the summary as an assumption — the question, the default taken, and why.
- No runnable browser → mark tools could-not-verify and still ship plan-conformant code.

## Environment
- If the working directory ships its own site runbook (lifecycle commands, base URL, test identities — e.g. an eval capsule), use it for boot/reset; otherwise use the repo's own scripts. Never assume a harness exists.
- Browser verification needs WebMCP active: Chrome 150+ flag or `@mcp-b/webmcp-polyfill` — recipe in `references/verify.md`.

Referenced files: 11

View saved version →

---
name: verify
description: Check that a locally running site's WebMCP tools register and execute correctly. Use to verify WebMCP tools, confirm document.modelContext tools appear on the right pages and auth states, or test @nekuda/webmcp-sdk tools in a browser.
argument-hint: "[base URL of the running site]"
---

# WebMCP Kit — verify

Runtime check that a site's WebMCP tools register and work. Runs standalone, and is the ladder the `implement` skill uses in its Phase F.

## Before you start
- The site must run locally. Use its own runbook (lifecycle commands, base URL, test identities) if it ships one; otherwise its own dev script. Never assume a harness exists.
- WebMCP must be active in the browser: Chrome 150+ with the WebMCP flag (`chrome://flags`, enabled for localhost) — or load `@mcp-b/webmcp-polyfill` as backup. Confirm `document.modelContext` (or `navigator.modelContext` on Chrome 149) exists before testing.
- Browser automation is tool-agnostic: a chrome-devtools MCP, a CLI driver, or a guided manual check all work.

## Ladder
1. **Boot.** Site starts; the baseline page renders; no *new* console errors versus a clean load.
2. **Discover.** On each declared page and auth state — check anonymous **and** signed-in where relevant — list the registered tools. Confirm each tool appears where it should, is **absent** where it should not (logged-out account tools, wrong-role tools), and unregisters on its declared exits (empty cart, logout). Navigation is the expensive unit: visit each page × auth state **once** and settle every tool's expectations for that page in that single pass — never one navigation per tool.
3. **Invoke read-only.** Call read-only tools with sample inputs; check the returned data **and** the visible ui_effect. Batch by page: invoke a page's tools in the visit that discovered them.
4. **Invoke state-changing.** Only against local/dev/seeded data, with an explicit go-ahead. **Never** fire real POSTs at third-party or production services. No safe way to invoke → don't; report could-not-verify.

## Report — one state per tool
- **verified** — registered and invoked as declared (note the rung reached).
- **failed** — did not register or errored; must be fixed or dropped, never shipped.
- **could-not-verify** — plausible but unproven (no browser, or no safe way to invoke); ships flagged.

Print a per-tool table and restate any could-not-verify items.