Tích hợp tác nhân MCP

MCP Server của Sa2web cung cấp trình duyệt từ xa dưới dạng các công cụ MCP chuẩn cho Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Roo Code, opencode, Gemini CLI, Zed, Hermes Agent và OpenClaw.

Dự án MCP đã mở nguồn tại sa2web/sa2web-mcp và được phát hành trên npm với tên @sa2web/mcp.

Để thao tác trực tiếp từ terminal, xem CLI trình duyệt từ xa.

Trang đích được hiển thị trong iframe#rbi-frame và Server điều khiển iframe này qua Playwright.

Cài đặt

Cài Node.js 18 trở lên, sau đó cài gói npm toàn cục:

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

Lệnh này cung cấp sa2, sa2-browser và entry MCP sa2-mcp trong PATH.

Để phát triển từ source, clone repository công khai rồi build:

git clone https://github.com/sa2web/sa2web-mcp.git
cd sa2web-mcp
npm install
npx playwright install --with-deps
npm run build

Cấu hình máy khách

Sau khi cài toàn cục, dùng trực tiếp sa2-mcp:

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "sa2-mcp",
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

Nếu máy khách không tìm thấy lệnh toàn cục, hãy dùng path đầy đủ tới sa2-mcp hoặc node /absolute/path/to/sa2web-mcp/dist/server.js từ bản build source.

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "node",
      "args": ["/absolute/path/to/sa2web-mcp/dist/server.js"],
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

VS Code Copilot dùng trường gốc servers, opencode dùng mcp, còn Zed dùng context_servers. Với Hermes Agent, thêm vào mcp_servers trong ~/.hermes/config.yaml; với OpenClaw, thêm vào mcp.servers của cấu hình Gateway. Khởi động lại máy khách và kiểm tra có công cụ sa2_help.

Thông tin xác thực

Không lưu clientSecret thật trong Git hoặc tài liệu. Hãy thay ngay mọi thông tin xác thực đã bị lộ.

Biến môi trường chính

Biến	Mặc định	Công dụng
SA2_LOGIN_URL	không có	URL đăng nhập bắt buộc; origin trình duyệt từ xa được suy ra từ đây
SA2_AUTO_LOGIN_BEFORE_NAVIGATE	true	Tự động đăng nhập trước khi mở đích
SA2_HEADLESS	false	Chạy Playwright không giao diện
SA2_BROWSER	chromium	chromium, firefox hoặc webkit
SA2_IGNORE_HTTPS_ERRORS	true	Bỏ qua lỗi chứng chỉ HTTPS; đặt false để yêu cầu chứng chỉ hợp lệ
SA2_RBI_FRAME_CONTENT_WAIT_MS	15000	Thời gian chờ nội dung iframe
SA2_NAVIGATION_TIMEOUT_MS	45000	Thời gian chờ điều hướng
SA2_ACTION_TIMEOUT_MS	15000	Thời gian chờ thao tác
SA2_LOG_STDERR	true	Ghi log vào stderr và dành stdout cho MCP
SA2_LOG_FILE	không có	Tệp log tùy chọn

Không cấu hình các biến cũ SA2_REMOTE_BROWSER_PREFIX hoặc SA2_REMOTE_BROWSER_BASE_URL.

Quy trình đề xuất

sa2_help
  -> sa2_list_available_targets    # chỉ cho SaaS, workspace hoặc trang nội bộ
  -> sa2_open_target
  -> browser_snapshot / browser_extract_text
  -> browser_click / browser_type / browser_press / browser_wait

URL công khai:

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

Đích đã lưu:

{ "targetId": "workspace:123" }

Sau khi mở trang, ưu tiên browser_snapshot và truyền các giá trị ref=eN trả về cho công cụ tương tác. id=tN và context=[tN] chỉ là tham chiếu văn bản trong snapshot, không phải CSS selector hay ref có thể thao tác.

Tham chiếu đầy đủ công cụ

Tất cả công cụ đăng ký trong Server hiện tại được mô tả dưới đây. Tham số thuộc đối tượng MCP arguments.

