Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

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.

Autor
ora ↗
Repozytorium
webmcp ↗
Licencja
MIT
Ostatnia zmiana repozytorium
07.09.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
12
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
4
Przestarzałość

Brak sygnałów. Repozytorium zmienione 07.09.2026, bez odwołań do wycofanych modeli i API.

Licencja

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

WebMCP-compatibleagent-ready
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

  1. Hard rules
  2. Workflow
  3. Decision tree
  4. Anti-patterns
  5. Sources of truth
Sekcje z nagłówków SKILL.md, w oryginale · 212 linii, 1 352 słów
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

RepozytoriumWynikLicencja
Ta strona · ora/webmcp100MIT
TerminalSkills/skills100Apache-2.0
alpic-ai/webmcp100MIT
agricidaniel/web-mcp90MIT
jordanhubbard/literate-ai85Apache-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.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.