Ryan Malloy
6120506e91
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.
78 lines
3.4 KiB
Markdown
78 lines
3.4 KiB
Markdown
# 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. |