# Browser Operator ⚡

> Connects your live Google Chrome browser directly to AI Agents and MCP clients without restarting Chrome, bypassing the need for guest profiles or remote debugging flags.

Built with a **Manifest V3 Chrome Extension** (`chrome.tabs`, `chrome.scripting`, `chrome.debugger`) and a local **Model Context Protocol (MCP) Server** communicating over an authenticated local WebSocket bridge (`ws://127.0.0.1:8765`).

---

## 🌟 How it Works

```mermaid
graph LR
  A["AI Agent / MCP Client"] -->|MCP stdio| B["Local MCP Server (Node.js)"]
  B <-->|Authenticated WS ws://127.0.0.1:8765| C["Chrome Extension (Manifest V3)"]
  C <-->|chrome.tabs & scripting API| D["Your Live Chrome (Any Website / Web App)"]
```

Unlike traditional debugging flags (`--remote-debugging-port`), this architecture works seamlessly inside your existing Chrome instance with:
- ✅ **No Chrome restarts required**
- ✅ **Works across ANY website & web application** (Gmail, LinkedIn, GitHub, AWS, ChatGPT, etc.)
- ✅ **All active logins & sessions preserved**
- ✅ **Full session cookies & 2FA intact**
- ✅ **Instant tab switching, clicking, typing, scrolling, and DOM extraction**

---

## 🔒 Security Architecture

To protect your browser against unauthorized local access and malicious websites, the bridge implements multi-layered security controls:

1. **Cryptographic Token Authentication (Shared Secret)**:
   - All connections to the local WebSocket bridge require a 256-bit entropy token.
   - Automatically generated and securely stored at `~/.browser-operator/token`.
   - Unauthenticated or invalid connections are dropped immediately (`4001 Unauthorized`).
   - Run `npm run token` to view your security token.

2. **Cross-Site WebSocket Hijacking (CSWSH) Prevention**:
   - Web browsers do not enforce Same-Origin Policy on WebSockets by default. To prevent malicious websites visited in your browser from attempting to connect to `127.0.0.1:8765`, the bridge inspects the `Origin` header.
   - Any connection originating from a web page (`http://` or `https://`) is immediately terminated (`4003 Forbidden`).
   - Only the trusted Chrome Extension origin (`chrome-extension://`) and local Node.js backend processes are permitted.

---

## 🚀 Quick Setup (1 Minute)

### 1. Load the Chrome Extension:
1. Open Google Chrome and go to `chrome://extensions`.
2. Toggle on **Developer mode** (top right corner).
3. Click **Load unpacked** (top left).
4. Select the `extension` folder from this project:
   ```
   C:\Users\r123t\Documents\www\browser-operator\extension
   ```
5. You'll see the **⚡ Browser Operator** icon appear in your Chrome toolbar.

### 2. Pair with Security Token:
1. Get your security token by running:
   ```bash
   npm run token
   ```
   *(or copy it from `~/.browser-operator/token`)*
2. Click the **Browser Operator** icon in Chrome.
3. Paste the token into the **Security Token** field and click **Save Token**.
4. The status badge will turn green: **Connected** and **Authenticated**.

---

## 🛠️ MCP Tools Provided

| Tool Name | Description |
|-----------|-------------|
| `browser_list_profiles` | Lists all Google Chrome user profiles detected on this computer, showing folder names, emails, extension status, and real-time connection state. |
| `browser_launch_profile` | Launches a specific Google Chrome user profile window directly by name, folder, or email. |
| `browser_list_tabs` | Returns all open tabs across your Chrome windows (ID, title, URL, active state). |
| `browser_select_tab` | Focuses / switches to a specific tab by ID. |
| `browser_navigate` | Navigates the current tab to any URL and waits for page load. |
| `browser_get_dom` | Extracts title, URL, visible text, links, and indexed interactive `elements` with numerical `ref` IDs (`[1]`, `[2]`, ...). |
| `browser_click` | Clicks elements using an indexed `ref` (recommended), CSS selector, or visible text (smart-matches buttons/links/inputs and skips scripts/styles). |
| `browser_type` | Types into input / text fields by `ref` or CSS selector with optional Enter keypress. |
| `browser_select_option` | Selects an option from a `<select>` dropdown or custom listbox by `ref` or selector with `value` or `text`. |
| `browser_set_checked` | Sets the checked state (`true`/`false`) of a checkbox, radio, or toggle switch by `ref` or selector. |
| `browser_screenshot` | Captures visible screenshot of any tab and saves as a PNG/JPEG image to disk (supports Set-of-Marks `annotate: true`). |
| `browser_scroll` | Scrolls tab up or down smoothly. |
| `browser_evaluate` | Executes arbitrary JavaScript inside the page context. |
| `browser_upload_file` | Uploads local files to file inputs autonomously via Chrome DevTools Protocol & DataTransfer without opening OS file picker. |
| `browser_new_tab` | Opens a new tab with a given URL. |
| `browser_close_tab` | Closes any specific tab. |

---

## 📄 License
MIT © Hashan Walauwatta