How luminati-io/brightdata-mcp works
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