Skip to main content
Glama
README.md
# vscode-browser MCP

MCP server untuk mengendalikan browser dari AI agent. Menyediakan **dua mode**:

1. **Playwright headless** (`playwright-core`) — cepat dan ringan, cocok untuk otomasi umum.
2. **Integrated Browser VS Code** — memakai mesin browser bawaan VS Code sehingga lebih tahan terhadap proteksi anti-bot (mis. Cloudflare).

Halaman juga dapat ditampilkan sebagai **live screencast** di tab VS Code melalui extension pendukung.

> Dibangun di atas [`@modelcontextprotocol/sdk`](package.json), [`playwright-core`](package.json), dan [`ws`](package.json).

---

## Daftar Tool

### Tool browser Playwright (headless)
| Tool | Fungsi |
|---|---|
| `browser_navigate` | Buka URL dan (opsional) tampilkan viewer di tab VS Code |
| `browser_show_panel` | Tampilkan ulang viewer untuk halaman aktif |
| `browser_snapshot` | Ambil accessibility snapshot (teks) untuk memilih selector |
| `browser_click` | Klik elemen via selector Playwright |
| `browser_type` | Isi field input (opsional tekan Enter) |
| `browser_press_key` | Tekan tombol keyboard |
| `browser_evaluate` | Jalankan ekspresi JavaScript di halaman |
| `browser_console` | Ambil pesan console/error |
| `browser_tabs` / `browser_select_tab` | Kelola daftar tab |
| `browser_resize` | Ubah viewport (uji responsif) |
| `browser_reload` / `browser_back` | Reload / kembali |
| `browser_screenshot` | Simpan screenshot ke file |
| `browser_viewer_status` | Status bridge screencast & panel |
| `browser_close` | Tutup browser & panel |

### Tool Integrated Browser VS Code
| Tool | Fungsi |
|---|---|
| `browser_integrated_open` | Buka halaman di Integrated Browser, kembalikan `pageId` + snapshot |
| `browser_integrated_read` | Baca snapshot ARIA halaman aktif |
| `browser_integrated_click` | Klik elemen memakai `ref` dari snapshot |
| `browser_integrated_type` | Ketik teks / tekan tombol pada elemen |
| `browser_integrated_navigate` | Navigasi, `back`, atau `reload` |
| `browser_integrated_pages` | Daftar halaman yang dibagikan |
| `browser_integrated_screenshot` | Screenshot halaman Integrated Browser |
| `browser_integrated_playwright` | Jalankan potongan kode Playwright pada halaman |
| `browser_integrated_status` | Status page yang dikendalikan |

---

## Arsitektur singkat

```
AI Agent (Cline/Roo/klien MCP)
        │  stdio (MCP)
        ▼
  src/server.js  ──►  src/tools.js
        │                 │
        │                 ├─► src/browser.js     (Playwright headless: msedge/chrome)
        │                 ├─► src/viewer.js      (panel live, HTTP ke extension port 47823)
        │                 └─► src/integrated.js  (Integrated Browser via extension port 47823)
        │
        └─► src/bridge.js  (WebSocket screencast, :47824, token)
```

**Penting:** fitur *Integrated Browser* dan *live viewer* bergantung pada extension VS Code
**FMK VSCode Browser** yang menyediakan HTTP API lokal di `127.0.0.1:47823`. Extension ini
merupakan komponen terpisah dan **tidak termasuk dalam repo ini**. Tanpa extension tersebut,
semua tool Playwright tetap berfungsi, tetapi tool `browser_integrated_*` akan gagal
(`fetch failed`).

---

## Prasyarat

- **Node.js 18+**
- **Google Chrome atau Microsoft Edge** terpasang. `playwright-core` tidak membundel browser;
  ia memakai channel `msedge` lalu `chrome`. Jika tidak ada, set `BROWSER_EXECUTABLE`.
- (Opsional) Extension **FMK VSCode Browser** untuk fitur tab VS Code.

---

## Instalasi

```bash
npm install
```

Jalankan server:

```bash
npm start
```

Server berkomunikasi lewat **stdio** (standar MCP), dan membuka bridge WebSocket di
`ws://127.0.0.1:47824/view` untuk screencast.

