# agentdeskai/browser-tools-mcp architecture

> Architecture diagram of the GitHub repository agentdeskai/browser-tools-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/agentdeskai/browser-tools-mcp
- Repository: https://github.com/agentdeskai/browser-tools-mcp

## Overview

##### MCP Server (located under browser-tools-mcp)
- Implements the Model Context Protocol (MCP) which is used to expose standardized tools to MCP clients (like Cursor, Claude, etc.).
- Serves as the entry point for commands coming from the IDE, and it formats these for further processing.
- Written in TypeScript (mcp-server.ts, package.json, tsconfig.json).

##### Node Server (located under browser-tools-server)
- Acts as a middleware between the MCP server and the Chrome extension.
- Handles incoming logs, screenshots, console events, and also integrates audit tools (using Lighthouse modules for accessibility, performance, SEO, best practices, and NextJS audits).
- Contains several TypeScript modules (browser-connector.ts, puppeteer-service.ts, along with a dedicated folder for Lighthouse integration).

##### Chrome Extension (located under chrome-extension)
- Runs in Chrome to capture browser events such as network activity, XHR requests, console logs, and DOM selections.
- Communicates with the Node Server via WebSocket (as per the README) and relays this information for audit analysis.
- Contains essential files like manifest.json and scripts for background tasks and DevTools integrations (background.js, devtools.js, panel.js).

A. Identify and Label Main Components:
1. MCP Client – Represents any MCP-compatible client (e.g., Cursor IDE) that triggers audits.
3. Node Server – Denote the middleware component (browser-tools-server) which includes both the browser connector and dedicated audit modules (including Lighthouse integration). Emphasize its dual role in processing logs and handling auditing tool invocations.
4. Chrome Extension – The front-end tool in the browser capturing logs, screenshots, and other necessary UI events.

B. Define the Relationships & Data/Control Flow:
- From Node Server, illustrate the flow of commands and information to the Chrome Extension.
- Also, show the feedback loop where audit results (like accessibility, performance, SEO audit results) flow back from the Node Server through the MCP Server and ultimately are returned to the MCP Client.
- Additionally, detail that the Node Server not only processes logs and requests but also auto-handles reconnection, truncation of data, and other data normalization tasks.

C. Highlight Architectural Patterns and Design Principles:
- Separation of concerns by showing distinct layers (presentation in the extension, a middleware processing layer, and the MCP interfacing server).
- Make note of the integration of audit tools (Lighthouse modules) within the Node Server. Showing these as a sub-module can help highlight the extensibility of the auditing process.
- That each component is containerized in separate directories and has its own configuration/build scripts (package.json, tsconfig.json) – a design decision that aids in modularity and independent versioning/deployment.

D. Include Relevant Technologies & Frameworks:
- TypeScript is predominantly used in both server components.
- Puppeteer is used for headless Chrome automation within the Node Server.
- Lighthouse is integrated for running multiple audits (accessibility, performance, SEO, best practices, and specialized NextJS auditing).
- The Chrome Extension itself leverages standard web extension APIs (as specified in its manifest.json) to interact with browser internals.

- Lighthouse integration (for various audits with separate modules such as accessibility, performance, SEO, etc.)
- Puppeteer service components used for headless browser control.
- Browser connector for handling communication with the Chrome extension.
┌─────────────┐     ┌──────────────┐     ┌───────────────┐     ┌─────────────┐
│ MCP Client  │ ──► │ MCP Server   │ ──► │  Node Server  │ ──► │ Chrome      │
│  (IDE)      │ ◄── │ (Protocol    │ ◄── │ (Middleware   │ ◄── │ Extension   │
│             │     │  Handler)    │     │ & Audits)     │     │             │
└─────────────┘     └──────────────┘     └───────────────┘     └─────────────┘

## Diagram (Mermaid)

