SA2 Playwright MCP Wrapper

Languages: English | 中文 | 日本語 | Français | Español | Русский

This project exposes a DOM-based remote browser as MCP tools through Playwright.

The remote browser shell renders the target website inside iframe#rbi-frame. browser_snapshot always starts from that iframe and recursively includes descendant iframe nodes. DOM tools such as browser_extract_text, browser_click, browser_type, and browser_wait operate inside that iframe tree by default.

For agents, the recommended path is intentionally small:

sa2_help
  -> sa2_list_available_targets   # only when opening saved SaaS/workspace/inner sites
  -> sa2_open_target
  -> browser_snapshot or browser_extract_text
  -> browser_click / browser_type / browser_press / browser_wait

Use sa2_open_target directly for arbitrary public websites:

{
  "type": "cloud",
  "url": "https://example.com"
}

Use sa2_list_available_targets first for saved SaaS, workspace, and inner-site entries. It returns stable targetId values such as saas:12, workspace:34, and inner:56; pass one of those to sa2_open_target.

The lower-level browser_* list/enter/navigate tools are still available for compatibility and advanced control, but normal agents should prefer the sa2_* tools above.

browser_navigate opens target URLs through cloud browsing. The remote browser origin is inferred from SA2_LOGIN_URL.

So browser_navigate({ "url": "https://example.com" }) opens:

https://www.test7878.com/?surf=direct&_d=https%3A%2F%2Fexample.com

Install

After the package is published to npm, normal users can install it globally so sa2, sa2-browser, and sa2-mcp are available on PATH:

npm install -g sa2web-mcp

If you are installing from a local checkout instead of npm, build first and then install the current folder globally:

npm install
npx playwright install chromium
npm run build
npm install -g .

Plain npm install only installs dependencies for the current checkout; it does not put this package's own commands on your global PATH. For development, npm link is also fine after npm run build.

Run

npm start

Development mode:

npm run dev

CLI:

npm run build
npm run cli -- help
npm run cli -- shell
npm run cli -- targets
npm run cli -- open https://example.com
npm run cli -- open --target-id workspace:123
npm run cli -- open workspace 123
npm run cli -- saas GitHub
npm run cli -- inner 7
npm run cli -- snapshot --url https://example.com --headless true
npm run cli -- snapshot --url https://example.com --filter 'main article'
npm run cli -- click --url https://example.com --ref e3
npm run cli -- type --url https://example.com --selector '#email' --text hello@example.com

After global install or link, the package exposes sa2 and sa2-browser CLI commands, plus sa2-mcp for MCP clients. The CLI starts the MCP server over stdio internally and supports shell, open, targets, saved-target shortcuts (workspace, saas, inner), snapshot, text, click, type, paste, scroll, device, press, wait, screenshot, back, forward, reload, close, and raw tool commands. Use sa2 shell for a persistent browser session. Single-command invocations still start their own server process and close it when the command finishes, so pass --url, --target-id, or another target selector for commands that need page state. If no target is provided, the CLI opens SA2_LOGIN_URL.

Inside sa2 shell, refs from snapshot stay available for later commands:

sa2> open https://example.com
sa2> targets
sa2> open --target-id workspace:123
sa2> open saas GitHub
sa2> inner 7
sa2> snapshot
sa2> click --ref e3
sa2> type --selector '#email' --text hello@example.com
sa2> screenshot --output page.png
sa2> exit

MCP Client Config

The repository includes .mcp.json for local development. MCP clients can run sa2-mcp only after the package is globally installed or linked:

npm install
npm run build
npm install -g .

Use npm link instead of npm install -g . if you want changes in the checkout to be reflected immediately during development.

The important values are:

{
  "SA2_LOGIN_URL": "https://www.test7878.com/agent/login?clientId=...&clientSecret=...",
  "SA2_LOGIN_REDIRECT_PATH": "/app/login",
  "SA2_LOGIN_REDIRECT_WAIT_MS": "8000",
  "SA2_RBI_FRAME_SELECTOR": "#rbi-frame",
  "SA2_RBI_FRAME_WAIT_MS": "5000",
  "SA2_RBI_FRAME_CONTENT_WAIT_MS": "15000",
  "SA2_AUTO_LOGIN_BEFORE_NAVIGATE": "true",
  "SA2_LOGIN_SETTLE_MS": "1500",
  "SA2_IGNORE_HTTPS_ERRORS": "true",
  "SA2_LOG_LEVEL": "info",
  "SA2_LOG_STDERR": "true",
  "SA2_LOG_FILE": "/tmp/sa2-browser.log"
}

