@ricardodeazambuja/browser-mcp-server 1.0.3 → 1.3.0

package/CHANGELOG-v1.3.0.md

@@ -0,0 +1,42 @@
+# Changelog - v1.3.0 (2025-12-27)
+
+This is a major architectural release that modularizes the entire codebase for better maintainability, testing, and extensibility.
+
+## ⭐ New Features
+
+- **Modular Architecture**: The codebase is now organization into focused modules in `src/`:
+  - `src/index.js`: Main entry point and MCP protocol handler
+  - `src/browser.js`: Centralized browser connection and state management
+  - `src/tools/`: Dedicated modules for each tool category (navigation, interaction, media, etc.)
+  - `src/utils.js`: Shared utilities
+- **Plugin System**: New `plugins/` directory allows adding specialized tool modules that are auto-discovered by `src/tools/index.js`.
+- **Improved Test Suite**: Tests are now organized in the `tests/` directory with `fixtures/`.
+- **Reduced Bundle Size**: The main entry point is now cleaner and easier to maintain.
+
+## 🛠 Refactoring
+
+- **Source Code**: Moved all source code from the root directory to `src/`.
+- **Entry Point**: Replaced the monolithic `browser-mcp-server-playwright.js` with `src/index.js`.
+- **Tool Logic**: Extracted tool implementations from the main server file into:
+  - `src/tools/navigation.js`
+  - `src/tools/interaction.js`
+  - `src/tools/media.js`
+  - `src/tools/system.js`
+  - `src/tools/console.js`
+  - `src/tools/info.js`
+  - `src/tools/mouse.js`
+  - `src/tools/keyboard.js`
+  - `src/tools/pages.js`
+- **Utilities**: Extracted `debugLog`, `loadPlaywright`, and `findChromeExecutable` to `src/utils.js`.
+
+## 🧹 Cleanup
+
+- Removed the legacy `browser-mcp-server-playwright.js` wrapper file.
+- Removed old `.tgz` build artifacts.
+- Updated `package.json` to point `main` and `bin` to `src/index.js`.
+
+## 🧪 Testing
+
+- Verified all 36 tools function correctly after modularization.
+- Verified MCP protocol communication.
+- Verified browser connection strategies (Antigravity, System Chrome, Playwright).

package/README.md

@@ -2,14 +2,15 @@
 
 A universal browser automation MCP server using Playwright. Control Chrome programmatically through the Model Context Protocol.
 
-**16 powerful browser automation tools** including navigation, clicking, typing, screenshots, console capture, and session recording.
+**37 powerful browser automation tools** including multi-tab management, media monitoring/control, low-level interaction, session recording, and on-demand documentation.
 
 ## Features
 
 - ✅ **Smart Chrome Detection**: Automatically finds and uses system Chrome/Chromium
 - ✅ **Three-Tier Strategy**: Antigravity Chrome → System Chrome → Playwright Chromium
 - ✅ **Universal**: Works with Antigravity, Claude Desktop, and any MCP client
