Contributing

​

Architecture

1. Chrome Extension: captures console output, network activity, screenshots and the selected DOM element, and scrubs credentials before sending anything.
2. MCP Server: implements the Model Context Protocol for AI clients, and embeds the browser connector that the extension talks to.

​

Chrome Extension

• Runs entirely in the DevTools page — there is no background service worker, which is what removed the Manifest V3 worker eviction behind “Could not establish connection. Receiving end does not exist.”
• Monitors console output and XHR/fetch requests and responses; tracks the selected DOM element
• Redacts credentials in the browser, before truncation and before transmission, so a recognised secret never crosses the socket
• Captures screenshots through the DevTools protocol, degrading PNG → JPEG → downscale to stay inside a byte budget
• Reports its tab id, so telemetry is attributed per tab
• Connects only to 127.0.0.1 / localhost
• Exposes settings in the BrowserTools panel: capture toggles, capture mode, size limits and optional cookie access

​

MCP Server

• Implements the Model Context Protocol over stdio: 16 tools, 3 prompts and 5 resource templates
• Declares an output schema on every tool and annotates read-only tools, so clients can auto-approve them
• Embeds the connector: an Express 5 HTTP API plus a ws WebSocket server, bound to loopback, bearer-token authenticated, with origin and Host validation
• Runs a second redaction pass server-side as defence in depth
• Stores telemetry in memory with per-tab retention, and writes screenshots and full audit reports to disk as MCP resources
• Drives Lighthouse through chrome-launcher against any installed Chromium-based browser

​

Development

npm install
npm run build
npm test           # unit + integration, no browser required
npm run test:e2e   # real Chromium with the extension loaded

​

Ideas worth taking on

• Verify Firefox. The extension is built cross-browser but has never been run there, and screenshots cannot work as written — they need the DevTools protocol. A Firefox path would use browser.tabs.captureTab.
• Windows and WSL testing beyond CI
• Integrate Stagehand for natural-language DOM traversal
• Integrate Browser Use for automated feature testing

​

Contributing to BrowserTools MCP

​

How to Contribute

• Bug Reports: Help us improve the project by reporting issues or bugs.
• Feature Requests: Suggest new features or improvements.
• Code Contributions: Submit bug fixes, enhancements, or new features via pull requests.
• Documentation: Improve the documentation or add new guides.
• Testing: Help test new releases and report issues.

​

Getting Started

1. Fork the Repository: Click the Fork button on the top right of the repository page.
2. Clone Your Fork
3. Create a Branch: Create a new branch for your work. Use a descriptive name:
   git checkout -b feature/your-feature-name
   
4. Make Your Changes: Write your code or documentation changes, with tests.
5. Commit Your Changes: Write clear commit messages. If your change fixes an issue, include the issue number (e.g., Fixes #42):
   git commit -m "Add feature to improve user login (Fixes #42)"
   
6. Push to Your Fork:
   git push origin feature/your-feature-name
   
7. Open a Pull Request: Navigate to the original repository and click on New Pull Request. Fill in the template provided and describe your changes.

​

Reporting Issues

• A clear description of the issue.
• Steps to reproduce (for bugs).
• Expected and actual behavior.
• The output of npx @agentdeskai/browser-tools-mcp --doctor.
• Screenshots, logs, or any other details that can help us understand the problem.

​

Coding Guidelines

• Write clear and descriptive commit messages.
• Ensure your code is well-commented and follows best practices.
• Include tests for your code changes. npm test must pass.

​

Documentation

• Update the documentation with your changes if necessary.
• Ensure that new features and improvements are reflected in the README or separate documentation files.
• Consider adding examples or code snippets to help users understand how to use new features.

​

Getting Help

• Open an issue on GitHub.
• Reach out to @tedx_ai (DMs should be open)