# @zibby/mcp-browser

Wrapper for `@playwright/mcp` with stable ID support and event recording.

## Features

- ✅ Injects stable IDs via `--init-script` for reliable element targeting
- ✅ Records browser events to `events.json` with stable IDs
- ✅ Video recording with accurate timestamp synchronization
- ✅ Passes through all official Playwright MCP functionality

## Installation

```bash
npm install @zibby/mcp-browser
```

## Usage

### As MCP Server

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@zibby/mcp-browser"]
    }
  }
}
```

### Command Line

```bash
# Basic usage (same as @playwright/mcp)
npx @zibby/mcp-browser

# With headless mode
npx @zibby/mcp-browser --headless

# With custom output directory
npx @zibby/mcp-browser --output-dir ./recordings
```

## How It Works

This package wraps the official `@playwright/mcp` and adds:

1. **Stable ID Injection**: Automatically injects stable element IDs into the page
2. **Event Recording**: Records all browser interactions with stable IDs
3. **Video Sync**: Synchronizes event timestamps with video recordings

## Event Recording

Events are recorded to `events.json` in the session directory:

```json
[
  {
    "id": 0,
    "type": "navigate",
    "timestamp": "2026-03-05T12:00:00.000Z",
    "videoOffsetMs": 0,
    "videoOffsetFormatted": "00:00:00.000",
    "data": {
      "url": "https://example.com"
    }
  },
  {
    "id": 1,
    "type": "click",
    "timestamp": "2026-03-05T12:00:02.500Z",
    "videoOffsetMs": 2500,
    "videoOffsetFormatted": "00:00:02.500",
    "data": {
      "element": "Login button",
      "stableId": "zibby-login-btn-a1b2c3"
    }
  }
]
```

## Configuration

Set the session path via environment variable:

```bash
export ZIBBY_SESSION_INFO=/path/to/.session-info.json
```

## Remote / sidecar browser (pluggable runtime)

By default the wrapper launches a **local** Chromium (the official `@playwright/mcp`
behavior). If you set `BROWSER_WS_ENDPOINT` to a remote Chrome's CDP/WS endpoint,
it instead **connects to that browser over CDP** (`connectOverCDP`) and launches
**no local Chromium** — so a browser agent can run on a slim image with no baked
browser binary, pointing at a HOSTED Chrome (browserless / Browserbase / any
CDP endpoint). On a Zibby self-host box the platform's own browser is the
on-demand `browser` sidecar deployed from the marketplace, reached over MCP —
this knob is only for bringing your own hosted Chrome.

```bash
# Connect to a hosted Chrome over CDP (no local Chromium needed):
export BROWSER_WS_ENDPOINT='wss://chrome.browserless.io?token=...'
npx @zibby/mcp-browser
```

Implemented by reusing `@playwright/mcp`'s native `--cdp-endpoint` flag (which
takes precedence over local launch). Aliases `BROWSER_CDP_ENDPOINT` and
`PLAYWRIGHT_WS_ENDPOINT` are also accepted. Unset → unchanged (launch local).

## Compatibility

- Node.js >= 18.0.0
- Compatible with all `@playwright/mcp` features
- Works with Playwright >= 1.49.0

## License

Proprietary — Copyright (c) 2026 Zibby Labs. All rights reserved.
Unauthorized copying, distribution, or use is prohibited.

## Related Packages

- [@zibby/cli](https://www.npmjs.com/package/@zibby/cli) - Command-line interface
- [@zibby/test-automation-core](https://www.npmjs.com/package/@zibby/test-automation-core) - Core automation engine
- [@zibby/mcp-jira](https://www.npmjs.com/package/@zibby/mcp-jira) - Jira MCP server