-- ✅ **16 Tools**: Navigate, click, type, screenshot, console logs, and more
+- ✅ **37 Tools**: Media control, multi-tab, pixel-based interaction, and more
+- ✅ **On-Demand Docs**: Built-in documentation tool with return schemas and examples
 - ✅ **Auto-Install**: Playwright installed automatically via npm (no manual setup)
 - ✅ **Safe**: Isolated browser profile (won't touch your personal Chrome)
 - ✅ **Console Capture**: Debug JavaScript errors in real-time
@@ -73,8 +74,8 @@ npx playwright install chromium
 
 ```bash
 # Download the main file directly (no git required)
-curl -o browser-mcp-server-playwright.js \
-  https://raw.githubusercontent.com/ricardodeazambuja/browser-mcp-server/main/browser-mcp-server-playwright.js
+curl -o src/index.js \
+  https://raw.githubusercontent.com/ricardodeazambuja/browser-mcp-server/main/src/index.js
 
 # Install Playwright
 npm install playwright
@@ -93,7 +94,7 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
   "mcpServers": {
     "browser-tools": {
       "command": "node",
-      "args": ["/absolute/path/to/browser-mcp-server-playwright.js"]
+      "args": ["/absolute/path/to/src/index.js"]
     }
   }
 }
@@ -123,7 +124,7 @@ Add to `~/.gemini/antigravity/mcp_config.json`:
   "mcpServers": {
     "browser-tools": {
       "command": "node",
-      "args": ["/home/username/.gemini/antigravity/browser-mcp-server-playwright.js"]
+      "args": ["/home/username/.gemini/antigravity/src/index.js"]
     }
   }
 }
@@ -151,12 +152,12 @@ Add the browser-mcp-server using the Claude CLI:
 ```bash
 # Install the MCP server with default isolated profile
 claude mcp add --transport stdio browser \
-  -- node /absolute/path/to/browser-mcp-server-playwright.js
+  -- node /absolute/path/to/src/index.js
 
 # Or with custom browser profile for more control
 claude mcp add --transport stdio browser \
   --env MCP_BROWSER_PROFILE=/path/to/custom/profile \
-  -- node /absolute/path/to/browser-mcp-server-playwright.js
+  -- node /absolute/path/to/src/index.js
 ```
 
 **Using NPM:**
@@ -202,11 +203,11 @@ Add the browser-mcp-server using the Gemini CLI commands:
 **Using local installation:**
 ```bash
 # Install the MCP server with default isolated profile
-gemini mcp add browser node /absolute/path/to/browser-mcp-server-playwright.js
+gemini mcp add browser node /absolute/path/to/src/index.js
 
 # Or with custom browser profile
 gemini mcp add -e MCP_BROWSER_PROFILE=/path/to/custom/profile browser \
-  node /absolute/path/to/browser-mcp-server-playwright.js
+  node /absolute/path/to/src/index.js
 ```
 
 **Using NPM:**
@@ -243,40 +244,124 @@ gemini mcp remove browser
 
 ```bash
 # Add with specific scope (user vs project)
-gemini mcp add -s user browser node /path/to/browser-mcp-server-playwright.js
+gemini mcp add -s user browser node /path/to/src/index.js
 
 # Add with timeout configuration
-gemini mcp add --timeout 30000 browser node /path/to/browser-mcp-server-playwright.js
+gemini mcp add --timeout 30000 browser node /path/to/src/index.js
 
 # Skip tool confirmation prompts (use with caution)
-gemini mcp add --trust browser node /path/to/browser-mcp-server-playwright.js
+gemini mcp add --trust browser node /path/to/src/index.js
 ```
 
-## Available Tools (16)
+## Available Tools (37)
+
+### Documentation
+1. **browser_docs(toolName?)** - Get detailed docs, return schemas, examples, and caveats for any tool
+
+### Multi-Page Management
+2. **browser_list_pages()** - List all open tabs/pages
+3. **browser_new_page(url?)** - Open a new tab
+4. **browser_switch_page(index)** - Switch active tab
+5. **browser_close_page(index?)** - Close a tab
+
+### Media Awareness & Control
+6. **browser_get_media_summary()** - List all audio/video elements with state
+7. **browser_get_audio_analysis(durationMs?, selector?)** - Analyze audio output (volume, spectrum)
+8. **browser_control_media(selector, action, value?)** - Play, pause, mute, seek
 
 ### Navigation & Interaction
-1. **browser_navigate(url)** - Navigate to a URL
-2. **browser_click(selector)** - Click an element
-3. **browser_type(selector, text)** - Type text into an input
-4. **browser_scroll(x?, y?)** - Scroll the page
+9. **browser_navigate(url)** - Navigate to a URL
+10. **browser_click(selector)** - Click an element (selector-based)
+11. **browser_type(selector, text)** - Type text into an input
+12. **browser_scroll(x?, y?)** - Scroll the page (generic)
+13. **browser_reload()** - Reload current page
+14. **browser_go_back()** - Navigate back
+15. **browser_go_forward()** - Navigate forward
+16. **browser_wait(ms)** - Pause execution
+
+### Low-Level Interaction
+17. **browser_mouse_move(x, y)** - Move mouse to pixel coordinates
+18. **browser_mouse_click(x?, y?, button?, count?)** - Click at pixel coordinates
+19. **browser_mouse_drag(fromX, fromY, toX, toY)** - Drag and drop
+20. **browser_mouse_wheel(deltaX, deltaY)** - Scroll mouse wheel
+21. **browser_press_key(key)** - Send keyboard event (e.g. "Enter")
 
 ### Information Gathering
-5. **browser_screenshot(fullPage?)** - Capture screenshot
-6. **browser_get_text(selector)** - Get text from element
-7. **browser_get_dom(selector?)** - Get DOM structure
-8. **browser_evaluate(code)** - Execute JavaScript
-
-### Console Debugging ⭐ NEW
-9. **browser_console_start(level?)** - Start capturing console logs
-10. **browser_console_get(filter?)** - Get captured logs
-11. **browser_console_clear()** - Clear logs and stop
-
-### Advanced
-12. **browser_wait_for_selector(selector, timeout?)** - Wait for element
-13. **browser_resize_window(width, height)** - Resize browser window
-14. **browser_start_video_recording(path?)** - Start recording session (Playwright traces)
-15. **browser_stop_video_recording()** - Stop and save recording
-16. **browser_health_check()** - Verify browser connection
+22. **browser_screenshot(fullPage?)** - Capture screenshot
+23. **browser_get_text(selector)** - Get text from element
+24. **browser_get_dom(selector?)** - Get DOM structure
+25. **browser_read_page()** - Get page metadata (title, URL)
+26. **browser_evaluate(code)** - Execute JavaScript
+
+### Console Debugging
+27. **browser_console_start(level?)** - Start capturing logs
+28. **browser_console_get(filter?)** - Get captured logs
+29. **browser_console_clear()** - Clear logs and stop
+
+### Advanced Interaction
+30. **browser_hover(selector)** - Hover over element
+31. **browser_focus(selector)** - Focus element
+32. **browser_select(selector, values)** - Select dropdown options
+33. **browser_wait_for_selector(selector, timeout?)** - Wait for element
+34. **browser_resize_window(width, height)** - Resize window
+35. **browser_start_video_recording(path?)** - Start session recording
+36. **browser_stop_video_recording()** - Stop and save recording
+37. **browser_health_check()** - Verify browser connection
+
+## On-Demand Documentation
+
+The `browser_docs` tool provides comprehensive documentation for all browser tools **without increasing token overhead** in normal operations.
+
+### Why This Matters
+
+- **Token Efficient**: Tool descriptions stay concise (saving tokens on every request)
+- **Comprehensive**: Detailed docs available when needed (return schemas, examples, caveats)
+- **Self-Documenting**: AI agents can discover tool capabilities on-demand
+
+### What You Get
+
+When calling `browser_docs(toolName)`, you receive:
+- **Parameter Details**: Types, optionality, defaults, enums
+- **Return Value Schemas**: Exact structure of what the tool returns
+- **Selector Syntax**: How to write Playwright selectors (CSS, text, data attributes)
+- **Important Caveats**: Warnings about CORS, clearing behavior, state management
+- **Practical Examples**: Real-world usage patterns
+
+### Usage
+
+```javascript
+// Get docs for a specific tool
+browser_docs({ toolName: 'browser_get_audio_analysis' })
+
+// List all available tools
+browser_docs({})
+
+// Invalid tool name suggests similar tools
+browser_docs({ toolName: 'navigate' })
+// → Did you mean: browser_navigate, browser_go_back, ...
+```
+
+### Example Output
+
+```
+📖 browser_type(selector, text)
+
+Type text into an input field.
+
+Parameters:
+  • selector (string, required) - Playwright selector for the input
+  • text (string, required) - Text to type
+
+Returns:
+  { content: [{ type: 'text', text: 'Typed into <selector>' }] }
+
+⚠️ Important:
+  • Uses page.fill() which CLEARS the field first, then types
+  • Does NOT append to existing text
+
+Example:
+  browser_type({ selector: '#username', text: 'john@example.com' })
+```
 
 ## Examples
 
@@ -297,14 +382,48 @@ browser_console_get(filter: "error")
 // Shows: ❌ [ERROR] Uncaught TypeError: ...
 ```
 
-### Automate Form Submission
+### Media Monitoring & Control
+```javascript
+// Agent uses:
+browser_navigate("https://youtube.com/watch?v=...")
+browser_get_media_summary() // See active video state
+browser_control_media(selector: "video", action: "play")
+browser_get_audio_analysis(durationMs: 2000) // "Hear" the volume
+```
+
+### Multi-Tab Automation
 ```javascript
 // Agent uses:
-browser_navigate("https://example.com/login")
-browser_type("#username", "user@example.com")
-browser_type("#password", "secret")
-browser_click("#login-button")
-browser_wait_for_selector(".dashboard")
+browser_navigate("https://wikipedia.org")
+browser_new_page("https://google.com")
+browser_list_pages() // Shows 2 pages
+browser_switch_page(0) // Back to Wikipedia
+```
+
+### Pixel-Based Interaction
+```javascript
+// Agent uses:
+browser_mouse_move(500, 300)
+browser_mouse_click(button: "right")
+browser_press_key("Enter")
+```
+
+### Get Tool Documentation
+```javascript
+// Agent uses:
+browser_docs(toolName: "browser_get_audio_analysis")
+// Returns:
+// 📖 browser_get_audio_analysis(durationMs?, selector?)
+//
+// Parameters:
+//   • durationMs (number, optional) - Duration to analyze in ms (default: 2000)
+//   • selector (string, optional) - Selector for specific media element
+//
+// Returns: { isSilent: boolean, averageVolume: number, ... }
+// ⚠️ Important: Requires CORS headers for cross-origin media
+
+// List all tools:
+browser_docs()  // Shows all 37 tools
 ```
 
 ## How It Works
@@ -381,7 +500,7 @@ This MCP server provides powerful browser automation capabilities. Please review
 export MCP_BROWSER_PROFILE="$HOME/.mcp-browser-profile"
 
 # Then run the server
-node browser-mcp-server-playwright.js
+node src/index.js
 ```
 
 ### MCP Config with Environment Variables
@@ -391,7 +510,7 @@ node browser-mcp-server-playwright.js
   "mcpServers": {
     "browser-tools": {
       "command": "node",
-      "args": ["/path/to/browser-mcp-server-playwright.js"],
+      "args": ["/path/to/src/index.js"],
       "env": {
         "MCP_BROWSER_PROFILE": "/tmp/my-custom-profile"
       }
@@ -452,7 +571,14 @@ Use the `browser_health_check` tool to verify:
 
 ```
 browser-mcp-server/
-├── browser-mcp-server-playwright.js  # Main server
+├── src/index.js                      # Main server entry point
+├── src/                              # Source code
+│   ├── index.js                      # Main server class
+│   ├── browser.js                    # Browser management
+│   ├── tools/                        # Tool modules
+│   └── utils.js                      # Utilities
+├── tests/                            # Test suite
+├── plugins/                          # Plugin directory
 ├── package.json                      # npm package config
 ├── README.md                         # This file
 └── LICENSE                           # MIT license
@@ -465,7 +591,7 @@ browser-mcp-server/
 npm test
 
 # Manual test
-echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node browser-mcp-server-playwright.js
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node src/index.js
 ```
 
 ### Debug Logging
@@ -520,7 +646,7 @@ Check `/tmp/mcp-browser-server.log` for detailed logs:
 ## Comparison with Other Tools
 
 ### vs. Puppeteer MCP Servers
-- ✅ More tools (16 vs typical 8-10)
+- ✅ More tools (37 vs typical 8-10)
 - ✅ Console capture built-in
 - ✅ Better error messages
 - ✅ Hybrid mode (connect OR launch)
@@ -563,6 +689,25 @@ MIT License - see LICENSE file
 
 ## Changelog
 
+### v1.3.0 (2025-12-27) ⭐ NEW
+- ✅ **On-Demand Documentation**: New `browser_docs` tool provides detailed specs, return schemas, examples, and caveats for all 37 tools
+- ✅ **Modular Architecture**: Complete refactor into `src/` modules for better maintainability
+- ✅ **Plugin System**: New `plugins/` directory for extending functionality
+- ✅ **Improved Testing**: Dedicated `tests/` directory with fixtures
+- ✅ **Core Stability**: Separated browser logic, tools, and protocol handling
+- ✅ **Token Efficient**: Documentation loaded on-demand, keeping tool descriptions concise
+
+### v1.2.0 (2025-12-27)
+- ✅ **Media Awareness**: Added audio/video inspection, spectral analysis, and control tools (36 tools total)
+- ✅ **Tool**: `browser_get_media_summary`, `browser_get_audio_analysis`, `browser_control_media`
+
+### v1.1.0 (2025-12-27)
+- ✅ **Tool Parity**: Achieved parity with `browser-subagent` (33 tools total)
+- ✅ **Multi-Page**: Added support for multiple browser tabs/pages
+- ✅ **Low-Level Control**: Added keyboard/mouse event tools (pixel-based)
+- ✅ **Utilities**: Added `reload`, `go_back`, `go_forward`, `wait`, `hover`, `focus`, `select`
+- ✅ **Testing**: Updated test suites to include new tools
+
 ### v1.0.3 (2025-12-26)
 - ✅ **Documentation**: Updated README with v1.0.2 features and clearer installation instructions
 - ✅ **Code Comments**: Updated header to reflect universal compatibility and all features

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@ricardodeazambuja/browser-mcp-server",
-  "version": "1.0.3",
+  "version": "1.3.0",
   "description": "Universal browser automation MCP server using Playwright. Works with Antigravity, Claude Desktop, and any MCP client.",
-  "main": "browser-mcp-server-playwright.js",
+  "main": "src/index.js",
   "bin": {
-    "browser-mcp-server": "./browser-mcp-server-playwright.js"
+    "browser-mcp-server": "./src/index.js"
   },
   "scripts": {
-    "start": "node browser-mcp-server-playwright.js",
+    "start": "node src/index.js",
     "install-browsers": "npx playwright install chromium",
-    "test": "echo 'Testing MCP server...' && echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0.0\"}}}' | node browser-mcp-server-playwright.js"
+    "test": "node tests/test-mcp.js"
   },
   "keywords": [
     "mcp",
@@ -40,11 +40,11 @@
     "playwright": "^1.57.0"
   },
   "files": [
-    "browser-mcp-server-playwright.js",
+    "src/",
     "README.md",
     "LICENSE",
-    "CHANGELOG-v1.0.2.md",
-    "test-mcp.js",
-    "test-browser-automation.js"
+    "CHANGELOG-v1.3.0.md",
+    "tests/",
+    "plugins/"
   ]
-}
+}

package/src/browser.js

@@ -0,0 +1,150 @@
+/**
+ * Browser connection and state management
+ */
+
+const os = require('os');
+const { debugLog, loadPlaywright, findChromeExecutable } = require('./utils');
+
+// Browser state
+let browser = null;
+let context = null;
+let page = null;
+let activePageIndex = 0;
+
+/**
+ * Connect to existing Chrome or launch new instance (hybrid mode)
+ * @returns {Object} { browser, context, page }
+ */
+async function connectToBrowser() {
+    // Check if browser is disconnected or closed
+    if (browser && (!browser.isConnected || !browser.isConnected())) {
+        debugLog('Browser connection lost, resetting...');
+        browser = null;
+        context = null;
+        page = null;
+    }
+
+    if (!browser) {
+        try {
+            const pw = loadPlaywright();
+
+            // STRATEGY 1: Try to connect to existing Chrome (Antigravity mode)
+            try {
+                debugLog('Attempting to connect to Chrome on port 9222...');
+                browser = await pw.chromium.connectOverCDP('http://localhost:9222');
+                debugLog('✅ Connected to existing Chrome (Antigravity mode)');
+
+                const contexts = browser.contexts();
+                context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+            } catch (connectError) {
+                debugLog(`Could not connect to existing Chrome: ${connectError.message}`);
+            }
+
+            // STRATEGY 2: Launch our own Chrome (Standalone mode)
+            if (!browser) {
+                debugLog('No existing Chrome found. Launching new instance...');
+
+                const profileDir = process.env.MCP_BROWSER_PROFILE ||
+                    `${os.tmpdir()}/chrome-mcp-profile`;
+
+                debugLog(`Browser profile: ${profileDir}`);
+
+                const chromeExecutable = findChromeExecutable();
+                const launchOptions = {
+                    headless: false,
+                    args: [
+                        '--remote-debugging-port=9222',
+                        '--no-first-run',
+                        '--no-default-browser-check',
+                        '--disable-fre',
+                        '--disable-features=TranslateUI,OptGuideOnDeviceModel',
+                        '--disable-sync',
+                        '--disable-component-update',
+                        '--disable-background-networking',
+                        '--disable-breakpad',
+                        '--disable-background-timer-throttling',
+                        '--disable-backgrounding-occluded-windows',
+                        '--disable-renderer-backgrounding'
+                    ]
+                };
+
+                if (chromeExecutable) {
+                    debugLog(`Using system Chrome/Chromium: ${chromeExecutable}`);
+                    launchOptions.executablePath = chromeExecutable;
+                } else {
+                    debugLog('No system Chrome/Chromium found. Attempting to use Playwright Chromium...');
+                }
+
+                try {
+                    context = await pw.chromium.launchPersistentContext(profileDir, launchOptions);
+                    browser = context;
+                } catch (launchError) {
+                    if (!chromeExecutable && launchError.message.includes("Executable doesn't exist")) {
+                        debugLog('Playwright Chromium not installed and no system Chrome found');
+                        throw new Error(
+                            '❌ No Chrome/Chromium browser found!\n\n' +
+                            'This MCP server needs a Chrome or Chromium browser to work.\n\n' +
+                            'Option 1 - Install Chrome/Chromium on your system\n' +
+                            'Option 2 - Install Playwright\'s Chromium: npx playwright install chromium\n' +
+                            'Option 3 - Use with Antigravity: Open browser via Chrome logo\n'
+                        );
+                    }
+                    throw launchError;
+                }
+                debugLog('✅ Successfully launched new Chrome instance (Standalone mode)');
+            }
+
+        } catch (error) {
+            debugLog(`Failed to connect/launch Chrome: ${error.message}`);
+            throw error;
+        }
+    }
+
+    // Ensure we have a context and page
+    if (!context) {
+        const contexts = browser.contexts();
+        context = contexts.length > 0 ? contexts[0] : await browser.newContext();
+    }
+
+    const pages = context.pages();
+    if (pages.length === 0) {
+        page = await context.newPage();
+        activePageIndex = 0;
+    } else {
+        if (activePageIndex >= pages.length) activePageIndex = pages.length - 1;
+        page = pages[activePageIndex];
+    }
+
+    return { browser, context, page };
+}
+
+/**
+ * Get browser state
+ */
+function getBrowserState() {
+    return { browser, context, page, activePageIndex };
+}
+
+/**
+ * Set active page index
+ */
+function setActivePageIndex(index) {
+    activePageIndex = index;
+}
+
+/**
+ * Reset browser state
+ */
+function resetBrowserState() {
+    browser = null;
+    context = null;
+    page = null;
+    activePageIndex = 0;
+}
+
+module.exports = {
+    connectToBrowser,
+    getBrowserState,
+    setActivePageIndex,
+    resetBrowserState
+};