Công cụ	Công dụng, tham số chính và kết quả
sa2_help	Không tham số. Trả về quy trình đề xuất, ví dụ và danh sách công cụ tương thích.
sa2_list_available_targets	Liệt kê proxy, SaaS, tài khoản workspace, trang nội bộ cùng targetId ổn định.
sa2_open_target	Điều hướng ưu tiên: type=cloud + url, hoặc targetId/type + id/name; hỗ trợ surf, waitUntil.
browser_open_login	Mở SA2_LOGIN_URL; waitUntil tùy chọn. Dùng chẩn đoán đăng nhập.
browser_navigate	Điều hướng URL tương thích: bắt buộc url; tùy chọn surf, waitUntil.
browser_navigate_back	Lùi bằng thanh công cụ ngoài. Sau đó tạo snapshot mới.
browser_navigate_forward	Tiến bằng thanh công cụ ngoài.
browser_reload	Tải lại bằng thanh công cụ; refs cũ không còn hợp lệ.
browser_list_proxies	Trả về free-browse, proxy và options gồm direct.
browser_list_saas_sites	Trả về danh mục SaaS và danh sách sites phẳng.
browser_enter_saas_site	Mở SaaS theo id hoặc name; waitUntil tùy chọn.
browser_list_workspaces	Trả về dữ liệu workspace và đích cấp tài khoản.
browser_enter_workspace	Mở tài khoản theo accountId, hoặc siteId + username.
browser_list_inner_sites	Trả về các trang nội bộ có thể truy cập.
browser_enter_inner_site	Mở trang nội bộ theo id hoặc name.
browser_snapshot	filter CSS thật tùy chọn. Trả snapshot ngữ nghĩa; dùng ref=eN, không dùng id=tN, cho thao tác.
browser_extract_text	selector CSS thật tùy chọn. Trả văn bản hiển thị từ cây iframe.
browser_click	Nhấp theo ref, selector, role/name, text hoặc tọa độ x/y.
browser_type	Bắt buộc text; đích qua ref/selector/role, hỗ trợ append, pressEnter.
browser_press	Bắt buộc key, ví dụ Enter, Escape, Control+A.
browser_press_key	Bí danh tương thích của browser_press, cùng tham số.
browser_wait	Chờ selector, text, urlIncludes hoặc ms (mặc định 1000).
browser_scroll	Cuộn root/phần tử với by, to, intoView; không tham số sẽ xuống 600 px.
browser_hover	Hover phần tử theo ref, selector, role/name hoặc văn bản.
browser_drag	Kéo từ startRef/startSelector đến endRef/endSelector.
browser_fill_form	Điền tuần tự mảng fields chứa locator và value bắt buộc.
browser_select_option	Tìm select bằng ref/selector, chọn qua values, value, label hoặc index.
browser_check	Chọn checkbox/radio theo ref, selector, role/name hoặc văn bản.
browser_uncheck	Bỏ chọn checkbox; không hỗ trợ radio.
browser_file_upload	Tải path/paths mà Server đọc được qua file input.
browser_paste	Dán text, html, rtf và/hoặc tệp vào đích hay phần tử focus.
browser_handle_dialog	Chấp nhận/từ chối alert, confirm, prompt; accept mặc định true, có promptText, timeoutMs.
browser_resize	Cần width, height dương; đổi desktop hoặc kích thước giả lập đang bật.
browser_list_devices	Không tham số, không mở trang. Liệt kê Desktop và thiết bị Playwright với viewport, screen, DPR, touch/mobile, browser.
browser_toggle_device	Đổi giả lập không tạo lại context. Nhận enabled, device, kích thước, DPR, touch, UA, orientation, reload; trả state, observed, targetObserved, warnings.
browser_screenshot	Trả PNG; fullPage mặc định false.
browser_take_screenshot	Bí danh chụp; fullPage mặc định true.
browser_evaluate	Chạy expression với arg tùy chọn trong iframe, trả JSON.
browser_run_code	Chạy code bất đồng bộ với page, rootFrame, helpers. Chỉ dùng mã tin cậy.
browser_close	Đóng browser/context và xóa refs, đăng nhập, dialog, CDP, trạng thái thiết bị.

Chuyển đổi thiết bị

Gọi browser_list_devices trước, rồi ví dụ browser_toggle_device với { "device": "Pixel 7", "orientation": "portrait" }. Cookie và đăng nhập được giữ lại. Dùng reload: true để yêu cầu sau dùng UA mới và { "device": "Desktop" } để phục hồi viewport desktop trước đó.

Chromium dùng CDP để đổi viewport, screen, DPR, touch, orientation và UA. Firefox/WebKit chỉ đổi động viewport và báo giới hạn trong warnings. observed đo shell ngoài, targetObserved đo iframe đích. Tạo snapshot mới sau mỗi lần chuyển.

An toàn và xử lý sự cố

Phải có xác nhận rõ ràng của người dùng trước khi xuất bản, gửi, xóa, mua, cấp quyền, chuyển tiền hoặc gửi tin nhắn.

• Không thấy công cụ: kiểm tra build và đường dẫn tuyệt đối tới node, dist/server.js, rồi khởi động lại máy khách.
• Đăng nhập thất bại: kiểm tra SA2_LOGIN_URL, thông tin xác thực và trạng thái tài khoản.
• Chỉ thấy thanh công cụ: gọi browser_wait hoặc tăng thời gian chờ iframe.
• Không tìm thấy phần tử: tạo snapshot mới và dùng ref=eN mới nhất.