mirror of
https://gitea.toothfairyai.com/ToothFairyAI/tf_code.git
synced 2026-04-11 03:08:41 +00:00
chore: bump version to 1.0.20
This commit is contained in:
Gab
314
docs/playwright-mcp-setup.md
Normal file
314
docs/playwright-mcp-setup.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 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_
|
||||
Reference in New Issue
Block a user