Create fallback site adapters for websites that do not expose native WebMCP. Use when a site needs a new adapter module, tool schema design, browser-side req...
--- name: webmcp-adapter-creator description: Create fallback site adapters for websites that do not expose native WebMCP. Use when a site needs a new adapter module, tool schema design, browser-side request execution, or request-template extraction from observed page behavior. --- # 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 <site> --host <host> --url <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`
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit inputs section with env vars and external connections, structured procedure as 10 discrete steps with input/output contracts, extracted decision logic into dedicated section covering adapter necessity, fallback triggering, and error states, documented output contract with file structure and response format, and added outcome signal showing user-facing success criteria and test validation.
build or update a fallback SiteAdapter module for @webmcp-bridge/local-mcp when a target website lacks native navigator.modelContext support. use this skill to design tool schemas, extract stable request templates from live page behavior, implement browser-side request execution with fallback DOM scraping layers, and test end-to-end adapter integration. stop and use $webmcp-bridge instead if the site already exposes native WebMCP or an adapter exists and needs only minor tweaks.
target site and auth context
local environment
pnpm installed and available on PATHnpx playwright install already executed if Playwright-based browser automation will be usedskills/webmcp-adapter-creator/ directory structureexternal dependencies and connections
@webmcp-bridge/local-mcp package and its runtime (handles bridge lifecycle)scripts/scaffold-adapter.sh helper script (bundled in skill package)reference materials
references/workflow.md (end-to-end adapter creation flow)references/network-discovery.md (request capture and analysis)references/request-template-patterns.md (template design patterns)references/adapter-runtime-patterns.md (streamed responses, interception, session-aware tools)references/testing.md (adapter test expectations)confirm adapter necessity
navigator.modelContexttools array, the site has native WebMCP support; output: stop, recommend $webmcp-bridge insteadscaffold or locate adapter package
skills/webmcp-adapter-creator/scripts/scaffold-adapter.sh --name <site> --host <host> --url <url>skills/webmcp-adapter-creator/adapters/<site>/ with package.json, src/index.ts, src/manifest.ts, and test stubsdesign the tool manifest contract
tweet.get, timeline.home.list, user.getparameters as a JSON schema with required and optional fieldsdescription fields, not in the tool descriptionreturns schema with explicit field types and descriptions for the response shapemanifest() function in src/manifest.ts to export these tool definitionssrc/manifest.ts with complete tool definitions and createAdapter() stubdiscover stable request templates from live page behavior
timeline.home.list){userId}, {cursor})src/templates/<tool-name>.json (one file per tool)implement browser-side request execution
src/index.ts, add a function that accepts user parameters (e.g., {userId}, {query})page.evaluate() with fetch() so the site's own session/auth is reusedreturns schemasource: "network" and reason: "template execution" fields to the output so callers see which path ransrc/index.ts with full tool implementations and error handlingimplement fallback DOM extraction layers
tweet.get)source: "dom" and reason: "network unavailable" or reason: "template missing" to the outputtype() or fill() only if one-shot insertion failssrc/index.ts with fallback DOM extraction code marked with comments // fallback: domadd explicit error handling and guardrails
AUTH_REQUIRED, UPSTREAM_CHANGED, CHALLENGE_REQUIREDsrc/index.ts with error handling and guardrail commentswrite package-local unit tests
src/__tests__/tools.test.tssrc/__tests__/tools.test.ts with >80% code coveragewrite local-mcp integration tests
src/__tests__/integration.test.tssrc/__tests__/integration.test.ts with end-to-end scenarios passingvalidate and publish
pnpm test and confirm all unit and integration tests passpnpm build and confirm no TypeScript or build errorsif native navigator.modelContext exists on the target site
$webmcp-bridge to connect to the site insteadif starting a new adapter from scratch vs. updating an existing one
if a network request template is discovered and validated (step 4)
if network request template is missing or cannot be discovered
note: "dom-only, may break on layout changes" fieldif network execution fails at runtime (timeout, 4xx, 5xx)
source: "dom" in outputsource: "network", reason: "<http status or timeout>", and actionable error messageif a fallback DOM path would lose current session context (e.g., reloading the page)
source: "network", reason: "fallback would lose context", with instructions to manually trigger the action in the browserif the tool output is ambiguous or the upstream state is unknown (AUTH_REQUIRED, UPSTREAM_CHANGED, CHALLENGE_REQUIRED)
if a helper function is used by multiple adapters and is not site-specific
@webmcp-bridge/adapter-utils package instead of duplicating codeadapter package structure
skills/webmcp-adapter-creator/adapters/<site>/package.json: declares @webmcp-bridge/local-mcp as peer dependency, exports createAdapter as main entrysrc/manifest.ts: exports manifest: Record<string, ToolDefinition> with tool names, input/output schemas, and descriptionssrc/index.ts: exports createAdapter(): SiteAdapter factory function that returns an object with manifest and tools propertiessrc/templates/<tool-name>.json: request templates with placeholder variables (one file per tool using network execution)src/__tests__/tools.test.ts: unit tests with >80% code coverage, mocked network/DOMsrc/__tests__/integration.test.ts: end-to-end bridge integration teststool response format
data: the requested data (shape defined in tool schema returns)source: either "network" or "dom" indicating which path executedreason: string explaining why that path was chosen (e.g., "template execution", "network unavailable", "template missing")error (optional): if the tool failed, a string with error details and actionable next stepstest output
build output
dist/index.js and dist/index.d.ts: compiled adapter with type definitionssource and reason fields so the user can verify which execution path ran