browsing-with-playwright · diff
git:20251221.db5ce2a to git:20251221.180758f
131 added, 37 removed. Audit A to A.
---
name: browsing-with-playwright
description: |
- Automates browser interactions via Playwright MCP server.
- Use when tasks require web browsing, form submission, web scraping,
- UI testing, screenshot capture, or any browser interaction.
- NOT when only fetching static content (use curl/wget instead).
+ Browser automation using Playwright MCP. Navigate websites, fill forms, click elements,
+ take screenshots, and extract data. Use when tasks require web browsing, form submission,
+ web scraping, UI testing, or any browser interaction. NOT when only fetching static
+ content (use curl/wget instead).
---
- ## Quick Start
+ # Browser Automation
+ Automate browser interactions via Playwright MCP server.
+
+ ## Server Lifecycle
+
+ ### Start Server
```bash
- # Start server
+ # Using helper script (recommended)
bash scripts/start-server.sh
- # Navigate and interact
+ # Or manually
+ npx @playwright/mcp@latest --port 8808 --shared-browser-context &
+ ```
+
+ ### Stop Server
+ ```bash
+ # Using helper script (closes browser first)
+ bash scripts/stop-server.sh
+
+ # Or manually
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_close -p '{}'
+ pkill -f "@playwright/mcp"
+ ```
+
+ ### When to Stop
+ - **End of task**: Stop when browser work is complete
+ - **Long sessions**: Keep running if doing multiple browser tasks
+ - **Errors**: Stop and restart if browser becomes unresponsive
+
+ **Important:** The `--shared-browser-context` flag is required to maintain browser state across multiple mcp-client.py calls. Without it, each call gets a fresh browser context.
+
+ ## Quick Reference
+
+ ### Navigation
+
+ ```bash
+ # Go to URL
python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate \
-p '{"url": "https://example.com"}'
+
+ # Go back
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate_back -p '{}'
```
- ## Instructions
+ ### Get Page State
- 1. Start Playwright MCP server:
- ```bash
- bash scripts/start-server.sh
- ```
+ ```bash
+ # Accessibility snapshot (returns element refs for clicking/typing)
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_snapshot -p '{}'
- 2. Navigate to target URL:
- ```bash
- python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_navigate \
- -p '{"url": "https://example.com"}'
- ```
+ # Screenshot
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_take_screenshot \
+ -p '{"type": "png", "fullPage": true}'
+ ```
- 3. Get element refs via snapshot:
- ```bash
- python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_snapshot -p '{}'
- ```
+ ### Interact with Elements
- 4. Interact using refs from snapshot:
- ```bash
- # Click
- python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_click \
- -p '{"element": "Submit", "ref": "e42"}'
+ Use `ref` from snapshot output to target elements:
- # Type
- python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_type \
- -p '{"element": "Search", "ref": "e15", "text": "query", "submit": true}'
- ```
+ ```bash
+ # Click element
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_click \
+ -p '{"element": "Submit button", "ref": "e42"}'
- 5. Run verification: `python3 scripts/verify.py`
+ # Type text
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_type \
+ -p '{"element": "Search input", "ref": "e15", "text": "hello world", "submit": true}'
- 6. Stop server when done:
- ```bash
- bash scripts/stop-server.sh
- ```
+ # Fill form (multiple fields)
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_fill_form \
+ -p '{"fields": [{"ref": "e10", "value": "john@example.com"}, {"ref": "e12", "value": "password123"}]}'
+ # Select dropdown
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_select_option \
+ -p '{"element": "Country dropdown", "ref": "e20", "values": ["US"]}'
+ ```
+
+ ### Wait for Conditions
+
+ ```bash
+ # Wait for text to appear
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
+ -p '{"text": "Success"}'
+
+ # Wait for time (ms)
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_wait_for \
+ -p '{"time": 2000}'
+ ```
+
+ ### Execute JavaScript
+
+ ```bash
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_evaluate \
+ -p '{"function": "return document.title"}'
+ ```
+
+ ### Multi-Step Playwright Code
+
+ For complex workflows, use `browser_run_code` to run multiple actions in one call:
+
+ ```bash
+ python3 scripts/mcp-client.py call -u http://localhost:8808 -t browser_run_code \
+ -p '{"code": "async (page) => { await page.goto(\"https://example.com\"); await page.click(\"text=Learn more\"); return await page.title(); }"}'
+ ```
+
+ **Tip:** Use `browser_run_code` for complex multi-step operations that should be atomic (all-or-nothing).
+
+ ## Workflow: Form Submission
+
+ 1. Navigate to page
+ 2. Get snapshot to find element refs
+ 3. Fill form fields using refs
+ 4. Click submit
+ 5. Wait for confirmation
+ 6. Screenshot result
+
+ ## Workflow: Data Extraction
+
+ 1. Navigate to page
+ 2. Get snapshot (contains text content)
+ 3. Use browser_evaluate for complex extraction
+ 4. Process results
+
+ ## Verification
+
+ Run: `python3 scripts/verify.py`
+
+ Expected: `✓ Playwright MCP server running`
+
## If Verification Fails
1. Run diagnostic: `pgrep -f "@playwright/mcp"`
2. Check: Server process running on port 8808
- 3. **Stop and report** - do not proceed with downstream steps
+ 3. Try: `bash scripts/start-server.sh`
+ 4. **Stop and report** if still failing - do not proceed with downstream steps
- ## References
+ ## Tool Reference
See [references/playwright-tools.md](references/playwright-tools.md) for complete tool documentation.
+
+ ## Troubleshooting
+
+ | Issue | Solution |
+ |-------|----------|
+ | Element not found | Run browser_snapshot first to get current refs |
+ | Click fails | Try browser_hover first, then click |
+ | Form not submitting | Use `"submit": true` with browser_type |
+ | Page not loading | Increase wait time or use browser_wait_for |
+ | Server not responding | Stop and restart: `bash scripts/stop-server.sh && bash scripts/start-server.sh` |