@ricardodeazambuja/browser-mcp-server 1.0.3 → 1.4.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/CHANGELOG-v1.4.0.md

@@ -0,0 +1,8 @@
+# Changelog - v1.4.0 (2026-01-01)
+
+- ✅ **Full Power User Suite**: Added 26 CDP-based tools for performance, network, security, and storage analysis (63 tools total)
+- ✅ **Version Unification**: Centralized version management to use `package.json` as the single source of truth
+- ✅ **Performance Profiling**: Added CPU profiling, heap snapshots, and web vitals monitoring
+- ✅ **Network Analysis**: Added request monitoring, HAR export, and WebSocket inspection
+- ✅ **Security Testing**: Added security header inspection, CSP monitoring, and certificate details
+- ✅ **Storage Inspection**: Added IndexedDB, Cache Storage, and Service Worker management

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.
+**63 powerful browser automation tools** including multi-tab management, media monitoring/control, low-level interaction, session recording, CDP-based performance profiling, network analysis, security testing, 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
+- ✅ **63 Tools**: Media control, multi-tab, pixel-based interaction, CDP power user tools, 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,197 @@ 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 (63)
+
+### 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
+
+## 🔬 Power User Tools (CDP-Based)
+
+Advanced diagnostic tools using Chrome DevTools Protocol for performance analysis, network debugging, security testing, and storage inspection. These 26 additional tools provide deep insights into browser internals.
+
+### Performance Profiling (8 tools)
+38. **browser_perf_start_profile(sampleInterval?)** - Start CPU profiling
+39. **browser_perf_stop_profile()** - Get CPU profile data with summary
+40. **browser_perf_take_heap_snapshot(reportProgress?)** - Capture memory snapshot
+41. **browser_perf_get_heap_usage()** - Current JavaScript heap statistics
+42. **browser_perf_get_metrics()** - Runtime metrics (DOM nodes, listeners, etc.)
+43. **browser_perf_get_performance_metrics()** - Web vitals (FCP, LCP, CLS, TTFB)
+44. **browser_perf_start_coverage(resetOnNavigation?)** - Track code coverage
+45. **browser_perf_stop_coverage()** - Get coverage results
+
+**Use Cases**: Memory leak detection, CPU profiling, performance optimization, code coverage analysis, web vitals monitoring
+
+### Network Analysis (7 tools)
+46. **browser_net_start_monitoring(patterns?)** - Monitor network requests
+47. **browser_net_get_requests(filter?)** - Get captured requests with timing
+48. **browser_net_stop_monitoring()** - Stop monitoring and clear log
+49. **browser_net_export_har(includeContent?)** - Export HTTP Archive log
+50. **browser_net_get_websocket_frames(requestId)** - Inspect WebSocket frames
+51. **browser_net_set_request_blocking(patterns)** - Block URL patterns
+52. **browser_net_emulate_conditions(offline, latency, download, upload)** - Network throttling
+
+**Use Cases**: API debugging, HAR export, WebSocket debugging, performance testing, request blocking, network throttling
+
+### Security Testing (6 tools)
+53. **browser_sec_get_security_headers()** - Inspect security HTTP headers
+54. **browser_sec_get_certificate_info()** - TLS/SSL certificate details
+55. **browser_sec_detect_mixed_content()** - Find HTTP resources on HTTPS pages
+56. **browser_sec_start_csp_monitoring()** - Monitor CSP violations
+57. **browser_sec_get_csp_violations()** - Get violation log
+58. **browser_sec_stop_csp_monitoring()** - Stop monitoring
+
+**Use Cases**: Security audits, CSP debugging, HTTPS migration, certificate validation, mixed content detection
+
+### Storage & Service Workers (5 tools)
+59. **browser_storage_get_indexeddb(databaseName?, objectStoreName?)** - Inspect IndexedDB
+60. **browser_storage_get_cache_storage(cacheName?)** - List Cache Storage entries
+61. **browser_storage_delete_cache(cacheName)** - Delete cache
+62. **browser_storage_get_service_workers()** - Service worker state
+63. **browser_storage_unregister_service_worker(scopeURL)** - Unregister worker
+
+**Use Cases**: IndexedDB inspection, Cache Storage management, Service Worker debugging, offline functionality testing
+
+### Getting Started with CDP Tools
+
+```javascript
+// Start CPU profiling
+browser_perf_start_profile({})
+// ... perform actions to profile ...
+browser_perf_stop_profile({})  // Get results
+
+// Monitor network activity
+browser_net_start_monitoring({})
+// ... navigate and interact ...
+browser_net_get_requests({ filter: 'api' })
+browser_net_export_har({})
+
+// Security audit
+browser_sec_get_security_headers({})
+browser_sec_start_csp_monitoring({})
+// ... trigger violations ...
+browser_sec_get_csp_violations({})
+
+// Inspect storage
+browser_storage_get_indexeddb({ databaseName: 'myDB' })
+browser_storage_get_cache_storage({ cacheName: 'my-cache-v1' })
+```
+
+**Note**: All CDP tools have comprehensive documentation available via `browser_docs({ toolName: 'browser_perf_start_profile' })`.
+
+## 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 +455,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://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_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_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 63 tools
 ```
 
 ## How It Works
@@ -381,7 +573,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 +583,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 +644,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 +664,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 +719,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 (63 vs typical 8-10)
 - ✅ Console capture built-in
 - ✅ Better error messages
 - ✅ Hybrid mode (connect OR launch)
@@ -563,6 +762,33 @@ MIT License - see LICENSE file
 
 ## Changelog
 
+### v1.4.0 (2026-01-01) ⭐ NEW
+- ✅ **Full Power User Suite**: Added 26 CDP-based tools for performance, network, security, and storage analysis (63 tools total)
+- ✅ **Version Unification**: Centralized version management to use `package.json` as the single source of truth
+- ✅ **Performance Profiling**: Added CPU profiling, heap snapshots, and web vitals monitoring
+- ✅ **Network Analysis**: Added request monitoring, HAR export, and WebSocket inspection
+- ✅ **Security Testing**: Added security header inspection, CSP monitoring, and certificate details
+- ✅ **Storage Inspection**: Added IndexedDB, Cache Storage, and Service Worker management
+
+### v1.3.0 (2025-12-27)
+- ✅ **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.4.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/run-all.js"
   },
   "keywords": [
     "mcp",
@@ -40,11 +40,12 @@
     "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",
+    "CHANGELOG-v1.4.0.md",
+    "tests/",
+    "plugins/"
   ]
-}
+}