# ray-0906/browser_mcp architecture

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

- Interactive diagram: https://gitdiagram.com/ray-0906/browser_mcp
- Repository: https://github.com/ray-0906/browser_mcp

## Overview

##### Project type and purpose
- This is a hybrid automation server combining:
- A Model Context Protocol (MCP) “service” (stdio-based) for AI/agent clients
- An optional FastAPI REST interface for traditional HTTP clients
- Core purpose: expose browser automation (via Playwright and/or CDP) as MCP tools and/or REST endpoints.

##### File structure
Top-level files/directories:
- mcp_server.py – entry point for the MCP server
- app/ – the FastAPI application (api endpoints, config, logging, security, services)
- browser_mcp/ – FastMCP app registering MCP tools & resources, shared context
- requirements.txt – Python dependencies
- README.md, .gitignore
- docs/, logs/, scripts/ (per README) – auxiliary documentation, logs, utilities

In app/:
- app/main.py – FastAPI uvicorn app
- app/api/endpoints/browser.py – HTTP routes for browser actions
- app/core/ – configuration, exceptions, logging setup, security policies
- app/services/ – browser_service (Playwright/CDP abstraction), session_service (in-memory session management)

In browser_mcp/:
- browser_mcp/mcp/app.py – MCP application factory and tool/resource registration
- browser_mcp/mcp/context.py – shared runtime context (sessions, config)
- browser_mcp/mcp/lifespan.py – startup/shutdown hooks
- browser_mcp/mcp/resources.py – MCP resource definitions (screenshots, page content)
- browser_mcp/mcp/tools.py – MCP tool definitions (navigate, click_by_text, etc.)

##### README for additional insights
- Features emphasize universal browser control, session heuristics, resource streaming
- Two “servers”: MCP (stdio transport) and optional FastAPI (HTTP/Swagger docs)
- No external database; session state in memory
- Relies on Playwright (or CDP-attached browser) for automation

##### How to model this
a. Main components
- MCP Server Process
– mcp_server.py → uses browser_mcp/mcp/app and tools/resources
– stdio transport ↔ MCP client (e.g., Claude Desktop)
- FastAPI Server Process
– app/main.py → HTTP API endpoints (app/api/endpoints/browser.py)
– uvicorn host:port
- Shared Service Layer (imported by both)
– BrowserService (Playwright + CDP abstraction)
– SessionService (in-memory session registry)
– Core modules (config, logging, security)
- External Browser Targets
– Headless Playwright browsers (Chromium, WebKit, Firefox)
– User-controlled Chrome/Edge via CDP (remote debugging)
- Optional: Logging sink (logs/app.log)

b. Relationships & interactions
- MCP client → stdio ↔ MCP server → invokes MCP tools → Service Layer → Browser/Playwright
- HTTP client → HTTP ↔ FastAPI server → calls browser endpoints → Service Layer → Browser/Playwright
- Service Layer maintains session state and issues Playwright/CDP calls → returns data or streams resources → tool or REST response
- Logging configured in core logs to file

c. Architectural patterns & design principles
- Layered architecture (API layer, service layer, integration layer)
- Single in-memory session registry (Stateful session management)
- Adapter pattern for Playwright vs. CDP (“bring your own browser”)
- Hexagonal (ports & adapters) style: two adapters (MCP, HTTP) powering a shared core

