WebSAPE MCP Bridge

This package exposes the WebSAPE Chrome extension as an MCP server. It supports both a stdio bridge for generic MCP clients and a long-lived HTTP daemon for desktop integrations.

Architecture:

MCP client -> MCP server/daemon -> localhost WebSocket -> WebSAPE extension -> browser agent

The MCP client starts this process over stdio. While a tool call is active, the process also owns the localhost WebSocket and waits briefly for the Chrome extension to reconnect.

Defaults:

WEBSAPE_BRIDGE_PORT=17322
WEBSAPE_BRIDGE_TOKEN=websape-dev-token
WEBSAPE_BRIDGE_TIMEOUT_MS=600000
WEBSAPE_BRIDGE_CONNECT_TIMEOUT_MS=30000
WEBSAPE_MCP_TOOL_MODE=agent
WEBSAPE_SCREENSHOT_DIR=websape-screenshots
WEBSAPE_MCP_HTTP_PORT=17323
WEBSAPE_BRIDGE_AUTH_MODE=token

WEBSAPE_BRIDGE_TOKEN is a local development default, not a secret. Override it when running in a shared or less-trusted environment.

Entrypoints:

• websape-mcp-bridge: stdio MCP server for generic clients. Defaults to token-based WebSocket auth.
• websape-connector: long-lived HTTP MCP daemon. Defaults to WEBSAPE_MCP_TRANSPORT=http, WEBSAPE_MCP_TOOL_MODE=browser, and WEBSAPE_BRIDGE_AUTH_MODE=origin.

HTTP daemon mode:

npx -y --package @websape/[email protected] websape-connector

The daemon listens on:

http://127.0.0.1:17323/mcp
ws://127.0.0.1:17322

In origin auth mode, the WebSocket accepts Chrome extension origins. For a published extension, set WEBSAPE_EXTENSION_ORIGINS=chrome-extension://<extension-id> to require the exact extension ID.

Tool modes:

• agent (default): exposes websape_status and websape_run_task.
• browser: exposes websape_status, the high-level browser_tabs_* / page_* tools, and the websape_browser_* low-level browser-control tools.
• all: exposes both sets for development and debugging.

Tools in agent mode:

• websape_status
• websape_run_task

Tools in browser mode:

• websape_status
• browser_tabs_list
• browser_tabs_open
• browser_tabs_navigate
• browser_tabs_close
• page_get_text
• page_get_html
• page_get_links
• page_get_tables
• page_snapshot
• page_screenshot
• page_find
• page_click
• page_fill
• page_select
• page_keypress
• page_scroll
• page_wait_for
• page_console_read
• page_network_read
• page_network_wait
• page_dom_inspect
• browser_download_wait
• browser_download_list
• page_file_choose
• page_media_download
• browser_computer
• websape_browser_start_session
• websape_browser_end_session
• websape_browser_observe
• websape_browser_screenshot
• websape_browser_current_page
• websape_browser_navigate_to
• websape_browser_go_back
• websape_browser_click_element
• websape_browser_input_text
• websape_browser_scroll_mouse_wheel
• websape_browser_hover_to_element
• websape_browser_drag_element
• websape_browser_extract_page_content
• websape_browser_get_select_options
• websape_browser_select_option
• websape_browser_get_all_tabs
• websape_browser_switch_tab
• websape_browser_wait

Browser sessions:

websape_browser_start_session creates a dedicated Chrome tab group by default. The session keeps its own groupId, activeTabId, and owned tab list so browser automation stays inside the WebSAPE session group.

{
  "task": "Find product pricing",
  "initialUrl": "https://example.com",
  "useTabGroup": true,
  "tabGroupTitle": "WebSAPE",
  "tabGroupColor": "blue"
}

Set useTabGroup to false only for debugging existing active-tab behavior. In tab-group mode, websape_browser_get_all_tabs and websape_browser_switch_tab are scoped to the session group.

High-level browser tools:

The new browser_tabs_* and page_* tools are the agent-facing surface intended for scraping and simple browser control. They reuse the same session created by websape_browser_start_session, but return more semantic outputs than the lower-level websape_browser_* action tools.

• browser_tabs_list: returns the tabs owned by the current browser session.
• browser_tabs_open: opens a URL in a new session tab.
• browser_tabs_navigate: navigates the active tab, or a specific tabId.
• browser_tabs_close: closes the active tab, or a specific tabId.
• page_get_text: returns compact readable page text.
• page_get_html: returns the current page HTML.
• page_get_links: returns extracted links from the current page.
• page_get_tables: returns extracted table data.
• page_find: finds candidate interactive elements by query or selector hints.
• page_click: clicks a matched element and returns an updated observation.
• page_fill: fills a matched input-like element.
• page_select: selects an option in a native <select>.
• page_keypress: sends trusted keyboard input through CDP.
• page_scroll: scrolls the active page.
• page_wait_for: waits for text, URL, or load-state conditions.
• page_console_read: returns recent console diagnostics for the session.
• page_network_read: returns recent network diagnostics for the session.
• page_network_wait: waits for a matching network event.
• page_dom_inspect: inspects a DOM element by selector, query, or point.
• browser_download_wait: waits for the next session download to complete or fail.
• browser_download_list: lists recent session downloads.
• page_file_choose: sets absolute file paths on a file input through CDP.
• page_media_download: downloads matched media through Chrome's download manager.
• browser_computer: viewport-relative fallback for screenshot/click/hover/type/key/scroll/drag/wait/zoom.
• page_snapshot: returns text, HTML, links, tables, pseudo-html, and compact interactive element refs.
• page_screenshot: captures a screenshot and can optionally save it to disk using the MCP bridge process.

Example:

{
  "sessionId": "wbs_..."
}

For a navigation call:

{
  "sessionId": "wbs_...",
  "url": "https://example.com",
  "tabId": 123
}

Screenshot saving:

websape_browser_screenshot can return MCP image content and/or save the image to disk. This is useful for clients that do not render image content in their UI.

{
  "sessionId": "wbs_...",
  "variant": "clean",
  "saveToFile": true,
  "returnImage": false
}

By default, saved screenshots are written under the MCP process working directory in websape-screenshots/. Set WEBSAPE_SCREENSHOT_DIR, pass outputDir, or pass outputPath to customize it. Use variant: "clean" when the screenshot is for external UX or visual inspection; omit it, or use "annotated", to preserve the original bounding-box screenshot behavior.

Build:

npm install
npm run build

MCP client source example:

HTTP daemon mode, recommended when a client manages a long-lived connector process:

{
  "mcp": {
    "transport": "http",
    "url": "http://127.0.0.1:17323/mcp"
  }
}

Stdio mode, recommended for generic MCP clients:

{
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "--package",
      "@websape/[email protected]",
      "websape-mcp-bridge"
    ],
    "env": {
      "WEBSAPE_BRIDGE_PORT": "17322",
      "WEBSAPE_BRIDGE_TOKEN": "websape-dev-token",
      "WEBSAPE_BRIDGE_TIMEOUT_MS": "600000",
      "WEBSAPE_MCP_TOOL_MODE": "agent"
    }
  }
}

To let an MCP client drive the browser loop directly, set WEBSAPE_MCP_TOOL_MODE to browser. Keep it as agent when you want WebSAPE to run the browser-use loop internally through websape_run_task.