@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

npm install @zibby/mcp-browser

Usage

As MCP Server

Add to your MCP configuration:

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

Command Line

# 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:

[
  {
    "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:

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

Compatibility

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

License

MIT

Related Packages

• @zibby/cli - Command-line interface
• @zibby/test-automation-core - Core automation engine
• @zibby/mcp-jira - Jira MCP server