tf_code/docs/playwright-mcp-setup.md

# Playwright MCP Setup Guide for tfcode

This guide explains how to run the Playwright MCP server locally using Docker and integrate it with tfcode.

## What is Playwright MCP?

[Playwright MCP](https://github.com/microsoft/playwright-mcp) is a Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. It enables AI coding agents to:

- Navigate to web pages
- Click elements and interact with forms
- Capture page snapshots and screenshots
- Run JavaScript in the browser context
- Automate web-based workflows

The key advantage: it uses Playwright's accessibility tree instead of screenshots, making it token-efficient and LLM-friendly without requiring vision models.

## Prerequisites

Before starting, ensure you have:

1. **Docker Desktop** - [Download here](https://www.docker.com/products/docker-desktop/)
   - Make sure Docker daemon is running
   - Verify: `docker info`

2. **tfcode** - ToothFairyAI's coding agent
   - Install: `npm install -g tfcode`
   - Or run from source

## Setup Steps

### Step 1: Pull the Docker Image

```bash
docker pull mcr.microsoft.com/playwright/mcp
```

This downloads the official Playwright MCP container (~500MB).

### Step 2: Verify the Container

Test that the container runs correctly:

```bash
docker run --rm mcr.microsoft.com/playwright/mcp --help
```

You should see the Playwright MCP help output with available options.

### Step 3: Configure tfcode

Add the Playwright MCP server to your tfcode configuration.

**Option A: Project-level config (`opencode.json`)**

Create or edit `opencode.json` in your project root:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "--init", "mcr.microsoft.com/playwright/mcp"],
      "enabled": true
    }
  }
}
```

**Option B: Global config (`~/.config/opencode/opencode.json`)**

For all projects, add to your global config:

```json
{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "--init", "mcr.microsoft.com/playwright/mcp"],
      "enabled": true
    }
  }
}
```

### Step 4: Verify Connection

Run tfcode MCP list to verify the connection:

```bash
# If installed globally
tfcode mcp list

# Or running from source
bun run packages/tfcode/src/index.ts mcp list
```

Expected output:

```
✓ playwright connected
    docker run -i --rm --init mcr.microsoft.com/playwright/mcp
```

## Configuration Options

The Docker container supports various options. Pass them as additional arguments in the command array:

### Headless Mode (Default for Docker)

```json
{
  "command": ["docker", "run", "-i", "--rm", "--init", "mcr.microsoft.com/playwright/mcp", "--headless"]
}
```

### Browser Selection

```json
{
  "command": ["docker", "run", "-i", "--rm", "--init", "mcr.microsoft.com/playwright/mcp", "--browser", "firefox"]
}
```

Options: `chrome`, `firefox`, `webkit`, `msedge`

### Viewport Size

```json
{
  "command": [
    "docker",
    "run",
    "-i",
    "--rm",
    "--init",
    "mcr.microsoft.com/playwright/mcp",
    "--viewport-size",
    "1920x1080"
  ]
}
```

### Multiple Options

```json
{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "-i",
        "--rm",
        "--init",
        "mcr.microsoft.com/playwright/mcp",
        "--headless",
        "--browser",
        "chromium",
        "--viewport-size",
        "1280x720"
      ],
      "enabled": true
    }
  }
}
```

## Available Tools

Once connected, tfcode can use these Playwright MCP tools:

| Tool                       | Description                                                 |
| -------------------------- | ----------------------------------------------------------- |
| `browser_navigate`         | Navigate to a URL                                           |
| `browser_click`            | Click on an element                                         |
| `browser_type`             | Type text into an input field                               |
| `browser_snapshot`         | Capture accessibility snapshot (preferred over screenshots) |
| `browser_take_screenshot`  | Take a screenshot of the page                               |
| `browser_hover`            | Hover over an element                                       |
| `browser_evaluate`         | Execute JavaScript in the page                              |
| `browser_select_option`    | Select an option in a dropdown                              |
| `browser_fill_form`        | Fill multiple form fields at once                           |
| `browser_press_key`        | Press a keyboard key                                        |
| `browser_wait_for`         | Wait for text, element, or time                             |
| `browser_close`            | Close the browser                                           |
| `browser_tabs`             | Manage browser tabs (list, create, close, select)           |
| `browser_console_messages` | Get console messages                                        |
| `browser_network_requests` | List network requests                                       |

## Usage Examples

### Navigate to a Website

Ask tfcode:

```
Navigate to https://example.com and tell me what's on the page
```

### Form Interaction

```
Go to https://httpbin.org/forms/post, fill in the form with test data, and submit it
```

### Debugging Web Apps

```
Navigate to localhost:3000, take a snapshot, and check for any console errors
```

### Automated Testing

```
Open my local dev server at localhost:5173, click through the login flow, and verify the dashboard loads correctly
```

## Running as a Long-lived Service

Instead of spawning a container per session, you can run Playwright MCP as a persistent service:

```bash
docker run -d -i --rm --init \
  --name playwright \
  -p 8931:8931 \
  --entrypoint node \
  mcr.microsoft.com/playwright/mcp \
  cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0
```

Then configure tfcode with a remote connection:

```json
{
  "mcp": {
    "playwright": {
      "type": "remote",
      "url": "http://localhost:8931/mcp",
      "enabled": true
    }
  }
}
```

## Security Notes

- Playwright MCP is **not a security boundary** - it can access any URL
- In Docker, the browser runs in a containerized environment
- For sensitive operations, consider:
  - Using `--allowed-hosts` to restrict navigation
  - Running in isolated mode with `--isolated`
  - Using `--storage-state` for authentication persistence

## Troubleshooting

### Container Fails to Start

```bash
# Check Docker is running
docker info

# Pull latest image
docker pull mcr.microsoft.com/playwright/mcp
```

### MCP Server Shows "Failed"

```bash
# Test the container directly
docker run -i --rm --init mcr.microsoft.com/playwright/mcp

# Check tfcode logs
tfcode debug
```

### Browser Crashes or Times Out

Add timeout configuration:

```json
{
  "command": [
    "docker",
    "run",
    "-i",
    "--rm",
    "--init",
    "mcr.microsoft.com/playwright/mcp",
    "--timeout-navigation",
    "30000"
  ]
}
```

### Permission Denied on Docker Socket

```bash
# On Linux, add user to docker group
sudo usermod -aG docker $USER
# Then logout and login again
```

## Additional Resources

- [Playwright MCP GitHub](https://github.com/microsoft/playwright-mcp)
- [Playwright Documentation](https://playwright.dev)
- [MCP Specification](https://modelcontextprotocol.io)
- [tfcode Documentation](https://toothfairyai.com/developers)

---

_Last updated: 2026-03-27_