mybrowsercontrol

satwareAG/mybrowsercontrol

3.1

If you are the rightful owner of mybrowsercontrol and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

MyBrowserControl is an advanced browser automation MCP server built on the Microsoft Playwright MCP foundation, designed to enhance AI assistant capabilities with features like stealth mode, session management, and more.

MyBrowserControl

Advanced browser automation MCP server built on Microsoft Playwright MCP foundation

🎯 Overview

MyBrowserControl is a unified browser automation MCP (Model Context Protocol) server that combines the best features from multiple browser automation solutions:

  • Microsoft Playwright MCP - Enterprise-grade foundation (21.4k stars, 96% issue resolution)
  • AgentDesk AI - Lighthouse audits and advanced tooling
  • BrowserMCP - Stealth mode and session management

Three-Mode Architecture

  1. Native Mode (Default) - Fast, direct Playwright automation
  2. Lighthouse Mode - Performance audits and QA analysis
  3. Extension Mode - Connect to existing browser sessions

🚀 Quick Start

Installation

npm install -g @mybrowsercontrol/mcp

Basic Usage

# Start server in native mode (default)
mybrowsercontrol

# Start in Lighthouse mode
mybrowsercontrol --mode lighthouse

# Start in headless mode
mybrowsercontrol --headless

# Start with headed mode (visible browser window)
mybrowsercontrol --headed

# Use system-installed browser instead of Playwright's bundled browser
mybrowsercontrol --executable-path /usr/bin/chromium

# Combined: headed mode with system browser
mybrowsercontrol --headed --executable-path /usr/bin/chromium

MCP Configuration

Add to your ~/.cline/mcp_servers.json:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@mybrowsercontrol/mcp@latest"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/home/mw/Projects/mybrowsercontrol/dist/index.js"]
    }
  }
}

📚 Available Tools

Core Tools (v0.1.0)

  • browser_navigate - Navigate to a URL
  • browser_screenshot - Capture page screenshot
  • browser_content - Get page HTML content
  • browser_close - Close the browser

Coming Soon (Phase 2-3)

  • browser_lighthouse_audit - Run Lighthouse performance audits
  • browser_session_save - Save browser session state
  • browser_session_restore - Restore saved session
  • browser_stealth_enable - Enable anti-detection mode
  • browser_optimize_tokens - AI-optimized result filtering

🏗️ Architecture

┌─────────────────────────────────────┐
│     AI Assistant (Cline/Claude)      │
└──────────────┬──────────────────────┘
               │ MCP Protocol
               ▼
┌─────────────────────────────────────┐
│   MyBrowserControl MCP Server        │
│                                      │
│  ┌────────────────────────────────┐ │
│  │  Core: Playwright Foundation   │ │
│  │  - 3 deployment modes          │ │
│  │  - Multi-browser support       │ │
│  │  - Accessibility-first         │ │
│  └────────────────────────────────┘ │
│                                      │
│  ┌────────────────────────────────┐ │
│  │  Extensions (Coming Soon)      │ │
│  │  - Lighthouse integration      │ │
│  │  - Stealth mode                │ │
│  │  - Session management          │ │
│  │  - Screenshot optimization     │ │
│  └────────────────────────────────┘ │
└──────────────┬──────────────────────┘
               │ Playwright API
               ▼
        ┌──────────────┐
        │   Browser    │
        │ (Chrome/FF)  │
        └──────────────┘

🛠️ Development

Prerequisites

  • Node.js 18+
  • npm or yarn
  • Git

Setup

# Clone repository
git clone https://github.com/satwareAG/mybrowsercontrol.git
cd mybrowsercontrol

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Project Structure

mybrowsercontrol/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── config/
│   │   └── types.ts          # Configuration types
│   ├── core/
│   │   └── playwright.ts     # Playwright wrapper
│   ├── extensions/           # Future extensions
│   │   ├── lighthouse/
│   │   ├── stealth/
│   │   ├── screenshot/
│   │   └── session/
│   └── tools/                # MCP tool implementations
├── dist/                     # Compiled output
├── docs/                     # Documentation
└── tests/                    # Test suite

🧪 Testing

MyBrowserControl follows Test-Driven Design (TDD) principles with comprehensive test coverage:

Test Suite Status

  • Unit Tests: ✅ 46 tests passing
  • Application Tests: 🚧 Pending implementation
  • Integration Tests: 🚧 Pending implementation
  • Acceptance Tests: 🚧 Pending implementation

Running Tests

# Run all unit tests
npm run test:unit

# Run with coverage
npm run test:unit -- --coverage

# Watch mode for TDD
npm run test:watch

# Run all tests (when implemented)
npm test

Manual Testing with MCP Inspector

Test tools interactively using the official MCP Inspector:

# Build project
npm run build

# Launch Inspector
npx @modelcontextprotocol/inspector node dist/index.js

The Inspector provides a web UI to:

  • List all available MCP tools
  • Execute tools with custom parameters
  • View responses and debug issues
  • Monitor MCP protocol messages

Documentation

  • - Comprehensive testing strategy
  • - MCP Inspector usage and debugging

📖 Documentation

  • (coming soon)
  • (coming soon)
  • (coming soon)
  • ✅
  • ✅

🗺️ Roadmap

Phase 1: Foundation (Current - Months 1-2)

  • Project structure and TypeScript setup
  • Core Playwright wrapper
  • Basic MCP server implementation
  • Native mode with 4 core tools
  • Testing framework
  • CI/CD pipeline

Phase 2: Extensions (Month 3)

  • Lighthouse integration
  • Screenshot optimization
  • AI-optimized result filtering
  • Extended tool set

Phase 3: Advanced Features (Month 4)

  • Multi-tab session management
  • Stealth mode
  • Session save/restore
  • Selective tool loading

Phase 4: Polish & Release (Months 5-6)

  • Comprehensive testing
  • Performance benchmarking
  • Complete documentation
  • v1.0.0 public release

🤝 Contributing

Contributions are welcome! This is an open-source project under the Apache 2.0 license.

Development Workflow

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

📄 License

Apache License 2.0 - See file for details.

🙏 Acknowledgments

Built on the shoulders of giants:

  • Microsoft Playwright MCP - Foundation and core architecture
  • AgentDesk AI - Lighthouse integration inspiration
  • BrowserMCP - Stealth mode techniques
  • Model Context Protocol - MCP SDK and specification

📞 Support

🔗 Links

Status: 🚧 Active Development (v0.1.0 - Phase 1)

Made with ❤️ by satware AG