Playwright MCP Server

A custom Model Context Protocol (MCP) server for generating Playwright tests directly from Cursor's chat interface.

Overview

This MCP server integrates with Cursor to provide AI-powered Playwright test generation. When you type a prompt in Cursor's chat, the server:

1. Identifies which page you're referring to using your site context file
2. Navigates to that page to capture the current HTML and screenshot
3. Analyzes your existing test files to extract reusable code patterns
4. Determines the best location for the new test based on your project structure
5. Combines all this context with your prompt
6. Generates a complete Playwright test that follows your existing patterns

Key Features

• Site Context Integration: Uses your site-context.json file to understand your website structure
• Authentication Support: Handles pages that require login
• Code Reuse: Analyzes your existing tests to avoid duplicating code
• Project Structure Analysis: Ensures generated tests follow your project's conventions
• Cursor Integration: Works directly from Cursor's chat interface

Installation

# Clone or extract this repository
cd playwright-mcp-server

# Install dependencies
npm install

# Make the server executable
chmod +x src/index.js

# Link the package globally (optional)
npm link

Usage

Setting Up Your OpenAI API Key

The MCP server requires an OpenAI API key to generate tests. Set it as an environment variable:

export OPENAI_API_KEY="your-api-key"

Starting the Server Manually

You can start the server manually for testing:

npm start

Configuring Cursor to Use Your MCP

Create or update .cursor/settings.json in your project:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "playwright-mcp-server"
      ]
    }
  }
}

If you didn't use npm link, specify the path to the server:

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": [
        "/path/to/playwright-mcp-server/src/index.js"
      ]
    }
  }
}

Using in Cursor Chat

Once configured, you can use it in Cursor's chat:

/mcp playwright Create a test on the checkout page that validates the payment button

Site Context File

The server looks for a site context file in your project. This file should be named site-context.json and should have the following structure:

{
  "baseURL": "https://your-site.com",
  "pages": {
    "/": {
      "title": "Homepage",
      "description": "Main landing page",
      "elements": {
        "loginButton": "#login-btn",
        "signupLink": ".signup-link"
      }
    },
    "/checkout": {
      "title": "Checkout",
      "description": "Payment processing page",
      "elements": {
        "paymentButton": "#pay-now-btn",
        "cardNumberField": "input[name='card-number']"
      }
    }
  }
}

The server will look for this file in the following locations:

• site-context.json in the project root
• site-context.txt in the project root
• data/site-context.json
• config/site-context.json
• playwright-mcp-system/site-context.json

Authentication Configuration

For pages that require authentication, you can create an authentication configuration file:

1. Create a file named .playwright-mcp-auth.json in your project root:

{
  "enabled": true,
  "loginUrl": "https://your-site.com/login",
  "usernameSelector": "#username",
  "passwordSelector": "#password",
  "submitSelector": "button[type='submit']",
  "username": "your-username",
  "password": "your-password",
  "requiresLogin": [
    "/account*",
    "/checkout",
    "*secure*"
  ]
}

2. Or use the API to create a sample configuration:

curl -X POST http://localhost:3000/create-sample-auth \
  -H "Content-Type: application/json" \
  -d '{"workspaceRoot": "/path/to/your/project"}'

How It Works

Page Identification

When you mention a page in your prompt (e.g., "Create a test on the checkout page"), the server:

1. Looks for exact matches of page names in your site context
2. Checks if your prompt mentions page descriptions
3. Defaults to the homepage if no match is found

Test File Analysis

The server analyzes your existing test files to:

1. Extract locators, fixtures, helper functions, and page objects
2. Identify common patterns in your tests
3. Determine your project's file naming conventions
4. Understand your project's directory organization

Project Structure Analysis

The server analyzes your project structure to:

1. Determine where test files are located
2. Identify file naming conventions (kebab-case, camelCase, etc.)
3. Understand directory organization (flat, by-feature, etc.)
4. Find fixture, helper, and page object files

MCP Generation

The server generates an MCP that includes:

1. Page URL, title, and description
2. Current HTML of the page
3. A screenshot of the page
4. Existing elements and locators from your site context
5. Reusable code patterns from your existing tests
6. Project structure information
7. Recommended location for the new test
8. Your original prompt

Test Generation

The AI uses this context to generate a Playwright test that:

1. Uses existing locators when available
2. Follows the patterns from your existing test files
3. Includes appropriate assertions
4. Handles necessary setup and teardown
5. Is robust and maintainable
6. Follows your project's file naming conventions
7. Is saved to the appropriate location in your project

API Endpoints

The server provides the following API endpoints:

• POST /mcp: Main endpoint for generating MCPs
• POST /save-test: Saves a generated test to the appropriate location
• POST /auth-config: Gets or updates authentication configuration
• POST /create-sample-auth: Creates a sample authentication configuration

Troubleshooting

Server Won't Start

• Make sure you have Node.js installed
• Check that all dependencies are installed with npm install
• Verify that the server file is executable with chmod +x src/index.js

API Key Issues

• Ensure your OpenAI API key is set: export OPENAI_API_KEY="your-api-key"
• Check that the key is valid and has sufficient credits

Cursor Integration Issues

• Verify your .cursor/settings.json file is correctly formatted
• Make sure Cursor can find the MCP server executable
• Try restarting Cursor after making changes

Test Generation Issues

• Check that your site context file is valid JSON
• Ensure your site is accessible from the server
• Make your prompts more specific if the wrong page is being identified

Publishing to npm

To publish the package to npm:

1. Update the package.json file with your details
2. Login to npm: npm login
3. Publish the package: npm publish

License

MIT