# SA2WEB MCP

Languages: English | [中文](README.zh.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md) | [Русский](README.ru.md)

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:

```text
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:

```json
{
  "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:

```text
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:

```bash
npm install -g @sa2web/mcp
npx playwright install chromium --with-deps
```

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

```bash
npm install
npx playwright install chromium --with-deps
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

```bash
npm start
```

Development mode:

```bash
npm run dev
```

CLI:

```bash
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:

```text
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:

```bash
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:

```json
{
  "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](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](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](docs/OPENCODE_USAGE.md).

## Manual test

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

Keep the browser open while debugging:

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