WebMCP Adapter Creator

intent

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.

inputs

target site and auth context

• target site URL (required)
• site login credentials if the site requires authentication (user provides in browser)
• existing adapter package path if updating an adapter (optional)

local environment

• pnpm installed and available on PATH
• npx playwright install already executed if Playwright-based browser automation will be used
• write access to skills/webmcp-adapter-creator/ directory structure
• Node.js 18+ runtime

external dependencies and connections

• @webmcp-bridge/local-mcp package and its runtime (handles bridge lifecycle)
• Playwright browser contexts for network interception and DOM access (no external auth required, runs locally)
• target site HTTP/HTTPS access (must be reachable from user's network; no proxy tunneling assumed)
• 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)

procedure

1. confirm adapter necessity

   • input: target site URL
   • open the site in a browser DevTools console and run navigator.modelContext
   • if the result is truthy and contains a tools array, the site has native WebMCP support; output: stop, recommend $webmcp-bridge instead
   • if the result is falsy or undefined, proceed to step 2
   • output: decision to build new adapter vs. update existing one

2. scaffold or locate adapter package

   • input: site name (e.g., "twitter"), site host (e.g., "x.com"), target URL
   • if starting from scratch: run skills/webmcp-adapter-creator/scripts/scaffold-adapter.sh --name <site> --host <host> --url <url>
   • output: new directory at skills/webmcp-adapter-creator/adapters/<site>/ with package.json, src/index.ts, src/manifest.ts, and test stubs
   • if updating existing: input existing adapter path and skip this step
   • output: adapter package root

3. design the tool manifest contract

   • input: list of user-facing actions on the target site (e.g., "get a tweet", "list home timeline", "get user profile")
   • for each action, create a tool entry with stable product names like tweet.get, timeline.home.list, user.get
   • define input parameters as a JSON schema with required and optional fields
   • put all parameter documentation in the schema field description fields, not in the tool description
   • define returns schema with explicit field types and descriptions for the response shape
   • implement the manifest() function in src/manifest.ts to export these tool definitions
   • validate that all payloads (inputs and outputs) are JSON-serializable; reject circular references, functions, or undefined values
   • output: src/manifest.ts with complete tool definitions and createAdapter() stub

4. discover stable request templates from live page behavior

   • input: authenticated browser context (user logs in manually if needed)
   • for each tool, trigger the corresponding user action (e.g., click "home" for timeline.home.list)
   • open DevTools Network tab and capture the HTTP request (method, URL, headers, body, query params)
   • identify which parts change per user input (ids, cursors, queries, feature flags) and which are static
   • create a reusable request template with placeholder syntax for variable parts (e.g., {userId}, {cursor})
   • validate the template by substituting placeholders with real values and re-running the request; confirm the response matches live behavior
   • output: request template JSON stored in src/templates/<tool-name>.json (one file per tool)

5. implement browser-side request execution

   • input: request templates from step 4
   • in src/index.ts, add a function that accepts user parameters (e.g., {userId}, {query})
   • substitute placeholders in the request template with user-provided values
   • execute the request in the page context using page.evaluate() with fetch() so the site's own session/auth is reused
   • parse and validate the response JSON against the tool's returns schema
   • add source: "network" and reason: "template execution" fields to the output so callers see which path ran
   • handle network failures (timeout, 4xx, 5xx status) by catching the error and moving to step 6
   • output: src/index.ts with full tool implementations and error handling

6. implement fallback DOM extraction layers

   • input: tool definition and authenticated page context, if network execution fails or template is missing
   • implement DOM selectors to extract the same data that the network request would return (e.g., parse rendered tweet cards for tweet.get)
   • only extract from DOM if the data is already rendered on the page (no hidden or deferred elements)
   • add source: "dom" and reason: "network unavailable" or reason: "template missing" to the output
   • do not attempt to re-render or reload the page to fetch fallback data if doing so would lose current conversation context
   • for chat/image products: prefer intercepting the product's real request/response path over reading rendered text
   • for long prompt insertion: prefer one-shot DOM insertion into the real composer; use incremental type() or fill() only if one-shot insertion fails
   • for chat/image completion waits: use activity-aware idle deadlines (e.g., stop controls, response fingerprint changes, feedback buttons, image count changes) instead of fixed wall-clock timeouts
   • compare normalized snapshot of previous response before declaring new answer ready
   • output: src/index.ts with fallback DOM extraction code marked with comments // fallback: dom

