How ray-0906/browser_mcp works
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