@ricardodeazambuja/browser-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ricardo de Azambuja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,544 @@
+# Browser MCP Server
+
+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.
+
+## Features
+
+- ✅ **Universal**: Works with Antigravity, Claude Desktop, and any MCP client
+- ✅ **Hybrid Mode**: Connects to existing Chrome OR launches its own
+- ✅ **Safe**: Isolated browser profile (won't touch your personal Chrome)
+- ✅ **16 Tools**: Navigate, click, type, screenshot, console logs, and more
+- ✅ **Console Capture**: Debug JavaScript errors in real-time
+- ✅ **Session Recording**: Playwright traces with screenshots, DOM, and network activity
+- ✅ **Portable**: One codebase works everywhere
+
+## Quick Reference
+
+| Installation Method | Best For | Setup Time |
+|-------------------|----------|------------|
+| **Clone Repository** | Development, contributing | 2 minutes |
+| **Direct Download** | Quick testing, minimal setup | 1 minute |
+| **NPM Package** (coming soon) | Production use, easy updates | 30 seconds |
+
+| MCP Client | Config File Location |
+|------------|---------------------|
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)<br>`%APPDATA%/Claude/claude_desktop_config.json` (Windows) |
+| **Antigravity** | `~/.gemini/antigravity/mcp_config.json` |
+| **Claude Code** | Use `claude mcp add` command |
+| **Gemini CLI** | Use `gemini mcp add` command |
+
+**Key Points:**
+- ✅ Requires Node.js >= 16.0.0
+- ✅ Must install Playwright separately
+- ✅ Uses absolute paths in config files
+- ✅ Isolated browser profile (won't touch personal Chrome)
+- ✅ Restart MCP client after config changes
+
+## Quick Start
+
+### Installation
+
+#### Method 1: Clone Repository (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/ricardodeazambuja/browser-mcp-server.git
+cd browser-mcp-server
+
+# Install Playwright (one-time setup)
+npm install playwright
+npx playwright install chromium
+```
+
+#### Method 2: Direct Download (Single File)
+
+```bash
+# Download the main file directly (no git required)
+curl -o browser-mcp-server-playwright.js \
+  https://raw.githubusercontent.com/ricardodeazambuja/browser-mcp-server/master/browser-mcp-server-playwright.js
+
+# Install Playwright
+npm install playwright
+npx playwright install chromium
+```
+
+#### Method 3: NPM Package (Coming Soon)
+
+Once published to npm:
+
+```bash
+# Install globally
+npm install -g @ricardodeazambuja/browser-mcp-server
+
+# Or use directly with npx (no installation needed)
+npx @ricardodeazambuja/browser-mcp-server
+```
+
+### Usage with Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+**Using local installation:**
+```json
+{
+  "mcpServers": {
+    "browser-tools": {
+      "command": "node",
+      "args": ["/absolute/path/to/browser-mcp-server-playwright.js"]
+    }
+  }
+}
+```
+
+**Using NPM (when published):**
+```json
+{
+  "mcpServers": {
+    "browser-tools": {
+      "command": "npx",
+      "args": ["-y", "@ricardodeazambuja/browser-mcp-server"]
+    }
+  }
+}
+```
+
+**Note:** Replace `/absolute/path/to/` with the actual path where you installed the file.
+
+### Usage with Antigravity
+
+Add to `~/.gemini/antigravity/mcp_config.json`:
+
+**Using local installation:**
+```json
+{
+  "mcpServers": {
+    "browser-tools": {
+      "command": "node",
+      "args": ["/home/username/.gemini/antigravity/browser-mcp-server-playwright.js"]
+    }
+  }
+}
+```
+
+**Using NPM (when published):**
+```json
+{
+  "mcpServers": {
+    "browser-tools": {
+      "command": "npx",
+      "args": ["-y", "@ricardodeazambuja/browser-mcp-server"]
+    }
+  }
+}
+```
+
+Then refresh MCP servers in Antigravity.
+
+### Usage with Claude Code
+
+Add the browser-mcp-server using the Claude CLI:
+
+**Using local installation:**
+```bash
+# Install the MCP server with default isolated profile
+claude mcp add --transport stdio browser \
+  -- node /absolute/path/to/browser-mcp-server-playwright.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
+```
+
+**Using NPM (when published):**
+```bash
+# Install using npx (no local installation needed)
+claude mcp add --transport stdio browser \
+  -- npx -y @ricardodeazambuja/browser-mcp-server
+
+# With custom browser profile
+claude mcp add --transport stdio browser \
+  --env MCP_BROWSER_PROFILE=/path/to/custom/profile \
+  -- npx -y @ricardodeazambuja/browser-mcp-server
+```
+
+**Verify installation:**
+```bash
+# List all MCP servers
+claude mcp list
+
+# Check server status
+claude mcp get browser
+```
+
+**Example usage in Claude Code:**
+
+```bash
+# Natural language commands
+> Navigate to https://example.com and take a screenshot
+> Click the login button and fill in the username field
+> What's the text in the .main-content selector?
+
+# Direct tool invocation via slash commands
+> /mcp__browser__browser_navigate https://example.com
+> /mcp__browser__browser_screenshot
+```
+
+**Note:** The server uses an isolated browser profile at `/tmp/chrome-mcp-profile` by default, ensuring it won't access your personal Chrome cookies or data.
+
+### Usage with Gemini CLI
+
+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
+
+# 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
+```
+
+**Using NPM (when published):**
+```bash
+# Install using npx (no local installation needed)
+gemini mcp add browser npx -y @ricardodeazambuja/browser-mcp-server
+
+# With custom browser profile
+gemini mcp add -e MCP_BROWSER_PROFILE=/path/to/custom/profile browser \
+  npx -y @ricardodeazambuja/browser-mcp-server
+```
+
+**Management commands:**
+```bash
+# List all configured MCP servers
+gemini mcp list
+
+# Remove the server if needed
+gemini mcp remove browser
+```
+
+**Example usage in Gemini CLI:**
+
+```bash
+# Natural language commands
+> Navigate to https://github.com and take a screenshot
+> Click the search button and type "MCP servers"
+> Get the text from the .repository-content selector
+
+# The CLI will use the browser automation tools automatically
+```
+
+**Advanced options:**
+
+```bash
+# Add with specific scope (user vs project)
+gemini mcp add -s user browser node /path/to/browser-mcp-server-playwright.js
+
+# Add with timeout configuration
+gemini mcp add --timeout 30000 browser node /path/to/browser-mcp-server-playwright.js
+
+# Skip tool confirmation prompts (use with caution)
+gemini mcp add --trust browser node /path/to/browser-mcp-server-playwright.js
+```
+
+## Available Tools (16)
+
+### 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
+
+### 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
+
+## Examples
+
+### Navigate and Screenshot
+```javascript
+// Agent uses:
+browser_navigate("https://example.com")
+browser_screenshot(fullPage: true)
+```
+
+### Debug JavaScript Errors
+```javascript
+// Agent uses:
+browser_console_start()
+browser_navigate("https://myapp.com")
+browser_click("#submit-button")
+browser_console_get(filter: "error")
+// Shows: ❌ [ERROR] Uncaught TypeError: ...
+```
+
+### Automate Form Submission
+```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")
+```
+
+## How It Works
+
+### Hybrid Mode (Automatic)
+
+The server automatically detects your environment:
+
+**Antigravity Mode:**
+- Detects Chrome on port 9222
+- Connects to existing browser
+- Uses Antigravity's browser profile
+- No new browser window
+
+**Standalone Mode:**
+- No Chrome detected on port 9222
+- Launches new Chrome instance
+- Uses isolated profile (`/tmp/chrome-mcp-profile`)
+- New browser window appears
+
+### Safety Features
+
+- **Isolated Profile**: Uses `/tmp/chrome-mcp-profile` (not your personal Chrome!)
+- **No Setup Dialogs**: Silent startup with `--no-first-run` flags
+- **Clean Environment**: No extensions, sync, or background updates
+- **Reproducible**: Same behavior across systems
+
+## Security
+
+This MCP server provides powerful browser automation capabilities. Please review these security considerations:
+
+### Isolated Browser Profile
+- Uses `/tmp/chrome-mcp-profile` by default (configurable via `MCP_BROWSER_PROFILE`)
+- **Does NOT access your personal Chrome data** (cookies, passwords, history)
+- Each instance runs in a clean, isolated environment
+
+### Tool Safety
+
+**browser_evaluate**: Executes arbitrary JavaScript in the browser context
+- Code runs in browser sandbox (no access to your host system)
+- Only executes when explicitly called by MCP client
+- Requires user approval in most MCP clients
+- **Recommendation**: Only use with trusted MCP clients and review code when possible
+
+**browser_navigate**: Navigates to any URL
+- Can visit any website the browser can access
+- Uses isolated profile to prevent cookie/session theft
+- **Recommendation**: Be cautious with URLs from untrusted sources
+
+### Debug Logs
+- Server logs to `/tmp/mcp-browser-server.log`
+- Logs may contain visited URLs and error messages
+- Log file is cleared on system reboot (stored in `/tmp`)
+- **Does NOT log** page content or sensitive data
+
+### Best Practices
+- ✅ Only use with trusted MCP clients (Claude Desktop, Antigravity, etc.)
+- ✅ Review automation scripts before execution when possible
+- ✅ Use the default isolated profile (don't point to your personal Chrome)
+- ✅ Report security issues via [GitHub Issues](https://github.com/ricardodeazambuja/browser-mcp-server/issues)
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Custom browser profile location (optional)
+export MCP_BROWSER_PROFILE="$HOME/.mcp-browser-profile"
+
+# Then run the server
+node browser-mcp-server-playwright.js
+```
+
+### MCP Config with Environment Variables
+
+```json
+{
+  "mcpServers": {
+    "browser-tools": {
+      "command": "node",
+      "args": ["/path/to/browser-mcp-server-playwright.js"],
+      "env": {
+        "MCP_BROWSER_PROFILE": "/tmp/my-custom-profile"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### "Playwright is not installed"
+
+```bash
+npm install playwright
+npx playwright install chromium
+```
+
+### "Cannot connect to Chrome"
+
+**For Antigravity:**
+- Click the Chrome logo (top right) to launch browser
+
+**For Standalone:**
+- The server will auto-launch Chrome
+- Ensure Playwright is installed (see above)
+
+### Check Server Status
+
+Use the `browser_health_check` tool to verify:
+- Connection mode (Antigravity vs Standalone)
+- Playwright source
+- Browser profile location
+- Current page URL
+
+## Development
+
+### Project Structure
+
+```
+browser-mcp-server/
+├── browser-mcp-server-playwright.js  # Main server
+├── package.json                      # npm package config
+├── README.md                         # This file
+└── LICENSE                           # MIT license
+```
+
+### Testing
+
+```bash
+# Test server initialization
+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
+```
+
+### Debug Logging
+
+Check `/tmp/mcp-browser-server.log` for detailed logs:
+- Playwright loading attempts
+- Browser connection/launch status
+- Console capture events
+- Tool execution
+
+## Technical Details
+
+### MCP Protocol
+- Implements MCP 2024-11-05 protocol
+- JSON-RPC 2.0 over stdio
+- Supports `initialize`, `notifications/initialized`, `tools/list`, `tools/call`
+
+### Browser Control
+- Uses Playwright for automation
+- Connects via Chrome DevTools Protocol (CDP)
+- Port 9222 for remote debugging
+
+### Chrome Launch Flags
+```bash
+--remote-debugging-port=9222          # Enable CDP
+--user-data-dir=/tmp/chrome-mcp-profile  # Isolated profile
+--no-first-run                        # Skip setup
+--no-default-browser-check            # No popups
+--disable-fre                         # No first-run experience
+--disable-sync                        # No Google sync
+--disable-component-update            # No auto-updates
+# + more stability flags
+```
+
+## Compatibility
+
+### Tested With
+- ✅ Antigravity
+- ✅ Claude Desktop (macOS, Windows, Linux)
+- ✅ Other MCP clients via stdio
+
+### Requirements
+- Node.js >= 16.0.0
+- Playwright (peer dependency)
+- Chrome/Chromium browser
+
+### Platforms
+- ✅ Linux
+- ✅ macOS
+- ✅ Windows
+
+## Comparison with Other Tools
+
+### vs. Puppeteer MCP Servers
+- ✅ More tools (16 vs typical 8-10)
+- ✅ Console capture built-in
+- ✅ Better error messages
+- ✅ Hybrid mode (connect OR launch)
+
+### vs. Selenium Grid
+- ✅ Simpler setup (no grid needed)
+- ✅ MCP protocol integration
+- ✅ Built for AI agents
+- ✅ Lightweight (single process)
+
+### vs. Browser Extensions
+- ✅ Works headlessly if needed
+- ✅ No extension installation
+- ✅ Programmable via MCP
+- ✅ Works with any MCP client
+
+## Contributing
+
+Contributions welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file
+
+## Credits
+
+- Built with [Playwright](https://playwright.dev/)
+- Implements [Model Context Protocol](https://modelcontextprotocol.io/)
+- Originally developed for [Antigravity](https://antigravity.google/)
+
+## Support
+
+- 🐛 [Report Issues](https://github.com/ricardodeazambuja/browser-mcp-server/issues)
+- 💬 [Discussions](https://github.com/ricardodeazambuja/browser-mcp-server/discussions)
+- 📧 Contact: Via GitHub Issues
+
+## Changelog
+
+### v1.0.0 (2025-12-26)
+- ✅ Initial release
+- ✅ 16 browser automation tools
+- ✅ Console capture (start/get/clear)
+- ✅ Hybrid mode (connect OR launch)
+- ✅ Safe Chrome launch with isolated profile
+- ✅ Multi-source Playwright loading
+- ✅ Universal compatibility (Antigravity + Claude Desktop + more)
+
+---
+
+**Made with ❤️ for the MCP community**

package/browser-mcp-server-playwright.js

@@ -0,0 +1,684 @@
+#!/usr/bin/env node
+
+/**
+ * Browser Automation MCP Server for Antigravity (Playwright Edition)
+ *
+ * This MCP server provides 13 browser automation tools by connecting to
+ * Antigravity's Chrome instance that runs with remote debugging on port 9222.
+ *
+ * Antigravity launches Chrome with:
+ *   --remote-debugging-port=9222
+ *   --user-data-dir=~/.gemini/antigravity-browser-profile
+ *
+ * This server uses the same Playwright installation as browser_subagent,
+ * allowing seamless integration with Antigravity's browser ecosystem.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const logFile = `${os.tmpdir()}/mcp-browser-server.log`;
+
+// Helper to log debug info
+function debugLog(msg) {
+  const timestamp = new Date().toISOString();
+  fs.appendFileSync(logFile, `${timestamp} - ${msg}\n`);
+}
+
+debugLog('Server starting...');
+debugLog(`HOME: ${process.env.HOME}`);
+debugLog(`CWD: ${process.cwd()}`);
+
+let playwright = null;
+let playwrightError = null;
+let playwrightPath = null;
+
+// Try to load Playwright from multiple sources
+function loadPlaywright() {
+  if (playwright) return playwright;
+  if (playwrightError) throw playwrightError;
+
+  const sources = [
+    // 1. Antigravity's Go-based Playwright
+    { path: `${process.env.HOME}/.cache/ms-playwright-go/1.50.1/package`, name: 'Antigravity Go Playwright' },
+    // 2. Standard npm Playwright (local)
+    { path: 'playwright', name: 'npm Playwright (local)' },
+    // 3. Global npm Playwright
+    { path: `${process.env.HOME}/.npm-global/lib/node_modules/playwright`, name: 'npm Playwright (global)' }
+  ];
+
+  for (const source of sources) {
+    try {
+      debugLog(`Trying to load Playwright from: ${source.path}`);
+      playwright = require(source.path);
+      playwrightPath = source.path;
+      debugLog(`✅ Playwright loaded successfully: ${source.name}`);
+      return playwright;
+    } catch (error) {
+      debugLog(`❌ Could not load from ${source.path}: ${error.message}`);
+    }
+  }
+
+  // None worked
+  playwrightError = new Error(
+    '❌ Playwright is not installed.\n\n' +
+    'To install Playwright:\n' +
+    '1. In Antigravity: Click the Chrome logo (top right) to "Open Browser" - this installs Playwright automatically\n' +
+    '2. Standalone mode: Run:\n' +
+    '   npm install playwright\n' +
+    '   npx playwright install chromium\n\n' +
+    `Tried locations:\n${sources.map(s => `  - ${s.path}`).join('\n')}`
+  );
+  throw playwrightError;
+}
+
+const readline = require('readline');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false
+});
+
+let browser = null;
+let context = null;
+let page = null;
+
+// Console log capture
+let consoleLogs = [];
+let consoleListening = false;
+
+// Connect to existing Chrome OR launch new instance (hybrid mode)
+async function connectToBrowser() {
+  if (!browser) {
+    try {
+      // Load Playwright (will throw if not installed)
+      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();
+        const pages = context.pages();
+        page = pages.length > 0 ? pages[0] : await context.newPage();
+
+        debugLog('Successfully connected to Chrome');
+        return { browser, context, page };
+      } catch (connectError) {
+        debugLog(`Could not connect to existing Chrome: ${connectError.message}`);
+      }
+
+      // STRATEGY 2: Launch our own Chrome (Standalone mode)
+      debugLog('No existing Chrome found. Launching new instance...');
+
+      const profileDir = process.env.MCP_BROWSER_PROFILE ||
+                        `${os.tmpdir()}/chrome-mcp-profile`;
+
+      debugLog(`Browser profile: ${profileDir}`);
+
+      browser = await pw.chromium.launch({
+        headless: false,
+        args: [
+          // CRITICAL: Remote debugging
+          '--remote-debugging-port=9222',
+
+          // CRITICAL: Isolated profile (don't touch user's personal Chrome!)
+          `--user-data-dir=${profileDir}`,
+
+          // IMPORTANT: Skip first-run experience
+          '--no-first-run',
+          '--no-default-browser-check',
+          '--disable-fre',
+
+          // STABILITY: Reduce popups and background activity
+          '--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'
+        ]
+      });
+
+      context = await browser.newContext();
+      page = await context.newPage();
+
+      debugLog('✅ Successfully launched new Chrome instance (Standalone mode)');
+
+    } catch (error) {
+      debugLog(`Failed to connect/launch Chrome: ${error.message}`);
+      const errorMsg =
+        '❌ Cannot start browser.\n\n' +
+        'To fix this:\n' +
+        '1. In Antigravity: Click the Chrome logo (top right) to "Open Browser"\n' +
+        '2. Standalone mode: Ensure Playwright is installed:\n' +
+        '   npm install playwright\n' +
+        '   npx playwright install chromium\n\n' +
+        `Error: ${error.message}`;
+      throw new Error(errorMsg);
+    }
+  }
+  return { browser, context, page };
+}
+
+// MCP Tool definitions
+const tools = [
+  {
+    name: 'browser_navigate',
+    description: 'Navigate to a URL in the browser',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: { type: 'string', description: 'The URL to navigate to' }
+      },
+      required: ['url'],
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_click',
+    description: 'Click an element on the page using Playwright selector',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: { type: 'string', description: 'Playwright selector for the element' }
+      },
+      required: ['selector'],
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_screenshot',
+    description: 'Take a screenshot of the current page',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fullPage: { type: 'boolean', description: 'Capture full page', default: false }
+      },
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_get_text',
+    description: 'Get text content from an element',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: { type: 'string', description: 'Playwright selector for the element' }
+      },
+      required: ['selector'],
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_type',
+    description: 'Type text into an input field',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: { type: 'string', description: 'Playwright selector for the input' },
+        text: { type: 'string', description: 'Text to type' }
+      },
+      required: ['selector', 'text'],
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_evaluate',
+    description: 'Execute JavaScript in the browser context',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', description: 'JavaScript code to execute' }
+      },
+      required: ['code'],
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_wait_for_selector',
+    description: 'Wait for an element to appear on the page',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: { type: 'string', description: 'Playwright selector to wait for' },
+        timeout: { type: 'number', description: 'Timeout in milliseconds', default: 30000 }
+      },
+      required: ['selector'],
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_scroll',
+    description: 'Scroll the page',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        x: { type: 'number', description: 'Horizontal scroll position' },
+        y: { type: 'number', description: 'Vertical scroll position' }
+      },
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_resize_window',
+    description: 'Resize the browser window (useful for testing responsiveness)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        width: { type: 'number', description: 'Window width in pixels' },
+        height: { type: 'number', description: 'Window height in pixels' }
+      },
+      required: ['width', 'height'],
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_get_dom',
+    description: 'Get the full DOM structure or specific element data',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: { type: 'string', description: 'Optional selector to get DOM of specific element' }
+      },
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_start_video_recording',
+    description: 'Start recording browser session as video',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Path to save the video file' }
+      },
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_stop_video_recording',
+    description: 'Stop video recording and save the file',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_health_check',
+    description: 'Check if the browser is running and accessible on port 9222',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_console_start',
+    description: 'Start capturing browser console logs (console.log, console.error, console.warn, etc.)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        level: {
+          type: 'string',
+          description: 'Optional filter for log level: "log", "error", "warn", "info", "debug", or "all"',
+          enum: ['log', 'error', 'warn', 'info', 'debug', 'all']
+        }
+      },
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_console_get',
+    description: 'Get all captured console logs since browser_console_start was called',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        filter: {
+          type: 'string',
+          description: 'Optional filter by log level: "log", "error", "warn", "info", "debug", or "all"',
+          enum: ['log', 'error', 'warn', 'info', 'debug', 'all']
+        }
+      },
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  },
+  {
+    name: 'browser_console_clear',
+    description: 'Clear all captured console logs and stop listening',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+      $schema: 'http://json-schema.org/draft-07/schema#'
+    }
+  }
+];
+
+// Tool execution handlers
+async function executeTool(name, args) {
+  try {
+    const { page } = await connectToBrowser();
+
+    switch (name) {
+      case 'browser_navigate':
+        await page.goto(args.url, { waitUntil: 'domcontentloaded' });
+        return { content: [{ type: 'text', text: `Navigated to ${args.url}` }] };
+
+      case 'browser_click':
+        await page.click(args.selector);
+        return { content: [{ type: 'text', text: `Clicked ${args.selector}` }] };
+
+      case 'browser_screenshot':
+        const screenshot = await page.screenshot({
+          fullPage: args.fullPage || false,
+          type: 'png'
+        });
+        return {
+          content: [{
+            type: 'image',
+            data: screenshot.toString('base64'),
+            mimeType: 'image/png'
+          }]
+        };
+
+      case 'browser_get_text':
+        const text = await page.textContent(args.selector);
+        return { content: [{ type: 'text', text }] };
+
+      case 'browser_type':
+        await page.fill(args.selector, args.text);
+        return { content: [{ type: 'text', text: `Typed into ${args.selector}` }] };
+
+      case 'browser_evaluate':
+        const result = await page.evaluate(args.code);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(result, null, 2)
+          }]
+        };
+
+      case 'browser_wait_for_selector':
+        await page.waitForSelector(args.selector, {
+          timeout: args.timeout || 30000
+        });
+        return {
+          content: [{
+            type: 'text',
+            text: `Element ${args.selector} appeared`
+          }]
+        };
+
+      case 'browser_scroll':
+        await page.evaluate(({ x, y }) => {
+          window.scrollTo(x || 0, y || 0);
+        }, args);
+        return {
+          content: [{
+            type: 'text',
+            text: `Scrolled to (${args.x || 0}, ${args.y || 0})`
+          }]
+        };
+
+      case 'browser_resize_window':
+        await page.setViewportSize({
+          width: args.width,
+          height: args.height
+        });
+        return {
+          content: [{
+            type: 'text',
+            text: `Resized window to ${args.width}x${args.height}`
+          }]
+        };
+
+      case 'browser_get_dom':
+        const domContent = await page.evaluate((sel) => {
+          const element = sel ? document.querySelector(sel) : document.documentElement;
+          if (!element) return null;
+          return {
+            outerHTML: element.outerHTML,
+            textContent: element.textContent,
+            attributes: Array.from(element.attributes || []).map(attr => ({
+              name: attr.name,
+              value: attr.value
+            })),
+            children: element.children.length
+          };
+        }, args.selector);
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify(domContent, null, 2)
+          }]
+        };
+
+      case 'browser_start_video_recording':
+        const videoPath = args.path || `${os.tmpdir()}/browser-recording-${Date.now()}.webm`;
+        await context.tracing.start({
+          screenshots: true,
+          snapshots: true
+        });
+        // Start video recording using Playwright's video feature
+        if (!context._options.recordVideo) {
+          // Note: Video recording needs to be set when creating context
+          // For existing context, we'll use screenshots as fallback
+          return {
+            content: [{
+              type: 'text',
+              text: 'Started session tracing (screenshots). For full video, context needs recordVideo option at creation.'
+            }]
+          };
+        }
+        return {
+          content: [{
+            type: 'text',
+            text: `Started video recording to ${videoPath}`
+          }]
+        };
+
+      case 'browser_stop_video_recording':
+        const tracePath = `${os.tmpdir()}/trace-${Date.now()}.zip`;
+        await context.tracing.stop({ path: tracePath });
+        return {
+          content: [{
+            type: 'text',
+            text: `Stopped recording. Trace saved to ${tracePath}. Use 'playwright show-trace ${tracePath}' to view.`
+          }]
+        };
+
+      case 'browser_health_check':
+        // Connection already succeeded if we got here
+        const url = await page.url();
+
+        // Detect mode: connected to existing Chrome or launched our own
+        const isConnected = browser.isConnected && browser.isConnected();
+        const mode = isConnected ? 'Connected to existing Chrome (Antigravity)' : 'Launched standalone Chrome';
+
+        // Determine profile path based on mode
+        let browserProfile;
+        if (isConnected) {
+          browserProfile = `${process.env.HOME}/.gemini/antigravity-browser-profile`;
+        } else {
+          browserProfile = process.env.MCP_BROWSER_PROFILE || `${os.tmpdir()}/chrome-mcp-profile`;
+        }
+
+        return {
+          content: [{
+            type: 'text',
+            text: `✅ Browser automation is fully functional!\n\n` +
+                  `Mode: ${mode}\n` +
+                  `✅ Playwright: ${playwrightPath || 'loaded'}\n` +
+                  `✅ Chrome: Port 9222\n` +
+                  `✅ Profile: ${browserProfile}\n` +
+                  `✅ Current page: ${url}\n\n` +
+                  `All 16 browser tools are ready to use!`
+          }]
+        };
+
+      case 'browser_console_start':
+        if (!consoleListening) {
+          page.on('console', msg => {
+            const logEntry = {
+              type: msg.type(),
+              text: msg.text(),
+              timestamp: new Date().toISOString(),
+              location: msg.location()
+            };
+            consoleLogs.push(logEntry);
+            debugLog(`Console [${logEntry.type}]: ${logEntry.text}`);
+          });
+          consoleListening = true;
+          debugLog('Console logging started');
+        }
+        return {
+          content: [{
+            type: 'text',
+            text: `✅ Console logging started.\n\nCapturing: console.log, console.error, console.warn, console.info, console.debug\n\nUse browser_console_get to retrieve captured logs.`
+          }]
+        };
+
+      case 'browser_console_get':
+        const filter = args.filter;
+        const filtered = filter && filter !== 'all'
+          ? consoleLogs.filter(log => log.type === filter)
+          : consoleLogs;
+
+        if (filtered.length === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: consoleListening
+                ? `No console logs captured yet.\n\n${filter && filter !== 'all' ? `Filter: ${filter}\n` : ''}Console logging is active - logs will appear as the page executes JavaScript.`
+                : `Console logging is not active.\n\nUse browser_console_start to begin capturing logs.`
+            }]
+          };
+        }
+
+        const logSummary = `📋 Captured ${filtered.length} console log${filtered.length === 1 ? '' : 's'}${filter && filter !== 'all' ? ` (filtered by: ${filter})` : ''}:\n\n`;
+        const formattedLogs = filtered.map((log, i) => {
+          const icon = {
+            'error': '❌',
+            'warn': '⚠️',
+            'log': '📝',
+            'info': 'ℹ️',
+            'debug': '🔍'
+          }[log.type] || '📄';
+
+          return `${i + 1}. ${icon} [${log.type.toUpperCase()}] ${log.timestamp}\n   ${log.text}${log.location.url ? `\n   Location: ${log.location.url}:${log.location.lineNumber}` : ''}`;
+        }).join('\n\n');
+
+        return {
+          content: [{
+            type: 'text',
+            text: logSummary + formattedLogs
+          }]
+        };
+
+      case 'browser_console_clear':
+        const count = consoleLogs.length;
+        consoleLogs = [];
+        if (consoleListening) {
+          page.removeAllListeners('console');
+          consoleListening = false;
+        }
+        debugLog(`Cleared ${count} console logs and stopped listening`);
+        return {
+          content: [{
+            type: 'text',
+            text: `✅ Cleared ${count} console log${count === 1 ? '' : 's'} and stopped listening.\n\nUse browser_console_start to resume capturing.`
+          }]
+        };
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    debugLog(`Tool execution error (${name}): ${error.message}`);
+    return {
+      content: [{
+        type: 'text',
+        text: `❌ Error executing ${name}: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+}
+
+// MCP Protocol handler
+rl.on('line', async (line) => {
+  let request;
+  try {
+    debugLog(`Received: ${line.substring(0, 200)}`);
+    request = JSON.parse(line);
+
+    if (request.method === 'initialize') {
+      debugLog(`Initialize with protocol: ${request.params.protocolVersion}`);
+      respond(request.id, {
+        protocolVersion: request.params.protocolVersion || '2024-11-05',
+        capabilities: { tools: {} },
+        serverInfo: {
+          name: 'browser-automation-playwright',
+          version: '1.0.0'
+        }
+      });
+    } else if (request.method === 'notifications/initialized') {
+      // This is a notification - no response needed
+      debugLog('Received initialized notification');
+    } else if (request.method === 'tools/list') {
+      debugLog('Sending tools list');
+      respond(request.id, { tools });
+    } else if (request.method === 'tools/call') {
+      debugLog(`Calling tool: ${request.params.name}`);
+      const result = await executeTool(request.params.name, request.params.arguments || {});
+      respond(request.id, result);
+    } else {
+      debugLog(`Unknown method: ${request.method}`);
+      respond(request.id, null, { code: -32601, message: 'Method not found' });
+    }
+  } catch (error) {
+    debugLog(`Error processing request: ${error.message}`);
+    console.error('Error processing request:', error.message, 'Request:', line);
+    const id = request?.id || null;
+    respond(id, null, { code: -32603, message: error.message });
+  }
+});
+
+function respond(id, result, error = null) {
+  const response = { jsonrpc: '2.0', id };
+  if (error) response.error = error;
+  else response.result = result;
+  console.log(JSON.stringify(response));
+}
+
+// Cleanup on exit
+process.on('SIGTERM', async () => {
+  if (browser) await browser.close();
+  process.exit(0);
+});
+
+process.on('SIGINT', async () => {
+  if (browser) await browser.close();
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ricardodeazambuja/browser-mcp-server",
+  "version": "1.0.0",
+  "description": "Universal browser automation MCP server using Playwright. Works with Antigravity, Claude Desktop, and any MCP client.",
+  "main": "browser-mcp-server-playwright.js",
+  "bin": {
+    "browser-mcp-server": "./browser-mcp-server-playwright.js"
+  },
+  "scripts": {
+    "start": "node browser-mcp-server-playwright.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"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "browser-automation",
+    "playwright",
+    "claude",
+    "antigravity",
+    "web-automation",
+    "testing",
+    "scraping"
+  ],
+  "author": "Ricardo de Azambuja (https://ricardodeazambuja.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ricardodeazambuja/browser-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ricardodeazambuja/browser-mcp-server/issues"
+  },
+  "homepage": "https://github.com/ricardodeazambuja/browser-mcp-server#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {
+    "playwright": "^1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    }
+  },
+  "files": [
+    "browser-mcp-server-playwright.js",
+    "README.md",
+    "LICENSE"
+  ]
+}