"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

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│  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 │ │ │
                                                       │ │ └─────────────┘ │ │
                                                       │ └─────────────────┘ │
                                                       └─────────────────────┘

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

// 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

// 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 };
}

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

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

# 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

{
  "mcpServers": {
    "playwright-automation": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/your/playwright-automation-mcp"
    }
  }
}

cd /path/to/playwright-automation-mcp
npm run build
npm start

# In your project root
mkdir -p .cursor

{
  "mcpServers": {
    "playwright-automation": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "."
    }
  }
}

npm run build
npm start

# 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"

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

You: @mcp Can you list available automation functions?
Cursor: Shows list of playwright-automation functions

npm start

✅ Playwright Automation MCP Server started
🚀 Server ready for MCP connections
🎭 Playwright browsers initialized

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

// 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"
}

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

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

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

# Debug MCP communication
DEBUG=mcp:* npm start

# Debug Playwright actions
DEBUG=pw:api npm start

# Debug everything
DEBUG=* npm start

# 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

# Reinstall Playwright browsers
npx playwright install --force

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

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