# executeautomation/mcp-playwright architecture

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

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

## Overview

##### Project Type and Purpose
- The project is a Node.js-based server that automates browser actions using Playwright. It functions as a Model Context Protocol (MCP) server, enabling large language models (LLMs) like Claude to interact with web pages, take screenshots, and execute JavaScript in an actual browser environment.
- The system is designed to provide remote browser automation capabilities that can be integrated into other systems (or LLM clients) via a command-driven protocol.

##### Analyzing the File Structure and Purpose of Each Element

- .github & .github/workflows
- Purpose: These directories contain configuration files for continuous integration and deployment. They include workflows for running tests, building documentation (e.g., using Docusaurus), and ensuring compatibility with various Node.js versions.

- Dockerfile
- Purpose: Provides the instructions for containerizing the server, making deployment and scaling easier in different environments.

- README.md
- Purpose: Gives an overview of the project, installation instructions, configuration examples for integrating with Claude Desktop, and testing commands. It also links to live documentation and API reference materials.

- docs/
- docs/docs/ and its subdirectories (e.g., ai-courses, local-setup, playwright-api, playwright-web, testing-videos)
- Purpose: Contains Markdown files and media for detailed documentation of various features, API usage, local setup guidelines, and tool-specific examples. It is set up for a static site generator (Docusaurus) to provide a friendly documentation website.
- docs/docusaurus.config.ts, sidebars.ts, package.json, etc.
- Purpose: Configuration and build files for the documentation website ensuring opinions on navigation, theming, and overall site functionality.

- image/
- Purpose: Stores images such as screenshots (e.g., the Playwright + Claude screenshot) that support the README and documentation.

- jest.config.cjs, run-tests.cjs, run-tests.js, tsconfig.json (and tsconfig.test.json)
- Purpose: These configuration files are used to run tests (via Jest) and compile TypeScript code. They dictate coding standards and the test environment needed to ensure the server behaves as expected.

- package.json and package-lock.json (present at both the project root and within docs/)
- Purpose: Define the dependencies and scripts for building and testing the project (mainly for the server code and separately for the documentation site).

- smithery.yaml
- Purpose: Likely used by the Smithery tool to facilitate installation or deployment workflows, as mentioned in the README.

- src/
- src/index.ts
- Purpose: Acts as the main entry point for the server application.
- src/requestHandler.ts
- Purpose: Responsible for processing incoming requests from clients (such as LLM calls) and routing them appropriately.
- src/toolHandler.ts
- Purpose: Coordinates the execution of various tools/modules that perform browser automation tasks.
- src/tools.ts and src/tools/ (subdirectories)
- Purpose: Houses the core functionalities broken into modular components:
▪ api/: Contains logic for handling API-based commands, with files like base.ts and requests.ts.
▪ browser/: Contains modules for handling browser-specific interactions. Examples include:
- base.ts: Likely provides shared functionality or common interfaces for browser operations.
- console.ts, interaction.ts, navigation.ts, screenshot.ts: Each file corresponds to a different browser automation function such as logging to the console, interacting with page elements, navigation commands, and capturing screenshots.
▪ common/: Contains shared type definitions and common utilities to support both API and browser operations.

- src/__tests__/ and related snapshot directories
- Purpose: Contains test suites to verify that the various components (request handling, browser interactions, API calls) are functioning correctly. This is critical for maintaining reliability and ensuring quality assurance through Jest.

- test-import.js
- Purpose: Likely a simple script or utility used for dry-run or debugging the import mechanisms within the project.

a. Main Components:
- Client/LLM: Represents external clients or LLMs (e.g., Claude) that send automation requests.
- Server Entry Point: The core Node.js server initiated in src/index.ts.
- Request Handling Layer: Handled by requestHandler.ts to manage and interpret incoming protocol messages.
- Tool Handler Module: Acts as a dispatcher that invokes specific functionalities from the tools directory.
- Tools Modules:
- API Tools: Modules under src/tools/api for processing API requests.
- Browser Tools: Modules under src/tools/browser for simulating browser interactions.
- Common Utilities: Shared utilities and type definitions in src/tools/common.
- Testing & CI/CD: Represented by Jest configurations and GitHub workflows ensuring continuous quality and integration.
- Documentation Service: Represented by the docs/ directory and the Docusaurus configuration, which interactively explains usage and API interfaces.
- Deployment/Containerization: Dockerfile and smithery.yaml illustrate how the application is built and deployed.

