MCP/playwright-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
playwright-mcp/CLAUDE.md
Ryan Malloy 6120506e91
Some checks failed
CI / test (ubuntu-latest) (push) Has been cancelled
Details
CI / test (windows-latest) (push) Has been cancelled
Details
CI / test_docker (push) Has been cancelled
Details
CI / lint (push) Has been cancelled
Details
CI / test (macos-latest) (push) Has been cancelled
Details
feat: comprehensive MCP client debug enhancements and voice collaboration 
Adds revolutionary features for MCP client identification and browser automation:

MCP Client Debug System:
- Floating pill toolbar with client identification and session info
- Theme system with 5 built-in themes (minimal, corporate, hacker, glass, high-contrast)
- Custom theme creation API with CSS variable overrides
- Cross-site validation ensuring toolbar persists across navigation
- Session-based injection with persistence across page loads

Voice Collaboration (Prototype):
- Web Speech API integration for conversational browser automation
- Bidirectional voice communication between AI and user
- Real-time voice guidance during automation tasks
- Documented architecture and future development roadmap

Code Injection Enhancements:
- Model collaboration API for notify, prompt, and inspector functions
- Auto-injection and persistence options
- Toolbar integration with code injection system

Documentation:
- Comprehensive technical achievement documentation
- Voice collaboration architecture and implementation guide
- Theme system integration documentation
- Tool annotation templates for consistency

This represents a major advancement in browser automation UX, enabling
unprecedented visibility and interaction patterns for MCP clients.
2025-11-14 21:36:08 -07:00

3.4 KiB
Raw Permalink Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the Playwright MCP (Model Context Protocol) server - a TypeScript/Node.js project that provides browser automation capabilities through structured accessibility snapshots. It enables LLMs to interact with web pages without requiring screenshots or vision models.

Development Commands

Build:

  • npm run build - Build TypeScript to JavaScript in lib/ directory
  • npm run build:extension - Build browser extension in extension/lib/
  • npm run watch - Watch mode for main build
  • npm run watch:extension - Watch mode for extension build

Testing:

  • npm test - Run all Playwright tests
  • npm run ctest - Run Chrome-specific tests only
  • npm run ftest - Run Firefox-specific tests only
  • npm run wtest - Run WebKit-specific tests only

Linting & Quality:

  • npm run lint - Run linter and type checking (includes README update)
  • npm run lint-fix - Auto-fix linting issues
  • npm run update-readme - Update README with generated tool documentation

Development:

  • npm run clean - Remove built files from lib/ and extension/lib/

Architecture

Core Components:

  • src/index.ts - Main entry point providing createConnection() API
  • src/server.ts - MCP server implementation with connection management
  • src/connection.ts - Creates MCP server with tool handlers and request processing
  • src/tools.ts - Aggregates all available tools from src/tools/ directory
  • src/context.ts - Browser context management and state handling
  • src/browserContextFactory.ts - Factory for creating browser contexts with different configurations

Tool System:

  • All browser automation tools are in src/tools/ directory
  • Each tool file exports an array of tool definitions
  • Tools are categorized by capability: core, tabs, install, pdf, vision
  • Tool capabilities are filtered based on config to enable/disable features

Browser Management:

  • Supports multiple browsers: Chrome, Firefox, WebKit, Edge
  • Two modes: persistent profile (default) or isolated contexts
  • Browser contexts are created through factory pattern for flexibility
  • CDP (Chrome DevTools Protocol) support for remote browser connections

Configuration:

  • src/config.ts - Configuration resolution and validation
  • Supports both CLI arguments and JSON config files
  • Browser launch options, context options, network settings, capabilities

Transport:

  • Supports both STDIO and HTTP/SSE transports
  • STDIO for direct MCP client connections
  • HTTP mode for standalone server operation

Key Files

  • cli.js - CLI entry point (imports lib/program.js)
  • src/program.ts - Command-line argument parsing and server setup
  • playwright.config.ts - Test configuration for multiple browser projects
  • tests/fixtures.ts - Custom Playwright test fixtures for MCP testing

Extension

The extension/ directory contains a browser extension for CDP relay functionality, built separately with its own TypeScript config.

Voice Collaboration System (Future Development)

REVOLUTIONARY FEATURE: This project includes a groundbreaking voice collaboration system for conversational browser automation. See docs/voice-collaboration/README.md for complete implementation details and future development roadmap.

Status: Prototype complete with proven architecture. Requires Linux Web Speech API integration work for full functionality.