---

## Konfigurasi Environment

| Variabel | Default | Keterangan |
|---|---|---|
| `BROWSER_EXECUTABLE` | _(kosong)_ | Path Chrome/Edge lain. Kosong = pakai channel `msedge`/`chrome` |
| `HEADLESS` | `1` | `1` = headless; `0` = tampil jendela (lebih tahan anti-bot) |
| `BRIDGE_PORT` | `47824` | Port WebSocket viewer bridge |
| `BRIDGE_TOKEN` | _(acak)_ | Token akses bridge |
| `VSCODE_BROWSER_PORT` | `47823` | Port HTTP API extension VS Code |
| `VIEWER_MODE` | `live` | `live` (screencast) atau `integrated` |
| `INTEGRATED_PAGE_ID` | _(kosong)_ | Page ID Integrated Browser awal |

Lihat [`.env.example`](.env.example) untuk contoh. **Jangan** commit file `.env` berisi rahasia.

---

## Menambahkan ke klien MCP (contoh Cline/Roo)

Tambahkan entri berikut ke konfigurasi MCP klien Anda (sesuaikan path clone):

```json
{
  "mcpServers": {
    "vscode-browser": {
      "command": "node",
      "args": ["/path/ke/mcp-vscode-browser/src/server.js"],
      "env": {
        "HEADLESS": "0"
      }
    }
  }
}
```

> Gunakan `HEADLESS=0` bila banyak situs menolak akses headless.

---

## Menjalankan extension VS Code (opsional)

Untuk mengaktifkan Integrated Browser & live viewer:

1. Pasang extension **FMK VSCode Browser** (`fmkelana.fmk-vscode-browser`) di VS Code.
2. **Reload window** VS Code (`Developer: Reload Window`) agar server di port `47823` aktif.
3. Verifikasi: `curl http://127.0.0.1:47823/status` harus mengembalikan `{"ok":true,...}`.

---

## Struktur Proyek

```
.
├─ src/
│  ├─ server.js        # entry point MCP (stdio + bridge)
│  ├─ tools.js         # registrasi semua tool MCP
│  ├─ browser.js       # Playwright headless (navigate/click/screenshot/…)
│  ├─ bridge.js        # WebSocket screencast viewer
│  ├─ viewer.js        # klien HTTP ke extension (panel live)
│  ├─ integrated.js    # klien Integrated Browser (extension :47823)
│  ├─ selftest.js      # uji cepat browser
│  ├─ mcptest.js       # uji end-to-end via MCP client
│  └─ bridgetest.js    # uji bridge WebSocket
├─ .env.example
├─ .gitignore
├─ package.json
└─ README.md
```

---

## Testing

```bash
npm run selftest      # uji navigate, snapshot, evaluate, console
npm run test:mcp      # uji end-to-end lewat MCP client
npm run test:bridge   # uji WebSocket bridge
```

Skrip test memakai URL default `https://fmkelana.fmk`; ubah lewat env `SELFTEST_URL`
mis. `SELFTEST_URL=https://example.com npm run selftest`.

---

## Troubleshooting

- **`fetch failed` pada `browser_integrated_*` / `browser_show_panel`** → extension belum
  aktif. Reload window VS Code lalu pastikan port `47823` listen.
- **Cloudflare "Just a moment…" / status 403** → headless mudah terdeteksi. Jalankan dengan
  `HEADLESS=0` dan/atau gunakan Integrated Browser.
- **Situs anti-bot ketat (mis. Shopee) menampilkan halaman verifikasi** → umumnya butuh sesi
  login dan reputasi IP bersih; otomasi anonim akan ditolak oleh server.
- **`Gagal meluncurkan browser headless`** → Chrome/Edge tidak terpasang. Set
  `BROWSER_EXECUTABLE` ke path browser.

---

## Keamanan

- Bridge hanya bind ke `127.0.0.1` dan memakai token acak per sesi.
- **Jangan commit** file berisi rahasia (`.env`, backup konfigurasi MCP pribadi).
  Aturan ini sudah ditangani oleh [`.gitignore`](.gitignore).

---

## Lisensi

MIT