webmcp-bridge（WebMCP 桥）

WebMCP Bridge

Use this skill to operate @webmcp-bridge/local-mcp through one fixed uxc shortcut command per site.

If the target site does not expose native WebMCP and does not already have a fallback adapter, switch to $webmcp-adapter-creator.

Prerequisites

• uxc is installed and available in PATH.
• npx is installed and available in PATH.
• Network access is available for the target website.
• On a fresh machine, or under an isolated HOME, install Playwright browsers first with npx playwright install.
• For local repo development, you may replace the default npx -y @webmcp-bridge/local-mcp launcher with WEBMCP_LOCAL_MCP_COMMAND='node packages/local-mcp/dist/cli.js'.

Core Workflow

1. Identify the bridge source mode before creating any link:

- Native or polyfill target: use --url <url>. - Built-in adapter preset: use --site <site>. - Third-party adapter module: use --adapter-module <specifier> and optionally --url <url>.

1. Pick one stable site name and one site-scoped profile path:

- default profile root: ~/.uxc/webmcp-profile/<site> - never share one profile across different sites

1. Create or refresh the fixed link for that site:

- command -v <site>-webmcp-cli - if the link is missing or the source config changed, run skills/webmcp-bridge/scripts/ensure-links.sh

1. Inspect the bridge and tool schema before calling tools:

- <site>-webmcp-cli -h - <site>-webmcp-cli <operation> -h - <site>-webmcp-cli <operation> field=value - <site>-webmcp-cli <operation> '{"field":"value"}'

1. Treat presentation mode as explicit runtime state, not command-name intent:

- check current state with <site>-webmcp-cli bridge.session.status - or <site>-webmcp-cli bridge.session.mode.get - --headless or --no-headless only sets the preferred default for bridge-managed sessions - the actual runtime mode is presentationMode

1. Switch modes explicitly when needed:

- for normal automation, stay in headless - for login, MFA, or human collaboration, run <site>-webmcp-cli bridge.session.mode.set '{"mode":"headed"}' - then open or focus the visible session with <site>-webmcp-cli bridge.open - if the user manually closes that window, the headed owner session ends; run bridge.open again to start a new headed session on the same profile - close the visible owner session with <site>-webmcp-cli bridge.close

1. Parse JSON output only:

- success path: .ok == true, consume .data - failure path: .ok == false, inspect .error.code and .error.message

When Only Bridge Tools Are Visible

If <site>-webmcp-cli -h only shows bridge.* tools, do not keep retrying site tools blindly. The bridge is alive, but the page runtime is not attached to site tools yet.

Use this recovery order:

1. Inspect session state first:

- <site>-webmcp-cli bridge.session.status

1. If the session is bootstrap-only or auth is incomplete:

- run <site>-webmcp-cli bridge.session.bootstrap - complete login in the browser window - then re-run <site>-webmcp-cli -h

1. If a browser/profile already exists but the session is not attached to page tools:

- run <site>-webmcp-cli bridge.session.attach - then re-run <site>-webmcp-cli -h

1. If the task needs a visible browser:

- run <site>-webmcp-cli bridge.session.mode.set '{"mode":"headed"}' - run <site>-webmcp-cli bridge.open

1. Only call site operations after help output shows site tools again.

For auth-sensitive adapter sites such as x and google, seeing only bridge tools during first use is expected until bootstrap or attach completes successfully.

Link Contract

Every site gets one fixed command:

• <site>-webmcp-cli

The link must keep one stable site profile and daemon lock:

• profile path: ~/.uxc/webmcp-profile/<site>
• daemon key: same as profile path

The generated command should default to:

• use --headless
• use --no-auto-login-fallback

This keeps automation deterministic while still allowing runtime switching through:

• bridge.session.mode.get
• bridge.session.mode.set
• bridge.open
• bridge.close

Do not treat one command invocation as a guarantee that the current runtime has already switched. Always inspect presentationMode when mode matters.

Guardrails

• Prefer browser-side execution for privileged site actions. Do not move site credentials into local scripts.
• Do not share one --user-data-dir across multiple unrelated sites.
• Do not dynamically rename link commands at runtime. The skill author chooses the link name once.
• For managed sessions, use bridge.session.mode.set instead of relying on a new launcher invocation to force a mode change.
• For external attach sessions, bridge.session.mode.set is unavailable. Attach to a headed external browser if the task needs a visible window.
• During bootstrap_then_attach, bootstrap is always headed. Do not try to switch mode until attach completes.
• bridge.open and bridge.window.open return UNSUPPORTED_IN_HEADLESS_SESSION when the current runtime is headless.
• For destructive writes, inspect tool help first and require explicit user intent.
• Use --url only for the site the user asked for. Do not silently redirect hosts.

References

• Common creation and invocation patterns:

- references/usage-patterns.md

• Source mode selection and argument mapping:

- references/source-modes.md

• Link patterns, naming, and profile layout:

- references/link-patterns.md

• Common failures and recovery steps:

- references/troubleshooting.md

• Concrete creation script:

- scripts/ensure-links.sh