How agentdeskai/browser-tools-mcp works
MCP Server (located under browser-tools-mcp)
• Implements the Model Context Protocol (MCP) which is used to expose standardized tools to MCP clients (like Cursor, Claude, etc.).
• Serves as the entry point for commands coming from the IDE, and it formats these for further processing.
• Written in TypeScript (mcp-server.ts, package.json, tsconfig.json).
Node Server (located under browser-tools-server)
• Acts as a middleware between the MCP server and the Chrome extension.
• Handles incoming logs, screenshots, console events, and also integrates audit tools (using Lighthouse modules for accessibility, performance, SEO, best practices, and NextJS audits).
• Contains several TypeScript modules (browser-connector.ts, puppeteer-service.ts, along with a dedicated folder for Lighthouse integration).
Chrome Extension (located under chrome-extension)
• Runs in Chrome to capture browser events such as network activity, XHR requests, console logs, and DOM selections.
• Communicates with the Node Server via WebSocket (as per the README) and relays this information for audit analysis.
• Contains essential files like manifest.json and scripts for background tasks and DevTools integrations (background.js, devtools.js, panel.js).
A. Identify and Label Main Components:
1. MCP Client – Represents any MCP-compatible client (e.g., Cursor IDE) that triggers audits.
3. Node Server – Denote the middleware component (browser-tools-server) which includes both the browser connector and dedicated audit modules (including Lighthouse integration). Emphasize its dual role in processing logs and handling auditing tool invocations.
4. Chrome Extension – The front-end tool in the browser capturing logs, screenshots, and other necessary UI events.
B. Define the Relationships & Data/Control Flow:
• From Node Server, illustrate the flow of commands and information to the Chrome Extension.
• Also, show the feedback loop where audit results (like accessibility, performance, SEO audit results) flow back from the Node Server through the MCP Server and ultimately are returned to the MCP Client.
• Additionally, detail that the Node Server not only processes logs and requests but also auto-handles reconnection, truncation of data, and other data normalization tasks.
C. Highlight Architectural Patterns and Design Principles:
• Separation of concerns by showing distinct layers (presentation in the extension, a middleware processing layer, and the MCP interfacing server).
• Make note of the integration of audit tools (Lighthouse modules) within the Node Server. Showing these as a sub-module can help highlight the extensibility of the auditing process.
• That each component is containerized in separate directories and has its own configuration/build scripts (package.json, tsconfig.json) – a design decision that aids in modularity and independent versioning/deployment.
D. Include Relevant Technologies & Frameworks:
• TypeScript is predominantly used in both server components.
• Puppeteer is used for headless Chrome automation within the Node Server.
• Lighthouse is integrated for running multiple audits (accessibility, performance, SEO, best practices, and specialized NextJS auditing).
• The Chrome Extension itself leverages standard web extension APIs (as specified in its manifest.json) to interact with browser internals.
• Lighthouse integration (for various audits with separate modules such as accessibility, performance, SEO, etc.)
• Puppeteer service components used for headless browser control.
• Browser connector for handling communication with the Chrome extension.
┌─────────────┐ ┌──────────────┐ ┌───────────────┐ ┌─────────────┐
│ MCP Client │ ──► │ MCP Server │ ──► │ Node Server │ ──► │ Chrome │
│ (IDE) │ ◄── │ (Protocol │ ◄── │ (Middleware │ ◄── │ Extension │
│ │ │ Handler) │ │ & Audits) │ │ │
└─────────────┘ └──────────────┘ └───────────────┘ └─────────────┘