Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/holon-run/webmcp-bridge

Bridge local MCP clients to browser WebMCP tools through Playwright, using native WebMCP when available and injected adapters when not.
https://github.com/holon-run/webmcp-bridge

ai-agent browser-automation browser-tools mcp model-context-protocol playwright webmcp

Last synced: 2 months ago
JSON representation

Bridge local MCP clients to browser WebMCP tools through Playwright, using native WebMCP when available and injected adapters when not.

Awesome Lists containing this project

README 

          
# webmcp-bridge



`webmcp-bridge` lets a local MCP client call browser WebMCP tools through a stable local bridge.



Primary runtime path:

`local-mcp (stdio MCP) -> playwright -> browser navigator.modelContext`



The bridge uses native WebMCP when available, and falls back to injected adapters when not:



- if the page exposes native WebMCP, calls go to browser `navigator.modelContext`

- if the page does not, the bridge falls back to an injected adapter path



This gives local MCP clients one call path for both:



- native WebMCP sites

- non-native sites that need a shim



## Why this exists



Without a bridge, local MCP clients cannot directly use browser-only WebMCP capabilities such as:



- tools exposed by a live website in the current browser session

- tools that depend on existing site authentication

- human + AI collaboration on the same page



`webmcp-bridge` keeps execution in the browser where those capabilities already exist, while exposing a normal local stdio MCP surface to the caller.



## Who this is for



- MCP client authors who need a stable local bridge to browser WebMCP

- browser app authors who want to expose native WebMCP tools

- adapter authors who want a fallback path for sites without native WebMCP yet



## Use Policy



This project is intended for:



- WebMCP research and experimentation

- development, testing, and normal end-user workflows

- user-authorized actions inside the user's own browser session



It is not intended for:



- unauthorized data collection or bulk scraping

- bypassing access controls, rate limits, or platform restrictions

- abusive automation, account misuse, or privacy-invasive collection



Users are responsible for complying with applicable laws, website terms, and platform rules. If you use adapters or browser automation against a third-party service, you are responsible for that use and its consequences.



## What you can do with it



- connect a local MCP client to a native WebMCP website

- inject a fallback adapter for sites that do not expose WebMCP yet

- reuse the same logged-in browser session instead of moving credentials into the local process

- run headless automation or open a visible browser window for human + AI collaboration



## When to use which mode



- `--url `: the site already exposes native WebMCP

- `--site `: use a built-in fallback adapter such as `x`

- `--adapter-module `: use a third-party adapter package



## Agent skills



If your agent workflow uses `skills`, install the `uxc` skill first, then install the bridge skills.



Install from ClawHub:



```bash

clawhub install uxc

clawhub install webmcp-bridge

clawhub install board-webmcp

clawhub install x-webmcp

clawhub install google-webmcp

clawhub install webmcp-adapter-creator

```



Or install directly from GitHub:



```bash

npx -y skills@latest add holon-run/uxc --skill uxc

npx -y skills@latest add holon-run/webmcp-bridge --skill webmcp-bridge --skill board-webmcp --skill x-webmcp --skill google-webmcp --skill webmcp-adapter-creator

```



The GitHub form uses the shorter shorthand supported by `skills add` and installs only the named skills instead of referencing each `SKILL.md` URL directly. The commands do not pin `--agent`, so you can choose the target agent during installation.



The bridge skills depend on `uxc` because they create and use stable `uxc link` commands such as:



- `board-webmcp-cli`

- `x-webmcp-cli`

- `google-webmcp-cli`



Recommended skill flow:



1. Use `webmcp-bridge` for general site connection and link creation.

2. Use `board-webmcp` for the public board demo at `https://board.holon.run`.

3. Use `webmcp-adapter-creator` when a site has no native WebMCP and no existing adapter.



## First 2 minutes



