# 🎭 MCP Playwright Server

MCP (Model Context Protocol) server that enables Claude Code to control a browser via Playwright. Perfect for web scraping, automation, and research in **research-modular**.

## Features

- ✅ **Navigate**: Load any website and wait for dynamic content
- ✅ **Screenshot**: Capture full pages or viewport screenshots  
- ✅ **Scrape**: Extract text, links, images, forms with structured output
- ✅ **Form Fill**: Interact with forms, fill fields, submit
- ✅ **PDF Export**: Generate PDFs from any page
- ✅ **Session Management**: Multiple browser sessions simultaneously
- ✅ **Output Formats**: JSON, Markdown, HTML

## Installation

### Option 1: npm (once published)
```bash
npm install -g mcp-playwright-server
```

### Option 2: Direct from GitHub (now)
```bash
npx -y github:Jens0110/mcp-playwright-server
```

### Option 3: Local development
```bash
git clone https://github.com/Jens0110/mcp-playwright-server
cd mcp-playwright-server
npm install
npm run build
npm start
```

## Setup with Claude Code

### 1. Add MCP server to Claude config
```bash
claude mcp add playwright -- npx -y github:Jens0110/mcp-playwright-server
```

Or manually in `~/.claude/config.json`:
```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "github:Jens0110/mcp-playwright-server"]
    }
  }
}
```

### 2. Restart Claude Code
The browser automation tools are now available in Claude Code.

## Usage Examples

### Navigate to a website
```
use_mcp_tool: playwright_navigate
{
  "url": "https://www.fillout.com",
  "timeout": 30000
}
```

### Take a screenshot
```
use_mcp_tool: playwright_screenshot
{
  "session_id": "default",
  "full_page": true,
  "filename": "fillout-homepage.png"
}
```

### Scrape content
```
use_mcp_tool: playwright_scrape
{
  "session_id": "default",
  "extract_text": true,
  "extract_links": true,
  "extract_forms": true,
  "format": "json"
}
```

### Fill and submit a form
```
use_mcp_tool: playwright_form_fill
{
  "session_id": "default",
  "selectors": {
    "input[name='email']": "user@example.com",
    "input[name='password']": "secret123",
    "input[type='checkbox']": "on"
  },
  "submit_selector": "button[type='submit']",
  "wait_for_navigation": true
}
```

### Generate PDF
```
use_mcp_tool: playwright_pdf
{
  "session_id": "default",
  "filename": "page-export.pdf",
  "format": "A4"
}
```

## Integration with research-modular

Perfect for competitive analysis:

```
/research-modular

"Analyze Fillout's pricing page"

→ navigate to fillout.com/pricing
→ screenshot
→ scrape pricing tables
→ extract feature comparison
→ → Add to Feature-Matrix
→ → Generate Positioning Map
```

## Output Locations

- **Screenshots**: `~/.cache/research-modular/screenshots/`
- **PDFs**: `~/.cache/research-modular/pdfs/`
- **Scraped data**: JSON output (in-memory)

## Session Management

Each session maintains its own browser context:

```javascript
// Session 1: Analyze Competitor A
playwright_navigate({ url: "competitor-a.com", session_id: "competitor-a" })
playwright_scrape({ session_id: "competitor-a" })

// Session 2: Analyze Competitor B (parallel!)
playwright_navigate({ url: "competitor-b.com", session_id: "competitor-b" })
playwright_scrape({ session_id: "competitor-b" })
```

## Performance

- First page load: ~3-5 seconds (browser startup)
- Subsequent pages: ~1-2 seconds  
- Screenshot generation: ~500ms
- PDF generation: ~1-2 seconds
- Memory: ~200MB per active session

## Limitations

- No support for authenticated browsing yet (Session 2)
- JavaScript execution limited to DOM manipulation (no custom scripts)
- Form interactions limited to standard inputs (no complex JS-heavy forms)

## Troubleshooting

### "Browser launch failed"
```bash
# Install browser dependencies
npm install -D @playwright/test
npx playwright install chromium
```

### "Connection timeout"
- Increase `timeout` parameter (in milliseconds)
- Check internet connection
- Website might be blocking automated access

### "Form fill not working"
- Verify CSS selector is correct
- Try waiting longer with navigation
- Check if form requires JavaScript initialization

## Future Enhancements

- [ ] Session persistence (cookies/auth)
- [ ] Custom JavaScript execution
- [ ] Network interception & HAR export
- [ ] Performance metrics collection
- [ ] Video recording
- [ ] Mobile device emulation

## Architecture

```
Claude Code
    ↓
[MCP Protocol]
    ↓
Playwright Server
    ↓
[Browser Pool]
    ↓
Chromium Browser
    ↓
[websites]
```

## Contributing

Contributions welcome! Please:
1. Fork the repo
2. Create a feature branch
3. Add tests
4. Submit PR

## License

MIT

## Support

- Issues: https://github.com/Jens0110/mcp-playwright-server/issues
- Docs: https://playwright.dev
- MCP Spec: https://modelcontextprotocol.io