WebMCP Adapter Creator

Use this skill to create or update a fallback SiteAdapter for @webmcp-bridge/local-mcp.

When To Use

Use this skill when:

• the target site does not expose native navigator.modelContext
• an existing adapter does not exist yet
• an existing adapter needs new tools, pagination, or request-template refresh
• a site requires browser-side request execution instead of DOM-only scraping

If the user only needs to connect to an existing site through the bridge, use $webmcp-bridge instead.

Prerequisites

• The target site URL is known.
• The user can authenticate in the browser profile if the site requires login.
• pnpm is installed for local package work.
• npx playwright install has already been run in the current environment when Playwright browsers are not present.

Core Workflow

1. Confirm the site really needs a fallback adapter:
• check whether native navigator.modelContext already exists
• if native WebMCP exists, stop and use $webmcp-bridge instead of writing an adapter
2. Scaffold a new adapter package when starting from scratch:
• skills/webmcp-adapter-creator/scripts/scaffold-adapter.sh --name --host --url
3. Fix the contract first:
• implement manifest
• implement createAdapter()
• keep all payloads JSON-serializable
4. Design the tool surface before coding extraction logic:
• use stable product names such as tweet.get, timeline.home.list, user.get
• put parameter details in schema field descriptions, not only in tool descriptions
5. Prefer browser-side request execution over server-side credential replay:
• run requests in the page context so the site's own auth/session state is reused
• do not move cookies or bearer tokens into local-mcp
6. Discover stable request templates from real page behavior:
• trigger the target action in the page
• observe the network request shape
• extract a reusable request template with placeholders for ids, cursors, queries, or feature flags
7. Implement fallback layers explicitly:
• first try browser-side network/template execution
• for assistant/chat products, prefer intercepting the product's real request/response path over reading rendered text
• if network execution is unavailable or the template is missing, fall back to DOM extraction when safe
• include source and reason fields so callers can see which path ran
• when a helper is cross-site and not product-specific, prefer putting it in a shared adapter utility package instead of copying it into one adapter
• for long prompts, prefer one-shot DOM insertion into the real composer and use incremental type() or fill() only as a fallback
• when waiting for chat/image completion, use activity-aware idle deadlines instead of a fixed wall-clock timeout
• activity signals may include stop controls, response fingerprint changes, feedback buttons, or generated image count changes
• compare against a normalized snapshot of the previous response before declaring a new answer ready
• do not reset or reopen the page during fallback confirmation if that would lose the current conversation/session context
8. Add contract and integration coverage:
• package-local unit tests for tool behavior and validation
• local-mcp integration tests for full bridge execution
• cover long prompt insertion, long-thinking waits, stale-response misdetection, and session-preserving fallback paths

Guardrails

• Keep site logic inside the adapter package only.
• Fail closed on ambiguous upstream states such as AUTH_REQUIRED, UPSTREAM_CHANGED, and CHALLENGE_REQUIRED.
• Prefer stable request templates over brittle DOM-only scraping for authenticated data reads.
• Do not add credential vaulting, secret replay, or auth bypass logic.
• The browser page is the execution environment for privileged site actions.

References

• End-to-end adapter creation flow:
• references/workflow.md
• How to discover requests from page behavior:
• references/network-discovery.md
• How to turn captured requests into reusable templates:
• references/request-template-patterns.md
• Runtime patterns for streamed responses, request interception, and session-aware tools:
• references/adapter-runtime-patterns.md
• Testing expectations for adapter packages:
• references/testing.md
• Adapter scaffold helper:
• scripts/scaffold-adapter.sh