# 🎭 Playwright MCP Automation

> **Bridge the gap between AI assistants and browser automation** — Control Playwright directly from natural language prompts using the Model Context Protocol (MCP).

---

## 🌟 Overview

This project integrates **Playwright** with the **Model Context Protocol (MCP)**, enabling AI tools like GitHub Copilot, Claude Desktop, or Cursor to perform browser automation tasks through simple conversational prompts.

### Why MCP + Playwright?

- **Natural Language Control**: Describe what you want instead of writing test code
- **AI-Powered Testing**: Let AI assistants handle browser interactions
- **Rapid Prototyping**: Test ideas without manual script writing
- **Flexible Automation**: Combine vision-based clicking, PDF generation, and assertions

---

## ✨ What You Can Do

Simply ask your AI assistant:

```
"Open Google and search for Playwright"
"Verify the title contains 'Playwright' and take a screenshot"
"Click the Docs tab and generate a PDF of the page"
"Find the download button using visual recognition and click it"
```

The AI translates your request → MCP Protocol → Browser Actions → Results ✨

**No need to run `npx playwright test` manually!**

---

## 📁 Project Structure

```
Playwright_MCP/
├── tests/
│   └── mcp-playwright.spec.ts    # Example Playwright test suite
├── scripts/
│   └── run-via-mcp.js             # Manual MCP client (optional)
├── mcp.config.json                # MCP server configuration
├── playwright.config.ts           # Playwright configuration
├── package.json                   # Dependencies
└── README.md                      # This file
```

---

## 🚀 Getting Started

### Prerequisites

Ensure you have the following installed:

| Tool | Check Version | Required Version |
|------|---------------|------------------|
| **Node.js** | `node --version` | v18.0.0 or higher |
| **npm** | `npm --version` | Latest stable |
| **Playwright** | `npx playwright --version` | Latest |

### Installation

1. **Clone or navigate to your project directory**

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Install Playwright browsers** (if not already installed)
   ```bash
   npx playwright install
   ```

---

## ⚙️ Configuration

### MCP Server Setup

The MCP configuration is defined in `mcp.config.json`:

```json
{
  "servers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--caps=vision,pdf,testing,tracing"
      ],
      "env": {}
    }
  }
}
```

### Enabled Capabilities

| Capability | Description |
|------------|-------------|
| **vision** | Use coordinates and OCR for element interaction |
| **pdf** | Generate PDF snapshots of web pages |
| **testing** | Run assertions (visibility, text content, values) |
| **tracing** | Collect debug traces for troubleshooting |

---

## 🎯 Usage

### Method 1: AI Assistant Integration (Recommended)

1. **Start the MCP server** in a terminal:
   ```bash
   npx @playwright/mcp@latest --caps=vision,pdf,testing,tracing --output-dir=playwright-mcp-output
   ```

   You should see:
   ```
   Listening on http://localhost:8931
   ```
   
   ⚠️ **Keep this terminal running** — the MCP server must stay active

2. **Open your AI tool** (Claude Desktop, Cursor, GitHub Copilot, etc.)

3. **Issue natural language commands**:
   ```
   "Open google.com, search 'Playwright', verify results appear, and take a screenshot"
   ```

4. **Watch the magic happen** — the AI will:
   - Connect to your MCP server
   - Control the browser
   - Execute the automation
   - Return results/screenshots

### Method 2: Manual MCP Client (Testing)

If you want to test MCP functionality without an AI assistant:

```bash
node scripts/run-via-mcp.js
```

This script will:
- Launch a browser via MCP
- Navigate to Google
- Search for "Playwright"
- Save a screenshot locally

### Method 3: Traditional Playwright Tests

Run Playwright tests the standard way (without MCP):

```bash
npx playwright test tests/mcp-playwright.spec.ts
```

---

## 📦 Output & Artifacts

All generated files are saved to:

```
playwright-mcp-output/
```

**Example artifacts:**
- `google-playwright-search.png` — Screenshots
- `page.pdf` — PDF exports
- `trace.zip` — Playwright trace files

---

## 🔧 Troubleshooting

| Issue | Solution |
|-------|----------|
| `Error: spawn npx ENOENT` | Ensure the MCP server is running in a separate terminal |
| `Server disconnected` | Restart the MCP server terminal window |
| `Browser not launching` | Run `npx playwright install` to install browser binaries |
| `Port 8931 already in use` | Kill the existing MCP process or change the port |
| `Vision capabilities not working` | Ensure `--caps=vision` is included in server args |

### Debug Mode

Run the MCP server with verbose logging:

```bash
DEBUG=* npx @playwright/mcp@latest --caps=vision,pdf,testing,tracing
```

---

## 🎯 Roadmap & Future Enhancements

- [ ] Automate complex login flows via MCP
- [ ] Advanced cursor-based interactions
- [ ] File download verification
- [ ] Trace log streaming to AI assistants
- [ ] Multi-browser support (Chromium, Firefox, WebKit)
- [ ] CI/CD pipeline integration

---

## 🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs
- Suggest new features
- Submit pull requests

---

## 📄 License

This project is licensed under the MIT License.

---

## 🔗 Resources

- [Playwright Documentation](https://playwright.dev/)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Playwright MCP Package](https://www.npmjs.com/package/@playwright/mcp)

---

**Built with ❤️ using Playwright & MCP**