d. Key technologies & frameworks
- Python 3.9+
- FastAPI, uvicorn (HTTP REST)
- mcp-server (Model Context Protocol over stdio)
- Playwright (browser automation) + Chrome/Edge CDP
- Pydantic (schemas)
- Logging, security modules in app/core

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        MCP_CL["MCP Client"]:::external
        HTTP_CL["HTTP Client"]:::external
    end

    %% Protocol Adapters
    subgraph "Protocol Adapters"
        MCP_SR["MCP Server Process"]:::adapter
        HTTP_SR["FastAPI HTTP Server"]:::adapter
    end

    %% HTTP Endpoints
    BE_NODE["HTTP Browser Endpoints"]:::adapter

    %% MCP App Components
    subgraph "MCP Application"
        MCP_APP["MCP App Factory & Registration"]:::adapter
        MCP_CTX["MCP Shared Runtime Context"]:::adapter
        MCP_LIFE["MCP Startup/Shutdown Hooks"]:::adapter
        MCP_RES["MCP Resource Definitions"]:::adapter
        MCP_TOOL["MCP Tool Definitions"]:::adapter
    end

    %% Core Service Layer
    subgraph "Core Service Layer"
        BS["BrowserService"]:::core
        SS["SessionService"]:::core
        CM_CONFIG["Core Config Module"]:::core
        CM_EXC["Core Exceptions Module"]:::core
        CM_LOG["Core Logging Setup"]:::core
        CM_SEC["Core Security Policies"]:::core
    end

    %% External Systems
    subgraph "Browser Engines"
        H_PLAY["Headless Playwright"]:::external
        CDP_BR["User Browser via CDP"]:::external
    end
    LogFile["Log File Sink"]:::external

    %% Connections - Clients to Adapters
    MCP_CL -->|"stdio"| MCP_SR
    HTTP_CL -->|"HTTP/Swagger"| HTTP_SR

    %% Adapters to HTTP Endpoints
    HTTP_SR --> BE_NODE

    %% MCP Server to MCP App Components
    MCP_SR --> MCP_APP
    MCP_APP --> MCP_CTX
    MCP_APP --> MCP_LIFE
    MCP_APP --> MCP_RES
    MCP_APP --> MCP_TOOL

    %% Adapters to Core Services
    MCP_SR --> BS
    MCP_SR --> SS
    HTTP_SR --> BS
    HTTP_SR --> SS

    %% Core Modules Collaboration
    BS --> CM_CONFIG
    BS --> CM_SEC
    BS --> CM_LOG
    SS --> CM_CONFIG
    SS --> CM_EXC

    %% Core Services to Browsers
    BS --> H_PLAY
    BS --> CDP_BR

    %% Logging
    CM_LOG -->|"writes"| LogFile

    %% Click Events
    click MCP_SR "https://github.com/ray-0906/browser_mcp/blob/main/mcp_server.py"
    click HTTP_SR "https://github.com/ray-0906/browser_mcp/blob/main/app/main.py"
    click BE_NODE "https://github.com/ray-0906/browser_mcp/blob/main/app/api/endpoints/browser.py"
    click CM_CONFIG "https://github.com/ray-0906/browser_mcp/blob/main/app/core/config.py"
    click CM_EXC "https://github.com/ray-0906/browser_mcp/blob/main/app/core/exceptions.py"
    click CM_LOG "https://github.com/ray-0906/browser_mcp/blob/main/app/core/logging.py"
    click CM_SEC "https://github.com/ray-0906/browser_mcp/blob/main/app/core/security.py"
    click BS "https://github.com/ray-0906/browser_mcp/blob/main/app/services/browser_service.py"
    click SS "https://github.com/ray-0906/browser_mcp/blob/main/app/services/session_service.py"
    click MCP_APP "https://github.com/ray-0906/browser_mcp/blob/main/browser_mcp/mcp/app.py"
    click MCP_CTX "https://github.com/ray-0906/browser_mcp/blob/main/browser_mcp/mcp/context.py"
    click MCP_LIFE "https://github.com/ray-0906/browser_mcp/blob/main/browser_mcp/mcp/lifespan.py"
    click MCP_RES "https://github.com/ray-0906/browser_mcp/blob/main/browser_mcp/mcp/resources.py"
    click MCP_TOOL "https://github.com/ray-0906/browser_mcp/blob/main/browser_mcp/mcp/tools.py"

    %% Styles
    classDef adapter fill:#A2D2FF,stroke:#004E89,color:#000
    classDef core fill:#BDE0FE,stroke:#0077B6,color:#000
    classDef external fill:#FFC8DD,stroke:#D00000,color:#000
```
