Integrasi Agen MCP

MCP Server Sa2web menyediakan browser jarak jauh sebagai alat MCP standar untuk Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Roo Code, opencode, Gemini CLI, Zed, Hermes Agent, dan OpenClaw.

Proyek MCP bersifat open source di sa2web/sa2web-mcp dan dipublikasikan di npm sebagai @sa2web/mcp.

Untuk penggunaan langsung dari terminal, lihat CLI Browser Jarak Jauh.

Situs target ditampilkan di dalam iframe#rbi-frame dan dikendalikan server melalui Playwright.

Instalasi

Instal Node.js 18 atau yang lebih baru, lalu instal paket npm secara global:

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

Ini menyediakan sa2, sa2-browser, dan entri MCP sa2-mcp di PATH.

Untuk pengembangan dari source, clone repository publik lalu build:

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

Konfigurasi klien

Setelah instalasi global, gunakan sa2-mcp secara langsung:

{
  "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"
      }
    }
  }
}

Jika klien tidak dapat menemukan perintah global, gunakan path penuh ke sa2-mcp atau node /absolute/path/to/sa2web-mcp/dist/server.js dari 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 memakai field root servers, opencode memakai mcp, dan Zed memakai context_servers. Tambahkan ke mcp_servers dalam ~/.hermes/config.yaml untuk Hermes Agent, atau ke mcp.servers pada konfigurasi Gateway untuk OpenClaw. Mulai ulang klien dan pastikan sa2_help tersedia.

Kredensial

Jangan simpan clientSecret asli dalam Git atau dokumentasi. Segera rotasi kredensial yang pernah terekspos.

Variabel utama

Variabel	Default	Kegunaan
SA2_LOGIN_URL	tidak ada	URL login wajib; origin browser jarak jauh diturunkan dari URL ini
SA2_AUTO_LOGIN_BEFORE_NAVIGATE	true	Login otomatis sebelum membuka target
SA2_HEADLESS	false	Menjalankan Playwright tanpa antarmuka
SA2_BROWSER	chromium	chromium, firefox, atau webkit
SA2_IGNORE_HTTPS_ERRORS	true	Mengabaikan error sertifikat HTTPS; set false untuk mewajibkan sertifikat valid
SA2_RBI_FRAME_CONTENT_WAIT_MS	15000	Waktu tunggu konten iframe
SA2_NAVIGATION_TIMEOUT_MS	45000	Timeout navigasi
SA2_ACTION_TIMEOUT_MS	15000	Timeout aksi
SA2_LOG_STDERR	true	Menulis log ke stderr dan menyisakan stdout untuk MCP
SA2_LOG_FILE	tidak ada	File log opsional

Jangan gunakan variabel lama SA2_REMOTE_BROWSER_PREFIX atau SA2_REMOTE_BROWSER_BASE_URL.

Alur yang disarankan

sa2_help
  -> sa2_list_available_targets    # hanya untuk SaaS, workspace, atau situs internal
  -> sa2_open_target
  -> browser_snapshot / browser_extract_text
  -> browser_click / browser_type / browser_press / browser_wait

URL publik:

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

Target tersimpan:

{ "targetId": "workspace:123" }

Setelah halaman terbuka, utamakan browser_snapshot dan berikan ref=eN hasilnya ke alat interaksi. id=tN dan context=[tN] hanya referensi teks dalam snapshot, bukan selector CSS atau ref yang dapat dioperasikan.

Referensi lengkap alat

Semua alat yang terdaftar pada Server saat ini dijelaskan di bawah. Parameter adalah isi objek MCP arguments.

