agent-browser-bridge 2.0.0 → 2.2.0

package/README.md

@@ -53,7 +53,7 @@ Add a new MCP server in settings:
 
 ---
 
-## 🛠️ Complete Tool Catalog (39 Tools)
+## 🛠️ Complete Tool Catalog (68 Tools)
 
 ### Multi-Profile & Tab Management
 - `browser_list_profiles`: List all connected browser profiles (Work, Personal, Brave, Edge).
@@ -61,9 +61,21 @@ Add a new MCP server in settings:
 - `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.
@@ -75,40 +87,60 @@ Add a new MCP server in settings:
 - `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 from source element/coords to destination element/coords.
+- `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 given a map of `{ selector_or_ref: value }`.
-- `browser_press_key`: Press keyboard keys or shortcuts (`Enter`, `Tab`, `Escape`, `Backspace`, `ArrowDown`).
+- `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.
 
-### Device & Network Emulation
-- `browser_resize_page`: Set viewport dimensions (width, height, deviceScaleFactor, mobile).
-- `browser_emulate`: Emulate dark/light color scheme, CPU throttling, network conditions, Geolocation, or User Agent.
-
-### Network, Cookies & Local Storage
+### 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 specific requestId.
-- `browser_get_network_body`: Fetch raw response body for any recorded network request.
+- `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 (name, value, domain, path, secure, httpOnly).
+- `browser_set_cookie`: Set a cookie.
 - `browser_clear_cookies`: Clear all cookies for the profile.
 - `browser_storage`: Read, write, or clear `localStorage` / `sessionStorage`.
 
-### Console, Telemetry & Diagnostics
-- `browser_list_console_messages`: List captured console logs, warnings, errors, and uncaught exceptions with stack traces.
-- `browser_get_telemetry`: Combined telemetry snapshot (console logs, network requests, dialog events).
-
-### Performance, Memory & Screenshots
-- `browser_screenshot`: Capture high-resolution PNG tab screenshot.
+### 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).
-
-### JavaScript Execution & Raw CDP Escape Hatch
-- `browser_eval_js`: Evaluate arbitrary JavaScript in the tab context with async/await.
-- `browser_raw_cdp`: Execute ANY Chrome DevTools Protocol command with custom parameters.
+- `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.
 
 ---
 

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();
+}
+