# 🌟 AI-Powered Web Automation with MCP
## Playwright + Model Context Protocol: Intelligent Browser Automation 🤖

> Transform your testing workflow with AI-driven automation! Combine Playwright's robust browser automation with MCP (Model Context Protocol) for intelligent, natural language-controlled testing.

[![Playwright](https://img.shields.io/badge/playwright-v1.40-brightgreen.svg)](https://playwright.dev/)
[![TypeScript](https://img.shields.io/badge/typescript-v5.3-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/mcp-v1.0-purple.svg)](https://modelcontextprotocol.ai)

## 🌟 Overview

Experience the future of web automation where AI understands your testing intentions! Simply describe what you want to test in natural language, and watch as AI orchestrates complex browser interactions automatically.

### 🔌 What is MCP (Model Context Protocol)?

MCP is an open protocol that standardizes how applications provide context to LLMs, acting like a "USB-C port for AI applications" that provides a standardized way to connect AI models to different data sources and tools. It enables seamless communication between AI assistants (like Claude) and your local automation tools, making complex web testing as simple as having a conversation.

### 🎯 What Makes This Revolutionary

- 🗣️ **Natural Language Control**: "Register a new user and add items to cart"
- 🧠 **AI-Powered Execution**: Smart element detection, timing, and error handling
- 🎲 **Dynamic Test Data**: Automatically generates realistic user data
- 🔄 **Self-Healing Tests**: Adapts to UI changes intelligently
- 🌐 **Cross-Platform**: Works with Claude Desktop, Cursor IDE, and other MCP clients

### ✨ Natural Language Examples

```
"Navigate to the website and create a new user account"
→ AI automatically generates user data and completes registration

"Browse women's clothing and add a blue dress to the cart"
→ AI navigates categories, finds products, and manages cart

"Login with the account we just created and verify it worked"
→ AI remembers credentials and validates successful authentication

"Take a screenshot of the current page"
→ AI captures and saves the current browser state
```

## 🏗️ Architecture & Execution Flow

### 🔄 Complete Execution Architecture

```
┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  You (Human User)   │    │   Cloud AI Service  │    │  Your Local Machine │
│  ┌───────────────┐  │    │  ┌───────────────┐  │    │  ┌───────────────┐  │
│  │ Claude Desktop│  │◄──►│  │ Claude AI     │  │◄──►│  │ MCP Server    │  │
│  │      or       │  │    │  │  Assistant    │  │    │  │ (Node.js)     │  │
│  │ Cursor IDE    │  │    │  │               │  │    │  │               │  │
│  └───────────────┘  │    │  └───────────────┘  │    │  └───────────────┘  │
└─────────────────────┘    └─────────────────────┘    └─────────┬───────────┘
                                                                 │
                                                                 ▼
                                                       ┌─────────────────────┐
                                                       │ Playwright Engine   │
                                                       │ ┌─────────────────┐ │
                                                       │ │ Real Browser    │ │
                                                       │ │ (Chromium)      │ │
                                                       │ │                 │ │
                                                       │ │ ┌─────────────┐ │ │
                                                       │ │ │Real Website │ │ │
                                                       │ │ │Interactions │ │ │
                                                       │ │ └─────────────┘ │ │
                                                       │ └─────────────────┘ │
                                                       └─────────────────────┘
```

### 🎯 Detailed Execution Flow

#### 📋 Step-by-Step Process:

```
1. 💬 Human Input (You)
   ↓
   "Register a new user and add items to cart"
   
2. 🌐 Client Application (Claude Desktop/Cursor)
   ↓
   Sends request to Claude AI service over HTTPS
   
3. 🧠 Claude AI (Anthropic's Cloud)
   ↓
   • Understands natural language intent
   • Decides which automation functions to call
   • Generates parameters (random user data, etc.)
   
4. 📡 MCP Protocol Communication
   ↓
   Claude connects to your local MCP server via JSON-RPC
   
5. 🖥️ Your Local MCP Server (Node.js)
   ↓
   • Receives function calls from Claude
   • Validates parameters
   • Executes Playwright scripts
   
6. 🎭 Playwright Engine (Local)
   ↓
   • Launches real browser (Chromium)
   • Performs actual web interactions
   • Manages browser state and timing
   
7. 🌍 Real Website Interaction
   ↓
   • Actual HTTP requests to automationexercise.com
   • Real form submissions and user account creation
   • Genuine e-commerce interactions
   
8. ⬅️ Results Flow Back
   ↓
   Website → Browser → Playwright → MCP Server → Claude AI → You
```

### 🔍 What Happens Behind the Scenes

#### When You Say: *"Register a new user"*

#### 🧠 Claude AI Processing:
```javascript
// Claude's internal decision making:
1. Parse intent: "User wants to register on the website"
2. Identify required function: register_new_user
3. Generate realistic test data:
   - email: "testuser_1734721171547@example.com" 
   - password: "AutoPass2025!"
   - name: "John Smith"
   - address: "123 Main Street"
4. Send MCP function call to your local server
```

#### 🖥️ Your Local MCP Server Execution:
```javascript
// Actual Playwright code that executes:
async function registerNewUser(params) {
    // 1. Navigate to signup page
    await page.goto('https://automationexercise.com');
    await page.click('a[href="/login"]');
    
    // 2. Fill initial signup form
    await page.fill('input[data-qa="signup-name"]', params.name);
    await page.fill('input[data-qa="signup-email"]', params.email);
    await page.click('button[data-qa="signup-button"]');
    
    // 3. Fill detailed registration form
    await page.fill('input[data-qa="first_name"]', params.firstName);
    await page.fill('input[data-qa="password"]', params.password);
    await page.selectOption('select[data-qa="country"]', params.country);
    // ... more form filling
    
    // 4. Submit registration
    await page.click('button[data-qa="create-account"]');
    
    // 5. Return success result
    return { success: true, email: params.email };
}
```

#### 🌐 Real Browser Actions:
- 🌐 Chromium browser window opens (headless by default)
- 📄 Actual page loads from automationexercise.com
- 🖱️ Real mouse clicks and keyboard typing
- 📝 Form data submitted to real servers
- ✅ Actual user account created in their database

### 🖥️ Platform-Specific Execution

#### 🖥️ Claude Desktop Flow:
```
Your Computer:
├── Claude Desktop App (Electron)
│   ├── Connects to Anthropic's Claude AI
│   └── MCP client built-in
├── Local MCP Server (Node.js process)
│   ├── Receives MCP calls from Claude
│   └── Executes Playwright scripts
└── Browser Process (Chromium)
    └── Real web interactions
```

#### ⌨️ Cursor IDE Flow:
```
Your Computer:
├── Cursor IDE (VS Code fork)
│   ├── MCP extension/integration
│   └── Connects to Claude AI via API
├── Local MCP Server (Node.js process)
│   ├── Started via npm start
│   └── Listens for MCP connections
└── Browser Process (Chromium)
    └── Automated by Playwright
```

### 🔐 Security & Isolation

- **Local Execution**: All browser automation happens on your machine
- **Data Privacy**: Test data never leaves your system
- **Network Isolation**: Only connects to specified test websites
- **Process Isolation**: Each browser session is isolated
- **Credential Safety**: Login details stored locally only

### 💡 Key Technical Points

1. **No Remote Browser**: Browser runs locally, not in cloud
2. **Real Interactions**: Actual website calls, not mocked responses
3. **MCP Protocol**: Standard communication between AI and tools
4. **Persistent Sessions**: Browser state maintained across function calls
5. **Error Handling**: Both AI and local server handle failures gracefully

## 🚀 Quick Start

### 📋 Prerequisites

- Node.js 18+ installed
- npm or yarn package manager
- Git for cloning the repository

### 📦 Installation

```bash
# 1. Clone the repository
git clone https://github.com/yourusername/playwright-automation-mcp.git
cd playwright-automation-mcp

# 2. Install dependencies
npm install

# 3. Install Playwright browsers
npx playwright install

# 4. Build the project
npm run build
```

### ⚙️ MCP Server Configuration

> **🔑 Important**: The MCP server runs **locally on your machine**, not in the cloud. Claude AI connects to your local server to execute automation.

#### 🔧 Understanding the Setup:
- **Claude AI**: Runs in Anthropic's cloud, understands your requests
- **MCP Server**: Runs locally on your machine, executes Playwright
- **Browser**: Launches locally, performs real web interactions

#### Option 1: Claude Desktop

1. **Install Claude Desktop** from [claude.ai](https://claude.ai/download)

2. **Locate config file:**
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

3. **Create/edit the config file:**
```json
{
  "mcpServers": {
    "playwright-automation": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/your/playwright-automation-mcp"
    }
  }
}
```

4. **Start your local MCP server:**
```bash
cd /path/to/playwright-automation-mcp
npm run build
npm start
```

5. **Verification Steps:**
   - ✅ MCP server shows: "Playwright Automation MCP Server started"
   - ✅ Restart Claude Desktop completely
   - ✅ In Claude, try: "Can you navigate to the automation exercise website?"

#### Option 2: Cursor IDE

1. **Install Cursor** from [cursor.sh](https://cursor.sh/)

2. **Configure MCP in your project:**
```bash
# In your project root
mkdir -p .cursor
```

3. **Create `.cursor/mcp.json`:**
```json
{
  "mcpServers": {
    "playwright-automation": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "."
    }
  }
}
```

4. **Start MCP server separately:**
```bash
npm run build
npm start
```

5. **In Cursor, enable MCP integration:**
   - Open Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
   - Search for "MCP" settings
   - Ensure MCP integration is enabled

#### 🔧 Configuration Troubleshooting:

```bash
# 1. Verify your project is built
ls -la dist/index.js  # Should exist

# 2. Test MCP server manually
npm start  # Should show "Server started" message

# 3. Check for port conflicts
lsof -i :3000  # Default MCP port

# 4. Kill any existing MCP processes
pkill -f "dist/index.js"
```

#### ✅ Connection Verification:

When properly configured, you should be able to:

**🖥️ In Claude Desktop:**
```
You: "Can you help me test a website?"
Claude: "I can help you with web automation! I have access to Playwright tools..."
```

**⌨️ In Cursor:**
```
You: @mcp Can you list available automation functions?
Cursor: Shows list of playwright-automation functions
```

### 🎯 Verification

Start the MCP server to test your setup:

```bash
npm start
```

You should see:
```
✅ Playwright Automation MCP Server started
🚀 Server ready for MCP connections
🎭 Playwright browsers initialized
```

## 🎮 Usage

### 🤖 With AI Assistants (Recommended)

Simply chat with your AI assistant naturally:

```
You: "Can you test the user registration flow on the automation exercise website?"

AI Assistant: I'll help you test the registration flow. Let me:
1. Navigate to the website
2. Register a new user with random data
3. Verify the registration was successful

[Executes automation automatically...]

✅ Successfully registered user: testuser_1734721171547@example.com
✅ Account creation confirmed
✅ User can login with new credentials
```

### 🔧 Direct MCP Commands (Advanced)

For advanced users or debugging:

```typescript
// Navigate to website
playwright-automation:navigate_to_automation_exercise

// Register new user (AI generates data automatically)
playwright-automation:register_new_user
{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "password": "SecurePass123!",
  "firstName": "John",
  "lastName": "Doe",
  "company": "Tech Corp",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "California",
  "zipCode": "94102",
  "country": "United States",
  "mobileNumber": "555-123-4567"
}

// Browse products by category
playwright-automation:browse_products
{
  "category": "Women"
}

// Add product to cart
playwright-automation:add_product_to_cart
{
  "productName": "Blue Top"
}
```

## 🛠️ Available Functions

| Function | Description | Parameters |
|----------|-------------|------------|
| `navigate_to_automation_exercise` | Launch AutomationExercise website | None |
| `register_new_user` | Register new account with full details | User details object |
| `login_user` | Login with existing credentials | email, password |
| `logout_user` | Logout current user | None |
| `browse_products` | Browse product catalog | category (optional) |
| `add_product_to_cart` | Add specific product to cart | productName |
| `view_cart` | Display cart contents | None |
| `take_screenshot` | Capture current page | filename (optional) |
| `click_continue` | Click continue button | None |
| `close_browser` | Close browser and cleanup | None |

## 🧪 Testing Scenarios

### 🎯 Complete User Journey
```
1. Website Navigation ✅
2. User Registration ✅
3. Account Verification ✅
4. Product Browsing ✅
5. Shopping Cart ✅
6. User Authentication ✅
7. Session Management ✅
```

### 🎲 Dynamic Test Data
The system automatically generates:
- Unique email addresses with timestamps
- Realistic names and addresses
- Valid phone numbers
- Secure passwords
- Random but valid form data

## 🔧 Development

### 📁 Project Structure

```
src/
├── index.ts                 # MCP server entry point
├── playwright-automation.ts # Core automation functions
├── config.ts               # Configuration management
├── demo.ts                 # Demonstration flows
└── utils/
    ├── helpers.ts          # Utility functions
    ├── page-objects.ts     # Page object models
    └── test-data.ts        # Test data generators
```

### 🛠️ Available Scripts

```bash
npm start          # Start MCP server
npm run dev        # Development mode with auto-reload
npm run build      # Build TypeScript to JavaScript
npm run demo       # Run demonstration automation
npm test           # Execute test suite
npm run test:ui    # Run tests with Playwright UI
npm run codegen    # Generate Playwright code
```

### 🐛 Debugging

Enable debug mode:
```bash
# Debug MCP communication
DEBUG=mcp:* npm start

# Debug Playwright actions
DEBUG=pw:api npm start

# Debug everything
DEBUG=* npm start
```

## 🚨 Troubleshooting

### Common Issues & Solutions

#### ❌ MCP Server Not Connecting
```bash
# Check if server is running
ps aux | grep "dist/index.js"

# Kill existing instances
pkill -f "dist/index.js"

# Rebuild and restart
npm run build && npm start
```

#### ❌ Browser Not Launching
```bash
# Reinstall Playwright browsers
npx playwright install --force

# Check system dependencies (Linux)
npx playwright install-deps
```

#### ❌ Configuration Issues
- Verify absolute paths in config files
- Ensure `dist/index.js` exists after building
- Check file permissions
- Restart AI client after config changes

#### ❌ Function Calls Failing
- Confirm MCP server is running
- Check browser is properly initialized
- Verify website is accessible
- Review error messages in server logs

### 🔍 Health Check

Test your setup:
```bash
# Verify server health
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'
```

## 🎯 Target Application & Website

This automation targets [AutomationExercise](https://www.automationexercise.com/), which provides:

- 👤 **User Management**: Registration, login, logout flows
- 🛍️ **Product Catalog**: Categories, search, product details
- 🛒 **Shopping Cart**: Add/remove items, checkout process
- 📱 **Responsive Design**: Mobile and desktop layouts
- 🧪 **Rich Test Scenarios**: Perfect for automation practice

## 🤝 Contributing & Development

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push to branch: `git push origin feature/amazing-feature`
5. Open a Pull Request


## 🙋 Support

### 📚 **Documentation & Resources**

- 🎭 **[Playwright Documentation](https://playwright.dev)** - Master browser automation with comprehensive guides, APIs, and examples
- 🤖 **[MCP Documentation](https://docs.anthropic.com/en/docs/mcp)** - Learn Model Context Protocol for building AI-powered automation tools
- 🏢 **[Official Playwright MCP](https://github.com/microsoft/playwright-mcp)** - Microsoft's official MCP server implementation (17.6k ⭐)

## 👨‍💻 Author

**Devendra Singh** - Quality Engineering Specialist, AI & Automation Enthusiast

- 🔗 **[LinkedIn Profile](https://www.linkedin.com/in/devendra-singh-quality-engineering/)** - Connect for professional opportunities and collaboration
- 🐙 **[GitHub Profile](https://github.com/devqa07)** - View other projects and contributions
- 📧 **Contact** - Reach out through LinkedIn or GitHub for questions and partnerships

---

<div align="center">

### 🌟 Transform Your Testing with AI-Powered Automation! 🌟


</div>