# Playwright MCP HTTP Server

A standalone HTTP service that wraps the official `@playwright/mcp` package to provide browser automation capabilities via HTTP endpoints. This service enables the use of Playwright MCP in serverless environments where STDIO-based communication is not possible.

**🎯 Now Enhanced as a Visual Sensor Skill** - Beyond browser automation, this server provides intelligent, privacy-aware, and user-friendly web interaction capabilities.

## Features

- 🌐 **Streamable-HTTP Transport** - Implements the 2025 MCP standard for remote connections
- 🔒 **Bearer Token Authentication** - Secure authentication required for production use
- 🚀 **Serverless Compatible** - Works in serverless/cloud environments (Railway, Render, Fly.io, GCP Cloud Run, etc.)
- 🔄 **MCP v0.1 Compatible** - Fully implements the Model Context Protocol specification
- 📡 **Server-Sent Events (SSE)** - Bidirectional streaming support for real-time notifications
- 🎭 **Full Playwright Support** - All Playwright browser automation tools available
- 🐳 **Docker Ready** - Includes Dockerfile for easy containerization
- ⚡ **Production Ready** - Health checks, graceful shutdown, error handling
- ☁️ **Live Deployment** - Pre-deployed to Google Cloud Run with HTTPS (see below)

### 🆕 Visual Sensor Skill Features

- 🔍 **Snapshot-First Logic** - Token-efficient accessibility tree snapshots (no full DOM needed)
- 🛡️ **PII Blurring (Agentic Security)** - Automatic redaction of emails, credit cards, phone numbers, and other PII from screenshots
- 👤 **Human-in-the-Loop (Elicitation)** - Detects MFA/login walls and requests user input instead of failing
- 🎯 **High-Level Skills** - Skill-based tools (e.g., `perform_checkout`) that handle complex workflows internally

See [VISUAL_SENSOR_SKILL_IMPLEMENTATION.md](./VISUAL_SENSOR_SKILL_IMPLEMENTATION.md) for detailed documentation.

## Quick Start

### Prerequisites

- Node.js 18+ (LTS recommended)
- npm or yarn

### Installation

```bash
# Clone the repository
git clone https://github.com/mcpmessenger/playwright-mcp.git
cd playwright-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start
```

The server will start on port `8931` by default. You can access:

- **Service Info**: http://localhost:8931/
- **Health Check**: http://localhost:8931/health
- **MCP Endpoint**: http://localhost:8931/mcp
  - **POST** - Send JSON-RPC messages (client-to-server)
  - **GET** - Open SSE connection (server-to-client) with `Accept: text/event-stream`

### 🚀 Live Production Instance

The service is deployed to Google Cloud Run and ready to use:

- **Service URL**: https://playwright-mcp-http-server-554655392699.us-central1.run.app
- **Health Check**: https://playwright-mcp-http-server-554655392699.us-central1.run.app/health
- **MCP Endpoint**: https://playwright-mcp-http-server-554655392699.us-central1.run.app/mcp (POST only)

You can use the live instance immediately without deploying your own. See [Usage Examples](#example-usage) below.

### Development

```bash
# Run in development mode with auto-reload
npm run dev
```

## Configuration

Configuration is done via environment variables. Create a `.env` file or set environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8931` | HTTP server port |
| `PLAYWRIGHT_BROWSER` | `chromium` | Browser type (chromium, firefox, webkit) |
| `PLAYWRIGHT_HEADLESS` | `true` | Run browser in headless mode |
| `LOG_LEVEL` | `info` | Logging level (error, warn, info, debug) |
| `MAX_SESSIONS` | (unlimited) | Maximum concurrent browser sessions |
| `SESSION_TIMEOUT` | (none) | Session timeout in seconds |
| `CORS_ORIGIN` | `*` | CORS allowed origins |
| `AUTH_TOKEN` | (none) | Bearer token for authentication (required for production) |
| `AUTH_SECRET_NAME` | (none) | GCP Secret Manager secret name (alternative to AUTH_TOKEN) |
| `GCP_PROJECT_ID` | (auto) | GCP project ID (required if using AUTH_SECRET_NAME) |

See `.env.example` for a template.

## Authentication

**⚠️ Important**: For production deployments, authentication is required to comply with the 2025 MCP Streamable-HTTP standard.

### Setting Up Authentication

1. **Direct Token** (Development/Testing):
   ```bash
   export AUTH_TOKEN="your-secure-token-here"
   ```

2. **GCP Secret Manager** (Production - Recommended):
   ```bash
   export AUTH_SECRET_NAME="playwright-mcp-auth-token"
   export GCP_PROJECT_ID="your-project-id"
   ```

See [REGISTRY_CONFIG.md](./REGISTRY_CONFIG.md) for detailed authentication setup instructions.

### Using Authentication

All requests to `/mcp` require a bearer token:

```bash
curl -X POST http://localhost:8931/mcp \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

## API Documentation

### POST /mcp

Main MCP protocol endpoint for client-to-server messages. Accepts JSON-RPC 2.0 messages.

**Authentication**: Required (Bearer token)

**Request:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "browser_navigate",
    "arguments": {
      "url": "https://example.com"
    }
  }
}
```

**Response:**
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Navigation completed"
      }
    ],
    "isError": false
  }
}
```

