# Playwright MCP Proxy

A proxy server for Microsoft's [playwright-mcp](https://github.com/microsoft/playwright-mcp) that provides efficient handling of large binary data (screenshots, PDFs) through blob storage and supports browser pools for concurrent operations.

**Version 2.0.0**: Now with browser pools! Run multiple isolated browser instances with different configurations simultaneously.

## Features

- **Browser Pools**: Multiple isolated browser instances organized into named pools with different configurations
- **Concurrent Operations**: Lease browser instances for exclusive use, enabling parallel browser automation
- **Playwright Browser Automation**: Full access to all playwright-mcp browser automation tools
- **Stealth Mode**: Built-in anti-detection capabilities (see [STEALTH.md](docs/STEALTH.md))
- **Efficient Binary Handling**: Large screenshots and PDFs automatically stored as blobs to reduce token usage
- **Blob Storage**: Built-in blob management using [mcp-mapped-resource-lib](https://github.com/nickweedon/mcp_mapped_resource_lib)
- **Automatic Cleanup**: TTL-based automatic expiration of old blobs
- **Docker Support**: Containerized deployment with multi-runtime support (Python + Node.js + Playwright)
- **Health Monitoring**: Real-time pool status and instance health checks

## Quick Start

### Prerequisites

- Python 3.10 or higher
- Node.js 18+ (for playwright-mcp)
- [uv](https://github.com/astral-sh/uv) package manager (recommended)
- Docker (optional, for containerized deployment)

### Installation

1. Clone this repository:

```bash
git clone <this-repo> playwright-proxy-mcp
cd playwright-proxy-mcp
```

2. Install dependencies:

```bash
uv sync
```

3. Create your environment file:

```bash
cp .env.example.single-pool .env
# Edit .env with your configuration
```

4. Run the server:

```bash
uv run playwright-proxy-mcp
```

The server will:
- Start the playwright-mcp subprocess(es) via npx
- Initialize blob storage
- Initialize browser pools
- Listen for MCP client connections on stdio

## Browser Pools

### Overview

Browser pools allow you to run multiple browser instances with different configurations:

```bash
# Global defaults (apply to all pools)
PW_MCP_PROXY_BROWSER=chromium
PW_MCP_PROXY_HEADLESS=true

# Define a pool with 3 instances
PW_MCP_PROXY__DEFAULT_INSTANCES=3
PW_MCP_PROXY__DEFAULT_IS_DEFAULT=true
PW_MCP_PROXY__DEFAULT_DESCRIPTION="General purpose browsing"

# Instance-level overrides
PW_MCP_PROXY__DEFAULT__0_BROWSER=firefox      # Instance 0 uses Firefox
PW_MCP_PROXY__DEFAULT__1_ALIAS=debug          # Instance 1 has alias "debug"
PW_MCP_PROXY__DEFAULT__1_HEADLESS=false       # Instance 1 runs headed
```

### Using Pools

All browser tools accept optional `browser_pool` and `browser_instance` parameters:

```python
# Use default pool, FIFO instance selection
await browser_navigate(url="https://example.com")

# Use specific pool
await browser_navigate(url="https://example.com", browser_pool="FIREFOX")

# Use specific instance by alias
await browser_navigate(url="https://example.com", browser_instance="debug")
```

### Monitoring Pools

```python
# Get status of all pools
status = await browser_pool_status()
for pool in status["pools"]:
    print(f"{pool['name']}: {pool['available_instances']}/{pool['total_instances']} available")
```

See [docs/BROWSER_POOLS_SPEC.md](docs/BROWSER_POOLS_SPEC.md) for complete configuration reference.

## Docker Deployment

Build and run with Docker Compose:

```bash
docker compose up -d
```

This will:
- Build a container with Python, Node.js, and Playwright browsers
- Create persistent volumes for blob storage and playwright output
- Start the proxy server

## Configuration

Configure the proxy via environment variables in `.env`:

### Global Browser Settings

- `PW_MCP_PROXY_BROWSER`: Browser to use (chromium, firefox, webkit) - default: chromium
- `PW_MCP_PROXY_HEADLESS`: Run headless - default: true
- `PW_MCP_PROXY_CAPS`: Capabilities (vision,pdf,testing,tracing) - default: vision,pdf
- `PW_MCP_PROXY_TIMEOUT_ACTION`: Action timeout in ms - default: 15000
- `PW_MCP_PROXY_TIMEOUT_NAVIGATION`: Navigation timeout in ms - default: 30000

### Pool Configuration

- `PW_MCP_PROXY__<POOL>_INSTANCES`: Number of instances in pool
- `PW_MCP_PROXY__<POOL>_IS_DEFAULT`: Mark as default pool
- `PW_MCP_PROXY__<POOL>_DESCRIPTION`: Pool description
- `PW_MCP_PROXY__<POOL>__<ID>_BROWSER`: Browser for specific instance
- `PW_MCP_PROXY__<POOL>__<ID>_ALIAS`: Alias for specific instance
- `PW_MCP_PROXY__<POOL>__<ID>_HEADLESS`: Headless mode for specific instance

### Stealth Settings (Anti-Detection)

- `PW_MCP_PROXY_ENABLE_STEALTH`: **Quick enable** - Auto-configure stealth settings - default: false
- `PW_MCP_PROXY_USER_AGENT`: Custom user agent string - optional
- `PW_MCP_PROXY_INIT_SCRIPT`: Path to custom init script - optional
- `PW_MCP_PROXY_IGNORE_HTTPS_ERRORS`: Ignore HTTPS errors - default: false

**Tip**: Simply set `PW_MCP_PROXY_ENABLE_STEALTH=true` to automatically enable anti-detection features!

See [docs/STEALTH.md](docs/STEALTH.md) for detailed stealth configuration.

### Blob Storage Settings

- `BLOB_STORAGE_ROOT`: Storage directory - default: /mnt/blob-storage
- `BLOB_MAX_SIZE_MB`: Max size per blob - default: 500
- `BLOB_TTL_HOURS`: Time-to-live for blobs - default: 24
- `BLOB_SIZE_THRESHOLD_KB`: Size threshold for blob storage - default: 50
- `BLOB_CLEANUP_INTERVAL_MINUTES`: Cleanup frequency - default: 60

See example env files in the repository root for complete configuration examples.

## How It Works

### Binary Data Interception

The proxy automatically detects large binary data in playwright tool responses:

1. When playwright tools return screenshots or PDFs
2. If the data size exceeds the threshold (default: 50KB)
3. The proxy stores the binary data as a blob
4. The response is transformed to include a blob reference instead

**Before (direct playwright-mcp):**
```json
{
  "screenshot": "data:image/png;base64,iVBORw0KGgo...500KB of data..."
}
```

**After (through proxy):**
```json
{
  "screenshot": "blob://1733577600-a3f2c1d9e4b5.png",
  "screenshot_size_kb": 500,
  "screenshot_mime_type": "image/png",
  "screenshot_expires_at": "2024-12-08T10:00:00Z"
}
```

### Retrieving Blobs

Blob retrieval is handled by a separate MCP Resource Server. See [mcp-mapped-resource-lib](https://github.com/nickweedon/mcp_mapped_resource_lib) for details.

## Available Tools

### Browser Tools

All playwright-mcp tools are available with browser pool support:

- `browser_navigate`: Navigate to a URL
- `browser_click`: Click an element
- `browser_fill`: Fill a form field
- `browser_screenshot`: Take a screenshot (auto-stored as blob if large)
- `browser_snapshot`: Get ARIA snapshot
- `browser_evaluate`: Execute JavaScript
- And 40+ more tools...

All tools accept optional `browser_pool` and `browser_instance` parameters.

### Pool Management

- `browser_pool_status(pool_name)`: Get pool health, lease activity, and instance status

## Architecture

```
┌─────────────────────────────────┐
│  MCP Client (Claude Desktop)   │
└────────────┬────────────────────┘
             │ stdio
┌────────────▼────────────────────┐
│  FastMCP Proxy (Python)         │
│  - Pool Manager                 │
│  - Binary Interception          │
│  - Blob Storage Integration     │
│  - Instance Leasing (FIFO)      │
└────────────┬────────────────────┘
             │ stdio (per instance)
┌────────────▼────────────────────┐
│  playwright-mcp instances       │
│  - Browser Automation           │
│  - Screenshot/PDF Generation    │
└─────────────────────────────────┘
```

## Testing

Run the test suite:

```bash
uv run pytest -v
```

Lint the code:

```bash
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```

## Project Structure

```
src/playwright_proxy_mcp/
├── server.py              # Main MCP proxy server
├── types.py               # TypedDict definitions
├── playwright/            # Playwright proxy components
│   ├── config.py         # Configuration loading (pool config)
│   ├── pool_manager.py   # Browser pool management
│   ├── process_manager.py # Subprocess management
│   ├── blob_manager.py   # Blob storage wrapper
│   ├── middleware.py     # Binary interception
│   └── proxy_client.py   # Stdio transport integration
└── utils/
    ├── navigation_cache.py     # TTL-based pagination cache
    ├── aria_processor.py       # ARIA snapshot processing
    └── jmespath_extensions.py  # Custom JMESPath functions
```

## Benefits

### Token Savings

Large screenshots can consume 50,000+ tokens. With blob storage:
- Screenshots stored as blobs use ~100 tokens for the reference
- Retrieve full data only when needed
- Automatic cleanup prevents storage bloat

### Concurrent Operations

Browser pools enable:
- Parallel browser automation
- Instance isolation for concurrent tasks
- Different browser configurations for different use cases

### Performance

- Faster response times for tool calls
- Reduced context window usage
- Efficient deduplication of identical screenshots
- FIFO instance leasing for fair resource allocation

## Troubleshooting

### npx not found

Ensure Node.js is installed and npx is in your PATH:

```bash
node --version
npx --version
```

### Playwright browser installation fails

Install browsers manually:

```bash
npx playwright@latest install chromium --with-deps
```

### Blob storage permissions

Ensure the blob storage directory is writable:

```bash
chmod -R 755 /mnt/blob-storage
```

### Pool not starting

Check the pool configuration in your `.env` file. Ensure:
- At least one pool has `IS_DEFAULT=true`
- Instance counts are valid (positive integers)
- No alias conflicts with numeric instance IDs

## License

MIT

## Contributing

Contributions welcome! Please open an issue or pull request.

## Resources

- [Playwright MCP](https://github.com/microsoft/playwright-mcp)
- [FastMCP Documentation](https://gofastmcp.com)
- [MCP Mapped Resource Lib](https://github.com/nickweedon/mcp_mapped_resource_lib)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Browser Pools Specification](docs/BROWSER_POOLS_SPEC.md)