# Quest Browser MCP Server

An MCP (Model Context Protocol) server for controlling Oculus Browser via WebSocket CDP protocol. This server provides Playwright-like functionality using direct Chrome DevTools Protocol (CDP) commands, making it compatible with Oculus Browser's CDP 1.3 protocol.

## Features

- **Reliable WebSocket CDP Connection** - Bypasses Playwright's initialization issues
- **Full Playwright-like API** - All common browser automation features
- **TypeScript Implementation** - Type-safe and maintainable
- **MCP Protocol** - Standard Model Context Protocol server
- **CDP 1.3 Compatible** - Works with Oculus Browser's protocol version

## Prerequisites

1. **Oculus Quest** with browser running
2. **ADB** installed and in system PATH
3. **Device connected** via USB or wireless ADB

**Note:** The MCP server automatically sets up port forwarding on startup. You don't need to run `adb forward` manually.

## Installation

```bash
npm install
npm run build
```

## Usage

### As MCP Server

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "quest-browser": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "CDP_ENDPOINT": "http://localhost:9222",
        "ADB_PATH": "adb"
      }
    }
  }
}
```

### Direct Usage

```bash
# Development mode
npm run dev

# Production mode
npm run build
npm start
```

## Available Tools

### ADB Management

- `adb_check` - Check if ADB is available and get version
- `adb_list_devices` - List all ADB devices (connected and disconnected)
- `adb_get_connected_devices` - Get only connected ADB devices
- `adb_forward_port` - Set up ADB port forwarding (default: tcp:9222 -> localabstract:chrome_devtools_remote)
- `adb_list_forwardings` - List all active ADB port forwardings
- `adb_remove_forwarding` - Remove ADB port forwarding
- `adb_ensure_forwarding` - Ensure port forwarding is set up (check first, then set up if needed)

### Browser Management

- `browser_initialize` - Initialize browser connection and get available pages
- `browser_connect` - Connect to a specific page by index
- `browser_list_pages` - List all available pages
- `browser_get_current_page` - Get information about the currently connected page

### Navigation

- `browser_navigate` - Navigate to a URL
- `browser_wait_for_load` - Wait for page to finish loading
- `browser_get_url` - Get the current page URL
- `browser_get_title` - Get the page title
- `browser_go_back` - Navigate back in browser history
- `browser_go_forward` - Navigate forward in browser history
- `browser_reload` - Reload the current page
- `browser_wait_for_navigation` - Wait for navigation to complete
- `browser_wait_for_url` - Wait for URL to match pattern

### Interaction

- `browser_click` - Click an element by CSS selector
- `browser_type` - Type text into an input element
- `browser_wait_for_selector` - Wait for an element to appear
- `browser_fill` - Fill form field with value (more robust than type)
- `browser_select_option` - Select option(s) in a dropdown
- `browser_check` - Check a checkbox or radio button
- `browser_uncheck` - Uncheck a checkbox
- `browser_hover` - Hover over an element
- `browser_double_click` - Double click an element
- `browser_right_click` - Right click an element
- `browser_press_key` - Press a keyboard key
- `browser_drag_and_drop` - Drag and drop an element

### Content & Evaluation

- `browser_evaluate` - Evaluate JavaScript expression in page context
- `browser_get_content` - Get the full HTML content of the page
- `browser_screenshot` - Take a screenshot of the current page
- `browser_query_selector` - Query a single element by CSS selector
- `browser_query_selector_all` - Query multiple elements by CSS selector
- `browser_get_text` - Get text content of an element
- `browser_get_attribute` - Get attribute value of an element
- `browser_get_inner_html` - Get inner HTML of an element
- `browser_get_outer_html` - Get outer HTML of an element

### Wait Features

- `browser_wait_for_timeout` - Wait for specified time

### Network Features

- `browser_wait_for_response` - Wait for network response matching URL pattern
- `browser_get_network_logs` - Get network activity logs

### Advanced Features

- `browser_set_viewport_size` - Set viewport size
- `browser_set_geolocation` - Set geolocation
- `browser_set_permissions` - Set browser permissions
- `browser_add_init_script` - Add initialization script to run on every page load

### Accessibility

- `browser_get_accessibility_tree` - Get accessibility tree snapshot (Playwright MCP specific)
- `browser_snapshot` - Get accessibility snapshot (alias for browser_get_accessibility_tree)

### Additional Playwright MCP Tools

- `browser_close` - Close the browser connection
- `browser_console_messages` - Get console messages from the page
- `browser_file_upload` - Upload a file to a file input element
- `browser_fill_form` - Fill multiple form fields at once
- `browser_handle_dialog` - Handle a JavaScript dialog (alert, confirm, prompt)
- `browser_network_requests` - Get list of network requests
- `browser_resize` - Resize the browser viewport (alias for browser_set_viewport_size)

## Automatic ADB Setup

The MCP server automatically:

1. Checks if ADB is available in system PATH
2. Detects connected ADB devices
3. Sets up port forwarding: `tcp:9222 -> localabstract:chrome_devtools_remote`

This happens on server startup, so you don't need to manually run `adb forward`.

## Development

```bash
# Watch mode
npm run watch

# Development mode (with tsx)
npm run dev

# Build
npm run build

# Run
npm start
```

## Environment Variables

- `CDP_ENDPOINT` - CDP endpoint URL (default: `http://localhost:9222`)
- `ADB_PATH` - Path to ADB executable (default: `adb` from system PATH)