If your main workflow is "agent operates the site for me", install the skills in [Agent skills](#agent-skills) first.



If you prefer direct CLI use instead of agent + skill use, start here:



Run directly from npm against the public native WebMCP demo:



```bash

npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --headless

```



When `--browser-url` is not used, local-mcp now defaults to a stable managed profile under

`~/.uxc/webmcp-profile/` even if `--user-data-dir` is omitted.



To open a visible browser window for collaboration:



```bash

npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --no-headless

```



With `uxc`, create stable shortcuts:



```bash

uxc link board-webmcp-cli \

  "npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --headless --user-data-dir ~/.uxc/webmcp-profile/board" \

  --daemon-exclusive ~/.uxc/webmcp-profile/board



uxc link board-webmcp-ui \

  "npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --no-headless --user-data-dir ~/.uxc/webmcp-profile/board" \

  --daemon-exclusive ~/.uxc/webmcp-profile/board \

  --daemon-idle-ttl 0

```



The `cli` and `ui` links above are intended to reuse the same site profile through the same daemon/session, not through two independent browser processes at the same time. If a target site is sensitive to headed/headless switching or browser fingerprint changes, keep separate profiles for the two modes.



`--headless` and `--no-headless` set the preferred runtime presentation mode for bridge-managed sessions. The actual runtime mode is reported by `bridge.session.status` and may differ when local-mcp reattaches to an existing session.



Then:



```bash

board-webmcp-ui bridge.open

board-webmcp-ui diagram.get

```



Expected result:



- `board-webmcp-ui bridge.open` opens a visible browser session for the board demo

- `board-webmcp-ui diagram.get` returns the current board state as JSON



## Quick start details



On a fresh machine, or when running under a brand new `HOME`, install Playwright browsers first:



```bash

npx playwright install

```



Or install globally:



```bash

npm i -g @webmcp-bridge/local-mcp

webmcp-local-mcp --url https://board.holon.run --headless

```



Run from this repository:



```bash

pnpm install

pnpm --filter @webmcp-bridge/local-mcp build

node packages/local-mcp/dist/cli.js --url https://board.holon.run --headless

```



Built-in fallback adapter mode:



```bash

webmcp-local-mcp --site x --headless --user-data-dir ~/.uxc/webmcp-profile/x

```



For auth-sensitive sites such as `x`, `google`, and `weibo`, the recommended first step is a headed

session with a managed profile so local-mcp can bootstrap a normal browser for manual sign-in:



```bash

webmcp-local-mcp --site x --no-headless --user-data-dir ~/.uxc/webmcp-profile/x

```



Weibo example:



```bash

webmcp-local-mcp --site weibo --no-headless --user-data-dir ~/.uxc/webmcp-profile/weibo

```



Deterministic fixture mode:



```bash

webmcp-local-mcp --site fixture --headless

```



External adapter module mode:



```bash

webmcp-local-mcp --adapter-module @your-scope/webmcp-adapter --headless

```



## Runtime model



![Bridge architecture](docs/images/bridge-architecture.png)



`webmcp-local-mcp` owns one site session per process, drives a Playwright page, and proxies `tools/list` / `tools/call` into browser-side WebMCP execution.



The bridge uses native WebMCP when available, and falls back to injected adapters when not:



- native sites execute through browser `navigator.modelContext`

- non-native sites execute through injected WebMCP shim paths



Both paths return standard JSON-serializable MCP payloads to the local caller.



If a page exposes neither native WebMCP nor a configured adapter, local-mcp starts in

`overlay-bootstrap` mode instead of failing immediately. In that mode:



- `bridge.debug.eval` can inspect or prototype page-context scripts

- `bridge.overlay.*` can persist draft overlay tools, switch them between `namespaced` and `override`, and export adapter drafts

- installed overlay tools always appear as `overlay..`

- overlays in `override` mode also expose their canonical tool names while preserving the `overlay..*` aliases



## Collaborative board demo



The public demo at `https://board.holon.run` is the easiest way to see human + AI collaboration on the same WebMCP surface.



- open a visible session with `board-webmcp-ui bridge.open`

- keep AI tool calls on `board-webmcp-ui` while the human is collaborating in the same visible session

- keep the browser open while the human and the AI work on the same diagram

- if the human closes the last headed window, that owner session ends; the next `board-webmcp-ui bridge.open` starts a new headed session on the same profile



See [examples/board/README.md](examples/board/README.md) for the full collaboration flow in Codex / Claude Code.



## Package status



- `@webmcp-bridge/core`: shared bridge contracts and shim runtime.

- `@webmcp-bridge/playwright`: WebMCP page gateway for Playwright.

- `@webmcp-bridge/adapter-x`: production fallback adapter for X/Twitter.

- `@webmcp-bridge/adapter-weibo`: fallback adapter for Weibo reads, writes, article workflows, and search.

- `@webmcp-bridge/adapter-fixture`: deterministic fallback adapter for integration/contract tests.

- `@webmcp-bridge/testkit`: shared contract test helpers.

- `@webmcp-bridge/local-mcp`: local stdio MCP server.



## Repository skills



This repository includes six agent skills with distinct responsibilities:



- `webmcp-bridge`: general bridge operations for existing sites. Use it to decide between `--url`, `--site`, and `--adapter-module`, create fixed `uxc` links, manage per-site profiles, and switch between headless and UI bridge modes.

- `board-webmcp`: site wrapper for the public native demo at `https://board.holon.run`. Use it when the task is specifically about the shared board example.

- `x-webmcp`: site wrapper for X, including timeline, Grok, and X Articles workflows.

- `google-webmcp`: site wrapper for Google and Gemini workflows, including text and image generation.

- `weibo-webmcp`: site wrapper for Weibo timeline, post, comment, article, and search workflows.

- `webmcp-adapter-creator`: adapter creation workflow for sites that do not expose native WebMCP. Use it to scaffold a new adapter package, design tool schemas, and implement browser-side request-template execution.



These skills assume the `uxc` CLI and the `uxc` skill are already installed.



They are published on ClawHub as `webmcp-bridge`, `board-webmcp`, `x-webmcp`, `google-webmcp`, and `webmcp-adapter-creator`.



## Adapter authoring



See [Adapter Authoring](docs/adapters/authoring.md) for:



- `manifest + createAdapter` module contract

- tool naming and schema guidelines

- pagination/error shape conventions

- fail-closed adapter requirements



## Native Example App



`examples/board` is a native WebMCP provider example built as a browser app, not an adapter.



Public demo:



```bash

webmcp-local-mcp --url https://board.holon.run --headless

```



Run it locally:



```bash

pnpm --filter @webmcp-bridge/example-board dev

```



Then connect through the existing bridge:



```bash

webmcp-local-mcp --url http://127.0.0.1:4173 --headless

```



This example is meant to demonstrate human + AI collaboration on the same diagram surface.



Useful board tools:



- `bridge.open` / `bridge.close`

- `diagram.get` / `diagram.loadDemo` / `diagram.setTitle` / `diagram.export`

- `nodes.*`

- `edges.*`

- `selection.get` / `selection.remove`

- `view.fit`



## Development



```bash

pnpm typecheck

pnpm test

pnpm lint

pnpm build

```



## Publish to npm



Releases are published from GitHub Actions through Changesets plus npm trusted publishing. Do not publish from a local shell.



```bash

pnpm changeset

```



After the feature PR with its changeset lands on `main`, the `Release` workflow opens or updates a version PR. Merging that version PR publishes the packages from GitHub Actions with npm provenance. For release details, see [`docs/release.md`](docs/release.md).



To validate the monorepo locally before merging:



```bash

pnpm typecheck

pnpm test

pnpm lint

pnpm build

```



## Constraints



- Assumes users are already authenticated in the browser session.

- Does not implement credential vaulting or auth bypass.

- Target URL defaults to adapter manifest and can be overridden by CLI, but must match adapter host allowlist.