mcp-playwright-assistant

mcpassistant/mcp-playwright-assistant

3.2

If you are the rightful owner of mcp-playwright-assistant and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Playwright Assistant is an AI-enhanced server designed for intelligent web debugging and automation.

Tools
5
Resources
0
Prompts
0

MCP Playwright Assistant

AI-enhanced Playwright MCP server for intelligent web debugging and automation.

Overview

The MCP Playwright Assistant provides comprehensive web automation and debugging capabilities through the Model Context Protocol (MCP), with AI-powered visual analysis, cross-browser testing, and performance monitoring. It's designed to integrate seamlessly with Claude Code and Claude Desktop for advanced web development workflows.

Features

🎭 Browser Control

  • Launch browsers with debugging capabilities
  • Intelligent navigation with comprehensive analysis
  • Smart element interaction with fallback strategies
  • Complete page state capture and analysis

🐛 Visual Debugging

  • CSS layout issue detection and analysis
  • Visual difference comparison between states
  • Deep element styling inspection
  • Responsive design testing across breakpoints

⚡ Performance Analysis

  • Core Web Vitals measurement (LCP, FID, CLS)
  • Loading performance optimization analysis
  • Runtime performance monitoring
  • Resource loading analysis and recommendations

♿ Accessibility Testing

  • WCAG compliance checking
  • Color contrast analysis
  • Keyboard navigation testing
  • Screen reader compatibility testing

🌐 Cross-Browser Testing

  • Multi-browser session management
  • Cross-browser visual comparison
  • Feature compatibility testing
  • Browser-specific issue detection

🧠 Intelligent Selectors

  • AI-powered element identification
  • Robust selector generation
  • Element visibility and interactability checking
  • Fallback selector strategies

Installation

  1. Install dependencies:

    npm install

  2. Install Playwright browsers:

    npm run install-browsers

  3. Setup the environment:

    npm run setup

Usage

MCP Server Mode

Start the MCP server for integration with Claude:

npm start

HTTP Service Mode

Start the HTTP service for direct API access:

npm run http

Development Mode

Start with debugging enabled:

npm run dev

Tools

Browser Control Tools

launch_debug_browser

Launch a browser with debugging capabilities.

  • Parameters: url, browserType, deviceType, headless, devtools
  • Returns: Session ID and browser information
navigate_and_analyze

Navigate to a URL with comprehensive analysis.

  • Parameters: sessionId, url, analysisLevel, takeScreenshot
  • Returns: Navigation metrics, performance data, DOM analysis
interact_with_element

Intelligently interact with page elements.

  • Parameters: sessionId, selector, action, value
  • Returns: Interaction result and element information
capture_page_state

Capture comprehensive page state.

  • Parameters: sessionId, includeScreenshot, includeConsole, includeNetwork
  • Returns: Complete page state snapshot

Visual Debugging Tools

debug_layout_issues

Analyze CSS layout problems.

  • Parameters: sessionId, selector, analysisType, highlightIssues
  • Returns: Layout issues with visual highlights
analyze_visual_differences

Compare visual differences between page states.

  • Parameters: sessionId, baselineImage, threshold, includePixelDiff
  • Returns: Pixel-level difference analysis
inspect_element_styling

Deep inspection of element styling.

  • Parameters: sessionId, selector, includeInherited, includeComputed
  • Returns: Complete styling information
debug_responsive_design

Test responsive design across breakpoints.

  • Parameters: sessionId, breakpoints, detectOverflow
  • Returns: Multi-breakpoint analysis

Performance Analysis Tools

analyze_page_performance

Comprehensive performance analysis.

  • Parameters: sessionId, includeResourceTiming, includeCoreWebVitals
  • Returns: Core Web Vitals, resource timing, optimization recommendations
optimize_loading_performance

Loading optimization analysis.

  • Parameters: sessionId, focusAreas, performanceBudget
  • Returns: Specific optimization recommendations
monitor_runtime_performance

Runtime performance monitoring.

  • Parameters: sessionId, duration, interactions, includeMemoryProfile
  • Returns: CPU, memory, and animation performance data

Configuration

The service can be configured through environment variables or configuration files:

  • LOG_LEVEL: Logging level (debug, info, warn, error)
  • NODE_ENV: Environment mode (development, production)
  • DEBUG: Enable debug mode for detailed logging

Integration

Claude Code/Desktop

Add the server to your MCP configuration to use with Claude Code or Claude Desktop.

HTTP API

The service provides RESTful endpoints for all tools:

  • GET /health - Health check
  • GET /tools - List available tools
  • POST /api/browser/* - Browser control endpoints
  • POST /api/debug/* - Visual debugging endpoints
  • POST /api/performance/* - Performance analysis endpoints

Ecosystem Integration

Automatically integrates with the Claude MCP ecosystem using unified port discovery (8200-8299 range).

Examples

Basic Browser Automation

// Launch browser
const session = await callTool('launch_debug_browser', {
  url: 'https://example.com',
  browserType: 'chromium',
  deviceType: 'desktop'
});

// Navigate and analyze
const analysis = await callTool('navigate_and_analyze', {
  sessionId: session.sessionId,
  url: 'https://example.com/page',
  analysisLevel: 'comprehensive'
});

// Interact with elements
const interaction = await callTool('interact_with_element', {
  sessionId: session.sessionId,
  selector: '#submit-button',
  action: 'click'
});

Visual Debugging

// Debug layout issues
const layoutIssues = await callTool('debug_layout_issues', {
  sessionId: session.sessionId,
  analysisType: 'comprehensive',
  highlightIssues: true
});

// Compare visual states
const comparison = await callTool('analyze_visual_differences', {
  sessionId: session.sessionId,
  baselineImage: './baseline.png',
  threshold: 0.1
});

Performance Analysis

// Analyze performance
const performance = await callTool('analyze_page_performance', {
  sessionId: session.sessionId,
  includeCoreWebVitals: true,
  includeResourceTiming: true
});

// Monitor runtime performance
const monitoring = await callTool('monitor_runtime_performance', {
  sessionId: session.sessionId,
  duration: 10000,
  includeMemoryProfile: true
});

Architecture

The assistant is built with a modular architecture:

  • src/tools/ - Tool implementations
  • src/utils/ - Shared utilities (BrowserManager, Logger)
  • screenshots/ - Generated screenshots and comparisons
  • performance/ - Performance analysis reports
  • logs/ - Application logs

Testing

Run the test suite:

npm test

Run integration tests:

npm run test:integration

Development

Linting

npm run lint

Debugging

Use the debug mode for detailed logging:

DEBUG=true npm run dev

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

Support

For issues and questions:

  • Create an issue in the repository
  • Check the documentation
  • Review the examples and tests