---
sidebar_position: 4
title: "@zibby/mcp-browser"
---

# @zibby/mcp-browser

Wrapper around [`@playwright/mcp`](https://github.com/anthropics/playwright-mcp) with stable ID injection, event recording, and session-aware video capture.

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

> Installed automatically as a dependency of `@zibby/core`.

## Why a Wrapper?

The official `@playwright/mcp` provides standard browser automation tools. `@zibby/mcp-browser` adds:

| Feature | Description |
|---|---|
| **Stable IDs** | Injects deterministic `data-zibby-id` attributes into the DOM, so selectors survive page re-renders |
| **Event Recording** | Captures every MCP tool call (navigate, click, type) with timestamps for the action timeline |
| **Session Awareness** | Reads `ZIBBY_SESSION_INFO` to know which session and node is active — saves videos and events to the right directory |
| **Video Capture** | Records browser sessions as video with configurable resolution |

## Usage

### As an MCP Server (standalone)

```bash
npx mcp-browser-zibby --save-video=1280x720 --viewport-size=1280x720 --output-dir=./output
```

### Via the Browser Skill (recommended)

The browser skill in `@zibby/skills` resolves to `@zibby/mcp-browser` automatically:

```javascript
import { SKILLS } from '@zibby/core';

export const myNode = {
  name: 'my_node',
  skills: [SKILLS.BROWSER],
  // The framework starts @zibby/mcp-browser as an MCP server
  // and wires it to whichever agent is active
};
```

### Programmatic

```javascript
import { startServer } from '@zibby/mcp-browser';

const server = await startServer({
  saveVideo: '1280x720',
  viewportSize: '1280x720',
  outputDir: './test-results',
});
```

## Stable IDs

Standard CSS selectors break when the DOM changes between renders. Stable IDs solve this by injecting deterministic attributes based on element role, position, and content:

```html
<!-- Before stable ID injection -->
<button class="btn-primary sc-fEOsli">Submit</button>

<!-- After stable ID injection -->
<button class="btn-primary sc-fEOsli" data-zibby-id="form-submit-button">Submit</button>
```

The stable ID algorithm considers:
- Element tag and ARIA role
- Accessible name and label
- Position relative to landmarks
- Content hash for disambiguation

This gives the AI and generated Playwright scripts more reliable selectors.

## Event Recording

Every MCP tool call is recorded as a structured event:

```json
{
  "timestamp": 1710784523000,
  "node": "execute_live",
  "tool": "browser_click",
  "arguments": { "element": "Submit button", "ref": "s1e45" },
  "result": "Clicked",
  "duration": 234
}
```

Events are saved to `{sessionPath}/{nodeName}/events.json` and used by:
- The **action timeline** in the Zibby dashboard
- The **generate_script** node to produce accurate Playwright scripts
- The **memory** system to record selector usage

## CLI Options

| Flag | Default | Description |
|---|---|---|
| `--save-video=WxH` | — | Record video at specified resolution |
| `--viewport-size=WxH` | `1280x720` | Browser viewport size |
| `--output-dir=PATH` | `test-results/` | Where to save video and event files |
| `--headed` | `false` | Show the browser window |
| `--headless` | `true` | Run without a visible window |