# rajendharmendra/playwright-mcp architecture

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

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

## Overview

##### Main Components

- MCP Server Core:
- Central server (src/server.ts) that initializes Playwright’s capabilities.
- That it is capable of launching Chrome with a dedicated user profile to run in headless or headed mode.

- CLI/Program Interface:
- Command-line entry points (cli.js, src/program.ts) that start the server and manage arguments (e.g., headless, vision flag).

- Context & Resource Management:
- Context module (src/context.ts) which likely handles shared application state and configurations.
- Resource handling submodules in src/resources (e.g., console.ts and resource.ts) that interface with browser snapshots or accessibility data.

- Tools Layer:
- “tools” directory (src/tools) which provides the core functionalities (common utilities, screenshot, snapshot, tool orchestration, and miscellaneous utilities).
- Separate the tools governing “Snapshot Mode” from those for “Vision Mode,” as highlighted in the README.

- Testing & CI/CD:
- Optionally, show the testing framework (tests folder) along with the GitHub workflows (.github/workflows) which indicate CI/CD integration.

- External Integration Points:
- Integration points with VS Code as described (command line installs, API usage via custom transports).
- API level “createServer()” function (used in programmatic usage) and SSE endpoints used for browser commands.

##### Denote Relationships and Data Flow

- How the MCP Server interacts with the “Tools” components via function calls—switching behavior between Snapshot Mode and Vision Mode as per command-line flags.
- Interaction from the server’s core to the context and tools modules that process commands (e.g., browser_navigate, browser_click) as defined in the README.

##### Architectural Patterns & Design Principles

- Modularity: Highlight that the system is divided into multiple modules and directories (each handling context, tools, resources) to isolate concerns.
- Extensibility: Note that the tool commands (from snapshot to vision mode operations) are designed for deterministic execution and are easy to extend.
- CI/CD and Testing: Emphasize the integration of GitHub actions and automated tests in validating changes.
- Clear Separation of Concerns: The CLI, server logic, and tool functionalities are distinctly represented which aligns well with separation of concerns.

##### Technologies, Frameworks, and Libraries

- Node.js is the runtime (as indicated by package.json, cli.js).
- Playwright is the underlying browser automation library.
- TypeScript is used (src files with .ts, tsconfig.json) ensuring type safety.
- GitHub Actions for CI/CD workflows.
- ESLint for linting (eslint.config.mjs) and testing frameworks (notably, the tests directory with Playwright tests).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Layer
    subgraph "Entry Layer"
        CLI1["CLI/Program Interface (cli.js)"]:::cli
        CLI2["CLI/Program Interface (src/program.ts)"]:::cli
    end

    %% MCP Server Core
    subgraph "MCP Server Core"
        Server["MCP Server Core (src/server.ts)"]:::server
        Context["Context Management (src/context.ts)"]:::server
        subgraph "Resource Management"
            Console["Console Resource (src/resources/console.ts)"]:::server
            ResourceHandler["Resource Handler (src/resources/resource.ts)"]:::server
        end
    end

    %% Tools Layer
    subgraph "Tools Layer"
        ToolsCommon["Common Utilities (src/tools/common.ts)"]:::tools
        ToolsUtils["Utils (src/tools/utils.ts)"]:::tools
        Screenshot["Screenshot Tool (src/tools/screenshot.ts)"]:::tools
        Snapshot["Snapshot Tool (src/tools/snapshot.ts)"]:::tools
        ToolCoord["Tool Coordinator (src/tools/tool.ts)"]:::tools
    end

    %% External Integration
    subgraph "External Integration"
        VSCode["VS Code Integration"]:::external
        Browser["Playwright Browser (Automated Chrome)"]:::external
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing"
        Tests["Tests (tests)"]:::cicd
        Workflows["CI/CD Workflows (.github/workflows)"]:::cicd
    end

    %% Connections
    CLI1 -->|"triggers"| Server
    CLI2 -->|"triggers"| Server
    VSCode -->|"initiates"| Server
    Server -->|"loads"| Context
    Server -->|"manages"| Console
    Server -->|"manages"| ResourceHandler
    Server -->|"orchestrates"| ToolsCommon
    Server -->|"orchestrates"| ToolsUtils
    Server -->|"orchestrates"| Screenshot
    Server -->|"orchestrates"| Snapshot
    Server -->|"orchestrates"| ToolCoord
    ToolsCommon -->|"executes"| Browser
    ToolsUtils -->|"executes"| Browser
    Screenshot -->|"executes"| Browser
    Snapshot -->|"executes"| Browser
    ToolCoord -->|"coordinates"| Browser
    Workflows -->|"runs tests on"| Tests
    Tests -->|"validate"| Server

    %% Click Events
    click Server "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/server.ts"
    click CLI1 "https://github.com/rajendharmendra/playwright-mcp/blob/main/cli.js"
    click CLI2 "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/program.ts"
    click Context "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/context.ts"
    click Console "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/resources/console.ts"
    click ResourceHandler "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/resources/resource.ts"
    click ToolsCommon "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/tools/common.ts"
    click ToolsUtils "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/tools/utils.ts"
    click Screenshot "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/tools/screenshot.ts"
    click Snapshot "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/tools/snapshot.ts"
    click ToolCoord "https://github.com/rajendharmendra/playwright-mcp/blob/main/src/tools/tool.ts"
    click Tests "https://github.com/rajendharmendra/playwright-mcp/tree/main/tests"
    click Workflows "https://github.com/rajendharmendra/playwright-mcp/tree/main/.github/workflows"

    %% Styles
    classDef cli fill:#C6F6D5,stroke:#2F855A,stroke-width:2px;
    classDef server fill:#BEE3F8,stroke:#2B6CB0,stroke-width:2px;
    classDef tools fill:#FEEBC8,stroke:#D69E2E,stroke-width:2px;
    classDef external fill:#E9D8FD,stroke:#9F7AEA,stroke-width:2px;
    classDef cicd fill:#FED7D7,stroke:#C53030,stroke-width:2px;
```
