playwright-mcp

What this skill does

# playwright-mcp

## Purpose
This skill provides a Playwright-based MCP server for browser automation, enabling programmatic control of web pages via the MCP protocol. It focuses on tasks like navigating sites, interacting with elements, and filling forms, integrated with OpenClaw for AI-driven workflows.

## When to Use
Use this skill for automating browser interactions in scenarios like web scraping, UI testing, or dynamic form submissions. It's ideal when you need remote browser control, such as in CI/CD pipelines, data extraction from JavaScript-heavy sites, or simulating user actions across multiple pages.

## Key Capabilities
- Launch browsers (e.g., Chromium, Firefox) and manage sessions via MCP protocol.
- Interact with page elements: select, click, or type using methods like `page.click('button')`.
- Handle form filling and submissions: auto-populate fields and submit with `page.fill('input[name="username"]', 'user123')`.
- Support for asynchronous operations: wait for elements with `page.waitForSelector('selector')`.
- Error-resilient navigation: retry failed loads with built-in timeouts.
- Configurable via JSON files, e.g., {"browser": "chromium", "headless": true}.

## Usage Patterns
To use this skill, start the MCP server and send commands from OpenClaw. Always initialize with authentication via `$PLAYWRIGHT_MCP_API_KEY`. Pattern 1: Launch a browser session and perform actions in sequence. Pattern 2: Use in loops for repetitive tasks, like form testing. For integration, wrap calls in try-catch blocks. Example pattern: Set up server with CLI, then use API endpoints to execute scripts.

## Common Commands/API
- CLI: Run `playwright-mcp start --port 8080 --headless` to launch the server; add `--debug` for verbose logging.
- API: POST to `/mcp/execute` with JSON payload, e.g., {"action": "navigate", "url": "https://example.com"}.
- Code snippet for basic navigation:
  ```
  const response = fetch('http://localhost:8080/mcp/execute', {
    method: 'POST',
    headers: {'Authorization': `Bearer ${process.env.PLAYWRIGHT_MCP_API_KEY}`},
    body: JSON.stringify({action: 'goto', url: 'https://example.com'})
  });
  ```
- For element interaction: Use `/mcp/interact` endpoint, e.g., POST with {"selector": '#id', "action": "click"}.
- Config format: YAML or JSON, e.g., {"timeout": 30000, "retries": 3} in a file passed via `--config path/to/config.json`.
- Authentication: Always include `$PLAYWRIGHT_MCP_API_KEY` in headers; check for 401 errors if missing.

## Integration Notes
Integrate by running the server as a subprocess or via HTTP clients in OpenClaw. Set `$PLAYWRIGHT_MCP_API_KEY` as an environment variable for authentication. For example, in OpenClaw scripts, import as a module and call functions like `mcpClient.execute({action: 'fill', selector: 'input', value: 'data'}). Use WebSockets for real-time updates on `/mcp/ws`. Ensure compatibility with Node.js 14+; handle CORS by adding `--allow-origins *` to CLI. Test integrations with mock servers to simulate failures.

## Error Handling
Common errors include timeout exceptions (e.g., network delays) or selector failures; use `page.waitForTimeout(5000)` before actions. For API errors, check response codes: 404 for invalid endpoints, 500 for server issues. Handle with try-catch in code, e.g.:
  ```
  try {
    await page.click('nonexistent');
  } catch (error) {
    console.error('Element not found:', error.message);
    // Retry or fallback
  }
  ```
Prescribe logging all errors with `--debug` flag. For authentication failures, verify `$PLAYWRIGHT_MCP_API_KEY` and retry. Use exponential backoff for transient errors like 429 (rate limit).

## Concrete Usage Examples
1. Automate form filling: Start server with `playwright-mcp start --port 8080`, then send API call to fill and submit a login form: POST `/mcp/execute` with {"action": "fill", "selector": '#username', "value": "testuser", "then": "click('#submit')"}. This extracts data or verifies login success.
2. Web scraping task: Use in OpenClaw to navigate to a page and extract content: CLI command `playwright-mcp execute --url 'https://site.com' --script 'page.evaluate(() => document.querySelector("#data").textContent)'`, then process the output for analysis.

## Graph Relationships
- Related to: browser-automation (depends on for core functionality), web-scraping (extends for data extraction), mcp-protocol (implements as base).
- Clusters: community (part of), automation-tools (links to for broader ecosystem).
- Dependencies: playwright-core (requires for browser control), mcp-server (bases on for protocol handling).