Alat	Kegunaan, parameter utama, dan hasil
sa2_help	Tanpa parameter. Mengembalikan alur yang disarankan, contoh, dan daftar alat kompatibilitas.
sa2_list_available_targets	Mendaftar proxy, SaaS, akun workspace, dan situs internal dengan targetId stabil.
sa2_open_target	Navigasi utama: type=cloud + url, atau targetId/type + id/name; mendukung surf, waitUntil.
browser_open_login	Membuka SA2_LOGIN_URL; waitUntil opsional. Untuk diagnosis login.
browser_navigate	Navigasi URL kompatibel: url wajib; surf, waitUntil opsional.
browser_navigate_back	Mundur melalui toolbar luar. Ambil snapshot baru.
browser_navigate_forward	Maju melalui toolbar luar.
browser_reload	Memuat ulang melalui toolbar; refs lama tidak berlaku.
browser_list_proxies	Mengembalikan free-browse, proxy, dan options termasuk direct.
browser_list_saas_sites	Mengembalikan kategori SaaS dan daftar sites datar.
browser_enter_saas_site	Membuka SaaS berdasarkan id atau name; waitUntil opsional.
browser_list_workspaces	Mengembalikan data workspace dan target tingkat akun.
browser_enter_workspace	Membuka akun berdasarkan accountId, atau siteId + username.
browser_list_inner_sites	Mengembalikan situs internal yang dapat diakses.
browser_enter_inner_site	Membuka situs internal berdasarkan id atau name.
browser_snapshot	filter CSS nyata opsional. Mengembalikan snapshot semantik; gunakan ref=eN, bukan id=tN, untuk aksi.
browser_extract_text	selector CSS nyata opsional. Mengembalikan teks terlihat dari pohon iframe.
browser_click	Klik berdasarkan ref, selector, role/name, text, atau koordinat x/y.
browser_type	text wajib; target dengan ref/selector/role, mendukung append, pressEnter.
browser_press	key wajib, misalnya Enter, Escape, Control+A.
browser_press_key	Alias kompatibel browser_press dengan parameter sama.
browser_wait	Menunggu selector, text, urlIncludes, atau ms (default 1000).
browser_scroll	Menggulir root/elemen dengan by, to, intoView; tanpa argumen turun 600 px.
browser_hover	Hover elemen berdasarkan ref, selector, role/name, atau teks.
browser_drag	Drag dari startRef/startSelector ke endRef/endSelector.
browser_fill_form	Mengisi array fields berisi locator dan value wajib secara berurutan.
browser_select_option	Menemukan select dengan ref/selector, memilih memakai values, value, label, atau index.
browser_check	Mencentang checkbox/radio berdasarkan ref, selector, role/name, atau teks.
browser_uncheck	Menghapus centang checkbox; radio tidak didukung.
browser_file_upload	Mengunggah path/paths yang dapat dibaca Server melalui file input.
browser_paste	Menempel text, html, rtf, dan/atau file ke target atau elemen fokus.
browser_handle_dialog	Menerima/menolak alert, confirm, prompt; accept default true, tersedia promptText, timeoutMs.
browser_resize	Memerlukan width, height positif; mengubah desktop atau ukuran emulasi aktif.
browser_list_devices	Tanpa parameter dan tidak membuka halaman. Mendaftar Desktop serta perangkat Playwright dengan viewport, screen, DPR, touch/mobile, browser.
browser_toggle_device	Mengubah emulasi tanpa membuat ulang context. Menerima enabled, device, ukuran, DPR, touch, UA, orientation, reload; mengembalikan state, observed, targetObserved, warnings.
browser_screenshot	Mengembalikan PNG; default fullPage adalah false.
browser_take_screenshot	Alias screenshot; default fullPage adalah true.
browser_evaluate	Menjalankan expression dan arg opsional di iframe, mengembalikan JSON.
browser_run_code	Menjalankan code async dengan page, rootFrame, helpers. Hanya kode tepercaya.
browser_close	Menutup browser/context dan menghapus refs, login, dialog, CDP, status perangkat.

Beralih perangkat

Panggil browser_list_devices lebih dahulu, lalu misalnya browser_toggle_device dengan { "device": "Pixel 7", "orientation": "portrait" }. Cookie dan login dipertahankan. Gunakan reload: true agar permintaan berikutnya memakai UA baru dan { "device": "Desktop" } untuk memulihkan viewport desktop sebelumnya.

Chromium memakai CDP untuk viewport, screen, DPR, touch, orientation, dan UA. Firefox/WebKit hanya dapat mengubah viewport secara dinamis dan melaporkan batasan melalui warnings. observed mengukur shell luar, targetObserved mengukur iframe target. Ambil snapshot baru setelah setiap perubahan.

Keamanan dan pemecahan masalah

Dapatkan konfirmasi eksplisit pengguna sebelum menerbitkan, mengirim, menghapus, membeli, memberi otorisasi, mentransfer uang, atau mengirim pesan.

• Alat tidak muncul: periksa build dan path absolut node serta dist/server.js, lalu mulai ulang klien.
• Login gagal: periksa SA2_LOGIN_URL, kredensial, dan status akun.
• Hanya toolbar yang terlihat: panggil browser_wait atau tambah waktu tunggu iframe.
• Elemen tidak ditemukan: ambil snapshot baru dan gunakan ref=eN terbaru.