### GET /health

Health check endpoint. Returns service status.

**Response:**
```json
{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2024-12-01T12:00:00.000Z"
}
```

### GET /

Service information endpoint.

**Response:**
```json
{
  "name": "Playwright MCP HTTP Server",
  "version": "1.0.0",
  "protocol": "MCP v0.1",
  "endpoints": {
    "mcp": "/mcp",
    "health": "/health"
  }
}
```

## Supported MCP Methods

The server supports all standard MCP methods:

- `initialize` - Initialize MCP connection
- `initialized` - Confirm initialization
- `tools/list` - List available Playwright tools
- `tools/call` - Invoke a Playwright tool

### Available Tools

#### Standard Playwright Tools

All tools from `@playwright/mcp` are supported:

- `browser_navigate` - Navigate to a URL
- `browser_snapshot` - Get accessibility snapshot (uses accessibility tree for token efficiency)
- `browser_take_screenshot` - Capture screenshot (automatically redacts PII)
- `browser_click` - Click an element
- `browser_type` - Type text
- `browser_fill_form` - Fill form fields
- `browser_evaluate` - Execute JavaScript
- `browser_wait_for` - Wait for conditions
- `browser_close` - Close browser/page

#### Custom Visual Sensor Skill Tools

- `get_accessibility_snapshot` - Token-efficient accessibility tree snapshot (snapshot-first approach)
  - Returns only interactive elements
  - Reduces token usage vs full DOM
  - Optimized for LLM consumption

- `perform_checkout` - High-level checkout skill
  - Orchestrates complete checkout process
  - Handles navigation, form filling, error handling, and retries internally
  - Returns only final confirmation

- `fill_form_skill` - Intelligent form filling
  - Automatically detects and fills form fields
  - Uses browser_fill_form internally with smart field detection

**Note**: Screenshots from `browser_take_screenshot` automatically have PII redacted before being returned. Login walls and MFA requirements automatically trigger elicitation requests via notifications.

For detailed tool parameters, see the [Playwright MCP documentation](https://github.com/microsoft/playwright-mcp) and [VISUAL_SENSOR_SKILL_IMPLEMENTATION.md](./VISUAL_SENSOR_SKILL_IMPLEMENTATION.md).

## Using the Server

- Start locally with `npm install`, build (`npm run build`), then run `npm start` (or use `npm run dev` for auto-reload during development).
- Call `/`, `/health`, or `/mcp` via curl/Postman/Playwright MCP clients; the `/mcp` endpoint accepts JSON-RPC POST requests (see the example below).
- Adjust behavior by editing `.env` or setting env vars such as `PORT`, `PLAYWRIGHT_BROWSER`, and `PLAYWRIGHT_HEADLESS`.
- Alternatively, containerize the service with `docker build -t playwright-mcp-http-server .` and `docker run -p 8931:8931 ...` for consistent deployments.

### Visual Sensor Skill Capabilities

The server automatically:
- ✅ **Redacts PII** from screenshots (emails, credit cards, phone numbers, SSNs)
- ✅ **Detects login walls** and sends elicitation requests via notifications
- ✅ **Provides token-efficient snapshots** via accessibility tree
- ✅ **Offers high-level skills** for complex workflows

See [VISUAL_SENSOR_SKILL_IMPLEMENTATION.md](./VISUAL_SENSOR_SKILL_IMPLEMENTATION.md) for detailed documentation on these features.

## Updating the GitHub Repository

- Pull the latest changes before making edits: `git pull --rebase origin main`.
- Use `git status` to see touched files, then stage with `git add <files>` and commit with a descriptive message.
- Push your branch with `git push origin HEAD` and open a pull request if the change needs review.

## Example Usage

### Using curl

```bash
# List available tools
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

# Navigate to a page
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "browser_navigate",
      "arguments": {
        "url": "https://example.com"
      }
    }
  }'

# Take a screenshot (PII automatically redacted)
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "browser_take_screenshot",
      "arguments": {
        "fullPage": true
      }
    }
  }'

# Get accessibility snapshot (token-efficient)
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_accessibility_snapshot",
      "arguments": {
        "interestingOnly": true
      }
    }
  }'

# Use high-level checkout skill
curl -X POST http://localhost:8931/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "perform_checkout",
      "arguments": {
        "cartData": {
          "items": [{"name": "Product", "quantity": 1}],
          "shippingAddress": {"name": "...", "address": "..."},
          "paymentMethod": {"type": "card", "cardNumber": "..."}
        }
      }
    }
  }'
```

### Using JavaScript/TypeScript

```typescript
// Use the live production instance or replace with your own deployment URL
const MCP_SERVER_URL = 'https://playwright-mcp-http-server-554655392699.us-central1.run.app/mcp';
const AUTH_TOKEN = 'your-token-here'; // Required for production

// Open SSE connection for server-to-client notifications
const eventSource = new EventSource(MCP_SERVER_URL, {
  headers: {
    'Authorization': `Bearer ${AUTH_TOKEN}`
  }
});

eventSource.onmessage = (event) => {
  const notification = JSON.parse(event.data);
  console.log('Server notification:', notification);
};

eventSource.onerror = (error) => {
  console.error('SSE connection error:', error);
};

// Send JSON-RPC requests (client-to-server)
async function callPlaywrightMCP(method: string, params?: any) {
  const response = await fetch(MCP_SERVER_URL, {
    method: 'POST',
    headers: { 
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${AUTH_TOKEN}`
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: Date.now(),
      method,
      params,
    }),
  });
  return response.json();
}

