# Laptop Browser Bridge — MCP server + Chrome extension

Yes — a Chrome extension is the right approach (and fully possible). This repo lets an **AI coding agent running on your VPS** control **any website in your laptop's Chrome**.

```
[Laptop Chrome + Extension] --outbound WSS--> [VPS: Bridge :3001 + MCP :3000] --MCP--> [AI agent on VPS]
```

Laptop is behind NAT, so the extension dials **out** to the VPS. No port-forwarding on the laptop. The MCP server runs next to the agent on the VPS.

## Repo layout

```
src/
  index.ts     # starts WS bridge (:3001) + MCP Streamable HTTP (:3000)
  bridge.ts    # tracks connected laptops, request/response correlation
  mcp.ts       # MCP tools: tabs_*, page_snapshot/click/type/press/scroll/...
  protocol.ts  # WS message types
extension/
  manifest.json
  popup.html / popup.js          # configure VPS URL + token
  background/service-worker.js   # WS client, tab APIs
  content/content.js             # DOM snapshot/click/type
```

## MCP tools (what the VPS agent gets)

| Tool | What it does |
|---|---|
| `bridge_status` | list connected laptops — call first |
| `tabs_list/create/close/activate` | manage laptop tabs |
| `page_navigate` | go to URL |
| `page_snapshot` | see page as `- [e12] button "Submit"` refs |
| `page_click` / `page_type` / `page_press` | act on refs |
| `page_scroll` / `page_text` | scroll, read text |
| `page_evaluate` | run custom JS (sparingly) |

Typical agent loop: `bridge_status` → `tabs_create`/`page_navigate` → `page_snapshot` → `page_click`/`page_type` → repeat.

## 1. VPS setup

```bash
git clone <this-repo> && cd browser-bridge-mcp
cp .env.example .env   # set BRIDGE_TOKEN to a long random secret
npm install
npm run build
BRIDGE_TOKEN=your-secret npm start
# → WS  ws://0.0.0.0:3001/bridge
# → MCP  http://0.0.0.0:3000/mcp
# → health http://0.0.0.0:3000/health
```

Production: put `wss://` in front via Caddy/Nginx (TLS terminates there, proxies to :3001). Keep `:3000` on localhost — the agent runs on the same VPS.

Connect your agent (same VPS) to `http://localhost:3000/mcp`. Examples:

**opencode / Claude Code / generic MCP client:**
```json
{ "mcpServers": { "laptop-browser": { "url": "http://localhost:3000/mcp" } } }
```

## 2. Laptop setup (Chrome)

1. `chrome://extensions` → enable **Developer mode** → **Load unpacked** → select `extension/`.
2. Click the extension icon → set:
   - Bridge URL: `wss://your-vps-domain` (or `ws://<vps-ip>:3001` for testing)
   - Token: same `BRIDGE_TOKEN`
   - Client ID: `laptop-1`
3. **Save + Connect** → status turns green. Keep Chrome open; laptop must stay awake.

## 3. Verify end-to-end

On VPS: `curl localhost:3000/health` should list `laptop-1`. Then in the agent: call `bridge_status`, then `tabs_list`, then `page_snapshot`.

## Security notes

- `BRIDGE_TOKEN` is mandatory in production — bridge rejects bad tokens (code 4401).
- Extension uses `<all_urls>` + `tabs`/`scripting` because the point is "any website". It only acts when the VPS sends a command.
- `page_evaluate` is powerful — only connect agents you trust. For hardening: bind MCP to `127.0.0.1`, add IP allowlist, rotate token.
- MV3 service workers sleep — the extension reconnects with backoff + `alarms` heartbeat (~20s).

## Dev

```bash
npm run typecheck
npm run build
npm run dev   # tsx watch
```