# browsermcp/mcp architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack (though “front” is a browser extension) automation server:
– A Node.js/TypeScript MCP server runs locally.
– A Chrome extension (“client”) connects to it.
– External AI-driven editors or services (e.g. VS Code, Claude) speak to the MCP server to automate the user’s real browser session.
- Purpose: Local, stealthy, private browser automation by proxying commands through the existing user profile.

##### File Structure
- src/server.ts & src/ws.ts
– HTTP/WebSocket server entrypoints.
- src/index.ts
– Bootstraps the server, loads config (port, logging).
- src/context.ts
– Manages per-connection contexts (one context = one browser session or client).
- src/tools/*.ts
– “Tool” plugins (common, custom, snapshot) implementing discrete browser actions.
- src/resources/resource.ts
- src/utils/*.ts
– Helpers (aria-snapshot for DOM snapshots, log, port detection).
- No database; all state is in-memory contexts.

##### README for Additional Insights
- Confirms local-only operation and real browser fingerprint use.
- Describes features: performance, privacy, stealth.
- Mentions adaptation from Playwright MCP—so the architecture mirrors a plugin-based command dispatcher.

##### Main Components & Boundaries
A. External Clients
1. AI-driven editor/service or CLI
2. Chrome extension (MCP client)
B. Local MCP Server (Node.js)
1. HTTP/WebSocket Layer (src/server.ts + ws.ts)
2. Context Manager (src/context.ts)
3. Tool Dispatcher (src/tools)
4. Resource Layer (src/resources)
5. Utility Layer (src/utils)
C. Browser (User’s real Chrome profile)
– Receives commands via extension, returns snapshots, performs clicks, etc.

##### Data Flows & Interactions
1. Client → MCP Server
- WebSocket handshake → open Context
- JSON-RPC or MCP commands over WS
2. Server Core
- Incoming command picked up by ws.ts
- Routed to the correct Context instance (context.ts)
3. Tool Execution
- Context invokes Tool (tool.ts) based on command type
- Tool uses Resources (e.g. resource.ts + aria-snapshot) and Utils to gather data or perform actions in the browser
4. Browser Extension ↔ Browser
- Extension injects scripts, executes commands in page context
5. MCP Server → Client
- Tool result (e.g. snapshot JSON, success/failure) sent back over WS

##### Architectural Patterns & Principles
- Plugin-style dispatcher
– Each action is a “Tool” implementing a common interface.
- Separation of concerns
– Server I/O, Context management, Tool logic, Resource formatting, Utilities all in distinct modules.
- In-memory session contexts
- No persistent storage—stateless across restarts.
- Local-first design for privacy and low latency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    AIClient("AI-driven Editor/Service or CLI"):::external

    %% Local Host Boundary
    subgraph "Local Host Machine" 
        direction TB

        %% Browser Extension
        ChromeExt("Chrome Extension (MCP Client)"):::external

        %% MCP Server Core (Blue)
        subgraph "MCP Server Core"
            direction TB
            HTTPServer["HTTP Server Layer<br/>src/server.ts"]:::server
            WebSocket["WebSocket Layer<br/>src/ws.ts"]:::server
            Bootstrap["Server Bootstrap & Config Loader<br/>src/index.ts"]:::server
            Context["Context Manager<br/>src/context.ts"]:::server
            Dispatcher["Tool Dispatcher Core Interface<br/>src/tools/tool.ts"]:::server
        end

        %% Tools Plugins (Green)
        subgraph "Tools Plugins"
            direction TB
            CommonTool["Common Tool Plugin<br/>src/tools/common.ts"]:::tools
            CustomTool["Custom Tool Plugin<br/>src/tools/custom.ts"]:::tools
            SnapshotTool["DOM Snapshot Tool Plugin<br/>src/tools/snapshot.ts"]:::tools
        end

        %% Resources & Utils (Yellow)
        subgraph "Resources & Utilities"
            direction TB
            ResourceDef["Resource Definition Layer<br/>src/resources/resource.ts"]:::resources
            ARIASnap["ARIA Snapshot Utility<br/>src/utils/aria-snapshot.ts"]:::resources
            LogUtil["Logging Utility<br/>src/utils/log.ts"]:::resources
            PortUtil["Port Detection Utility<br/>src/utils/port.ts"]:::resources
        end

        %% Browser
        Browser("Browser (User's real Chrome)"):::browser
    end

    %% Connections
    AIClient -->|"WebSocket handshake\nMCP commands"| HTTPServer
    HTTPServer -->|routes to| WebSocket
    WebSocket -->|routes commands to| Context
    Context -->|invokes| Dispatcher
    Dispatcher -->|uses plugin| CommonTool
    Dispatcher -->|uses plugin| CustomTool
    Dispatcher -->|uses plugin| SnapshotTool
    CommonTool -->|uses resources/utils| ResourceDef
    CommonTool --> ARIASnap
    CustomTool --> ResourceDef
    CustomTool --> LogUtil
    SnapshotTool --> ResourceDef
    SnapshotTool --> ARIASnap
    Dispatcher -->|executes via extension| ChromeExt
    ChromeExt -->|injects scripts into| Browser
    Browser -->|returns results to| ChromeExt
    ChromeExt -->|sends JSON snapshot/results over WS| WebSocket
    WebSocket -->|responds over WS| AIClient

    %% Click Events
    click HTTPServer "https://github.com/browsermcp/mcp/blob/main/src/server.ts"
    click WebSocket "https://github.com/browsermcp/mcp/blob/main/src/ws.ts"
    click Bootstrap "https://github.com/browsermcp/mcp/blob/main/src/index.ts"
    click Context "https://github.com/browsermcp/mcp/blob/main/src/context.ts"
    click Dispatcher "https://github.com/browsermcp/mcp/blob/main/src/tools/tool.ts"
    click CommonTool "https://github.com/browsermcp/mcp/blob/main/src/tools/common.ts"
    click CustomTool "https://github.com/browsermcp/mcp/blob/main/src/tools/custom.ts"
    click SnapshotTool "https://github.com/browsermcp/mcp/blob/main/src/tools/snapshot.ts"
    click ResourceDef "https://github.com/browsermcp/mcp/blob/main/src/resources/resource.ts"
    click ARIASnap "https://github.com/browsermcp/mcp/blob/main/src/utils/aria-snapshot.ts"
    click LogUtil "https://github.com/browsermcp/mcp/blob/main/src/utils/log.ts"
    click PortUtil "https://github.com/browsermcp/mcp/blob/main/src/utils/port.ts"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px,shape:roundRect
    classDef server fill:#ddf,stroke:#333,stroke-width:1px
    classDef tools fill:#dfd,stroke:#333,stroke-width:1px
    classDef resources fill:#ffd,stroke:#333,stroke-width:1px
    classDef browser fill:#fdd,stroke:#333,stroke-width:1px,shape:roundRect
```