```mermaid
graph TB
    %% Major Components
    MCPClient["MCP Client (IDE)"]:::client

    subgraph "MCP Server (IDE integration)"
        direction TB
        MCPServer_Core["Core Server"]:::server
        MCPServer_MCP["mcp-server.ts"]:::subcomponent
        MCPServer_Pkg["package.json"]:::subcomponent
        MCPServer_TS["tsconfig.json"]:::subcomponent
        MCPServer_Core --> MCPServer_MCP
        MCPServer_Core --> MCPServer_Pkg
        MCPServer_Core --> MCPServer_TS
    end

    subgraph "Node Server (Middleware & Audit Processor)"
        direction TB
        NodeServer_Core["Core Server"]:::middleware
        NodeServer_BC["Browser Connector"]:::subcomponent
        NodeServer_PS["Puppeteer Service"]:::subcomponent
        NodeServer_Core --> NodeServer_BC
        NodeServer_Core --> NodeServer_PS
        
        subgraph "Lighthouse Integration"
            direction TB
            Lighthouse_Accessibility["Accessibility"]:::subcomponent
            Lighthouse_Best["Best Practices"]:::subcomponent
            Lighthouse_Performance["Performance"]:::subcomponent
            Lighthouse_SEO["SEO"]:::subcomponent
            Lighthouse_Index["Index"]:::subcomponent
            Lighthouse_Types["Types"]:::subcomponent
        end
        NodeServer_Core --> Lighthouse_Accessibility
        NodeServer_Core --> Lighthouse_Best
        NodeServer_Core --> Lighthouse_Performance
        NodeServer_Core --> Lighthouse_SEO
        NodeServer_Core --> Lighthouse_Index
        NodeServer_Core --> Lighthouse_Types

        NodeServer_Pkg2["package.json"]:::subcomponent
        NodeServer_TS2["tsconfig.json"]:::subcomponent
        NodeServer_Core --> NodeServer_Pkg2
        NodeServer_Core --> NodeServer_TS2
    end

    subgraph "Chrome Extension (Browser-Side Integration)"
        direction TB
        ChromeExt_Core["Core Extension"]:::extension
        ChromeExt_Manifest["manifest.json"]:::subcomponent
        ChromeExt_Background["background.js"]:::subcomponent
        ChromeExt_DevtoolsHTML["devtools.html"]:::subcomponent
        ChromeExt_DevtoolsJS["devtools.js"]:::subcomponent
        ChromeExt_PanelHTML["panel.html"]:::subcomponent
        ChromeExt_PanelJS["panel.js"]:::subcomponent
        ChromeExt_Core --> ChromeExt_Manifest
        ChromeExt_Core --> ChromeExt_Background
        ChromeExt_Core --> ChromeExt_DevtoolsHTML
        ChromeExt_Core --> ChromeExt_DevtoolsJS
        ChromeExt_Core --> ChromeExt_PanelHTML
        ChromeExt_Core --> ChromeExt_PanelJS
    end

    %% Data/Control Flow Connections
    MCPClient -->|"commands"| MCPServer_Core
    MCPServer_Core -->|"forwards"| NodeServer_Core
    NodeServer_Core -->|"instructions"| ChromeExt_Core
    ChromeExt_Core -->|"logs & audit_results"| NodeServer_Core
    NodeServer_Core -->|"audit_responses"| MCPServer_Core
    MCPServer_Core -->|"results"| MCPClient

    %% Click Events for MCP Server (IDE integration)
    click MCPServer_MCP "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-mcp/mcp-server.ts"
    click MCPServer_Pkg "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-mcp/package.json"
    click MCPServer_TS "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-mcp/tsconfig.json"

    %% Click Events for Node Server (Middleware & Audit Processor)
    click NodeServer_BC "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/browser-connector.ts"
    click NodeServer_PS "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/puppeteer-service.ts"
    click Lighthouse_Accessibility "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/lighthouse/accessibility.ts"
    click Lighthouse_Best "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/lighthouse/best-practices.ts"
    click Lighthouse_Index "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/lighthouse/index.ts"
    click Lighthouse_Performance "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/lighthouse/performance.ts"
    click Lighthouse_SEO "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/lighthouse/seo.ts"
    click Lighthouse_Types "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/lighthouse/types.ts"
    click NodeServer_Pkg2 "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/package.json"
    click NodeServer_TS2 "https://github.com/agentdeskai/browser-tools-mcp/blob/main/browser-tools-server/tsconfig.json"

    %% Click Events for Chrome Extension (Browser-Side Integration)
    click ChromeExt_Manifest "https://github.com/agentdeskai/browser-tools-mcp/blob/main/chrome-extension/manifest.json"
    click ChromeExt_Background "https://github.com/agentdeskai/browser-tools-mcp/blob/main/chrome-extension/background.js"
    click ChromeExt_DevtoolsHTML "https://github.com/agentdeskai/browser-tools-mcp/blob/main/chrome-extension/devtools.html"
    click ChromeExt_DevtoolsJS "https://github.com/agentdeskai/browser-tools-mcp/blob/main/chrome-extension/devtools.js"
    click ChromeExt_PanelHTML "https://github.com/agentdeskai/browser-tools-mcp/blob/main/chrome-extension/panel.html"
    click ChromeExt_PanelJS "https://github.com/agentdeskai/browser-tools-mcp/blob/main/chrome-extension/panel.js"

    %% Styles
    classDef client fill:#a3c7e6,stroke:#1f77b4,stroke-width:2px;
    classDef server fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef middleware fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef extension fill:#f5c6cb,stroke:#c0392b,stroke-width:2px;
    classDef subcomponent fill:#dcdcdc,stroke:#555,stroke-width:1px;
```
