In agent development, giving an agent real browser capabilities is a common requirement. Web Bridge is an MCP server plugin that provides navigation, clicking, form filling, and screenshot capabilities using real browsers (Chromium/Firefox/WebKit). It identifies page elements through accessibility tree snapshots, enabling the agent to interact with pages precisely without relying on a visual model.

What Is This

Web Bridge is a browser automation tool based on real browsers. It is written in TypeScript, runs on Node.js ≥ 20, and communicates with DSH via the MCP protocol (stdio transport). Its core mechanism is to render web pages as accessibility tree snapshots and expose 22 web_-prefixed tools to DSH.

Core Capabilities

  • Real browser driving: Supports Chromium, Firefox, and WebKit; Chromium is used by default.
  • Accessibility tree driven: web_snapshot generates page structures with reference numbers, enabling precise interaction.
  • Page interaction: Supports operations such as clicking, form filling, dropdown selection, hovering, scrolling, and keyboard input.
  • Visual capabilities: Supports viewport, full-page, and element screenshots, with PNG/JPEG format support.
  • Script execution: Executes JavaScript in the page context and automatically sanitizes types such as circular references and BigInt.
  • Multi-tab and fine-grained waiting: Supports tab creation, switching, and closing, as well as waiting based on load state, element state, URL, or a fixed duration.
  • Session management: Supports persistent user data directories and can release resources via web_shutdown.

Installation and Enablement

Before installing, ensure your Node.js version is ≥ 20.

Add it via the plugin command in DSH:

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

This command adds the plugin to the demo configuration file. After installation, the plugin is loaded automatically and initializes the browser process.

Typical Usage

Configuration Management

The configuration precedence for Web Bridge is: defaults < config file < environment variables.

  1. Config file: Create a configuration file in the project root, such as web-bridge.config.json.
    {
      "browser": { "name": "chromium", "headless": true, "viewport": { "width": 1280, "height": 720 } },
      "context": { "ignoreHTTPSErrors": false, "permissions": ["geolocation"] },
      "timeouts": { "action": 10000, "navigation": 60000, "settle": 500 },
      "sandbox": true,
      "testIdAttribute": "data-testid"
    }

Startup command: `node dist/index.js --config web-bridge.config.json`.
  1. Environment variables: Override configuration using environment variables with the WEB_BRIDGE_ prefix.
    • WEB_BRIDGE_BROWSER: Specifies the browser engine.
    • WEB_BRIDGE_HEADLESS: Controls headless mode.
    • WEB_BRIDGE_VIEWPORT: Sets the viewport size.
    • WEB_BRIDGE_ACTION_TIMEOUT: Timeout for a single action (milliseconds).
    • WEB_BRIDGE_NAV_TIMEOUT: Navigation timeout.
    • WEB_BRIDGE_SETTLE_MS: Time to wait for asynchronous tasks to settle after an action.

Tool Invocation Examples

  • Navigation: web_open is used to open a URL and supports http/https/file/data protocols.
  • Get snapshot: web_snapshot returns the accessibility tree structure of the page, with elements carrying reference numbers for precise locating later.
  • Interaction: web_click uses a reference number or selector to click an element; web_fill is used for form filling.
  • Screenshot: web_screenshot can capture the viewport, the full page, or a specified element.

Applicable Scenarios and Considerations

This plugin is suitable for scenarios that require high-precision page interaction, handling complex forms, or executing dynamic web page scripts.

Permissions and security notes:
* The plugin runs with the permissions of the current DSH process.
* Navigation tools trigger real network requests and page rendering.
* Interaction tools trigger mouse events and script execution.
* Before installing, you must review the plugin’s source code and license (MIT).

Summary

Web Bridge provides DSH with reliable browser automation capabilities through real browsers and an accessibility tree snapshot mechanism. It supports fine-grained interaction control and session management, making it suitable for building agents that need to interact deeply with web applications.

Learn more: Plugin directory | GitHub repository