How emeryinlover/playwright-mcp works
Project Type and Purpose
• This is a Node.js–based “Model Context Protocol” (MCP) server using Playwright.
• It exposes a CLI/SSE interface so LLM-driven clients (VSCode, Cursor, Claude Desktop, etc.) can drive browser automation via structured accessibility snapshots or screenshots (vision mode).
Key Architectural Components
a. External MCP Clients
• VS Code, Cursor, Windsurf, Claude Desktop, custom scripts
• Communicate with the server over STDIO (cli.js) or an HTTP/SSE transport
b. Transport Layer
• CLI Transport (cli.js) using stdin/stdout JSON-RPC
• SSE HTTP server (SSEServerTransport in src/transport.ts) exposing /messages endpoint
c. Core Server
• Entry point: src/index.ts / cli.js
• Configuration loader (src/config.ts & config.d.ts)
• Connection manager (src/connection.ts)
• Context manager (src/context.ts)
• Program runner (src/program.ts) orchestrating request handling
d. Tool Dispatcher
• A registry of “tools” implementing MCP commands (src/tools/* and src/tools/utils.ts)
• Each tool translates a high-level MCP method (e.g. browser_click) into Playwright API calls
e. Page Snapshot & Resource Layer
• Accessibility snapshot generator (src/pageSnapshot.ts)
• Resource abstractions (src/resources/resource.ts)
f. Playwright Integration
• Playwright API wrappers (src/javascript.ts, src/manualPromise.ts)
• Browser & context launch (src/connection.ts)
• Underlying browser process (chromium/firefox/webkit) managed via Playwright
g. Persistence & Profiles
• User data directory (in OS cache paths) for browser state
• Optional ephemeral contexts
h. Tests & Examples
• End-to-end and unit tests under tests/ using Playwright Test & a local test HTTP server
i. Packaging & Deployment
• Dockerfile for containerized headless mode
• GitHub Actions (ci.yml, publish.yml)
• npm package (package.json, CLI entry point cli.js)
Interactions & Data Flow
1. Client → Transport
• Client issues JSON-RPC over STDIO or opens SSE connection.
2. Transport → Core Server
• Incoming JSON-RPC messages are dispatched to createConnection/connect → Program.
3. Program → Context & Tools
• Program parses method name → looks up corresponding Tool module → calls tool handler.
4. Tool → Playwright API
• Handler invokes Playwright through connection/context to perform clicks, snapshots, etc.
5. Playwright → Browser Process
• Playwright launches/controls the browser, executes page operations, returns snapshots or screenshots.
6. Browser Process → Playwright → Tool → Transport → Client
• Results (accessibility trees, screenshots, PDFs, etc.) are marshaled back up and sent to the client.
Architectural Patterns & Principles
• Modular “Tools” pattern: each MCP command is a self-contained module
• Separation of Concerns: transport layer is independent of core logic
• Single process Node.js service with in-process Playwright binder
• Plugin-style configuration: capabilities toggled via CLI options
• Deterministic commands: avoids free-text vision models, relies on structured ARIA snapshots