# browser-mcp — beri AI agent Anda browser sungguhan 🌐🤖

MCP server **standalone** yang memberi AI agent (opencode, Claude Code/Desktop, Cursor, Cline, dsb) kemampuan browser penuh via **Chromium lokal + CDP**:

- 👁️ **Lihat halaman** — snapshot DOM compact (mata utama AI), screenshot, visual grounding (x,y), combined view
- 🖱️ **Aksi manusiawi** — klik/type/keys/scroll + hover/move/dblclick/rightclick/drag (easing+jitter, lolos slider GeeTest)
- 🕷️ **Recon otonom** — spider BFS in-scope, ekstraktor API/GraphQL ala LinkFinder, HAR-lite, console hook, probe introspeksi GraphQL
- 🔐 **Auth 2-akun** — vault attacker/victim untuk differential testing (IDOR/priv-esc), password ter-redact di audit
- 🛠️ **Burp-like first-class** — intercept (request+response), repeater, intruder sniper, match-replace, scope allowlist, collaborator OOB
- 🛡️ **Aman by default** — scope check di semua navigasi/HTTP keluar, audit `audit.jsonl` dengan redact kredensial
- 📦 **Zero-deployment hell** — 1 repo, stdlib + `websocket-client` saja, backend CDP di-vendor (`vendor_browser_local.py`), tanpa binary global

> 47 tools. 1 perintah install. Browser tetap di mesin Anda — tidak ada cloud, tidak ada data keluar.

---

## Demo 30 detik

```bash
git clone https://github.com/eye-fox/browser-mcp.git
cd browser-mcp
./install.sh
# restart opencode / AI client Anda, lalu suruh agent:
# "launch browser-mcp session demo, scope ke example.com, navigate, snapshot"
python3 examples/quickstart.py   # tanpa LLM: bukti end-to-end lewat stdio
```

## Cara kerja

```mermaid
flowchart LR
    Agent["AI agent"] -- "MCP stdio<br/>JSON-RPC" --> Server["server.py"]
    Server -- "subprocess" --> Vendor["vendor_browser_local.py"]
    Vendor -- "CDP ws://" --> Chrome["Chromium lokal"]
    Server --- Scope["scope.json<br/>allowlist/blocklist"]
    Server --- Audit["audit.jsonl<br/>redacted"]
    Server --- Vault["auth_vault.json<br/>2 akun, 600"]
    Server --- Sessions["sessions.json<br/>sessionId → cdp_url"]
```

## Syarat

| Kebutuhan | Versi | Cek |
|---|---|---|
| Python | ≥ 3.9 | `python3 --version` |
| websocket-client | ≥ 1.8.0 | `python3 -c "import websocket"` (auto-install via `install.sh`) |
| Chromium/Chrome | baru | `which chromium` (Debian: `sudo apt install chromium`) |

## Install

```bash
./install.sh
```

Script melakukan: cek python → install `websocket-client` → deteksi chromium (auto-patch `BROWSER` di vendor) → `chmod +x` → init `scope.json` / `auth_vault.json` (600) / `sessions.json` / `audit.jsonl` dari `.example` → **auto-register ke `~/.config/opencode/opencode.json`** → smoke test `tools/list` (harus ≥40 tools).

Opsi:

```bash
./uninstall.sh   # hapus entri MCP + matikan daemon, repo tidak dihapus
```

## Config manual (non-opencode)

**Claude Desktop / Cursor / Cline (`mcp.json` / `claude_desktop_config.json`):**

```json
{
  "mcpServers": {
    "browser-mcp": {
      "command": "python3",
      "args": ["/ABSOLUTE/PATH/browser-mcp/server.py"]
    }
  }
}
```

Template siap copy: [`mcp.json.example`](mcp.json.example). Untuk opencode mentah: [`opencode.json.snippet`](opencode.json.snippet).

## Struktur repo

```text
browser-mcp/
├── install.sh              # setup full: deps + chromium detect + opencode register + smoke test
├── uninstall.sh            # cabut entri MCP + kill daemon
├── server.py               # MCP stdio server (47 tools, scope+audit+redact)
├── vendor_browser_local.py # backend CDP Chromium (stealth, intercept, cookies, dsb) — di-vendor
├── requirements.txt        # websocket-client saja
├── SKILL.md                # instruksi agent (copy ke skill-dir bila perlu)
├── scope.json.example      # -> scope.json (allowlist; default disabled)
├── auth_vault.json.example # -> auth_vault.json (chmod 600)
├── opencode.json.snippet   # referensi config opencode
├── mcp.json.example        # referensi config generik MCP
├── examples/quickstart.py  # e2e tanpa LLM: launch→scope→navigate→snapshot→close
├── scripts/smoke_test.py   # initialize + tools/list, exit 0 bila ≥40 tools
├── LICENSE (MIT)
└── .gitignore (melindungi audit/sessions/vault asli)
```

> `scope.json`, `auth_vault.json`, `sessions.json`, `audit.jsonl` adalah **runtime** — tidak ikut ke git (lihat `.gitignore`). Yang dipublish hanya `.example`.

## Pakai di agent (pola baku)

1. `mcp_browser_launch {"sessionId":"s1"}` → simpan `sessionId`
2. `mcp_scope_set {"allowed":["target.com"],"enabled":true}`
3. `mcp_browser_spider {"sessionId":"s1","startUrl":"https://target.com","maxPages":20,"depth":2}`
4. Per halaman menarik: `mcp_browser_js_endpoints` + `mcp_browser_console` + `mcp_browser_network_har`
5. `mcp_browser_snapshot` → `mcp_browser_click/type (wait:"idle")` → snapshot lagi → `mcp_browser_eval` verifikasi value
6. Auth differential: `mcp_auth_vault set victim/attacker`, `switch` bergantian
7. Intercept **hanya saat tahu momennya**: `mcp_intercept_set(pattern)` → aksi pemicu → `mcp_intercept_poll` **langsung** → `mcp_intercept_continue` (`forward|drop|modify|fulfill`, `id:"all"` untuk lepas semua)
8. `mcp_repeater_send` (replay tanpa browser) → `mcp_intruder_fuzz` (wordlist inline, auto URL-encode) → `mcp_browser_graphql` probe → `mcp_collaborator_start/poll` untuk OOB
9. `mcp_history_list` + HAR review → `mcp_browser_close`

Aturan detail + 47 tools: lihat [`SKILL.md`](SKILL.md).

### Tips anti-nyangkut (dari pengalaman)

- Tombol tak ada di elements → `mcp_browser_submit(formId)` atau `keys Enter`.
- CAPTCHA gambar/checkbox → `mcp_browser_ground`, klik via `x,y` dari gambar.
- Slider GeeTest / canvas → `mcp_browser_view` lalu `mcp_browser_drag(x1,y1,x2,y2)`.
- Session `Connection refused` / hang setelah intercept → `mcp_browser_recover` atau attach `sessionId` baru, jangan retry session yang wedge.
- `poll` harus **langsung** setelah trigger — `eval`-fetch yang menunggu = wedge.

## Keamanan

- Scope allowlist ditegakkan di `navigate`, `repeater_send`, `intruder_fuzz`, `graphql`. Default `scope.json.example` = disabled agar demo jalan; **aktifkan sebelum hunting target nyata**.
- `audit.jsonl`: key sensitif (`password/token/secret/cookie/api-key/bearer`) di-redact + body dipotong 500 char. Jangan commit file runtime.
- Vault 600. Jangan taruh kredensial asli di `.example`.
- Hanya pakai terhadap target yang Anda punya izin uji.

## Publish ke GitHub (checklist)

```bash
cd browser-mcp
# pastikan tidak ada secret bocor:
grep -ri "password\|token\|api.key\|bearer" --include="*.py" --include="*.md" --include="*.json" --include="*.sh" . | grep -v example | grep -v REDACT || echo "bersih"
git init && git add . && git commit -m "browser-mcp standalone v0.4.0" && git branch -M main
gh repo create browser-mcp --public --source=. --push
```

## Troubleshooting

| Gejala | Obat |
|---|---|
| `websocket` import error | `pip3 install websocket-client` |
| chromium not found | `sudo apt install chromium` / `brew install --cask chromium`, lalu `./install.sh` ulang |
| MCP tidak muncul di client | restart client; pastikan path `server.py` absolut; `python3 scripts/smoke_test.py` harus PASS |
| `Connection refused` / session wedged | `mcp_browser_recover` atau launch `reuse:false` / attach sessionId baru |
| stop intercept hang | server sudah auto-lepas paused + timeout 10 dtk; bila wedge, attach session baru dan abandon lama |

## Lisensi

MIT — lihat [LICENSE](LICENSE).