# angiejones/mcp-selenium architecture

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

- Interactive diagram: https://gitdiagram.com/angiejones/mcp-selenium
- Repository: https://github.com/angiejones/mcp-selenium

## Overview

##### Project Type and Purpose
- This is a server implementation for the Model Context Protocol (MCP) that leverages Selenium WebDriver to automate browser interactions.
- The README clearly shows that it is intended to serve as a bridge between MCP clients (like Goose Desktop or Claude Desktop) and browser automation tools. The server offers a variety of automation commands (start_browser, navigate, click, hover, etc.) and supports both Chrome and Firefox.
- It’s a Node.js project (using package.json, npm scripts) with a small file structure and is intended to be deployed via npx or Docker.

##### File Structure Insights
- Top-level files such as Dockerfile, LICENSE, and smithery.yaml indicate deployment and integration options.
- The “bin” directory contains the executable CLI (bin/mcp-selenium.js) which likely serves as the entry point.
- The “src” directory (specifically src/lib/server.js) contains the core server logic.
- Minimal structure suggests a focused design; the server file implements the logic to handle MCP requests and routes them to corresponding Selenium implementations.

##### Architectural Components to Capture
- CLI/Command Entry Point: bin/mcp-selenium.js that triggers the Node.js process.
- Server Core: src/lib/server.js where MCP commands are handled.
- MCP Client Integration: How external MCP clients (Goose, Claude, etc.) communicate with the server. This includes both the direct command execution (e.g., via NPX) and configuration (as shown in the README JSON examples).
- Selenium/WebDriver Interaction Module: Although not explicitly split as its own folder, the server is responsible for translating MCP tool commands (like start_browser, navigate, click, etc.) into Selenium commands that operate on a browser session.
- Browser Sessions: The layer where browser automation happens. This involves launching browsers, handling session data, and returning results (such as screenshots, webpage text, etc.).
- External Integration Configurations: The smithery.yaml suggests that the project is integrated with tools like Smithery for deployment and automatic installation.

##### Relationships and Interactions
- The entry point (CLI) initiates the server process.
- MCP clients send requests (commands defined in the README such as start_browser, navigate, etc.) to the server.
- The server (server.js) handles these requests, orchestrates the corresponding Selenium WebDriver calls, and interacts with the browser sessions.
- Results and responses (like screenshots, element texts) flow back via the MCP protocol to the client.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The CLI (entry point) is kept distinct from the server logic, allowing source code modularity.
- Client-Server Communication: The MCP server abstracts away the direct details of Selenium, exposing a higher-level protocol to clients.
- Modularity/Extensibility: Each tool (e.g., start_browser, navigate, etc.) could be conceptually thought of as service modules that the server exposes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "MCP Command Flow"
        MCP["MCP Client"]:::client
        CLI["CLI: mcp-selenium.js"]:::cli
        Server["Server Core: server.js"]:::server
        Selenium["Selenium Integration"]:::selenium
        Chrome["Browser: Chrome"]:::browser
        Firefox["Browser: Firefox"]:::browser

        MCP -->|"sendsCommands"| CLI
        CLI -->|"initiates"| Server
        Server -->|"translatesTo"| Selenium
        Selenium -->|"controls"| Chrome
        Selenium -->|"controls"| Firefox
        Chrome -->|"returnsResults"| Selenium
        Firefox -->|"returnsResults"| Selenium
        Selenium -->|"sendsResponse"| Server
        Server -->|"repliesTo"| MCP
    end

    subgraph "Deployment & Integration"
        Docker["Deployment: Dockerfile"]:::deploy
        Smithery["Integration: smithery.yaml"]:::integration
        Server ---|"configuredBy"| Docker
        Server ---|"configuredBy"| Smithery
    end

    click CLI "https://github.com/angiejones/mcp-selenium/blob/main/bin/mcp-selenium.js"
    click Server "https://github.com/angiejones/mcp-selenium/blob/main/src/lib/server.js"
    click Docker "https://github.com/angiejones/mcp-selenium/tree/main/Dockerfile"
    click Smithery "https://github.com/angiejones/mcp-selenium/blob/main/smithery.yaml"

    classDef client fill:#F7DC6F,stroke:#B7950B,stroke-width:2px;
    classDef cli fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef server fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef selenium fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef browser fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef deploy fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef integration fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
```