// List tools
const tools = await callPlaywrightMCP('tools/list');

// Navigate
await callPlaywrightMCP('tools/call', {
  name: 'browser_navigate',
  arguments: { url: 'https://example.com' },
});

// Take screenshot
const screenshot = await callPlaywrightMCP('tools/call', {
  name: 'browser_take_screenshot',
  arguments: { fullPage: true },
});
```

**Note**: For production, always use HTTPS and include the bearer token in the `Authorization` header.

### GET /mcp (Streamable-HTTP)

Opens a Server-Sent Events (SSE) connection for server-to-client messages. This implements the Streamable-HTTP transport protocol.

**Authentication**: Required (Bearer token)  
**Headers**: `Accept: text/event-stream`

**Example:**
```bash
curl -N -H "Accept: text/event-stream" \
     -H "Authorization: Bearer your-token-here" \
     http://localhost:8931/mcp
```

The connection will:
- Send connection confirmation
- Forward MCP notifications from the Playwright process
- Send periodic ping messages to keep the connection alive
- Close gracefully when the client disconnects

**Note**: 
- POST `/mcp` is for sending JSON-RPC requests (client-to-server)
- GET `/mcp` is for receiving notifications via SSE (server-to-client)
- Both endpoints require authentication when `AUTH_TOKEN` or `AUTH_SECRET_NAME` is set

## Deployment

### Railway

1. Create a new Railway project
2. Connect your Git repository
3. Railway will auto-detect Node.js and use `npm start`
4. Set environment variables if needed
5. Deploy!

The service will use Railway's `$PORT` environment variable automatically.

### Render

1. Create a new Web Service on Render
2. Connect your Git repository
3. Build command: `npm install && npm run build`
4. Start command: `npm start`
5. Set environment variables if needed
6. Deploy!

### Google Cloud Platform (Cloud Run)

See [DEPLOY_GCP.md](./DEPLOY_GCP.md) for detailed instructions.

**Quick deploy with authentication:**

```bash
# Set your project ID
export GCP_PROJECT_ID="your-project-id"

# Option 1: Deploy with bearer token (recommended)
export AUTH_MODE=token
export AUTH_TOKEN=$(openssl rand -hex 32)  # Generate secure token
chmod +x deploy-gcp.sh && ./deploy-gcp.sh

# Option 2: Deploy with Secret Manager (best for production)
export AUTH_MODE=secret
export AUTH_SECRET_NAME="playwright-mcp-auth-token"
chmod +x deploy-gcp.sh && ./deploy-gcp.sh

