{"id":47591950,"url":"https://github.com/holon-run/webmcp-bridge","last_synced_at":"2026-04-12T04:04:57.366Z","repository":{"id":344011303,"uuid":"1178462880","full_name":"holon-run/webmcp-bridge","owner":"holon-run","description":"Bridge local MCP clients to browser WebMCP tools through Playwright, using native WebMCP when available and injected adapters when not.","archived":false,"fork":false,"pushed_at":"2026-03-31T05:13:11.000Z","size":996,"stargazers_count":23,"open_issues_count":5,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-01T19:23:55.198Z","etag":null,"topics":["ai-agent","browser-automation","browser-tools","mcp","model-context-protocol","playwright","webmcp"],"latest_commit_sha":null,"homepage":"https://webmcp-bridge.holon.run","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/holon-run.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-11T03:33:46.000Z","updated_at":"2026-03-31T05:11:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/holon-run/webmcp-bridge","commit_stats":null,"previous_names":["holon-run/webmcp-bridge"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/holon-run/webmcp-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holon-run%2Fwebmcp-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holon-run%2Fwebmcp-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holon-run%2Fwebmcp-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holon-run%2Fwebmcp-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/holon-run","download_url":"https://codeload.github.com/holon-run/webmcp-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/holon-run%2Fwebmcp-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31569400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","browser-automation","browser-tools","mcp","model-context-protocol","playwright","webmcp"],"created_at":"2026-04-01T17:36:28.461Z","updated_at":"2026-04-08T19:00:28.785Z","avatar_url":"https://github.com/holon-run.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# webmcp-bridge\n\n`webmcp-bridge` lets a local MCP client call browser WebMCP tools through a stable local bridge.\n\nPrimary runtime path:\n`local-mcp (stdio MCP) -\u003e playwright -\u003e browser navigator.modelContext`\n\nThe bridge uses native WebMCP when available, and falls back to injected adapters when not:\n\n- if the page exposes native WebMCP, calls go to browser `navigator.modelContext`\n- if the page does not, the bridge falls back to an injected adapter path\n\nThis gives local MCP clients one call path for both:\n\n- native WebMCP sites\n- non-native sites that need a shim\n\n## Why this exists\n\nWithout a bridge, local MCP clients cannot directly use browser-only WebMCP capabilities such as:\n\n- tools exposed by a live website in the current browser session\n- tools that depend on existing site authentication\n- human + AI collaboration on the same page\n\n`webmcp-bridge` keeps execution in the browser where those capabilities already exist, while exposing a normal local stdio MCP surface to the caller.\n\n## Who this is for\n\n- MCP client authors who need a stable local bridge to browser WebMCP\n- browser app authors who want to expose native WebMCP tools\n- adapter authors who want a fallback path for sites without native WebMCP yet\n\n## Use Policy\n\nThis project is intended for:\n\n- WebMCP research and experimentation\n- development, testing, and normal end-user workflows\n- user-authorized actions inside the user's own browser session\n\nIt is not intended for:\n\n- unauthorized data collection or bulk scraping\n- bypassing access controls, rate limits, or platform restrictions\n- abusive automation, account misuse, or privacy-invasive collection\n\nUsers 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.\n\n## What you can do with it\n\n- connect a local MCP client to a native WebMCP website\n- inject a fallback adapter for sites that do not expose WebMCP yet\n- reuse the same logged-in browser session instead of moving credentials into the local process\n- run headless automation or open a visible browser window for human + AI collaboration\n\n## When to use which mode\n\n- `--url \u003chttps://site\u003e`: the site already exposes native WebMCP\n- `--site \u003cname\u003e`: use a built-in fallback adapter such as `x`\n- `--adapter-module \u003cspecifier\u003e`: use a third-party adapter package\n\n## Agent skills\n\nIf your agent workflow uses `skills`, install the `uxc` skill first, then install the bridge skills.\n\nInstall from ClawHub:\n\n```bash\nclawhub install uxc\nclawhub install webmcp-bridge\nclawhub install board-webmcp\nclawhub install x-webmcp\nclawhub install google-webmcp\nclawhub install webmcp-adapter-creator\n```\n\nOr install directly from GitHub:\n\n```bash\nnpx -y skills@latest add holon-run/uxc --skill uxc\nnpx -y skills@latest add holon-run/webmcp-bridge --skill webmcp-bridge --skill board-webmcp --skill x-webmcp --skill google-webmcp --skill webmcp-adapter-creator\n```\n\nThe 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.\n\nThe bridge skills depend on `uxc` because they create and use stable `uxc link` commands such as:\n\n- `board-webmcp-cli`\n- `x-webmcp-cli`\n- `google-webmcp-cli`\n\nRecommended skill flow:\n\n1. Use `webmcp-bridge` for general site connection and link creation.\n2. Use `board-webmcp` for the public board demo at `https://board.holon.run`.\n3. Use `webmcp-adapter-creator` when a site has no native WebMCP and no existing adapter.\n\n## First 2 minutes\n\nIf your main workflow is \"agent operates the site for me\", install the skills in [Agent skills](#agent-skills) first.\n\nIf you prefer direct CLI use instead of agent + skill use, start here:\n\nRun directly from npm against the public native WebMCP demo:\n\n```bash\nnpx -y @webmcp-bridge/local-mcp --url https://board.holon.run --headless\n```\n\nWhen `--browser-url` is not used, local-mcp now defaults to a stable managed profile under\n`~/.uxc/webmcp-profile/\u003csite-or-host\u003e` even if `--user-data-dir` is omitted.\n\nTo open a visible browser window for collaboration:\n\n```bash\nnpx -y @webmcp-bridge/local-mcp --url https://board.holon.run --no-headless\n```\n\nWith `uxc`, create stable shortcuts:\n\n```bash\nuxc link board-webmcp-cli \\\n  \"npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --headless --user-data-dir ~/.uxc/webmcp-profile/board\" \\\n  --daemon-exclusive ~/.uxc/webmcp-profile/board\n\nuxc link board-webmcp-ui \\\n  \"npx -y @webmcp-bridge/local-mcp --url https://board.holon.run --no-headless --user-data-dir ~/.uxc/webmcp-profile/board\" \\\n  --daemon-exclusive ~/.uxc/webmcp-profile/board \\\n  --daemon-idle-ttl 0\n```\n\nThe `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.\n\n`--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.\n\nThen:\n\n```bash\nboard-webmcp-ui bridge.open\nboard-webmcp-ui diagram.get\n```\n\nExpected result:\n\n- `board-webmcp-ui bridge.open` opens a visible browser session for the board demo\n- `board-webmcp-ui diagram.get` returns the current board state as JSON\n\n## Quick start details\n\nOn a fresh machine, or when running under a brand new `HOME`, install Playwright browsers first:\n\n```bash\nnpx playwright install\n```\n\nOr install globally:\n\n```bash\nnpm i -g @webmcp-bridge/local-mcp\nwebmcp-local-mcp --url https://board.holon.run --headless\n```\n\nRun from this repository:\n\n```bash\npnpm install\npnpm --filter @webmcp-bridge/local-mcp build\nnode packages/local-mcp/dist/cli.js --url https://board.holon.run --headless\n```\n\nBuilt-in fallback adapter mode:\n\n```bash\nwebmcp-local-mcp --site x --headless --user-data-dir ~/.uxc/webmcp-profile/x\n```\n\nFor auth-sensitive sites such as `x`, `google`, and `weibo`, the recommended first step is a headed\nsession with a managed profile so local-mcp can bootstrap a normal browser for manual sign-in:\n\n```bash\nwebmcp-local-mcp --site x --no-headless --user-data-dir ~/.uxc/webmcp-profile/x\n```\n\nWeibo example:\n\n```bash\nwebmcp-local-mcp --site weibo --no-headless --user-data-dir ~/.uxc/webmcp-profile/weibo\n```\n\nDeterministic fixture mode:\n\n```bash\nwebmcp-local-mcp --site fixture --headless\n```\n\nExternal adapter module mode:\n\n```bash\nwebmcp-local-mcp --adapter-module @your-scope/webmcp-adapter --headless\n```\n\n## Runtime model\n\n![Bridge architecture](docs/images/bridge-architecture.png)\n\n`webmcp-local-mcp` owns one site session per process, drives a Playwright page, and proxies `tools/list` / `tools/call` into browser-side WebMCP execution.\n\nThe bridge uses native WebMCP when available, and falls back to injected adapters when not:\n\n- native sites execute through browser `navigator.modelContext`\n- non-native sites execute through injected WebMCP shim paths\n\nBoth paths return standard JSON-serializable MCP payloads to the local caller.\n\nIf a page exposes neither native WebMCP nor a configured adapter, local-mcp starts in\n`overlay-bootstrap` mode instead of failing immediately. In that mode:\n\n- `bridge.debug.eval` can inspect or prototype page-context scripts\n- `bridge.overlay.*` can persist draft overlay tools, switch them between `namespaced` and `override`, and export adapter drafts\n- installed overlay tools always appear as `overlay.\u003cid\u003e.\u003ctool\u003e`\n- overlays in `override` mode also expose their canonical tool names while preserving the `overlay.\u003cid\u003e.*` aliases\n\n## Collaborative board demo\n\nThe public demo at `https://board.holon.run` is the easiest way to see human + AI collaboration on the same WebMCP surface.\n\n- open a visible session with `board-webmcp-ui bridge.open`\n- keep AI tool calls on `board-webmcp-ui` while the human is collaborating in the same visible session\n- keep the browser open while the human and the AI work on the same diagram\n- 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\n\nSee [examples/board/README.md](examples/board/README.md) for the full collaboration flow in Codex / Claude Code.\n\n## Package status\n\n- `@webmcp-bridge/core`: shared bridge contracts and shim runtime.\n- `@webmcp-bridge/playwright`: WebMCP page gateway for Playwright.\n- `@webmcp-bridge/adapter-x`: production fallback adapter for X/Twitter.\n- `@webmcp-bridge/adapter-weibo`: fallback adapter for Weibo reads, writes, article workflows, and search.\n- `@webmcp-bridge/adapter-fixture`: deterministic fallback adapter for integration/contract tests.\n- `@webmcp-bridge/testkit`: shared contract test helpers.\n- `@webmcp-bridge/local-mcp`: local stdio MCP server.\n\n## Repository skills\n\nThis repository includes six agent skills with distinct responsibilities:\n\n- `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.\n- `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.\n- `x-webmcp`: site wrapper for X, including timeline, Grok, and X Articles workflows.\n- `google-webmcp`: site wrapper for Google and Gemini workflows, including text and image generation.\n- `weibo-webmcp`: site wrapper for Weibo timeline, post, comment, article, and search workflows.\n- `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.\n\nThese skills assume the `uxc` CLI and the `uxc` skill are already installed.\n\nThey are published on ClawHub as `webmcp-bridge`, `board-webmcp`, `x-webmcp`, `google-webmcp`, and `webmcp-adapter-creator`.\n\n## Adapter authoring\n\nSee [Adapter Authoring](docs/adapters/authoring.md) for:\n\n- `manifest + createAdapter` module contract\n- tool naming and schema guidelines\n- pagination/error shape conventions\n- fail-closed adapter requirements\n\n## Native Example App\n\n`examples/board` is a native WebMCP provider example built as a browser app, not an adapter.\n\nPublic demo:\n\n```bash\nwebmcp-local-mcp --url https://board.holon.run --headless\n```\n\nRun it locally:\n\n```bash\npnpm --filter @webmcp-bridge/example-board dev\n```\n\nThen connect through the existing bridge:\n\n```bash\nwebmcp-local-mcp --url http://127.0.0.1:4173 --headless\n```\n\nThis example is meant to demonstrate human + AI collaboration on the same diagram surface.\n\nUseful board tools:\n\n- `bridge.open` / `bridge.close`\n- `diagram.get` / `diagram.loadDemo` / `diagram.setTitle` / `diagram.export`\n- `nodes.*`\n- `edges.*`\n- `selection.get` / `selection.remove`\n- `view.fit`\n\n## Development\n\n```bash\npnpm typecheck\npnpm test\npnpm lint\npnpm build\n```\n\n## Publish to npm\n\nReleases are published from GitHub Actions through Changesets plus npm trusted publishing. Do not publish from a local shell.\n\n```bash\npnpm changeset\n```\n\nAfter 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).\n\nTo validate the monorepo locally before merging:\n\n```bash\npnpm typecheck\npnpm test\npnpm lint\npnpm build\n```\n\n## Constraints\n\n- Assumes users are already authenticated in the browser session.\n- Does not implement credential vaulting or auth bypass.\n- Target URL defaults to adapter manifest and can be overridden by CLI, but must match adapter host allowlist.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholon-run%2Fwebmcp-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fholon-run%2Fwebmcp-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fholon-run%2Fwebmcp-bridge/lists"}