How browsermcp/mcp works
Project Type and Purpose
• This is a full-stack (though “front” is a browser extension) automation server:
– A Node.js/TypeScript MCP server runs locally.
– A Chrome extension (“client”) connects to it.
– External AI-driven editors or services (e.g. VS Code, Claude) speak to the MCP server to automate the user’s real browser session.
• Purpose: Local, stealthy, private browser automation by proxying commands through the existing user profile.
File Structure
• src/server.ts & src/ws.ts
– HTTP/WebSocket server entrypoints.
• src/index.ts
– Bootstraps the server, loads config (port, logging).
• src/context.ts
– Manages per-connection contexts (one context = one browser session or client).
• src/tools/*.ts
– “Tool” plugins (common, custom, snapshot) implementing discrete browser actions.
• src/resources/resource.ts
• src/utils/*.ts
– Helpers (aria-snapshot for DOM snapshots, log, port detection).
• No database; all state is in-memory contexts.
README for Additional Insights
• Confirms local-only operation and real browser fingerprint use.
• Describes features: performance, privacy, stealth.
• Mentions adaptation from Playwright MCP—so the architecture mirrors a plugin-based command dispatcher.
Main Components & Boundaries
A. External Clients
1. AI-driven editor/service or CLI
2. Chrome extension (MCP client)
B. Local MCP Server (Node.js)
1. HTTP/WebSocket Layer (src/server.ts + ws.ts)
2. Context Manager (src/context.ts)
3. Tool Dispatcher (src/tools)
4. Resource Layer (src/resources)
5. Utility Layer (src/utils)
C. Browser (User’s real Chrome profile)
– Receives commands via extension, returns snapshots, performs clicks, etc.
Data Flows & Interactions
1. Client → MCP Server
• WebSocket handshake → open Context
• JSON-RPC or MCP commands over WS
2. Server Core
• Incoming command picked up by ws.ts
• Routed to the correct Context instance (context.ts)
3. Tool Execution
• Context invokes Tool (tool.ts) based on command type
• Tool uses Resources (e.g. resource.ts + aria-snapshot) and Utils to gather data or perform actions in the browser
4. Browser Extension ↔ Browser
• Extension injects scripts, executes commands in page context
5. MCP Server → Client
• Tool result (e.g. snapshot JSON, success/failure) sent back over WS
Architectural Patterns & Principles
• Plugin-style dispatcher
– Each action is a “Tool” implementing a common interface.
• Separation of concerns
– Server I/O, Context management, Tool logic, Resource formatting, Utilities all in distinct modules.
• In-memory session contexts
• No persistent storage—stateless across restarts.
• Local-first design for privacy and low latency.