Logging uses a log4js-style timestamp, level, and category layout. Levels are trace, debug, info, warn, error, fatal, and off. Logs go to stderr by default because stdout is reserved for the MCP stdio protocol; SA2_LOG_FILE optionally appends the same redacted logs to a file. URL secrets, tokens, passwords, cookies, and authorization values are redacted.

For real use, keep clientSecret outside source control and inject it through your MCP client's environment configuration.

Different AI clients use different MCP config shapes. Ready-to-copy templates are available in configs/README.md, including Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, Cline, Roo Code, opencode, Gemini CLI, and Zed.

Tools

Recommended high-level tools:

• sa2_help: return the intended agent workflow and examples.
• sa2_list_available_targets: list proxy options plus all saved SaaS, workspace, and inner-site targets with stable targetId values.
• sa2_open_target: open any target. Use { "type": "cloud", "url": "https://example.com" } for public websites, or { "targetId": "workspace:34" } for saved targets.

Page inspection and interaction tools:

• browser_snapshot: return a flat semantic snapshot for models with interactable refs, readable text ids, media elements, descendant iframes, hidden raw URLs, and compact context=[t1,t2] references for controls. Optional filter accepts a CSS selector; omit it for the default full snapshot. Use ref=eN values for actions. id=tN and context=[tN] are snapshot-only text references, not DOM ids, CSS selectors, or actionable refs.
• browser_extract_text: return visible page text from the iframe tree. Its optional selector must be a real CSS selector; do not pass snapshot text ids such as t7, #t7, or text[id='t7'].
• browser_click: click by snapshot ref, selector, role/name, text, or x/y coordinates.
• browser_type: type/fill by snapshot ref, selector, role/name, or currently focused element, preserving multiline textarea and contenteditable input.
• browser_press / browser_press_key: press a keyboard key.
• browser_wait: wait for milliseconds, text, selector, or URL substring.
• browser_hover / browser_drag: mouse hover and drag.
• browser_fill_form / browser_select_option / browser_check / browser_uncheck: form operations.
• browser_file_upload: upload files through file inputs.
• browser_paste: paste plain text, HTML, RTF, and local files (including images) through clipboard data; file inputs use setInputFiles directly.
• browser_scroll: scroll the root page or an element by direction/distance, to coordinates or edges, or bring a ref/selector target into view.
• browser_list_devices: list every Playwright device preset accepted by device emulation.
• browser_toggle_device: toggle desktop/mobile emulation using Playwright device presets and Chromium CDP without recreating the browser context.
• browser_handle_dialog: accept or dismiss alert/confirm/prompt dialogs.
• browser_navigate_back / browser_navigate_forward / browser_reload: click the shell buttons #btn-back, #btn-forward, and #btn-reload.
• browser_screenshot / browser_take_screenshot: return a PNG screenshot.
• browser_resize: resize the viewport.
• browser_evaluate / browser_run_code: run debugging code against iframe#rbi-frame.
• browser_close: close the browser session.

Advanced compatibility tools:

• browser_open_login: open SA2_LOGIN_URL.
• browser_list_proxies: list cloud browsing proxy options from /api/v1/home/freebrowse.
• browser_navigate: open a target URL through cloud browsing; optional surf is validated against /api/v1/home/freebrowse.
• browser_list_saas_sites / browser_enter_saas_site: list and enter SaaS sites.
• browser_list_workspaces / browser_enter_workspace: list workspace accounts and enter an account-level workspace.
• browser_list_inner_sites / browser_enter_inner_site: list and enter internal sites.

Agent usage

See docs/AGENT_USAGE.md for detailed instructions on connecting this MCP server to an AI agent, recommended tool workflows, publishing safeguards, and troubleshooting.

For opencode-specific setup notes, see docs/OPENCODE_USAGE.md.

Manual test

npm run build
npm run manual-test -- https://example.com

Keep the browser open while debugging:

npm run manual-test -- https://example.com --keep-open