b. Relationships and Interactions:
- The Request Handler forwards the request to the Tool Handler.
- The Tool Handler decides which submodule (API or Browser tool) to engage based on the request type.
- Each tool module (e.g., browser/navigation, api/requests) processes specific commands and returns a result back through the tool handler to the request handler and finally to the client.
- Testing and CI/CD systems continuously verify these interactions.
- Documentation provides visibility of these interactions and available API endpoints, while Docker and Smithery ensure a smooth deployment process.

c. Architectural Patterns & Design Principles:
- Modular Design: Separation of concerns is achieved by splitting the automation logic into distinct modules (e.g., handling API vs. browser interactions).
- Layered Architecture: Clear separation between request processing (network layer), business logic (tool handler and tools modules), and infrastructure (deployment and CI/CD configurations).
- Test-Driven Development: Extensive testing directories and scripts indicate adherence to TDD, ensuring each layer is validated.
- Containerization and Automation: Use of Docker and CI/CD pipelines (via GitHub workflows) reflect modern DevOps practices.

d. Technologies, Frameworks, and Libraries:
- Node.js and TypeScript: The backbone of the server application.
- Playwright: Provides browser automation capabilities.
- Jest: Ensures comprehensive testing.
- Docusaurus: Powers the project documentation website.
- Docker: Containerization for deployment.
- Smithery: Tool for automated installation/deployment.

## Diagram (Mermaid)

```mermaid
graph TD
    Client["Client/LLM (sends automation requests)"]:::external

    subgraph "Core Components"
        ServerEntry["Server Entry Point (src/index.ts): Main entry point for the server"]:::backend
        RequestHandler["Request Handling (src/requestHandler.ts): Processes incoming requests"]:::backend
        ToolHandler["Tool Handler (src/toolHandler.ts): Dispatches commands to tool modules"]:::backend

        APITools["API Tools (src/tools/api): Processes API-based commands"]:::module
        BrowserTools["Browser Tools (src/tools/browser): Performs browser interactions"]:::module
        CommonUtils["Common Utilities (src/tools/common/types.ts): Shared types and utilities"]:::module
    end

    subgraph "Support Components"
        TestingCI["CI/CD & Testing (.github/workflows, jest.config.cjs, run-tests files, src/__tests__/)"]:::support
        Documentation["Documentation (docs/): Docusaurus config & Markdown docs"]:::support
        subgraph "Deployment/Containerization"
            D1["Dockerfile: Containerization instructions"]:::support
            D2["smithery.yaml: Deployment workflows"]:::support
        end
    end

    Client -->|"sends_request"| ServerEntry
    ServerEntry -->|"routes_to"| RequestHandler
    RequestHandler -->|"forwards_request"| ToolHandler
    ToolHandler -->|"invokes"| APITools
    APITools -->|"responds"| ToolHandler
    ToolHandler -->|"invokes"| BrowserTools
    BrowserTools -->|"responds"| ToolHandler
    ToolHandler -->|"aggregates_response"| RequestHandler
    RequestHandler -->|"sends_response"| ServerEntry
    ServerEntry -->|"responds"| Client

    ToolHandler -.->|"uses"| CommonUtils

    ServerEntry -.->|"verified_by"| TestingCI
    ServerEntry -.->|"documented_in"| Documentation
    ServerEntry -.->|"packaged_via"| D1
    ServerEntry -.->|"packaged_via"| D2

    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef backend fill:#99ccff,stroke:#333,stroke-width:2px;
    classDef module fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef support fill:#ff9999,stroke:#333,stroke-width:2px;

    click ServerEntry "https://github.com/executeautomation/mcp-playwright/blob/main/src/index.ts"
    click RequestHandler "https://github.com/executeautomation/mcp-playwright/blob/main/src/requestHandler.ts"
    click ToolHandler "https://github.com/executeautomation/mcp-playwright/blob/main/src/toolHandler.ts"
    click APITools "https://github.com/executeautomation/mcp-playwright/tree/main/src/tools/api"
    click BrowserTools "https://github.com/executeautomation/mcp-playwright/tree/main/src/tools/browser"
    click CommonUtils "https://github.com/executeautomation/mcp-playwright/blob/main/src/tools/common/types.ts"
    click TestingCI "https://github.com/executeautomation/mcp-playwright/tree/main/.github/workflows"
    click Documentation "https://github.com/executeautomation/mcp-playwright/tree/main/docs/"
    click D1 "https://github.com/executeautomation/mcp-playwright/tree/main/Dockerfile"
    click D2 "https://github.com/executeautomation/mcp-playwright/blob/main/smithery.yaml"
```
