# luminati-io/brightdata-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/luminati-io/brightdata-mcp
- Repository: https://github.com/luminati-io/brightdata-mcp

## Overview

##### Project type and purpose
- This is a Node.js–based CLI/server application implementing the Model Context Protocol (MCP) to empower LLMs and agents with real-time web data retrieval and scraping.
- It exposes a single-entry-point server (`server.js`), launched via `npx @brightdata/mcp`, that listens for MCP client commands, orchestrates a set of “tools,” and proxies web traffic through Bright Data services.

##### File structure
- Top-level files:
- `Dockerfile` – container build descriptor
- `server.js` – main Node.js server entry point
- `browser_tools.js`, `browser_session.js` – modules for remote browser automation
- `smithery.yaml` – tool specification in Smithery’s DSL (defines available MCP tools)
- `package.json`/`package-lock.json` – dependencies and scripts
- `assets/Tools.md` – human-readable tool list
- `examples` – usage demos
- No separate “frontend” directory – this is purely a backend/microservice.

##### README for insights
- Describes four main features: Real-time Web Access, Geo-bypass, Bot-detection bypass (Web Unlocker), Optional Browser Control
- Client integration via MCP over STDIN/STDOUT (e.g., Claude Desktop, Cursor)
- Environment variables (`API_TOKEN`, `WEB_UNLOCKER_ZONE`, `BROWSER_AUTH`) drive external connections.

##### Main components and interactions
a. MCP Client (e.g., Claude Desktop)
– Sends JSON-RPC commands conforming to Model Context Protocol
b. CLI Launcher (`npx @brightdata/mcp`)
– Spawns the Node.js process with the proper env vars
c. Node.js Server (`server.js`)
– Parses MCP messages → dispatches to tool handlers
– Loads tool definitions from `smithery.yaml`
d. Tool Modules
– `browser_tools.js` / `browser_session.js`: orchestrate remote browser API calls
– Other handlers (HTTP scrapers, data extraction routines) defined by smithery spec
e. External Services
– Bright Data Web Unlocker Proxy (for simple HTTP scraping via proxy zone)
– Bright Data Browser API zone (for heavy JS-driven or bot-protected pages)
– Target websites (the ultimate data sources)

##### Architectural patterns & design principles
- Plugin-style tools: smithery defines each “tool” interface, loaded at runtime
- Single responsibility: server.js handles protocol framing; individual modules handle web requests or browser sessions
- Configuration-driven: all credentials and zone names are injected via environment variables
- Extensibility: add new tools by updating `smithery.yaml` and dropping in new handler modules

##### Essential elements
- Core server code
- Tool modules
- External services
- Clients

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    MCPClient["MCP Client"]:::client

    %% Containerization
    DockerBuild["Docker Build & Run"]:::internal

    %% CLI and Server
    CLI["CLI Launcher (npx @brightdata/mcp)"]:::internal
    Server["Node.js MCP Server\n(server.js)"]:::internal
    Config["Env Vars\n(API_TOKEN, WEB_UNLOCKER_ZONE, BROWSER_AUTH)"]:::cylinder

    %% Tool Definitions and Modules
    smithery["Tool Definitions\n(smithery.yaml)"]:::module
    subgraph "Tool Modules"
        browserTools["Browser Automation Tools"]:::module
        browserSession["Browser Session Management"]:::module
        dataExtractors["Data Extractors"]:::module
    end

    %% Documentation and Config Files
    DocTools["Tools Documentation\n(assets/Tools.md)"]:::module
    Examples["Usage Examples\n(examples/)"]:::module
    packageJSON["Dependencies & Scripts\n(package.json\npackage-lock.json)"]:::module
    README["Project Readme\n(README.md)"]:::module
    Dockerfile["Dockerfile"]:::internal

    %% External Services
    subgraph "External Services"
        webUnlocker["Bright Data Web Unlocker Proxy"]:::external
        browserAPI["Bright Data Browser API"]:::external
        targetSites["Target Websites"]:::external
    end

    %% Flow
    MCPClient -->|MCP JSON-RPC| CLI
    DockerBuild --> CLI
    CLI -->|launch| Server
    Config --> Server
    Server -->|loads specs| smithery
    Server -->|dispatch| toolDispatcher[/"Tool Dispatcher"/]:::internal

    toolDispatcher --> browserTools
    toolDispatcher --> browserSession
    toolDispatcher --> dataExtractors

    browserTools -->|HTTP GET via Web Unlocker| webUnlocker
    webUnlocker -->|forwards to| targetSites
    targetSites -->|response| webUnlocker
    webUnlocker -->|data| browserTools
    browserTools -->|returns| Server

    browserSession -->|Browser API calls| browserAPI
    browserAPI -->|access JS pages| targetSites
    targetSites -->|response| browserAPI
    browserAPI -->|data| browserSession
    browserSession -->|returns| Server

    dataExtractors -->|direct scraping| webUnlocker
    webUnlocker -->|data| dataExtractors
    dataExtractors -->|returns| Server

    Server -->|MCP JSON-RPC Response| CLI
    CLI -->|stdout| MCPClient

    %% Additional Components
    Server --> packageJSON
    Server --> README
    Server --> DocTools
    Server --> Examples
    Server --> Dockerfile

    %% Click Events
    click CLI "https://github.com/luminati-io/brightdata-mcp/blob/main/package.json"
    click Dockerfile "https://github.com/luminati-io/brightdata-mcp/tree/main/Dockerfile"
    click Server "https://github.com/luminati-io/brightdata-mcp/blob/main/server.js"
    click smithery "https://github.com/luminati-io/brightdata-mcp/blob/main/smithery.yaml"
    click browserTools "https://github.com/luminati-io/brightdata-mcp/blob/main/browser_tools.js"
    click browserSession "https://github.com/luminati-io/brightdata-mcp/blob/main/browser_session.js"
    click DocTools "https://github.com/luminati-io/brightdata-mcp/blob/main/assets/Tools.md"
    click Examples "https://github.com/luminati-io/brightdata-mcp/tree/main/examples/"
    click packageJSON "https://github.com/luminati-io/brightdata-mcp/blob/main/package.json"
    click README "https://github.com/luminati-io/brightdata-mcp/blob/main/README.md"

    %% Styles
    classDef internal fill:#add8e6,stroke:#333,stroke-width:1px
    classDef module fill:#00008b,stroke:#fff,stroke-width:1px,color:#fff
    classDef external fill:#90ee90,stroke:#333,stroke-width:1px
    classDef cylinder fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef client fill:#ffa500,stroke:#333,stroke-width:1px
```
