agent-browser-bridge 0.0.0-stage → 2.2.0

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# agent-browser-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Live multi-tab, multi-profile Chrome DevTools Protocol (CDP) Model Context Protocol (MCP) server for AI coding agents.**
+
+Works with **Antigravity**, **Claude Desktop / Claude Code**, **Cursor**, **Windsurf**, and any MCP client.
+
+Unlike standard `chrome-devtools-mcp` (which requires launching a fresh, isolated Chrome instance without your logins or extensions), **`agent-browser-bridge` connects directly to your everyday browser profile** (Chrome, Edge, Brave) with all your active sessions, cookies, open tabs, and logged-in web apps intact.
+
+---
+
+## 🚀 Quick Start (Zero Install)
+
+Add `agent-browser-bridge` to your agent's MCP configuration:
+
+### 1. Google Antigravity
+In your workspace `.agents/mcp_config.json` or global config:
+```json
+{
+  "mcpServers": {
+    "agent-browser-bridge": {
+      "command": "npx",
+      "args": ["-y", "agent-browser-bridge"]
+    }
+  }
+}
+```
+
+### 2. Claude Desktop
+In `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+```json
+{
+  "mcpServers": {
+    "agent-browser-bridge": {
+      "command": "npx",
+      "args": ["-y", "agent-browser-bridge"]
+    }
+  }
+}
+```
+
+### 3. Cursor & Windsurf
+Add a new MCP server in settings:
+- **Type**: `command`
+- **Command**: `npx -y agent-browser-bridge`
+
+---
+
+## 🧩 Browser Extension Setup
+
+1. Install the companion extension from the Chrome Web Store (or load unpacked from source).
+2. Open the extension popup in your browser — ensure it shows **"Connected"** (port `18922`).
+3. Your AI agent now has full, real-time control over the browser profile!
+
+---
+
+## 🛠️ Complete Tool Catalog (68 Tools)
+
+### Multi-Profile & Tab Management
+- `browser_list_profiles`: List all connected browser profiles (Work, Personal, Brave, Edge).
+- `browser_list_tabs`: List open tabs across all browser windows.
+- `browser_switch_tab`: Focus a tab and bring its browser window to the foreground.
+- `browser_new_tab`: Open a new tab with an optional URL.
+- `browser_close_tab`: Close a tab by tabId.
+- `browser_duplicate_tab`: Duplicate an existing tab with its state and history.
+- `browser_pin_tab`: Pin or unpin a tab in the browser tab strip.
+- `browser_set_zoom`: Get or set zoom factor (1.0, 1.25, 0.8).
+- `browser_navigate`: Navigate an existing tab or open a new URL.
+- `browser_go_back`: Navigate back in history.
+- `browser_go_forward`: Navigate forward in history.
+- `browser_reload`: Reload tab with optional cache bypass.
+- `browser_scroll`: Scroll viewport or container in any direction with velocity HUD.
+- `browser_read_all_tabs`: Extract visible text and metadata from every open tab at once.
+- `browser_manage_tab_group`: Group, ungroup, colorize, collapse, or expand tabs.
+
+### Smart Content & Table Extraction
+- `browser_get_markdown`: Clean Markdown conversion stripping boilerplate/ads.
+- `browser_extract_table`: Structured table extraction to JSON, Markdown, or CSV.
+- `browser_find_in_page`: In-page search (Ctrl+F) with smooth scrolling and match highlighting.
+
+### DOM, Visual Refs & CSS Styling
+- `browser_get_interactive_snapshot`: Map interactive elements with deterministic `data-agent-ref` IDs (`ref_1`, `ref_2`...) and coordinates.
+- `browser_take_snapshot`: Accessibility (a11y) tree text snapshot matching `chrome-devtools-mcp`.
+- `browser_get_css_styles`: Inspect computed CSS styles for any element by ref or selector.
+- `browser_wait_for`: Wait for specific text or CSS selector to appear on the page.
+
+### Precision Hardware-Level Input
+- `browser_act_on_ref`: Visual highlight overlay + click or text input on a `data-agent-ref`.
+- `browser_click`: Hardware CDP mouse click (by ref, selector, or x/y coordinates).
+- `browser_hover`: Trigger mouse hover states.
+- `browser_drag`: Drag and drop with animated laser trajectory.
+- `browser_fill`: Clear and fill an input or textarea with text.
+- `browser_fill_form`: Fill multiple form fields simultaneously.
+- `browser_press_key`: Physical keyboard key press with 3D mechanical keycap popovers.
+- `browser_type_text`: Type text into current focus or target element.
+- `browser_select_option`: Select dropdown option by value, visible text, or index.
+- `browser_set_checked`: Toggle checkbox or radio button with spring bloom animation.
+- `browser_upload_file`: Upload local file(s) into file input elements (`DOM.setFileInputFiles`).
+- `browser_handle_dialog`: Accept or dismiss JavaScript `alert()`, `confirm()`, or `prompt()` dialogs.
+
+### User Context, Bookmarks & Desktop Notifications
+- `browser_search_bookmarks`: Search bookmarks by keyword or folder.
+- `browser_add_bookmark`: Create a new bookmark.
+- `browser_search_history`: Search browsing history by query and time range.
+- `browser_show_notification`: Display native OS desktop notifications.
+- `browser_clipboard`: Read or copy text to/from system clipboard.
+- `browser_download_file`: Trigger file download from URL.
+- `browser_wait_for_download`: Track active downloads until completion.
+- `browser_list_downloads`: List recent downloads in profile.
+
+### Media Controls (Audio & Video)
+- `browser_media_control`: Play, pause, seek, mute, volume, playback speed.
+- `browser_mute_tab`: Mute/unmute all audio output for a tab.
+- `browser_get_subtitles`: Extract live captions or video subtitles.
+
+### Network Interception, Ad-Blocking & Routing
+- `browser_block_urls`: Wildcard URL pattern blocking (`Network.setBlockedURLs`).
+- `browser_set_extra_headers`: Custom HTTP header injection on outgoing requests.
+- `browser_mock_route`: Real-time CDP Fetch route interception and custom response mocking.
+- `browser_list_network_requests`: List recorded network requests for a tab.
+- `browser_get_network_request`: Get full details and headers for a requestId.
+- `browser_get_network_body`: Fetch raw response body for any recorded request.
+- `browser_get_cookies`: Retrieve cookies for a tab's URL.
+- `browser_set_cookie`: Set a cookie.
+- `browser_clear_cookies`: Clear all cookies for the profile.
+- `browser_storage`: Read, write, or clear `localStorage` / `sessionStorage`.
+
+### Device & Network Emulation
+- `browser_resize_page`: Set viewport dimensions (width, height, deviceScaleFactor, mobile).
+- `browser_emulate`: Emulate dark/light mode, CPU throttling, network throttling, geolocation, user-agent.
+- `browser_emulate_timezone`: Override timezone and locale.
+
+### Diagnostics, Performance & Raw CDP
+- `browser_screenshot`: Capture high-resolution PNG or JPEG tab screenshot.
+- `browser_print_to_pdf`: Generate PDF document via `Page.printToPDF`.
+- `browser_list_console_messages`: List captured console logs, warnings, errors, and stack traces.
+- `browser_get_telemetry`: Combined telemetry snapshot (console, network, dialogs).
+- `browser_take_heapsnapshot`: V8 heap snapshot for memory leak analysis.
+- `browser_performance_trace`: Start or stop Chrome performance timeline trace.
+- `browser_performance_analyze_insight`: Extract Core Web Vitals (TTFB, FCP, DOMContentLoaded, LoadTime).
+- `browser_eval_js`: Evaluate arbitrary JavaScript in tab context with async/await.
+- `browser_raw_cdp`: Execute ANY raw Chrome DevTools Protocol command.
+- `browser_request_human_takeover`: Pause agent and display takeover banner for manual 2FA/CAPTCHA.
+- `browser_reload_extension`: Hot reload the extension service worker.
+
+---
+
+## 🔒 Security & Privacy
+
+- **Local-Only**: Only binds to `127.0.0.1:18922` by default. Never exposes ports to external networks.
+- **Instant Killswitch**: Toggle "Allow Agent Control" off anytime in the extension popup to instantly freeze agent access.
+- **Visual Action Overlay**: Every click and keystroke displays a glowing cyan overlay on your screen so you can clearly see what the agent is doing.
+
+---
+
+## 📄 License
+
+Apache-2.0

package/bin/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+/**
+ * Agent Bridge MCP - CLI Executable Entrypoint
+ * Enables zero-install execution via: npx -y agent-browser-bridge
+ */
+
+import "../index.js";

package/core/bridge.js

@@ -0,0 +1,293 @@
+// Agent Bridge MCP - Master Server & Relay Architecture (ES Module)
+import http from "http";
+import crypto from "crypto";
+import { WebSocketServer } from "ws";
+import {
+  PORT,
+  activeProfiles,
+  pendingRequests,
+  serverState,
+  log,
+  AUTO_SPAWN,
+  spawnIsolatedBrowser,
+} from "./state.js";
+
+export async function checkMasterAlive() {
+  try {
+    const res = await fetch(`http://127.0.0.1:${PORT}/health`, {
+      signal: AbortSignal.timeout(1000),
+      cache: "no-store",
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export function startMasterServer() {
+  if (serverState.isMasterServer && serverState.httpServer?.listening) return;
+
+  try {
+    if (serverState.httpServer) {
+      serverState.httpServer.close();
+      serverState.httpServer = null;
+    }
+  } catch {}
+
+  serverState.httpServer = http.createServer((req, res) => {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    const reqUrl = new URL(req.url, `http://${req.headers.host || "127.0.0.1"}`);
+
+    if (reqUrl.pathname === "/health" || reqUrl.pathname === "/") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", profiles: activeProfiles.size, pid: process.pid }));
+      return;
+    }
+
+    if (req.method === "GET" && reqUrl.pathname === "/profiles") {
+      const list = Array.from(activeProfiles.values()).map((p) => ({
+        id: p.id,
+        name: p.name,
+        browser: p.browser,
+        connectedAt: new Date(p.connectedAt).toISOString(),
+        lastActive: new Date(p.lastActive).toISOString(),
+      }));
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ count: list.length, profiles: list }));
+      return;
+    }
+
+    if (req.method === "POST" && reqUrl.pathname === "/rpc") {
+      let body = "";
+      req.on("data", (chunk) => (body += chunk));
+      req.on("end", async () => {
+        try {
+          const parsed = JSON.parse(body || "{}");
+          const targetProfile = parsed.profile || reqUrl.searchParams.get("profile");
+          const result = await callProfileExtensionInternal(targetProfile, parsed.action, parsed.params || {});
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ success: true, result }));
+        } catch (err) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ success: false, error: err.message }));
+        }
+      });
+      return;
+    }
+
+    res.writeHead(404);
+    res.end();
+  });
+
+  serverState.httpServer.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+      log(`Port ${PORT} in use. Running as Relay Client.`);
+      serverState.isMasterServer = false;
+    } else {
+      log("Server error:", err.message);
+    }
+  });
+
+  serverState.wss = new WebSocketServer({ server: serverState.httpServer });
+
+  serverState.wss.on("connection", (ws) => {
+    let currentProfileId = null;
+
+    ws.on("message", (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+
+        if (msg.type === "register") {
+          currentProfileId = msg.profileId;
+          activeProfiles.set(currentProfileId, {
+            id: msg.profileId,
+            name: msg.profileName || "Browser Profile",
+            browser: msg.browser || "Chromium",
+            ws,
+            connectedAt: Date.now(),
+            lastActive: Date.now(),
+          });
+          log(`Profile registered: "${msg.profileName}" (${msg.browser}) [${msg.profileId}]`);
+          return;
+        }
+
+        if (msg.type === "heartbeat") {
+          if (currentProfileId && activeProfiles.has(currentProfileId)) {
+            const p = activeProfiles.get(currentProfileId);
+            p.lastActive = Date.now();
+            if (msg.profileName) p.name = msg.profileName;
+          }
+          return;
+        }
+
+        if (msg.id && pendingRequests.has(msg.id)) {
+          const req = pendingRequests.get(msg.id);
+          pendingRequests.delete(msg.id);
+          clearTimeout(req.timer);
+          if (msg.error) {
+            req.reject(new Error(msg.error));
+          } else {
+            req.resolve(msg.result);
+          }
+        }
+      } catch (err) {
+        log("WebSocket message parse error:", err.message);
+      }
+    });
+
+    ws.on("close", () => {
+      if (currentProfileId && activeProfiles.has(currentProfileId)) {
+        const p = activeProfiles.get(currentProfileId);
+        log(`Profile disconnected: "${p.name}" [${currentProfileId}]`);
+        activeProfiles.delete(currentProfileId);
+      }
+    });
+
+    ws.on("error", (err) => {
+      log("WebSocket client error:", err.message);
+    });
+  });
+
+  serverState.httpServer.listen(PORT, "127.0.0.1", () => {
+    serverState.isMasterServer = true;
+    log(`Master Bridge listening on http://127.0.0.1:${PORT} (WebSocket + HTTP Relay)`);
+  });
+}
+
+export async function ensureMasterOrRelay() {
+  if (serverState.isMasterServer && serverState.httpServer?.listening) return true;
+  const alive = await checkMasterAlive();
+  if (alive) {
+    serverState.isMasterServer = false;
+    return false;
+  }
+  startMasterServer();
+  await new Promise((r) => setTimeout(r, 400));
+  return serverState.isMasterServer;
+}
+
+export function initMasterRelayWatchdog() {
+  setInterval(async () => {
+    if (!serverState.isMasterServer) {
+      const alive = await checkMasterAlive();
+      if (!alive) {
+        log("Master server offline. Auto-promoting this instance to Master Bridge...");
+        await ensureMasterOrRelay();
+      }
+    }
+  }, 3500);
+}
+
+export async function waitForProfile(timeoutMs = 10000) {
+  if (activeProfiles.size > 0) return;
+  if (AUTO_SPAWN && !serverState.browserProcess) spawnIsolatedBrowser();
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (activeProfiles.size > 0) return;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+export async function getTargetProfile(requestedProfile) {
+  await waitForProfile();
+
+  if (activeProfiles.size === 0) {
+    throw new Error(
+      `No browser profile with "Agent Bridge MCP" extension is currently connected on ws://127.0.0.1:${PORT}.\n` +
+      `Please open your browser (Chrome/Edge/Brave) where the extension is loaded and ensure the popup status shows "Connected".`
+    );
+  }
+
+  if (requestedProfile) {
+    const req = requestedProfile.toLowerCase().trim();
+    if (activeProfiles.has(requestedProfile)) {
+      return activeProfiles.get(requestedProfile);
+    }
+    for (const profile of activeProfiles.values()) {
+      if (profile.name.toLowerCase() === req || profile.id.toLowerCase() === req) {
+        return profile;
+      }
+    }
+    for (const profile of activeProfiles.values()) {
+      if (profile.name.toLowerCase().includes(req)) {
+        return profile;
+      }
+    }
+    const available = Array.from(activeProfiles.values())
+      .map((p) => `"${p.name}" (ID: ${p.id})`)
+      .join(", ");
+    throw new Error(`Profile "${requestedProfile}" not found. Available profiles: ${available}`);
+  }
+
+  if (activeProfiles.size === 1) {
+    return activeProfiles.values().next().value;
+  }
+
+  let mostRecent = null;
+  for (const profile of activeProfiles.values()) {
+    if (!mostRecent || profile.lastActive > mostRecent.lastActive) {
+      mostRecent = profile;
+    }
+  }
+  return mostRecent;
+}
+
+export async function callProfileExtensionInternal(profileQuery, action, params = {}, timeoutMs = 25000) {
+  const profile = await getTargetProfile(profileQuery);
+
+  return new Promise((resolve, reject) => {
+    if (!profile.ws || profile.ws.readyState !== 1) {
+      return reject(new Error(`Browser profile "${profile.name}" WebSocket is not open.`));
+    }
+
+    const id = crypto.randomUUID();
+    const timer = setTimeout(() => {
+      pendingRequests.delete(id);
+      reject(new Error(`Extension request timed out (${action}) on profile "${profile.name}".`));
+    }, timeoutMs);
+
+    pendingRequests.set(id, { resolve, reject, timer });
+    profile.ws.send(JSON.stringify({ id, action, params }));
+  });
+}
+
+export async function callProfileExtension(profileQuery, action, params = {}, timeoutMs = 25000) {
+  if (!serverState.isMasterServer) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${PORT}/rpc`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ profile: profileQuery, action, params }),
+        signal: AbortSignal.timeout(timeoutMs),
+      });
+      const data = await res.json();
+      if (!data.success) throw new Error(data.error);
+      return data.result;
+    } catch (err) {
+      log(`Relay call failed (${err.message}). Checking Master health...`);
+      const masterStillAlive = await checkMasterAlive();
+      if (!masterStillAlive) {
+        log("Master server died. Promoting this instance to Master Bridge...");
+        startMasterServer();
+        await new Promise((r) => setTimeout(r, 600));
+        if (serverState.isMasterServer) {
+          return callProfileExtensionInternal(profileQuery, action, params, timeoutMs);
+        }
+      }
+      throw err;
+    }
+  }
+
+  return callProfileExtensionInternal(profileQuery, action, params, timeoutMs);
+}
+

package/core/state.js

@@ -0,0 +1,68 @@
+// Agent Bridge MCP - Server State & Configuration (ES Module)
+import path from "path";
+import os from "os";
+import fs from "fs";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const EXTENSION_PATH = path.resolve(__dirname, "../../extension");
+export const PORT = Number(process.env.MCP_BROWSER_PORT) || 18922;
+export const AUTO_SPAWN = process.env.AUTO_SPAWN === "true";
+
+// Track connected browser profiles: profileId -> { id, name, browser, ws, lastActive, tabCount }
+export const activeProfiles = new Map();
+export const pendingRequests = new Map();
+
+export const serverState = {
+  isMasterServer: false,
+  httpServer: null,
+  wss: null,
+  browserProcess: null,
+};
+
+export function log(...args) {
+  console.error("[Agent Bridge MCP]", ...args);
+}
+
+export function jsonResult(data) {
+  return { content: [{ type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) }] };
+}
+
+export function resolveChromeBinary() {
+  if (process.env.CHROME_BIN) return process.env.CHROME_BIN;
+  if (process.platform === "win32") {
+    const candidates = [
+      "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+      "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+      path.join(process.env.LOCALAPPDATA || "", "Google\\Chrome\\Application\\chrome.exe"),
+    ];
+    return candidates.find((p) => fs.existsSync(p)) || candidates[0];
+  }
+  if (process.platform === "darwin") {
+    return "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+  }
+  return "google-chrome";
+}
+
+export function spawnIsolatedBrowser() {
+  if (serverState.browserProcess) return;
+  const profileDir = path.join(os.homedir(), ".agent-browser-profile");
+  const chromeBin = resolveChromeBinary();
+  log(`Spawning isolated fallback Chrome instance at ${profileDir}...`);
+
+  serverState.browserProcess = spawn(
+    chromeBin,
+    [
+      `--user-data-dir=${profileDir}`,
+      `--load-extension=${EXTENSION_PATH}`,
+      "--silent-debugger-extension-api",
+      "--no-first-run",
+      "--no-default-browser-check",
+      "about:blank",
+    ],
+    { detached: true, stdio: "ignore" }
+  );
+  serverState.browserProcess.unref();
+}
+

package/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// Agent Bridge MCP Server - Main Entrypoint (ES Module)
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ensureMasterOrRelay, initMasterRelayWatchdog } from "./core/bridge.js";
+import { registerAllTools } from "./tools/registry.js";
+
+// 1. Initialize Master Server or Relay Client
+await ensureMasterOrRelay();
+initMasterRelayWatchdog();
+
+// 2. Initialize MCP Server
+const server = new McpServer({
+  name: "custom-browser-bridge",
+  version: "2.2.0",
+});
+
+// 3. Register All 68 Tools Across Modules
+registerAllTools(server);
+
+// 4. Start Transport
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "agent-browser-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.2.0",
+  "description": "Live multi-tab, multi-profile Chrome DevTools MCP bridge for AI agents (Antigravity, Claude, Cursor, Windsurf)",
+  "author": "thisisdarkstar",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "agent-browser-bridge": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "index.js",
+    "core",
+    "tools",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "chrome-extension",
+    "browser-control",
+    "devtools",
+    "antigravity",
+    "claude",
+    "cursor"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.0",
+    "ws": "^8.18.0",
+    "zod": "^3.23.8"
+  }
+}