@browserbridge/bbx 1.0.1 → 1.2.0

package/packages/mcp-server/src/handlers-capture.js

@@ -0,0 +1,279 @@
+// @ts-check
+
+import {
+  dispatchToolAction,
+  getToolTokenBudget,
+  REQUEST_SOURCE,
+  requestBridge,
+  resolveToolRef,
+  resolveRef,
+  summarizeToolError,
+  summarizeToolResponse,
+  withToolClient,
+} from './handlers-utils.js';
+
+/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./handlers-utils.js').ToolAction} ToolAction */
+/** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
+
+/** @type {Record<string, ToolAction>} */
+export const CAPTURE_ACTIONS = {
+  element: {
+    ref: true,
+    method: 'screenshot.capture_element',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  region: {
+    ref: false,
+    method: 'screenshot.capture_region',
+    params: (a) => /** @type {Record<string, unknown>} */ (a.rect || {}),
+  },
+  full_page: {
+    ref: false,
+    method: 'screenshot.capture_full_page',
+    params: () => ({}),
+  },
+  cdp_document: { ref: false, method: 'cdp.get_document', params: () => ({}) },
+  cdp_dom_snapshot: {
+    ref: false,
+    method: 'cdp.get_dom_snapshot',
+    params: () => ({}),
+  },
+  cdp_box_model: {
+    ref: true,
+    method: 'cdp.get_box_model',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  cdp_computed_styles: {
+    ref: true,
+    method: 'cdp.get_computed_styles_for_node',
+    params: (_, r) => ({ elementRef: r }),
+  },
+};
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, rect?: Record<string, unknown>, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleCaptureTool(args) {
+  return dispatchToolAction(CAPTURE_ACTIONS, args, 'capture');
+}
+
+/** @type {Record<string, BridgeMethod>} */
+export const INPUT_ACTION_METHODS = {
+  click: 'input.click',
+  focus: 'input.focus',
+  type: 'input.type',
+  press_key: 'input.press_key',
+  cdp_press_key: 'cdp.dispatch_key_event',
+  set_checked: 'input.set_checked',
+  select_option: 'input.select_option',
+  hover: 'input.hover',
+  drag: 'input.drag',
+  scroll_into_view: 'input.scroll_into_view',
+};
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, button?: string, clickCount?: number, text?: string, clear?: boolean, submit?: boolean, key?: string, code?: string, modifiers?: string[], checked?: boolean, values?: string[], labels?: string[], indexes?: number[], duration?: number, sourceElementRef?: string, sourceSelector?: string, destinationElementRef?: string, destinationSelector?: string, offsetX?: number, offsetY?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleInputTool(args) {
+  return withToolClient(async (client) => {
+    const requestedTabId = typeof args.tabId === 'number' ? args.tabId : null;
+    const elementTarget = async () => ({
+      elementRef: await resolveToolRef(client, args, requestedTabId),
+    });
+
+    switch (args.action) {
+      case 'click': {
+        const response = await requestBridge(
+          client,
+          'input.click',
+          {
+            target: await elementTarget(),
+            button: args.button,
+            clickCount: args.clickCount,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.click');
+      }
+      case 'focus': {
+        const response = await requestBridge(
+          client,
+          'input.focus',
+          {
+            target: await elementTarget(),
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.focus');
+      }
+      case 'type': {
+        const response = await requestBridge(
+          client,
+          'input.type',
+          {
+            target: await elementTarget(),
+            text: args.text,
+            clear: args.clear,
+            submit: args.submit,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.type');
+      }
+      case 'press_key': {
+        const target = args.elementRef || args.selector ? await elementTarget() : undefined;
+        const response = await requestBridge(
+          client,
+          'input.press_key',
+          {
+            target,
+            key: args.key,
+            modifiers: args.modifiers,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.press_key');
+      }
+      case 'cdp_press_key': {
+        const response = await requestBridge(
+          client,
+          'cdp.dispatch_key_event',
+          {
+            key: args.key,
+            code: args.code,
+            modifiers: args.modifiers,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'cdp.dispatch_key_event');
+      }
+      case 'set_checked': {
+        const response = await requestBridge(
+          client,
+          'input.set_checked',
+          {
+            target: await elementTarget(),
+            checked: args.checked,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.set_checked');
+      }
+      case 'select_option': {
+        const response = await requestBridge(
+          client,
+          'input.select_option',
+          {
+            target: await elementTarget(),
+            values: args.values,
+            labels: args.labels,
+            indexes: args.indexes,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.select_option');
+      }
+      case 'hover': {
+        const response = await requestBridge(
+          client,
+          'input.hover',
+          {
+            target: await elementTarget(),
+            duration: args.duration,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.hover');
+      }
+      case 'drag': {
+        const source = {
+          elementRef:
+            args.sourceElementRef ||
+            (args.sourceSelector
+              ? await resolveRef(client, args.sourceSelector, requestedTabId, REQUEST_SOURCE)
+              : ''),
+        };
+        const destination = {
+          elementRef:
+            args.destinationElementRef ||
+            (args.destinationSelector
+              ? await resolveRef(client, args.destinationSelector, requestedTabId, REQUEST_SOURCE)
+              : ''),
+        };
+        if (!source.elementRef || !destination.elementRef) {
+          return summarizeToolError(
+            'sourceElementRef/sourceSelector and destinationElementRef/destinationSelector are required for drag.'
+          );
+        }
+        const response = await requestBridge(
+          client,
+          'input.drag',
+          {
+            source,
+            destination,
+            offsetX: args.offsetX,
+            offsetY: args.offsetY,
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.drag');
+      }
+      case 'scroll_into_view': {
+        const response = await requestBridge(
+          client,
+          'input.scroll_into_view',
+          {
+            target: await elementTarget(),
+          },
+          {
+            tabId: requestedTabId,
+            source: REQUEST_SOURCE,
+            tokenBudget: getToolTokenBudget(args),
+          }
+        );
+        return summarizeToolResponse(response, 'input.scroll_into_view');
+      }
+      default:
+        return summarizeToolError(`Unsupported input action "${args.action}".`);
+    }
+  });
+}

package/packages/mcp-server/src/handlers-dom.js

@@ -0,0 +1,196 @@
+// @ts-check
+
+import {
+  applyHtmlBudgetPreset,
+  applyTextBudgetPreset,
+  applyTreeBudgetPreset,
+  dispatchToolAction,
+  inferBudgetFromSelector,
+} from './handlers-utils.js';
+
+/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./handlers-utils.js').ToolAction} ToolAction */
+/** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
+
+/** @type {Record<string, ToolAction>} */
+export const DOM_ACTIONS = {
+  query: {
+    ref: false,
+    method: 'dom.query',
+    params: (a) => ({
+      selector: a.selector || 'body',
+      withinRef: a.withinRef,
+      maxNodes: a.maxNodes,
+      maxDepth: a.maxDepth,
+      textBudget: a.textBudget,
+      includeBbox: a.includeBbox,
+      attributeAllowlist: a.attributeAllowlist,
+    }),
+  },
+  describe: {
+    ref: true,
+    method: 'dom.describe',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  text: {
+    ref: true,
+    method: 'dom.get_text',
+    params: (a, r) => ({ elementRef: r, textBudget: a.textBudget }),
+  },
+  attributes: {
+    ref: true,
+    method: 'dom.get_attributes',
+    params: (a, r) => ({ elementRef: r, attributes: a.attributes || [] }),
+  },
+  wait: {
+    ref: false,
+    method: 'dom.wait_for',
+    params: (a) => ({
+      selector: a.selector,
+      text: a.text,
+      state: a.state,
+      timeoutMs: a.timeoutMs,
+    }),
+  },
+  find_text: {
+    ref: false,
+    method: 'dom.find_by_text',
+    params: (a) => ({
+      text: a.text,
+      exact: a.exact,
+      selector: a.selector,
+      maxResults: a.maxResults,
+    }),
+  },
+  find_role: {
+    ref: false,
+    method: 'dom.find_by_role',
+    params: (a) => ({
+      role: a.role,
+      name: a.name,
+      selector: a.selector,
+      maxResults: a.maxResults,
+    }),
+  },
+  html: {
+    ref: true,
+    method: 'dom.get_html',
+    params: (a, r) => ({
+      elementRef: r,
+      outer: a.outer,
+      maxLength: a.maxLength,
+    }),
+  },
+  accessibility_tree: {
+    ref: false,
+    method: 'dom.get_accessibility_tree',
+    params: (a) => ({ maxNodes: a.maxNodes, maxDepth: a.maxDepth }),
+  },
+};
+
+/**
+ * @param {{ action: string, selector?: string, elementRef?: string, withinRef?: string, maxNodes?: number, maxDepth?: number, textBudget?: number, includeBbox?: boolean, attributeAllowlist?: string[], attributes?: string[], text?: string, exact?: boolean, maxResults?: number, role?: string, name?: string, state?: string, timeoutMs?: number, outer?: boolean, maxLength?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleDomTool(args) {
+  if (args.action === 'query' || args.action === 'accessibility_tree') {
+    const inferred = inferBudgetFromSelector(args);
+    const withBudget = inferred ? { ...args, budgetPreset: args.budgetPreset ?? inferred } : args;
+    return dispatchToolAction(DOM_ACTIONS, applyTreeBudgetPreset(withBudget), 'DOM');
+  }
+  if (args.action === 'text') {
+    return dispatchToolAction(DOM_ACTIONS, applyTextBudgetPreset(args), 'DOM');
+  }
+  if (args.action === 'html') {
+    return dispatchToolAction(DOM_ACTIONS, applyHtmlBudgetPreset(args), 'DOM');
+  }
+  return dispatchToolAction(DOM_ACTIONS, args, 'DOM');
+}
+
+/** @type {Record<string, ToolAction>} */
+export const STYLES_LAYOUT_ACTIONS = {
+  computed: {
+    ref: true,
+    method: 'styles.get_computed',
+    params: (a, r) => ({ elementRef: r, properties: a.properties }),
+  },
+  matched_rules: {
+    ref: true,
+    method: 'styles.get_matched_rules',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  box_model: {
+    ref: true,
+    method: 'layout.get_box_model',
+    params: (_, r) => ({ elementRef: r }),
+  },
+  hit_test: {
+    ref: false,
+    method: 'layout.hit_test',
+    params: (a) => ({ x: a.x, y: a.y }),
+  },
+};
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, properties?: string[], x?: number, y?: number, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleStylesLayoutTool(args) {
+  return dispatchToolAction(STYLES_LAYOUT_ACTIONS, args, 'styles/layout');
+}
+
+/** @type {Record<string, ToolAction>} */
+export const PATCH_ACTIONS = {
+  apply_styles: {
+    ref: true,
+    method: 'patch.apply_styles',
+    params: (a, r) => ({
+      target: { elementRef: r },
+      declarations: a.declarations,
+      important: a.important,
+      verify: a.verify,
+    }),
+  },
+  apply_dom: {
+    ref: true,
+    method: 'patch.apply_dom',
+    params: (a, r) => {
+      const operation = typeof a.operation === 'string' ? a.operation : '';
+      /** @type {Record<string, string>} */
+      const opMap = {
+        setAttribute: 'set_attribute',
+        removeAttribute: 'remove_attribute',
+        addClass: 'toggle_class',
+        removeClass: 'toggle_class',
+        setTextContent: 'set_text',
+        setProperty: 'set_attribute',
+      };
+      return {
+        target: { elementRef: r },
+        operation: opMap[operation] || operation,
+        value: a.value,
+        name: a.name,
+        verify: a.verify,
+      };
+    },
+  },
+  list: { ref: false, method: 'patch.list', params: () => ({}) },
+  rollback: {
+    ref: false,
+    method: 'patch.rollback',
+    params: (a) => ({ patchId: a.patchId }),
+  },
+  commit_baseline: {
+    ref: false,
+    method: 'patch.commit_session_baseline',
+    params: () => ({}),
+  },
+};
+
+/**
+ * @param {{ action: string, elementRef?: string, selector?: string, declarations?: Record<string, string>, important?: boolean, operation?: string, value?: unknown, name?: string, patchId?: string, verify?: boolean, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handlePatchTool(args) {
+  return dispatchToolAction(PATCH_ACTIONS, args, 'patch');
+}

package/packages/mcp-server/src/handlers-navigation.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+import { callBridgeTool, getToolTokenBudget, summarizeToolError } from './handlers-utils.js';
+
+/** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
+/** @typedef {import('./handlers-utils.js').ToolResult} ToolResult */
+
+/**
+ * @param {{ action: string, url?: string, active?: boolean, tabId?: number }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleTabsTool(args) {
+  if (args.action === 'list') {
+    return callBridgeTool('tabs.list');
+  }
+  if (args.action === 'create') {
+    return callBridgeTool('tabs.create', {
+      url: args.url,
+      active: args.active,
+    });
+  }
+  if (args.action === 'close') {
+    if (typeof args.tabId !== 'number') {
+      return summarizeToolError('tabId is required for tabs.close.');
+    }
+    return callBridgeTool('tabs.close', { tabId: args.tabId });
+  }
+  return summarizeToolError(`Unsupported tabs action "${args.action}".`);
+}
+
+/** @type {Record<string, { method: BridgeMethod, params: (a: Record<string, unknown>) => Record<string, unknown> }>} */
+export const NAVIGATION_ACTIONS = {
+  navigate: {
+    method: 'navigation.navigate',
+    params: (a) => ({
+      url: a.url,
+      waitForLoad: a.waitForLoad,
+      timeoutMs: a.timeoutMs,
+    }),
+  },
+  reload: {
+    method: 'navigation.reload',
+    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
+  },
+  go_back: {
+    method: 'navigation.go_back',
+    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
+  },
+  go_forward: {
+    method: 'navigation.go_forward',
+    params: (a) => ({ waitForLoad: a.waitForLoad, timeoutMs: a.timeoutMs }),
+  },
+  scroll: {
+    method: 'viewport.scroll',
+    params: (a) => ({
+      top: a.top,
+      left: a.left,
+      behavior: a.behavior,
+      relative: a.relative,
+    }),
+  },
+  resize: {
+    method: 'viewport.resize',
+    params: (a) => ({ width: a.width, height: a.height, reset: a.reset }),
+  },
+};
+
+/**
+ * @param {{ action: string, url?: string, waitForLoad?: boolean, timeoutMs?: number, top?: number, left?: number, behavior?: string, relative?: boolean, width?: number, height?: number, reset?: boolean, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @returns {Promise<ToolResult>}
+ */
+export async function handleNavigationTool(args) {
+  const entry = NAVIGATION_ACTIONS[args.action];
+  if (!entry) return summarizeToolError(`Unsupported navigation action "${args.action}".`);
+  return callBridgeTool(entry.method, entry.params(args), {
+    tabId: typeof args.tabId === 'number' ? args.tabId : null,
+    tokenBudget: getToolTokenBudget(args),
+  });
+}