内容
# SA2 Playwright MCP 封装
## 语言: English | [中文](README.zh.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md) | [Русский](README.ru.md)
本项目通过 Playwright 将基于 DOM 的远程浏览器作为 MCP 工具公开。
远程浏览器 shell 在 `iframe#rbi-frame` 中渲染目标网站。`browser_snapshot` 始终从该 iframe 开始，并递归包含后代 iframe 节点。`browser_extract_text`、`browser_click`、`browser_type` 和 `browser_wait` 等 DOM 工具默认在该 iframe 树中操作。
对于代理，推荐的路径故意很小：
```text
sa2_help
-> sa2_list_available_targets # 仅在打开保存的 SaaS/工作区/内部站点时
-> sa2_open_target
-> browser_snapshot 或 browser_extract_text
-> browser_click / browser_type / browser_press / browser_wait
```
直接使用 `sa2_open_target` 访问任意公共网站：
```json
{
"type": "cloud",
"url": "https://example.com"
}
```
首先使用 `sa2_list_available_targets` 获取保存的 SaaS、工作区和内部站点条目的稳定 `targetId` 值；传递其中一个给 `sa2_open_target`。
较低级别的 `browser_*` 列表/进入/导航工具仍然可用，以兼容性和高级控制，但正常代理应优先使用上面的 `sa2_*` 工具。
`browser_navigate` 通过云浏览打开目标 URL。远程浏览器源从 `SA2_LOGIN_URL` 推断。
因此，`browser_navigate({ "url": "https://example.com" })` 打开：
```text
https://www.test7878.com/?surf=direct&_d=https%3A%2F%2Fexample.com
```
## 安装
在将软件包发布到 npm 后，普通用户可以全局安装它，以便在 PATH 上使用 `sa2`、`sa2-browser` 和 `sa2-mcp`：
```bash
npm install -g sa2web-mcp
```
如果从本地 checkout 安装而不是 npm，请先构建，然后全局安装当前文件夹：
```bash
npm install
npx playwright install chromium
npm run build
npm install -g .
```
普通的 `npm install` 只安装当前 checkout 的依赖项；它不会将此软件包自己的命令放在全局 PATH 上。对于开发，`npm link` 在 `npm run build` 后也很好用。
## 运行
```bash
npm start
```
开发模式：
```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
```
全局安装或链接后，该软件包公开了 `sa2` 和 `sa2-browser` CLI 命令，以及用于 MCP 客户端的 `sa2-mcp`。CLI 在内部启动 MCP 服务器，并支持 `shell`、`open`、`targets`、保存的目标快捷方式（`workspace`、`saas`、`inner`）、`snapshot`、`text`、`click`、`type`、`paste`、`scroll`、`device`、`press`、`wait`、`screenshot`、`back`、`forward`、`reload` 和原始 `tool` 命令。
在 `sa2 shell` 中使用 `sa2 shell` 进行持久浏览器会话。单个命令调用仍然启动自己的服务器进程，并在命令完成时关闭它，因此为需要页面状态的命令传递 `--url`、`--target-id` 或另一个目标选择器。如果未提供目标，CLI 将打开 `SA2_LOGIN_URL`。
在 `sa2 shell` 中，`snapshot` 的引用可用于后续命令：
```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 客户端配置
存储库中包含用于本地开发的 `.mcp.json`。MCP 客户端只能在软件包全局安装或链接后运行 `sa2-mcp`：
```bash
npm install
npm run build
npm install -g .
```
使用 `npm link` 代替 `npm install -g .`，如果您希望在开发过程中立即反映 checkout 中的更改。
重要的值是：
```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"
}
```
日志记录使用 log4js 样式的时间戳、级别和类别布局。级别为 `trace`、`debug`、`info`、`warn`、`error`、`fatal` 和 `off`。日志默认输出到 stderr，因为 stdout 保留用于 MCP stdio 协议；`SA2_LOG_FILE` 可选地将相同的编辑日志追加到文件中。URL 机密、令牌、密码、cookie 和授权值被编辑。
对于实际使用，请将 `clientSecret` 保存在源代码之外，并通过 MCP 客户端的环境配置注入。
不同的 AI 客户端使用不同的 MCP 配置形状。 [configs/README.md](configs/README.md) 中提供了现成的模板，包括 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot、Cline、Roo Code、opencode、Gemini CLI 和 Zed。
## 工具
推荐的高级工具：
- `sa2_help`：返回预期的代理工作流和示例。
- `sa2_list_available_targets`：列出代理选项以及所有保存的 SaaS、工作区和内部站点目标，带有稳定的 `targetId` 值。
- `sa2_open_target`：打开任意目标。使用 `{ "type": "cloud", "url": "https://example.com" }` 访问公共网站，或使用 `{ "targetId": "workspace:34" }` 访问保存的目标。
页面检查和交互工具：
- `browser_snapshot`：返回具有可交互引用、 readable 文本 ID、媒体元素、后代 iframe、隐藏原始 URL 和紧凑的 `context=[t1,t2]` 控件引用的扁平语义快照。可选的 `filter` 接受 CSS 选择器；省略它以获取默认的完整快照。使用 `ref=eN` 值进行操作。`id=tN` 和 `context=[tN]` 是仅快照的文本引用，不是 DOM ID、CSS 选择器或可操作引用。
- `browser_extract_text`：从 iframe 树中返回可见的页面文本。其可选的 `selector` 必须是实际的 CSS 选择器；不要传递诸如 `t7`、`#t7` 或 `text[id='t7']` 之类的快照文本 ID。
- `browser_click`：通过快照引用、选择器、角色/名称、文本或 x/y 坐标进行点击。
- `browser_type`：通过快照引用、选择器、角色/名称或当前聚焦元素进行输入/填充，保留多行文本区域和可编辑内容。
- `browser_press` / `browser_press_key`：按下键盘按键。
- `browser_wait`：等待毫秒、文本、选择器或 URL 子字符串。
- `browser_hover` / `browser_drag`：鼠标悬停和拖动。
- `browser_fill_form` / `browser_select_option` / `browser_check` / `browser_uncheck`：表单操作。
- `browser_file_upload`：通过文件输入上传文件。
- `browser_paste`：通过剪贴板数据粘贴纯文本、HTML、RTF 和本地文件（包括图像）；文件输入直接使用 `setInputFiles`。
- `browser_scroll`：按方向/距离、坐标或边缘滚动根页面或元素，或将引用/选择器目标带入视图。
- `browser_list_devices`：列出 Playwright 设备模拟接受的每个设备预设。
- `browser_toggle_device`：使用 Playwright 设备预设和 Chromium CDP 切换桌面/移动设备模拟，而不重新创建浏览器上下文。
- `browser_handle_dialog`：接受或拒绝警报/确认/提示对话框。
- `browser_navigate_back` / `browser_navigate_forward` / `browser_reload`：单击 shell 按钮 `#btn-back`、`#btn-forward` 和 `#btn-reload`。
- `browser_screenshot` / `browser_take_screenshot`：返回 PNG 快照。
- `browser_resize`：调整视口大小。
- `browser_evaluate` / `browser_run_code`：针对 `iframe#rbi-frame` 运行调试代码。
- `browser_close`：关闭浏览器会话。
高级兼容性工具：
- `browser_open_login`：打开 `SA2_LOGIN_URL`。
- `browser_list_proxies`：列出云浏览代理选项来自 `/api/v1/home/freebrowse`。
- `browser_navigate`：通过云浏览打开目标 URL；可选的 `surf` 验证 `/api/v1/home/freebrowse`。
- `browser_list_saas_sites` / `browser_enter_saas_site`：列出并进入 SaaS 站点。
- `browser_list_workspaces` / `browser_enter_workspace`：列出工作区帐户并进入帐户级工作区。
- `browser_list_inner_sites` / `browser_enter_inner_site`：列出并进入内部站点。
## 代理使用
参见 [docs/AGENT_USAGE.md](docs/AGENT_USAGE.md) 以获取有关将此 MCP 服务器连接到 AI 代理、推荐的工具工作流、发布防护措施和故障排除的详细说明。
有关 opencode 特定设置说明，请参见 [docs/OPENCODE_USAGE.md](docs/OPENCODE_USAGE.md)。
## 手动测试
```bash
npm run build
npm run manual-test -- https://example.com
```
保持浏览器打开进行调试：
```bash
npm run manual-test -- https://example.com --keep-open
```
