webmcp
/webmcp
Przygotowuje stronę do użycia przez agentów AI w przeglądarce: planuje ścieżki użytkownika i wdraża je przez document.modelContext.
Ocena i bezpieczeństwo
- Pliki w paczce
- 12
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 4
Brak sygnałów. Repozytorium zmienione 07.09.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Przygotowuje stronę do użycia przez agentów AI w przeglądarce: planuje ścieżki użytkownika i wdraża je przez document.modelContext.
Wyzwalacze z opisu
Oryginalny opis (EN)
This skill should be used when the user asks to make a website or web app "WebMCP-compatible", "agent-ready", or usable by in-browser AI agents, or mentions WebMCP, document.modelContext, navigator.modelContext, registerTool, declarative form tools (toolname/tooldescription), or exposing page tools to browser agents. Plans which user journeys to expose, then implements them on the standard document.modelContext API and verifies them in a real browser.
Jak działa
- Hard rules
- Workflow
- Decision tree
- Anti-patterns
- Sources of truth
Podgląd SKILL.md
---
name: webmcp
description: >-
This skill should be used when the user asks to make a website or web app
"WebMCP-compatible", "agent-ready", or usable by in-browser AI agents, or
mentions WebMCP, document.modelContext, navigator.modelContext, registerTool,
declarative form tools (toolname/tooldescription), or exposing page tools to
browser agents. Plans which user journeys to expose, then implements them on
the standard document.modelContext API and verifies them in a real browser.
---
# WebMCP: make a website agent-ready
WebMCP lets a **web page** register typed tools that in-browser AI agents call
directly, so agents act through the site's own logic instead of scraping the
DOM. It is not a remote MCP server and not a ChatGPT/Claude MCP App.
Canonical surface: `document.modelContext.registerTool(...)` (the only surface
in the current spec). `navigator.modelContext` is a deprecated Chrome ≤149
legacy surface; new code detects `document` only. Declarative surface: HTML
`<form>` attributes (`toolname`, `tooldescription`), currently a Chrome origin
trial. Exact API contract: [references/spec.md](references/spec.md).
**Do not use this skill** for building remote MCP servers or MCP Apps. For a
read-only agent-readiness report with no code changes, use the `audit` skill
from this plugin instead.
## Hard rules
1. **No file is written before the plan is approved.** Which journeys become
tools is a product decision; present the proposal and wait for an explicit
yes. Skipping the gate is the primary failure mode of this workflow.
2. **Standard API only.** Generated code targets `document.modelContext` with
feature detection and graceful no-op. Never invent a wrapper SDK; never
import a vendor SDK the repo does not already use. The one dependency this
plugin may add is `@ora-ai/webmcp-bridge`, and only for an approved Bridge
strategy.
3. **Imperative is the interoperable default.** Declarative form annotations
reach only Chrome's preview today; runtimes that read registered tools —
ChatGPT Site tools among them — never see form attributes. When the target
runtime is unknown, or includes ChatGPT Site tools, ship every journey
imperatively.
4. **Client-reachable wiring only.** `execute` may call the app's client data
layer, same-origin routes, or client-safe actions. Never server-only
imports, secrets, or third-party endpoints. A journey with no safe client
path is reported as *needs developer wiring*, never faked.
5. **Authorization stays on the server.** Registration gating by auth state is
UX, not security. Only wrap mutations whose routes independently enforce
authn/authz server-side.
6. **Irreversible or cost-bearing writes stop at a reversible boundary.**
Payments, deletes, cancellations never complete in one agent call: create
the app's own pending state and hand the final step to the app's confirm
UI, or use a prepare/confirm two-call shape.
7. **Code and analysis stay local.** Never send the repo's code, routes, or
schemas to any external service.
## Workflow
Copy and track:
```
WebMCP progress:
- [ ] 1. Inventory the app (read-only)
- [ ] 2. Propose journeys + strategy (HARD GATE: wait for approval)
- [ ] 3. Wire the runtime
- [ ] 4. Implement the approved plan
- [ ] 5. Verify in a browser (mandatory)
- [ ] 6. Harden
```
### 1. Inventory (read-only)
Identify the stack from manifests: framework, rendering mode (SPA / SSR /
MPA / static), router, package manager, whether a bundler exists at all.
Read high-signal sources before app code: README, route manifests, sitemap,
nav, homepage CTAs, existing `<form>` elements, the client data layer, auth
boundaries. Check for an existing remote MCP server and any existing WebMCP
registration (search for `modelContext`, `registerTool`, `toolname`). Batch
these reads in parallel; do not read one file per turn.
### 2. Propose journeys and strategy (hard gate)
Read [references/strategies.md](references/strategies.md) and
[references/tool-design.md](references/tool-design.md) together.
Think in **visitor journeys, not endpoints**: put a concrete visitor on
concrete pages and list what they would ask and ask for. Most sites converge
on 3-10 tools; a content-only site gets one retrieval tool and stops. For
each candidate tool decide: strategy (Imperative / Declarative / Bridge),
availability (which pages, which auth states), input, UI and state outcome,
and annotations.
Present the plan in this shape and **stop until the user approves**:
```
Proposed WebMCP tools:
- [strategy] tool_name — input -> UI/state outcome (pages, auth state)
- ...
Needs developer wiring (no safe client path): ...
Out of scope this round: ...
```
Tool descriptions ship verbatim from the approved plan; the description is
the product. If implementation later forces a deviation, stop and re-present.
### 3. Wire the runtime
Skip when the plan is Declarative-only. Otherwise ensure
`document.modelContext` exists (native or polyfill), with feature detection
that no-ops on unsupported browsers. Secure context (HTTPS or localhost) is
required. Details, polyfill choice, and iframe permissions policy:
[references/runtime.md](references/runtime.md).
### 4. Implement
Pick the per-strategy guide, then the framework guide that matches the stack:
- Imperative `registerTool` design (naming, schemas, returns, lifecycle):
[references/tool-design.md](references/tool-design.md)
- Declarative form annotations (Chrome preview reach only):
[references/declarative-forms.md](references/declarative-forms.md)
- Bridge to an existing MCP server (`@ora-ai/webmcp-bridge`, or
Cloudflare's zero-code toggle when the site is on Cloudflare); never
hand-wrap each remote tool:
[references/bridge-existing-mcp.md](references/bridge-existing-mcp.md)
- Framework wiring: [references/frameworks/react-next.md](references/frameworks/react-next.md),
[references/frameworks/vue.md](references/frameworks/vue.md),
[references/frameworks/svelte.md](references/frameworks/svelte.md),
[references/frameworks/vanilla-mpa.md](references/frameworks/vanilla-mpa.md)
Non-negotiables for imperative tools (full contract in
[references/spec.md](references/spec.md)):
1. Feature-detect before `registerTool`; human UI must survive a browser
without WebMCP
2. Pass `{ signal }` at registration; abort to unregister
(`unregisterTool()` does not exist)
3. Honor `execute`'s `{ signal }` in fetches and long work
4. `annotations.readOnlyHint` must match reality;
`untrustedContentHint: true` when returns carry user or third-party text
5. Validate input inside `execute`; fail by **returning**
`{ error: "actionable message" }`, never by throwing — the spec maps a
rejected `execute` to a bare `UnknownError` and discards the message.
A read that finds nothing returns an empty result plus an explicit note,
never a silent success. Rejection is for cancellation (`signal`) only
6. Return values must survive `JSON.stringify`
7. Names: ASCII `[a-zA-Z0-9_.-]`, 1-128 chars; one tool per approved journey;
duplicate names reject at registration
8. Match the repo's language, lint config, and file conventions
### 5. Verify (mandatory)
Work is not done until each tool is exercised the way an agent would call it.
Use the `verify` skill from this plugin: registration on the declared pages
and auth states, invocation of every tool, UI/state assertions, security
lint. Every tool ends **verified**, **failed** (fix or drop, never ship), or
**could-not-verify** (ship flagged). Fastest driver:
`npx @ora-ai/webmcp-verify <url>` (add `--exec <tool> --input '{...}'` to
invoke). Console fallback when nothing else is available:
```js
const mc = document.modelContext;
const tools = await mc.getTools();
const tool = tools.find(t => t.name === "search_docs");
let raw;
try { raw = await mc.executeTool(tool, { query: "x" }); } // spec shape: object
catch { raw = await mc.executeTool(tool, JSON.stringify({ query: "x" })); } // current Chrome parses only a JSON string
JSON.parse(raw); // executeTool resolves to a JSON string, not an object
```
### 6. Harden
Read [references/security.md](references/security.md). Minimum bar: least
privilege (drop tools on logout), honest annotations, no instructions or
secrets in tool metadata, sanitized outputs, server-side authz on every
mutating path, reversible boundaries on destructive actions, `exposedTo`
never listing origins the site does not control.
## Decision tree
```
Make this site agent-ready?
├─ Propose journeys with the user first (never skip)
├─ Default: unknown runtime, or ChatGPT Site tools -> Imperative registerTool
├─ Existing remote MCP server with right tools? -> Bridge (@ora-ai/webmcp-bridge)
└─ Real HTML <form>s AND the user accepts
Chrome-preview-only reach? -> Declarative attributes (opt-in)
```
**Runtime reach check before choosing Declarative:** form attributes ship
only in Chrome's origin trial today (the spec's declarative section is a
TODO), and agent runtimes that read only imperatively registered tools never
see them. When the user targets such a runtime, or the target runtime is
unknown, ship the journey with imperative `registerTool` instead — never as
declarative-only.
If the user is unsure: Imperative for the high-value journeys. Bridge only
when an MCP server already exists and its tools match the journeys.
Declarative only when the site is form-heavy **and** the user has accepted
Chrome-preview-only reach.
## Anti-patterns
- Implementing before the user approves journeys and strategy
- Wrapping REST endpoints 1:1 instead of packaging journeys
- Tool proliferation: near-duplicate tools dilute agent selection accuracy
- Inventing transactional tools on a content-only site
- Registering overlapping tools for one job across strategies
- Calling `registerTool` in server code; WebMCP is a document API
- Leaving a stale contextual tool registered after route or state change
- Skipping browser verification because the build passes
## Sources of truth
- Spec: https://webmachinelearning.github.io/webmcp/
- Chrome imperative API: https://developer.chrome.com/docs/ai/webmcp/imperative-api
- Chrome declarative API: https://developer.chrome.com/docs/ai/webmcp/declarative-api
- Chrome best practices: https://developer.chrome.com/docs/ai/webmcp/best-practices
The web view of these pages outranks any snapshot in this skill, including
[references/spec.md](references/spec.md); when they disagree, trust the docs.
Pliki w paczce (12)
- SKILL.md 10 KB
- references/bridge-existing-mcp.md 4 KB
- references/declarative-forms.md 3 KB
- references/runtime.md 3 KB
- references/security.md 2 KB
- references/spec.md 8 KB
- references/strategies.md 4 KB
- references/tool-design.md 5 KB
- references/frameworks/react-next.md 3 KB
- references/frameworks/svelte.md 2 KB
- references/frameworks/vanilla-mpa.md 4 KB
- references/frameworks/vue.md 3 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · ora/webmcp | 100 | MIT |
| TerminalSkills/skills | 100 | Apache-2.0 |
| alpic-ai/webmcp | 100 | MIT |
| agricidaniel/web-mcp | 90 | MIT |
| jordanhubbard/literate-ai | 85 | Apache-2.0 |
Migawka bazy z 13.11.2026 · wersja paczki 8e116fce6374 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100webmcpx
Dodaje do strony narzędzia WebMCP, aby agenty AI mogły z niej korzystać, i sprawdza definicje narzędzi. - 90webmcp-site-tools
Projektuje i testuje narzędzia WebMCP dla istniejącej aplikacji, by oferowała akcje dla agentów na żywo. - 90implement
Dodaje narzędzia WebMCP do strony internetowej, tak by agenty przeglądarki działały przez logikę witryny, a nie przez scraping. - 100verify
Weryfikuje narzędzia WebMCP na działającej stronie: rejestrację, wywołanie i kontrolę jakości każdego narzędzia. - 100webmcp-register-tool
Wdraża imperatywne API WebMCP: rejestruje narzędzia przez navigator.modelContext.registerTool() ze schematami, callbackami wykonania i zarządzaniem cyklem życia przy dynamicznej rejestracji w JavaScript. - 100orchardcore-ai-webmcp
Udostępnia agentom AI w przeglądarce narzędzia strony przez standardowe API document.modelContext w Orchard Core.