npm package: @freelw/playwright-mcp-wrapper
Description: A wrapper for @playwright/mcp that handles CDP endpoint acquisition from cloud platform for Cursor MCP integration
Author: wangli
Latest version: 2.0.3

# @freelw/playwright-mcp-wrapper

A wrapper for `@playwright/mcp` that handles CDP endpoint acquisition from cloud platform for Cursor MCP integration.

## Overview

This package serves as a bridge between Cursor's MCP (Model Context Protocol) system and Playwright MCP. It automatically acquires a CDP (Chrome DevTools Protocol) endpoint from your cloud platform using your project ID and API key, then launches Playwright MCP with the acquired endpoint.

## Installation

```bash
npm install @freelw/playwright-mcp-wrapper
```

## Usage in Cursor

Add this to your Cursor MCP configuration:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@freelw/playwright-mcp-wrapper@latest",
        "--project-id=your-project-id",
        "--api-key=your-api-key"
      ]
    }
  }
}
```

## Command Line Usage

You can also run it directly:

```bash
npx @freelw/playwright-mcp-wrapper --project-id=your-project-id --api-key=your-api-key
```

## Configuration

### Required Parameters (choose one)

**Option 1: Using Cloud Platform**
- `--project-id`: Your project ID for the cloud platform
- `--api-key`: Your API key for authentication

**Option 2: Using Direct CDP Endpoint**
- `--cdp-endpoint`: Direct CDP endpoint URL (e.g., `wss://example.com/devtools/browser/123`)

### Optional Parameters

- `--timeout-action`: Action timeout in milliseconds (default: 15000ms)
- `--timeout-navigation`: Navigation timeout in milliseconds (default: 15000ms)
- `--clear-all`: Close all existing pages before starting (requires CDP endpoint to be available)

### Examples

**Using project ID and API key:**
```bash
npx @freelw/playwright-mcp-wrapper --project-id=test_project_123 --api-key=test_api_key_456
```

**Using direct CDP endpoint:**
```bash
npx @freelw/playwright-mcp-wrapper --cdp-endpoint=wss://browser.example.com/devtools/browser/123
```

**Clear all existing pages before starting:**
```bash
# With CDP endpoint
npx @freelw/playwright-mcp-wrapper --cdp-endpoint=wss://... --clear-all

# With project ID and API key
npx @freelw/playwright-mcp-wrapper --project-id=xxx --api-key=xxx --clear-all
```

## How it Works

1. The wrapper receives your project ID and API key
2. It calls the cloud platform API to create a browser session
3. It retrieves the WebSocket CDP endpoint from the session
4. It launches `@playwright/mcp` with the acquired CDP endpoint
5. Cursor can now interact with Playwright through the MCP protocol

## API Endpoints

The wrapper uses the following cloud platform API endpoints:

- `POST /instance` - Create a new browser session
- `GET /json/version?session_id=<id>` - Get WebSocket debugger URL
- `GET /health` - Health check
- `GET /logs/<session_id>` - Get session logs
- `DELETE /instance?session_id=<id>` - Delete session

## Environment Variables

You can optionally set the following environment variables:

- `WS_PREFIX` - WebSocket URL prefix (default: `wss://freelw.cc`)
- `MCP_DEBUG` - Enable debug logging (set to `true` or `1` to enable)

### Debug Logging

When `MCP_DEBUG` is enabled, all stdin/stdout/stderr communications with the Playwright process will be logged to:

```
~/.playwright-mcp/logs/mcp-debug-{timestamp}.log
```

To enable debug logging in Cursor, add the environment variable to your MCP configuration:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@freelw/playwright-mcp-wrapper@latest",
        "--project-id=your-project-id",
        "--api-key=your-api-key"
      ],
      "env": {
        "MCP_DEBUG": "true"
      }
    }
  }
}
```

Or when running from command line:

```bash
MCP_DEBUG=true npx @freelw/playwright-mcp-wrapper --project-id=xxx --api-key=xxx
```

## Development

### Prerequisites

- Node.js 16+
- TypeScript

### Build

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

## License

MIT