# emeryinlover/playwright-mcp architecture

> Architecture diagram of the GitHub repository emeryinlover/playwright-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/emeryinlover/playwright-mcp
- Repository: https://github.com/emeryinlover/playwright-mcp

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External MCP Clients"
        direction TB
        VSCode["VS Code"] 
        Cursor["Cursor"]
        Windsurf["Windsurf"]
        Claude["Claude Desktop"]
        Scripts["Custom Scripts"]
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        CLI["CLI Transport\n(JSON-RPC over STDIO)"]:::transport
        SSE["SSE HTTP Transport\n(/messages endpoint)"]:::transport
    end

    %% Core Server
    subgraph "Core Server"
        direction TB
        Entry["Entry Point\n(src/index.ts / cli.js)"]:::core
        Config["Configuration Loader\n(src/config.ts & config.d.ts)"]:::core
        Connection["Connection Manager\n(src/connection.ts)"]:::core
        Context["Context Manager\n(src/context.ts)"]:::core
        Program["Program Runner\n(src/program.ts)"]:::core
    end

    %% Tools
    subgraph "Tools Registry & Modules"
        direction TB
        Registry["Tools Registry\n(src/tools.ts)"]:::tools
        Utils["Tools Utilities\n(src/tools/utils.ts)"]:::tools
        Navigate["navigate.ts"]:::tools
        Click["click.ts"]:::tools
        OtherTools["other src/tools/*.ts"]:::tools
    end

    %% Page Snapshot & Resources
    subgraph "Page Snapshot & Resources"
        direction TB
        Snapshot["Accessibility Snapshot\n(src/pageSnapshot.ts)"]:::tools
        Resource["Resource Abstractions\n(src/resources/resource.ts)"]:::tools
        Tab["Tab Abstraction\n(src/tab.ts)"]:::tools
    end

    %% Playwright Integration
    subgraph "Playwright Integration"
        direction TB
        JSWrapper["JavaScript Wrapper\n(src/javascript.ts)"]:::playwright
        ManualPromise["Manual Promise\n(src/manualPromise.ts)"]:::playwright
    end

    %% Browser Process
    Browser["Browser Process\n(chromium/firefox/webkit)"]:::playwright

    %% Persistence & Profiles
    Persistence["User Data Directory\n(OS cache)"]:::persistence

    %% Tests & Examples
    subgraph "Tests & Examples"
        direction TB
        Tests["tests/"] 
        Examples["examples/"]
    end

    %% Deployment & CI
    subgraph "Deployment & CI"
        direction TB
        Docker["Dockerfile"]
        CI[".github/workflows/ci.yml"]
        Publish[".github/workflows/publish.yml"]
        NPM["package.json"]
    end

    %% Connections
    VSCode -->|JSON-RPC over STDIO| CLI
    Scripts -->|JSON-RPC over STDIO| CLI
    Cursor -->|SSE/HTTP| SSE
    Windsurf -->|SSE/HTTP| SSE
    Claude -->|SSE/HTTP| SSE

    CLI -->|dispatch| Entry
    SSE -->|dispatch| Entry

    Entry -->|loads| Config
    Entry -->|init| Connection
    Entry -->|init| Context
    Entry -->|routes| Program

    Program -->|lookup| Registry
    Registry -->|includes| Utils
    Registry -->|includes| Navigate
    Registry -->|includes| Click
    Registry -->|includes| OtherTools

    Program -->|uses| Snapshot
    Program -->|uses| Resource
    Program -->|uses| Tab

    Navigate -->|calls Playwright API| JSWrapper
    Click -->|calls Playwright API| JSWrapper
    OtherTools -->|calls Playwright API| ManualPromise

    JSWrapper -->|controls| Browser
    ManualPromise -->|controls| Browser

    Browser -->|state| Persistence

    %% Return flows
    Browser -->|results| JSWrapper
    JSWrapper -->|response| Registry
    Registry -->|response| Program
    Program -->|send| Entry
    Entry -->|stdout| CLI
    Entry -->|SSE event| SSE

    %% Tests & Examples flows
    Tests -->|exercise| Entry
    Examples -->|guide| CLI

    %% Deployment & CI flows
    Docker -->|container| Entry
    CI -->|build/test| Entry
    Publish -->|release| NPM

    %% Click events
    click CLI "https://github.com/emeryinlover/playwright-mcp/blob/main/cli.js"
    click SSE "https://github.com/emeryinlover/playwright-mcp/blob/main/src/transport.ts"
    click Entry "https://github.com/emeryinlover/playwright-mcp/blob/main/src/index.ts"
    click Entry "https://github.com/emeryinlover/playwright-mcp/blob/main/index.js"
    click Config "https://github.com/emeryinlover/playwright-mcp/blob/main/src/config.ts"
    click Config "https://github.com/emeryinlover/playwright-mcp/blob/main/config.d.ts"
    click Connection "https://github.com/emeryinlover/playwright-mcp/blob/main/src/connection.ts"
    click Context "https://github.com/emeryinlover/playwright-mcp/blob/main/src/context.ts"
    click Program "https://github.com/emeryinlover/playwright-mcp/blob/main/src/program.ts"
    click Registry "https://github.com/emeryinlover/playwright-mcp/blob/main/src/tools.ts"
    click Utils "https://github.com/emeryinlover/playwright-mcp/blob/main/src/tools/utils.ts"
    click Navigate "https://github.com/emeryinlover/playwright-mcp/blob/main/src/tools/navigate.ts"
    click Click "https://github.com/emeryinlover/playwright-mcp/blob/main/src/tools/click.ts"
    click Snapshot "https://github.com/emeryinlover/playwright-mcp/blob/main/src/pageSnapshot.ts"
    click Resource "https://github.com/emeryinlover/playwright-mcp/blob/main/src/resources/resource.ts"
    click Tab "https://github.com/emeryinlover/playwright-mcp/blob/main/src/tab.ts"
    click JSWrapper "https://github.com/emeryinlover/playwright-mcp/blob/main/src/javascript.ts"
    click ManualPromise "https://github.com/emeryinlover/playwright-mcp/blob/main/src/manualPromise.ts"
    click Tests "https://github.com/emeryinlover/playwright-mcp/tree/main/tests/"
    click Examples "https://github.com/emeryinlover/playwright-mcp/tree/main/examples/"
    click Docker "https://github.com/emeryinlover/playwright-mcp/tree/main/Dockerfile"
    click CI "https://github.com/emeryinlover/playwright-mcp/blob/main/.github/workflows/ci.yml"
    click Publish "https://github.com/emeryinlover/playwright-mcp/blob/main/.github/workflows/publish.yml"
    click NPM "https://github.com/emeryinlover/playwright-mcp/blob/main/package.json"

    %% Styles
    classDef transport fill:#bbdefb,stroke:#2196f3,color:#0d47a1;
    classDef core fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef tools fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef playwright fill:#e1bee7,stroke:#8e24aa,color:#4a148c;
    classDef persistence fill:#eeeeee,stroke:#9e9e9e,color:#424242;
```
