sa2web/sa2web-mcp

# SA2WEB 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 树内运行。 对于代理，推荐路径非常精简： ``` 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 ``` 直接使用 `sa2_open_target` 访问任意公共网站： ``` { "type": "cloud", "url": "https://example.com" } ``` 对于已保存的 SaaS、workspace 和 inner-site 条目，请首先使用 `sa2_list_available_targets`。它 会返回稳定的 `targetId` 值，例如 `saas:12`、`workspace:34` 和 `inner:56`；将其中之一传递 给 `sa2_open_target`。 较低级别的 `browser_*` 列表/进入/导航工具仍可用于兼容性和 高级控制，但普通代理应优先使用上述 `sa2_*` 工具。 `browser_navigate` 通过云浏览打开目标 URL。远程浏览器源是从 `SA2_LOGIN_URL` 推断出来的。 因此 `browser_navigate({ "url": "https://example.com" })` 会打开： ``` https://www.test7878.com/?surf=direct&_d=https%3A%2F%2Fexample.com ``` ## 安装 当包发布到 npm 后，普通用户可以全局安装它，这样 `sa2`、`sa2-browser` 和 `sa2-mcp` 就可以在 PATH 中使用： ``` npm install -g @sa2web/mcp npx playwright install chromium --with-deps ``` 如果您是从本地检出版本而不是从 npm 安装，请先进行构建，然后全局安装当前文件夹： ``` npm install npx playwright install chromium --with-deps npm run build npm install -g . ``` 普通的 `npm install` 只会为当前检出的代码安装依赖；它不会将此包自身的命令添加到您的全局 PATH 中。对于开发，在 `npm run build` 之后执行 `npm link` 也是可以的。 ## 运行 ``` npm start ``` 开发模式： ``` 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 ``` 在全局安装或链接后，该包会暴露 `sa2` 和 `sa2-browser` CLI 命令，以及用于 MCP 客户端的 `sa2-mcp`。CLI 会在内部通过 stdio 启动 MCP 服务器，并支持 `shell`、`open`、`targets`、已保存目标的快捷方式（`workspace`、`saas`、`inner`）、`snapshot`、`text`、`click`、`type`、`paste`、`scroll`、`device`、`press`、`wait`、`screenshot`、`back`、`forward`、`reload`、`close` 以及原生 `tool` 命令。 使用 `sa2 shell` 获取持久的浏览器会话。单命令调用仍会启动自己的服务器进程，并在命令完成后将其关闭，因此对于需要页面状态的命令，请传递 `--url`、`--target-id` 或其他目标选择器。如果未提供目标，CLI 将打开 `SA2_LOGIN_URL`。 在 `sa2 shell` 中，来自 `snapshot` 的引用（ref）在后续命令中仍然可用： ``` 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`： ``` npm install npm run build npm install -g . ``` 如果您希望在开发过程中立即反映出检出版本中的更改，请使用 `npm link` 而不是 `npm install -g .`。 重要的值包括： ``` { "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 密钥、token、密码、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、workspace 和 inner-site 目标及其稳定的 `targetId` 值。 - `sa2_open_target`：打开任何目标。对于公共网站使用 `{ "type": "cloud", "url": "https://example.com" }`，或对于已保存的目标使用 `{ "targetId": "workspace:34" }`。 页面检查和交互工具： - `browser_snapshot`：为模型返回扁平的语义快照，包含可交互的引用（ref）、可读的文本 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`：通过快照引用（ref）、选择器、role/name、文本或 x/y 坐标进行点击。 - `browser_type`：通过快照引用（ref）、选择器、role/name 或当前聚焦的元素进行输入/填充，保留多行 textarea 和 contenteditable 输入。 - `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`：按方向/距离、至坐标或边缘滚动根页面或元素，或者将 ref/选择器目标滚动到可见范围内。 - `browser_list_devices`：列出设备模拟接受的每个 Playwright 设备预设。 - `browser_toggle_device`：使用 Playwright 设备预设和 Chromium CDP 切换桌面/移动模拟，而无需重新创建浏览器上下文。 - `browser_handle_dialog`：接受或关闭 alert/confirm/prompt 对话框。 - `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`：列出 workspace 帐户并进入帐户级别的 workspace。 - `browser_list_inner_sites` / `browser_enter_inner_site`：列出并进入 inner-site。 ## 代理使用 有关将此 MCP 服务器连接到 AI 代理、推荐的工具工作流程、发布保障和故障排除的详细说明，请参阅 [docs/AGENT_USAGE.md](docs/AGENT_USAGE.md)。 有关特定于 opencode 的设置说明，请参阅 [docs/OPENCODE_USAGE.md](docs/OPENCODE_USAGE.md)。 ## 手动测试 ``` npm run build npm run manual-test -- https://example.com ``` 在调试期间保持浏览器处于打开状态： ``` npm run manual-test -- https://example.com --keep-open ```

标签：AI代理工具, MCP, MITM代理, Playwright, 浏览器自动化, 特征检测, 自动化攻击, 远程浏览器