@dorothywebb/any-browser-mcp

# Organized Browser MCP Server **A properly organized MCP server that NEVER auto-launches browsers and only connects to your existing browser when actually needed.** ## 🛡️ Safety-First Design This MCP server is designed with strict safety policies to ensure it: - ✅ **NEVER auto-launches browsers** - Zero risk of unwanted browser instances - ✅ **Only connects to existing browsers** - Respects your current browser setup - ✅ **Lazy initialization** - No connections until you actually use MCP tools - ✅ **VS Code startup friendly** - Won't slow down or interfere with VS Code startup - ✅ **User-controlled** - You decide when and how to use browser automation ## 🏗️ Architecture Overview ### Core Components 1. **ConfigManager** (`src/core/ConfigManager.ts`) - Enforces safety policies at configuration level - Prevents any auto-launch configurations - Provides consistent settings across the application 2. **LazyBrowserManager** (`src/core/LazyBrowserManager.ts`) - Manages lazy initialization of browser connections - Only connects when MCP tools are actually called - Handles connection state and retry logic 3. **BrowserConnection** (`src/utils/BrowserConnection.ts`) - Low-level browser connection utility - Strict "existing browser only" policy - Chrome DevTools Protocol (CDP) based communication 4. **MCP Server** (`src/server.ts`) - Main MCP server implementation - Exposes browser automation tools - Integrates with lazy browser manager ## 🔧 Setup Instructions ### 1. Install Dependencies ```bash cd organized_browser_mcp npm install ``` ### 2. Build the Project ```bash npm run build ``` ### 3. Start Your Browser with Debugging **Before using the MCP server**, start your browser with debugging enabled: **Chrome:** ```bash # Close Chrome completely first, then: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 ``` **Edge:** ```bash msedge --remote-debugging-port=9222 ``` **Linux Chrome:** ```bash google-chrome --remote-debugging-port=9222 ``` ### 4. Configure VS Code Add to your VS Code `settings.json`: ```json { "mcp.servers": [ { "name": "organized-browser", "command": "node", "args": ["/path/to/organized_browser_mcp/bin/server.js"], "env": {} } ] } ``` ### 5. Test the Setup 1. **Start VS Code** - No browser should launch automatically ✅ 2. **Check MCP status** - Server should be ready but not connected ✅ 3. **Use a browser tool** - Now it connects to your existing browser ✅ 4. **Verify** - Should use your existing browser with all your data ✅ ## 🛠️ Available Tools Once you use a browser tool (and lazy initialization connects), you have access to: - `browser_navigate` - Navigate to URLs - `browser_screenshot` - Take screenshots - `browser_click` - Click elements - `browser_type` - Type text - `browser_get_content` - Extract page content - `browser_list_pages` - List all open tabs - `browser_status` - Get connection status ## 🔍 Debugging & Troubleshooting ### Check Browser Availability ```bash # Test if your browser debugging is working: curl http://localhost:9222/json/version ``` Should return browser information if properly configured. ### Enable Verbose Logging ```bash node bin/server.js --verbose ``` ### Common Issues **"Browser not available"** - Ensure browser is running with `--remote-debugging-port=9222` - Check that port 9222 is not blocked by firewall - Verify no other tools are using the debugging port **"Connection timeout"** - Browser might not have debugging enabled - Try restarting browser with debugging flag - Check browser process is actually running ## 🛡️ Safety Features ### Configuration-Level Safety ```typescript // These settings are ENFORCED regardless of config file: autoLaunch: false, // Never auto-launch allowLaunch: false, // Never allow launching useExistingOnly: true, // Only existing browsers initializeOnStartup: false, // Don't connect on startup lazyInitialization: true, // Connect only when needed neverLaunchBrowser: true, // Safety flag requireExistingBrowser: true // Must have existing browser ``` ### Code-Level Safety - **LaunchBrowser() method throws error** - Prevents accidental launches - **Connection checks before operations** - Validates browser availability - **Graceful failure** - Clear error messages when browser not available - **No automatic retries** - Won't keep trying to launch browsers ### Runtime Safety - **Lazy initialization** - No connections until tool use - **Connection validation** - Checks browser availability before connecting - **Clear error messages** - Guides user to start browser manually - **Graceful degradation** - Fails safely when browser not available ## 📁 Project Structure ``` organized_browser_mcp/ ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── config.json # Runtime configuration ├── bin/ │ └── server.js # CLI entry point ├── src/ │ ├── server.ts # Main MCP server │ ├── core/ │ │ ├── ConfigManager.ts # Configuration management │ │ └── LazyBrowserManager.ts # Lazy initialization logic │ ├── utils/ │ │ └── BrowserConnection.ts # Browser connection utility │ └── types/ │ └── index.ts # TypeScript type definitions └── dist/ # Compiled JavaScript (after build) ``` ## 🔄 How Lazy Initialization Works ### Before (❌ Bad Behavior) ``` VS Code starts → MCP server starts → Immediately connects to browser ``` ### After (✅ Good Behavior) ``` VS Code starts → MCP server starts → Waits quietly User calls browser tool → Lazy manager connects → Tool executes ``` ### Implementation Details 1. **Server Startup**: Only creates MCP server, no browser connections 2. **Tool Registration**: Tools are available but no browser access yet 3. **First Tool Call**: Triggers lazy initialization 4. **Browser Connection**: Connects to existing browser 5. **Tool Execution**: Performs the actual browser action 6. **Subsequent Tools**: Use existing connection ## 🎯 Benefits - ✅ **Zero VS Code startup impact** - No browser operations during startup - ✅ **Respects user workflow** - Uses your actual browser with all data - ✅ **Safe by design** - Cannot accidentally launch browsers - ✅ **Clear error handling** - Helpful messages when browser not ready - ✅ **Predictable behavior** - Consistent "existing browser only" policy - ✅ **Professional MCP behavior** - Works like a proper service ## 🔧 Development ### Build ```bash npm run build ``` ### Development Mode ```bash npm run dev ``` ### Test Connection ```bash node bin/server.js --verbose ``` ## 📜 License MIT License - See LICENSE file for details. --- **This MCP server prioritizes safety and user control over convenience. It will never surprise you by launching browsers automatically!** 🛡️