vscode-browser MCP
by FMKelana
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
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues