agent-browser-bridge 2.0.0 → 2.2.0

package/tools/emulation-tools.js

@@ -0,0 +1,138 @@
+// Agent Bridge MCP - Viewport, Emulation, Screenshots & PDF Tools (ES Module)
+import { z } from "zod";
+import { jsonResult } from "../core/state.js";
+import { callProfileExtension } from "../core/bridge.js";
+
+export function registerEmulationTools(server) {
+  server.registerTool(
+    "browser_resize_page",
+    {
+      description: "Emulate viewport screen dimensions and device scale factor via CDP Emulation.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        width: z.number().describe("Viewport width in pixels (e.g. 1280)"),
+        height: z.number().describe("Viewport height in pixels (e.g. 800)"),
+        deviceScaleFactor: z.number().optional().describe("Device scale factor / DPR (default 1)"),
+        mobile: z.boolean().optional().describe("Emulate mobile screen (default false)"),
+      },
+    },
+    async ({ profile, tabId, width, height, deviceScaleFactor, mobile }) => {
+      const res = await callProfileExtension(profile, "resize_page", { tabId, width, height, deviceScaleFactor, mobile });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_emulate",
+    {
+      description: "Emulate device color scheme, network throttling, CPU throttling, geolocation, or user agent.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        colorScheme: z.enum(["dark", "light", "no-preference"]).optional().describe("Emulate dark/light mode"),
+        userAgent: z.string().optional().describe("Custom User-Agent override"),
+        cpuThrottlingRate: z.number().optional().describe("CPU slowdown factor (1 = normal, 4 = 4x slowdown)"),
+        geolocation: z.object({
+          latitude: z.number(),
+          longitude: z.number(),
+          accuracy: z.number().optional(),
+        }).optional().describe("Mock geolocation coordinates"),
+        networkConditions: z.union([
+          z.enum(["offline", "slow3g", "fast3g", "4g"]),
+          z.object({
+            offline: z.boolean(),
+            latency: z.number(),
+            downloadThroughput: z.number(),
+            uploadThroughput: z.number(),
+          }),
+        ]).optional().describe("Network throttling preset or custom conditions"),
+      },
+    },
+    async ({ profile, tabId, colorScheme, userAgent, cpuThrottlingRate, geolocation, networkConditions }) => {
+      const res = await callProfileExtension(profile, "emulate", {
+        tabId,
+        colorScheme,
+        userAgent,
+        cpuThrottlingRate,
+        geolocation,
+        networkConditions,
+      });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_emulate_timezone",
+    {
+      description: "Override browser timezone and locale for geolocation testing or internationalization.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        timezoneId: z.string().describe("IANA Timezone ID (e.g. 'America/New_York', 'Asia/Tokyo', 'Europe/London')"),
+      },
+    },
+    async ({ profile, tabId, timezoneId }) => {
+      const res = await callProfileExtension(profile, "emulate_timezone", { tabId, timezoneId });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_screenshot",
+    {
+      description: "Capture high-resolution screenshot (PNG or compressed JPEG), full page, or clipped to an element ref/selector.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        format: z.enum(["png", "jpeg"]).optional().describe("Image format (default 'png')"),
+        quality: z.number().optional().describe("Compression quality 0-100 (for jpeg)"),
+        fullPage: z.boolean().optional().describe("Capture entire scrollable page height (default false)"),
+        target: z.string().optional().describe("Clip screenshot to this element ref (e.g. 'ref_1') or selector"),
+      },
+    },
+    async ({ profile, tabId, format, quality, fullPage, target }) => {
+      const res = await callProfileExtension(profile, "screenshot", { tabId, format, quality, fullPage, target });
+      return {
+        content: [
+          {
+            type: "image",
+            data: res.dataBase64,
+            mimeType: res.mimeType,
+          },
+        ],
+      };
+    }
+  );
+
+  server.registerTool(
+    "browser_print_to_pdf",
+    {
+      description: "Generate a PDF document of the webpage via Chrome DevTools Page.printToPDF.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        landscape: z.boolean().optional().describe("Paper orientation landscape (default false)"),
+        displayHeaderFooter: z.boolean().optional().describe("Display header and footer"),
+        printBackground: z.boolean().optional().describe("Print background graphics (default true)"),
+        scale: z.number().optional().describe("Scale factor 0.1 - 2.0 (default 1)"),
+      },
+    },
+    async ({ profile, tabId, landscape, displayHeaderFooter, printBackground, scale }) => {
+      const res = await callProfileExtension(profile, "print_to_pdf", { tabId, landscape, displayHeaderFooter, printBackground, scale });
+      return {
+        content: [
+          {
+            type: "resource",
+            resource: {
+              uri: `data:application/pdf;base64,${res.dataBase64}`,
+              mimeType: res.mimeType,
+              text: "PDF document generated successfully. Base64 encoded PDF.",
+            },
+          },
+        ],
+      };
+    }
+  );
+}
+

package/tools/extraction-tools.js

@@ -0,0 +1,74 @@
+// Agent Bridge MCP - Smart Content, Markdown & Table Extraction Tools (ES Module)
+import { z } from "zod";
+import { jsonResult } from "../core/state.js";
+import { callProfileExtension } from "../core/bridge.js";
+
+export function registerExtractionTools(server) {
+  server.registerTool(
+    "browser_get_markdown",
+    {
+      description: "Convert an entire webpage or a specific CSS container into clean, structured GitHub-flavored Markdown (stripping navbars, scripts, ads, and style bloat). Extremely token-efficient for LLM context windows.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        selector: z.string().optional().describe("Optional container ref or CSS selector to extract markdown from (defaults to entire page body)"),
+        includeLinks: z.boolean().optional().describe("Whether to preserve hyperlinks in markdown format (default true)"),
+        includeImages: z.boolean().optional().describe("Whether to preserve image alt/src in markdown format (default false)"),
+        maxLength: z.number().optional().describe("Maximum character length to return (default 50000)"),
+      },
+    },
+    async ({ profile, tabId, selector, includeLinks, includeImages, maxLength }) => {
+      const res = await callProfileExtension(profile, "get_markdown", {
+        tabId,
+        selector,
+        includeLinks,
+        includeImages,
+        maxLength,
+      });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_extract_table",
+    {
+      description: "Automatically detect and extract data from <table> elements or repeating grid layouts into clean structured JSON, CSV, or Markdown tables.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        target: z.string().optional().describe("Optional table element ref or selector. If omitted, extracts all tables on the page."),
+        format: z.enum(["json", "csv", "markdown"]).optional().describe("Output data format (default 'json')"),
+      },
+    },
+    async ({ profile, tabId, target, format }) => {
+      const res = await callProfileExtension(profile, "extract_table", { tabId, target, format });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_find_in_page",
+    {
+      description: "Search for text on the page (matching browser Ctrl+F), returning count of occurrences, surrounding text snippets, and optionally scrolling the matched occurrence into view.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        query: z.string().describe("Search term or text to find"),
+        caseSensitive: z.boolean().optional().describe("Whether the search is case-sensitive (default false)"),
+        matchIndex: z.number().optional().describe("Zero-based index of the specific match to scroll to (default 0)"),
+        scrollToMatch: z.boolean().optional().describe("Whether to scroll to the matched element with visual highlight (default true)"),
+      },
+    },
+    async ({ profile, tabId, query, caseSensitive, matchIndex, scrollToMatch }) => {
+      const res = await callProfileExtension(profile, "find_in_page", {
+        tabId,
+        query,
+        caseSensitive,
+        matchIndex,
+        scrollToMatch,
+      });
+      return jsonResult(res);
+    }
+  );
+}
+

package/tools/media-tools.js

@@ -0,0 +1,55 @@
+// Agent Bridge MCP - Media Player, Subtitles & Audio Tools (ES Module)
+import { z } from "zod";
+import { jsonResult } from "../core/state.js";
+import { callProfileExtension } from "../core/bridge.js";
+
+export function registerMediaTools(server) {
+  server.registerTool(
+    "browser_media_control",
+    {
+      description: "Control audio and video elements on the page: play, pause, toggle, mute, seek, change volume, or adjust playback speed.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        action: z.enum(["play", "pause", "toggle", "mute", "unmute", "seek", "set_volume", "set_speed"]).describe("Media action to execute"),
+        value: z.union([z.number(), z.string()]).optional().describe("Parameter value (seconds for 'seek', 0.0-1.0 for 'set_volume', 0.25-4.0 for 'set_speed')"),
+      },
+    },
+    async ({ profile, tabId, action, value }) => {
+      const res = await callProfileExtension(profile, "media_control", { tabId, action, value });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_mute_tab",
+    {
+      description: "Mute or unmute all audio output for an entire browser tab.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        muted: z.boolean().describe("Whether the tab should be muted (true) or unmuted (false)"),
+      },
+    },
+    async ({ profile, tabId, muted }) => {
+      const res = await callProfileExtension(profile, "mute_tab", { tabId, muted });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_get_subtitles",
+    {
+      description: "Extract current live captions, active subtitles, and text tracks from video players on the page (YouTube, Coursera, video players).",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+      },
+    },
+    async ({ profile, tabId }) => {
+      const res = await callProfileExtension(profile, "get_subtitles", { tabId });
+      return jsonResult(res);
+    }
+  );
+}
+

package/tools/navigation-tools.js

@@ -0,0 +1,71 @@
+// Agent Bridge MCP - Navigation Tools (ES Module)
+import { z } from "zod";
+import { jsonResult } from "../core/state.js";
+import { callProfileExtension } from "../core/bridge.js";
+
+export function registerNavigationTools(server) {
+  server.registerTool(
+    "browser_navigate",
+    {
+      description: "Navigate an existing tab or open a new one to a specific URL with customizable ready wait conditions.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().optional().describe("Existing tabId to navigate. Omit to open and navigate a new tab."),
+        url: z.string().describe("Target URL to navigate to"),
+        waitFor: z.enum(["load", "domcontentloaded", "none"]).optional().describe("Wait condition (default 'load')"),
+        timeoutMs: z.number().optional().describe("Timeout in milliseconds (default 15000)"),
+      },
+    },
+    async ({ profile, tabId, url, waitFor, timeoutMs }) => {
+      const res = await callProfileExtension(profile, "navigate_or_open", { tabId, url, waitFor, timeoutMs });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_go_back",
+    {
+      description: "Navigate back in browser history for a specific tab.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("The ID of the tab to navigate back"),
+      },
+    },
+    async ({ profile, tabId }) => {
+      const res = await callProfileExtension(profile, "go_back", { tabId });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_go_forward",
+    {
+      description: "Navigate forward in browser history for a specific tab.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("The ID of the tab to navigate forward"),
+      },
+    },
+    async ({ profile, tabId }) => {
+      const res = await callProfileExtension(profile, "go_forward", { tabId });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_reload",
+    {
+      description: "Reload a specific tab with optional cache bypass.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        ignoreCache: z.boolean().optional().describe("Whether to hard reload bypassing cache (default false)"),
+      },
+    },
+    async ({ profile, tabId, ignoreCache }) => {
+      const res = await callProfileExtension(profile, "reload_tab", { tabId, ignoreCache });
+      return jsonResult(res);
+    }
+  );
+}
+

package/tools/network-tools.js

@@ -0,0 +1,197 @@
+// Agent Bridge MCP - Network, Cookies, Storage & Routing Tools (ES Module)
+import { z } from "zod";
+import { jsonResult } from "../core/state.js";
+import { callProfileExtension } from "../core/bridge.js";
+
+export function registerNetworkTools(server) {
+  server.registerTool(
+    "browser_list_network_requests",
+    {
+      description: "List captured network requests for a tab (status, method, url, resourceType, mimeType, timestamp).",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        limit: z.number().optional().describe("Max requests to return (default 50)"),
+      },
+    },
+    async ({ profile, tabId, limit }) => {
+      const res = await callProfileExtension(profile, "list_network_requests", { tabId, limit });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_get_network_request",
+    {
+      description: "Get full details and request/response headers for a recorded requestId.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        requestId: z.string().describe("The requestId returned by browser_list_network_requests"),
+      },
+    },
+    async ({ profile, tabId, requestId }) => {
+      const res = await callProfileExtension(profile, "get_network_request", { tabId, requestId });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_get_network_body",
+    {
+      description: "Fetch the raw response body of a network request via CDP Network.getResponseBody.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        requestId: z.string().describe("The requestId"),
+      },
+    },
+    async ({ profile, tabId, requestId }) => {
+      const res = await callProfileExtension(profile, "get_network_body", { tabId, requestId });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_get_cookies",
+    {
+      description: "Retrieve cookies for the browser profile or filtered by URLs.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        urls: z.union([z.string(), z.array(z.string())]).optional().describe("URL(s) to filter cookies by"),
+      },
+    },
+    async ({ profile, urls }) => {
+      const res = await callProfileExtension(profile, "get_cookies", { urls });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_set_cookie",
+    {
+      description: "Set a cookie in the active browser profile.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        url: z.string().describe("The request-URI with which the cookie will be associated"),
+        name: z.string().describe("Cookie name"),
+        value: z.string().describe("Cookie value"),
+        domain: z.string().optional().describe("Cookie domain"),
+        path: z.string().optional().describe("Cookie path"),
+        secure: z.boolean().optional().describe("HTTPS only"),
+        httpOnly: z.boolean().optional().describe("HttpOnly flag"),
+        sameSite: z.enum(["unspecified", "no_restriction", "lax", "strict"]).optional(),
+        expirationDate: z.number().optional().describe("Expiration timestamp in seconds"),
+      },
+    },
+    async ({ profile, url, name, value, domain, path, secure, httpOnly, sameSite, expirationDate }) => {
+      const res = await callProfileExtension(profile, "set_cookie", {
+        url,
+        name,
+        value,
+        domain,
+        path,
+        secure,
+        httpOnly,
+        sameSite,
+        expirationDate,
+      });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_clear_cookies",
+    {
+      description: "Clear all cookies stored in the current browser profile.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+      },
+    },
+    async ({ profile }) => {
+      const res = await callProfileExtension(profile, "clear_cookies");
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_storage",
+    {
+      description: "Read, write, or clear localStorage or sessionStorage in a tab.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        type: z.enum(["local", "session"]).optional().describe("Storage type (default 'local')"),
+        action: z.enum(["get", "set", "remove", "clear"]).optional().describe("Storage action (default 'get')"),
+        key: z.string().optional().describe("Storage item key"),
+        value: z.any().optional().describe("Value to set"),
+      },
+    },
+    async ({ profile, tabId, type, action, key, value }) => {
+      const res = await callProfileExtension(profile, "storage", { tabId, type, action, key, value });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_block_urls",
+    {
+      description: "Block network requests matching specific URL wildcard patterns (e.g. ['*google-analytics*', '*ads*', '*.png']) via CDP Network.setBlockedURLs.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        patterns: z.union([z.string(), z.array(z.string())]).optional().describe("URL pattern(s) with wildcards to block"),
+        clear: z.boolean().optional().describe("If true, removes all URL blocking rules on this tab"),
+      },
+    },
+    async ({ profile, tabId, patterns, clear }) => {
+      const res = await callProfileExtension(profile, "block_urls", { tabId, patterns, clear });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_set_extra_headers",
+    {
+      description: "Inject custom HTTP headers (e.g. Authorization, custom API keys, mock cookies) into all outgoing HTTP requests on a tab via CDP Network.setExtraHTTPHeaders.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        headers: z.record(z.string()).optional().describe("Key-value dictionary of HTTP header names and values to inject"),
+        clear: z.boolean().optional().describe("If true, clears all custom headers on this tab"),
+      },
+    },
+    async ({ profile, tabId, headers, clear }) => {
+      const res = await callProfileExtension(profile, "set_extra_headers", { tabId, headers, clear });
+      return jsonResult(res);
+    }
+  );
+
+  server.registerTool(
+    "browser_mock_route",
+    {
+      description: "Intercept HTTP network requests matching a URL pattern and return custom mock status codes, headers, and response bodies via CDP Fetch interception.",
+      inputSchema: {
+        profile: z.string().optional().describe("Target browser profile"),
+        tabId: z.number().describe("Target tabId"),
+        urlPattern: z.string().optional().describe("URL pattern to intercept (e.g. '*api/v1/user*', 'https://api.example.com/*')"),
+        responseBody: z.any().optional().describe("Mock response body string or JSON object"),
+        status: z.number().optional().describe("HTTP response status code (default 200)"),
+        headers: z.record(z.string()).optional().describe("Custom HTTP response headers"),
+        clear: z.boolean().optional().describe("If true, disables Fetch interception and clears all mock routes for this tab"),
+      },
+    },
+    async ({ profile, tabId, urlPattern, responseBody, status, headers, clear }) => {
+      const res = await callProfileExtension(profile, "mock_route", {
+        tabId,
+        urlPattern,
+        responseBody,
+        status,
+        headers,
+        clear,
+      });
+      return jsonResult(res);
+    }
+  );
+}
+

package/tools/registry.js

@@ -0,0 +1,23 @@
+// Agent Bridge MCP - Tool Registry Aggregator (ES Module)
+import { registerTabTools } from "./tab-tools.js";
+import { registerNavigationTools } from "./navigation-tools.js";
+import { registerDomTools } from "./dom-tools.js";
+import { registerExtractionTools } from "./extraction-tools.js";
+import { registerNetworkTools } from "./network-tools.js";
+import { registerBrowserDataTools } from "./browser-data-tools.js";
+import { registerMediaTools } from "./media-tools.js";
+import { registerEmulationTools } from "./emulation-tools.js";
+import { registerDiagnosticTools } from "./diagnostic-tools.js";
+
+export function registerAllTools(server) {
+  registerTabTools(server);
+  registerNavigationTools(server);
+  registerDomTools(server);
+  registerExtractionTools(server);
+  registerNetworkTools(server);
+  registerBrowserDataTools(server);
+  registerMediaTools(server);
+  registerEmulationTools(server);
+  registerDiagnosticTools(server);
+}
+