7. add explicit error handling and guardrails

   • input: all tool implementations from steps 5 and 6
   • catch and reject ambiguous upstream states: AUTH_REQUIRED, UPSTREAM_CHANGED, CHALLENGE_REQUIRED
   • never add credential vaulting, secret replay, or auth bypass logic
   • ensure the browser page is the only execution environment for privileged site actions
   • keep all site-specific logic inside the adapter package; do not leak into bridge or shared utilities
   • for cross-site helpers that are not product-specific, extract into a shared utility package instead of copying into one adapter
   • output: src/index.ts with error handling and guardrail comments

8. write package-local unit tests

   • input: all tool implementations from steps 5-7
   • create test file at src/__tests__/tools.test.ts
   • test tool behavior, input validation, and schema compliance for each tool
   • cover long prompt insertion, long-thinking waits, stale-response misdetection, and session-preserving fallback paths
   • mock network requests and DOM selectors; do not make real requests to the target site in unit tests
   • output: src/__tests__/tools.test.ts with >80% code coverage

9. write local-mcp integration tests

   • input: all tool implementations and unit tests
   • create test file at src/__tests__/integration.test.ts
   • set up a real local-mcp bridge instance with the adapter loaded
   • test full end-to-end tool execution through the bridge (user request -> adapter tool -> bridge response)
   • test fallback paths by mocking network failures and confirming DOM extraction is triggered
   • output: src/__tests__/integration.test.ts with end-to-end scenarios passing

10. validate and publish

    • input: completed adapter package with tests
    • run pnpm test and confirm all unit and integration tests pass
    • run pnpm build and confirm no TypeScript or build errors
    • output: built adapter ready for use with local-mcp bridge

decision points

if native navigator.modelContext exists on the target site

• output: stop this skill and use $webmcp-bridge to connect to the site instead

if starting a new adapter from scratch vs. updating an existing one

• if new: run scaffold script and proceed to step 3
• if update: locate existing adapter package, review current manifest and implementations, and jump to the relevant step (3, 4, 5, 6, 7, or 8)

if a network request template is discovered and validated (step 4)

• implement browser-side request execution (step 5) as the primary tool implementation
• implement DOM extraction (step 6) as the fallback only

if network request template is missing or cannot be discovered

• skip step 5
• implement DOM extraction (step 6) as the only implementation, but mark the tool as "scrape-only" in the manifest with a note: "dom-only, may break on layout changes" field
• prioritize requesting the user or site author provide network request details

if network execution fails at runtime (timeout, 4xx, 5xx)

• if a fallback DOM extraction exists: silently trigger fallback and return source: "dom" in output
• if no fallback exists: return error with source: "network", reason: "<http status or timeout>", and actionable error message

if a fallback DOM path would lose current session context (e.g., reloading the page)

• do not execute the fallback
• return error: source: "network", reason: "fallback would lose context", with instructions to manually trigger the action in the browser

if the tool output is ambiguous or the upstream state is unknown (AUTH_REQUIRED, UPSTREAM_CHANGED, CHALLENGE_REQUIRED)

• fail closed
• return error with the ambiguous state and do not attempt fallback execution

if a helper function is used by multiple adapters and is not site-specific

• extract into @webmcp-bridge/adapter-utils package instead of duplicating code

output contract

adapter package structure

• directory: skills/webmcp-adapter-creator/adapters/<site>/
• package.json: declares @webmcp-bridge/local-mcp as peer dependency, exports createAdapter as main entry
• src/manifest.ts: exports manifest: Record<string, ToolDefinition> with tool names, input/output schemas, and descriptions
• src/index.ts: exports createAdapter(): SiteAdapter factory function that returns an object with manifest and tools properties
• src/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/DOM
• src/__tests__/integration.test.ts: end-to-end bridge integration tests

tool response format

• each tool returns a JSON object with:
  • data: the requested data (shape defined in tool schema returns)
  • source: either "network" or "dom" indicating which path executed
  • reason: 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 steps

test output

• unit tests: pass/fail summary and coverage percentage (>80% required)
• integration tests: pass/fail summary for each end-to-end scenario

build output

• dist/index.js and dist/index.d.ts: compiled adapter with type definitions
• no TypeScript errors or warnings
• all unit and integration tests passing

outcome signal

• the user successfully runs a tool from the new/updated adapter through the local-mcp bridge and receives the expected data
• the tool response includes accurate source and reason fields so the user can verify which execution path ran
• if the user triggers the tool multiple times, network caching and DOM caching work correctly (no stale data)
• if network execution fails (e.g., site API changes), the tool falls back to DOM extraction (if available) without user intervention
• if a fallback would lose session context, the tool returns a clear error instead of silently breaking the conversation
• the adapter package publishes to npm and can be installed by other users
• all unit and integration tests pass and are reproducible in CI/CD