简体中文

Web Bridge — Browser Automation MCP Server (dsh plugin)

Web Bridge is an automation MCP server that uses a real browser. It gives agents a browser's eyes and hands: open web pages, read page structure, click, fill forms, take screenshots, and execute scripts. Its core mechanism is the accessibility-tree snapshot — rendering the page into a structured text tree with numbered interactive elements, so agents can interact with pages precisely without a vision model.

• Language: TypeScript (Node.js ≥ 20), communicating over the MCP protocol (stdio transport)
• Browser engines: Chromium / Firefox / WebKit (Chromium by default)
• Tool count: 22, all named with the web_ prefix

Features

• Snapshot driven: web_snapshot produces an accessibility tree with reference numbers (ref), so elements can be clicked/filled precisely without guessing selectors
• Real interactions: click, double-click, right-click, key combos, form filling, dropdown selection, hover, scroll, keyboard input
• Visual capabilities: viewport / full-page / element screenshots (PNG/JPEG), returned to the caller or saved locally
• Script execution: run JS in the page context; results are sanitized (circular references, BigInt, NaN, etc. safely converted)
• Multi-tab: create, list, switch, and close tabs; popups are captured automatically
• Fine-grained waiting: wait by load state / element state / URL match / fixed duration
• Session management: lazy browser startup, web_shutdown releases resources, automatic cleanup on disconnect

Installation

npm install          # install dependencies
npm run build        # compile to dist/
npx playwright install chromium   # install browser engine (required on first use)

Firefox / WebKit engines are also supported: npx playwright install firefox, switchable via configuration.

Quick Start

Option A: generic MCP client (stdio)

{
  "mcpServers": {
    "web-bridge": {
      "command": "node",
      "args": ["D:/path/to/browser-automation/dist/index.js"]
    }
  }
}

Option B: command line verification

node dist/index.js --help        # view usage
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' | node dist/index.js

Option C: load as a dsh plugin (see next section)

Installing in DSH

dsh plugin --profile demo add github:JohnXu22786/browser-automation

Adds this plugin to the dsh demo profile from github:JohnXu22786/browser-automation. See the next section for authorization, loading, and lifecycle details.

Cordis bundle (dsh.bundle)

As an alternative to the dsh-plugin.json MCP-server manifest, the repo ships a Cordis bundle for hosts that consume dsh.bundle manifests: package.json declares dsh.bundle.patch → cordis.patch.yml, and index.js is the bridge a dsh profile loads. The bridge spawns the built MCP server (node dist/index.js) over stdio, performs the MCP handshake, and re-exposes the 22 web_* tools to the harness — the server itself is untouched.

In a source checkout dist/ is gitignored, so the bridge runs npm run build once on first load; installed npm packages ship dist/ in their files list and need no build step. Profile-level settings map to the same WEB_BRIDGE_* environment variables described below.

dsh Plugin Integration

…