# Option 3: Deploy without authentication (development only - NOT recommended)
export AUTH_MODE=public
chmod +x deploy-gcp.sh && ./deploy-gcp.sh
```

**Windows PowerShell:**
```powershell
$env:GCP_PROJECT_ID = "your-project-id"
$env:AUTH_MODE = "token"
$env:AUTH_TOKEN = [System.Convert]::ToBase64String([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32))
.\deploy-gcp.ps1 -ProjectId "your-project-id"
```

**⚠️ Security Note**: Always use authentication (`AUTH_MODE=token` or `AUTH_MODE=secret`) for production deployments. Public access (`AUTH_MODE=public`) should only be used for local development.

Or manually:

```bash
PROJECT_ID="your-project-id"
IMAGE="gcr.io/${PROJECT_ID}/playwright-mcp-http-server"

docker build -t $IMAGE .
docker push $IMAGE

gcloud run deploy playwright-mcp-http-server \
    --image $IMAGE \
    --region us-central1 \
    --platform managed \
    --allow-unauthenticated \
    --port 8931 \
    --memory 2Gi \
    --cpu 2
```

### Fly.io

1. Install Fly CLI: `curl -L https://fly.io/install.sh | sh`
2. Login: `fly auth login`
3. Launch app: `fly launch`
4. Deploy: `fly deploy`

### Docker

```bash
# Build the image
docker build -t playwright-mcp-http-server .

# Run the container
docker run -p 8931:8931 playwright-mcp-http-server

# With environment variables
docker run -p 8931:8931 \
  -e PORT=8931 \
  -e PLAYWRIGHT_HEADLESS=true \
  playwright-mcp-http-server
```

### Docker Compose

```yaml
version: '3.8'
services:
  playwright-mcp:
    build: .
    ports:
      - "8931:8931"
    environment:
      - PORT=8931
      - PLAYWRIGHT_HEADLESS=true
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:8931/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

## Streamable-HTTP (2025 MCP Standard)

This service implements the **Streamable-HTTP** transport protocol, which is the 2025 MCP standard for remote connections. Streamable-HTTP requires:

- ✅ **HTTPS** - Automatically provided by Cloud Run
- ✅ **Bearer Token Authentication** - Required for production use
- ✅ **Server-Sent Events (SSE)** - For server-to-client streaming
- ✅ **POST Endpoint** - For client-to-server JSON-RPC messages

### Registry Configuration

To register this service with an MCP registry, use this configuration:

```json
{
  "name": "playwright-service",
  "transport": "streamable-http",
  "url": "https://your-service-url.run.app/mcp",
  "auth": {
    "type": "bearer",
    "token": "your-secure-token"
  }
}
```

See [REGISTRY_CONFIG.md](./REGISTRY_CONFIG.md) for complete registry setup instructions.

## Architecture

The service works by:

1. **HTTP Server** (Express) receives JSON-RPC requests and SSE connections
2. **Authentication Middleware** validates bearer tokens
3. **MCP Handler** processes the requests and routes them to Playwright
4. **Playwright Process Manager** spawns `@playwright/mcp` as a child process
5. **STDIO Communication** handles JSON-RPC messages via stdin/stdout
6. **SSE Streaming** forwards server notifications to connected clients
7. **Response** is formatted and returned via HTTP

This architecture allows the Playwright process to run independently while being accessible via HTTP/HTTPS with full Streamable-HTTP support.

## Troubleshooting

### Service won't start

- Check that Node.js 18+ is installed: `node --version`
- Verify dependencies are installed: `npm install`
- Check logs for error messages

### Playwright browser not found

- The browser will be downloaded automatically on first run
- For Docker, ensure system dependencies are installed (included in Dockerfile)
- Check network connectivity for browser downloads

### High memory usage

- Consider setting `MAX_SESSIONS` to limit concurrent sessions
- Ensure `browser_close` is called when done with a session
- Monitor for memory leaks in long-running processes

### Timeout errors

- Increase request timeout if operations take longer than 30 seconds
- Check network connectivity to target URLs
- Verify Playwright process is not crashed

## Development

### Project Structure

```
playwright-mcp-http-server/
├── src/
│   ├── server.ts              # HTTP server setup
│   ├── mcp-handler.ts         # MCP protocol handler
│   ├── playwright-process.ts  # Playwright process management
│   ├── config.ts              # Configuration
│   └── types/
│       └── mcp.ts             # TypeScript types
├── dist/                      # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── Dockerfile
└── README.md
```

### Building

```bash
npm run build
```

### Running Tests

*Note: Tests are not yet implemented but planned for future releases*

## License

MIT

## References

- [Playwright MCP GitHub](https://github.com/microsoft/playwright-mcp)
- [MCP Specification](https://modelcontextprotocol.io)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
- [Playwright Documentation](https://playwright.dev)

## Support

For issues and questions, please open an issue on the repository.