@browserbridge/bbx 1.8.0 → 1.10.0

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

@@ -11,14 +11,17 @@ import * as z from 'zod/v4';
 
 import {
   handleAccessTool,
+  handleArtifactTool,
   handleCaptureTool,
   handleBatchTool,
   handleDomTool,
   handleHealthTool,
   handleInputTool,
+  handleInterceptTool,
   handleLogTool,
   handleNavigationTool,
   handlePageTool,
+  handleSensitiveReadTool,
   handlePatchTool,
   handleRawCallTool,
   handleSetupTool,
@@ -27,12 +30,15 @@ import {
   handleStylesLayoutTool,
   handleTabsTool,
   handleInvestigateTool,
+  createToolResult,
   MAX_BATCH_CALLS,
 } from './handlers.js';
 import {
+  ARTIFACT_CHUNK_BYTES,
   BUDGET_PRESETS,
   DEFAULT_CONSOLE_LIMIT,
   DEFAULT_EVAL_TIMEOUT_MS,
+  DEFAULT_HAR_LIMIT,
   DEFAULT_LOG_TAIL_LIMIT,
   DEFAULT_MAX_DEPTH,
   DEFAULT_MAX_HTML_LENGTH,
@@ -41,10 +47,12 @@ import {
   DEFAULT_TEXT_BUDGET,
   DEFAULT_NAV_TIMEOUT_MS,
   DEFAULT_WAIT_TIMEOUT_MS,
+  MAX_HAR_ENTRIES,
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
-import { MCP_SERVER_INSTRUCTIONS } from './guidance.js';
+import { getMcpServerInstructions } from './guidance.js';
+import { isInitiallyEnabledTool, LOADABLE_TOOLSET_TOOLS } from './toolset.js';
 
 export const BUDGET_PRESET_DESCRIPTION = `Budget preset: "quick", "normal", or "deep" (defaults: query ${BUDGET_PRESETS.normal.maxNodes} nodes / depth ${BUDGET_PRESETS.normal.maxDepth} / text ${BUDGET_PRESETS.normal.textBudget}). Numeric fields override the preset when both are provided.`;
 export const TAB_ID_DESCRIPTION =
@@ -78,24 +86,52 @@ const INVESTIGATE_SUBAGENT_BRIDGE_METHODS = Object.freeze(
   )
 );
 
-const INVESTIGATE_DELEGATION_HINT = Object.freeze({
-  recommended: true,
-  costTier: 'low',
-  preferredAgentProfile: {
-    modelClass: 'small',
-    reasoningEffort: 'low',
-  },
-  preferredTools: ['browser_dom', 'browser_page', 'browser_styles_layout', 'browser_batch'],
-  escalationTools: ['browser_capture'],
-  preferredBridgeMethods: INVESTIGATE_SUBAGENT_BRIDGE_METHODS,
-  escalationTriggers: [
-    'Structured DOM or page reads are insufficient.',
-    'Visual confirmation is required.',
-    'Debugger-backed evidence is required.',
-  ],
-});
+const INVESTIGATE_PREFERRED_TOOLS = Object.freeze(['browser_call', 'browser_batch']);
 
 /**
+ * Build the subagent delegation hint for browser_investigate using tools that
+ * are available before any on-demand expansion.
+ */
+function createInvestigateDelegationHint() {
+  return Object.freeze({
+    recommended: true,
+    costTier: 'low',
+    preferredAgentProfile: {
+      modelClass: 'small',
+      reasoningEffort: 'low',
+    },
+    preferredTools: INVESTIGATE_PREFERRED_TOOLS,
+    escalationTools: Object.freeze(['browser_call']),
+    preferredBridgeMethods: INVESTIGATE_SUBAGENT_BRIDGE_METHODS,
+    escalationTriggers: [
+      'Structured DOM or page reads are insufficient.',
+      'Visual confirmation is required.',
+      'Debugger-backed evidence is required.',
+    ],
+  });
+}
+
+/**
+ * Build the browser_investigate description for the progressive tool surface.
+ *
+ * @returns {string}
+ */
+function getInvestigateToolDescription() {
+  return (
+    'Investigate a page to answer a question or verify a condition. ' +
+    'Pass a natural-language objective and an optional scope (quick/normal/deep). ' +
+    'DELEGATION HINT: Prefer delegating this to a smaller, low-cost subagent ' +
+    'that starts with structured reads via browser_call and browser_batch. ' +
+    'Escalate through browser_call only ' +
+    'when structured reads are insufficient. ' +
+    'If subagent delegation is not available, a deterministic heuristic fallback ' +
+    'runs a scripted inspection sequence and returns a best-effort summary.'
+  );
+}
+
+/**
+ * Create the MCP server with a compact initial surface and on-demand typed tools.
+ *
  * @returns {McpServer}
  */
 export function createBridgeMcpServer() {
@@ -105,11 +141,33 @@ export function createBridgeMcpServer() {
       version: MCP_SERVER_VERSION,
     },
     {
-      instructions: MCP_SERVER_INSTRUCTIONS,
+      instructions: getMcpServerInstructions(),
     }
   );
 
-  server.registerTool(
+  /** @type {Map<string, ReturnType<typeof server.registerTool>>} */
+  const registrations = new Map();
+
+  /**
+   * Register a tool, then hide it when it is not part of the initial surface.
+   *
+   * Registering first keeps every call site checked against the SDK's own
+   * generic signature instead of a hand-written passthrough type. Disabling
+   * happens before `connect()`, so an excluded tool never reaches `tools/list`
+   * but can be enabled later by browser_toolset.
+   *
+   * @type {typeof server.registerTool}
+   */
+  const registerTool = (name, config, handler) => {
+    const registration = server.registerTool(name, config, handler);
+    registrations.set(name, registration);
+    if (!isInitiallyEnabledTool(name)) {
+      registration.disable();
+    }
+    return registration;
+  };
+
+  registerTool(
     'browser_status',
     {
       title: 'Browser Bridge Status',
@@ -125,7 +183,7 @@ export function createBridgeMcpServer() {
     handleStatusTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_setup',
     {
       title: 'Browser Bridge Setup Status',
@@ -140,7 +198,7 @@ export function createBridgeMcpServer() {
     handleSetupTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_logs',
     {
       title: 'Browser Bridge Logs',
@@ -162,7 +220,7 @@ export function createBridgeMcpServer() {
     handleLogTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_health',
     {
       title: 'Browser Bridge Health',
@@ -178,7 +236,7 @@ export function createBridgeMcpServer() {
     handleHealthTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_tabs',
     {
       title: 'Browser Tabs',
@@ -205,7 +263,7 @@ export function createBridgeMcpServer() {
     handleTabsTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_dom',
     {
       title: 'Browser DOM',
@@ -215,6 +273,10 @@ export function createBridgeMcpServer() {
         action: z
           .enum([
             'query',
+            'baseline_create',
+            'baseline_compare',
+            'baseline_describe',
+            'baseline_release',
             'describe',
             'text',
             'attributes',
@@ -237,6 +299,14 @@ export function createBridgeMcpServer() {
           .describe(
             'CSS selector (used if no elementRef; accessibility_tree requires exactly one match)'
           ),
+        baselineId: z.string().optional().describe('Opaque semantic DOM baseline identifier'),
+        maxChanges: z
+          .number()
+          .int()
+          .positive()
+          .max(200)
+          .optional()
+          .describe('Maximum returned change examples; exact counts are always retained'),
         elementRef: z
           .string()
           .optional()
@@ -322,7 +392,7 @@ export function createBridgeMcpServer() {
     handleDomTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_styles_layout',
     {
       title: 'Browser Styles And Layout',
@@ -361,12 +431,31 @@ export function createBridgeMcpServer() {
     handleStylesLayoutTool
   );
 
-  server.registerTool(
+  registerTool(
+    'browser_sensitive_read',
+    {
+      title: 'Sensitive Browser Read',
+      description:
+        'High-risk exact-value read for one local or session storage key. This operation is logged as Sensitive access, is never batched or retried, and returns the whole value or fails atomically.',
+      inputSchema: {
+        source: z.enum(['local_storage', 'session_storage']).describe('Exact storage source'),
+        key: z
+          .string()
+          .max(2_048)
+          .describe('Exact storage key, including an empty key if intended'),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+      },
+    },
+    handleSensitiveReadTool
+  );
+
+  registerTool(
     'browser_page',
     {
       title: 'Browser Page State',
       description:
-        'Read page-level data, wait for load/URL conditions, or explicitly inspect/handle JavaScript dialogs. For element-level reads, use browser_dom. evaluate, performance, handle_dialog, and source=cdp network capture are debugger-backed.',
+        'Read page-level data, export captured network evidence as HAR 1.2, wait for load/URL conditions, or explicitly inspect/handle JavaScript dialogs. The performance action returns a raw CDP Performance.getMetrics point sample: Chrome defines names and units, which vary, while BBX sets no navigation observation window and does not measure LCP, CLS, or INP. For element-level reads, use browser_dom. evaluate, performance, handle_dialog, and source=cdp network capture are debugger-backed.',
       inputSchema: {
         action: z
           .enum([
@@ -379,9 +468,12 @@ export function createBridgeMcpServer() {
             'text',
             'extract_content',
             'network',
+            'har',
             'performance',
           ])
-          .describe('Page operation to perform'),
+          .describe(
+            'Page operation to perform; performance reads raw Chrome/CDP counters, not LCP, CLS, or INP'
+          ),
         tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         budgetPreset: z
@@ -434,7 +526,9 @@ export function createBridgeMcpServer() {
           .int()
           .positive()
           .optional()
-          .describe(`Maximum entries to return (default: ${DEFAULT_CONSOLE_LIMIT})`),
+          .describe(
+            `Maximum entries to return (console default: ${DEFAULT_CONSOLE_LIMIT}; HAR default: ${DEFAULT_HAR_LIMIT}, max: ${MAX_HAR_ENTRIES})`
+          ),
         type: z
           .enum(['local', 'session'])
           .optional()
@@ -468,7 +562,11 @@ export function createBridgeMcpServer() {
           .positive()
           .optional()
           .describe('Maximum semantic extraction settlement wait (default: 2000)'),
-        urlPattern: z.string().optional().describe('Filter network entries by URL pattern'),
+        urlPattern: z
+          .string()
+          .max(2_048)
+          .optional()
+          .describe('Bounded URL pattern used to filter network entries or HAR export evidence'),
         source: z
           .enum(['fetch-xhr', 'cdp'])
           .optional()
@@ -477,6 +575,10 @@ export function createBridgeMcpServer() {
           .enum(['read', 'start', 'clear', 'stop'])
           .optional()
           .describe('Explicit CDP capture lifecycle action (default: read)'),
+        delivery: z
+          .enum(['auto', 'inline', 'artifact'])
+          .optional()
+          .describe('HAR delivery mode: auto chooses inline or a daemon-owned artifact'),
         waitForLoad: z
           .boolean()
           .optional()
@@ -491,7 +593,7 @@ export function createBridgeMcpServer() {
     handlePageTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_navigation',
     {
       title: 'Browser Navigation',
@@ -535,7 +637,7 @@ export function createBridgeMcpServer() {
     handleNavigationTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_input',
     {
       title: 'Browser Input',
@@ -626,7 +728,7 @@ export function createBridgeMcpServer() {
           .int()
           .nonnegative()
           .optional()
-          .describe('Hover duration in ms (default: 0)'),
+          .describe('Delay after hover dispatch in ms; does not end hover (default: 0)'),
         sourceElementRef: z.string().optional().describe('Drag source element (for drag action)'),
         sourceSelector: z
           .string()
@@ -647,7 +749,7 @@ export function createBridgeMcpServer() {
     handleInputTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_patch',
     {
       title: 'Browser Patch',
@@ -674,7 +776,14 @@ export function createBridgeMcpServer() {
           .describe('CSS property: value pairs (for apply_styles)'),
         important: z.boolean().optional().describe('Add !important flag (default: false)'),
         operation: z
-          .enum(['setAttribute', 'removeAttribute', 'addClass', 'removeClass', 'setTextContent'])
+          .enum([
+            'setAttribute',
+            'removeAttribute',
+            'addClass',
+            'removeClass',
+            'toggleClass',
+            'setTextContent',
+          ])
           .optional()
           .describe('DOM mutation type'),
         value: z.unknown().optional().describe('Value for the DOM operation'),
@@ -691,7 +800,7 @@ export function createBridgeMcpServer() {
     handlePatchTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_capture',
     {
       title: 'Browser Capture',
@@ -728,6 +837,11 @@ export function createBridgeMcpServer() {
           .positive()
           .optional()
           .describe('CDP node id for cdp_box_model/cdp_computed_styles'),
+        computedStyles: z
+          .array(z.string().min(1).max(128))
+          .max(100)
+          .optional()
+          .describe('CSS property names to include for cdp_dom_snapshot'),
         rect: z
           .object({
             x: z.number().nonnegative().describe('Region left edge (viewport pixels)'),
@@ -748,12 +862,101 @@ export function createBridgeMcpServer() {
           .max(100)
           .optional()
           .describe('JPEG/WebP quality from 0 to 100; ignored for PNG'),
+        delivery: z
+          .enum(['auto', 'inline', 'artifact'])
+          .optional()
+          .describe('Delivery mode: auto chooses inline or a daemon-owned artifact'),
+        scale: z
+          .number()
+          .min(0.1)
+          .max(4)
+          .optional()
+          .describe('Screenshot capture scale (0.1 to 4)'),
       },
     },
     handleCaptureTool
   );
 
-  server.registerTool(
+  registerTool(
+    'browser_artifact',
+    {
+      title: 'Browser Artifact',
+      description:
+        'Read (chunked base64) or delete a daemon-owned artifact produced by artifact delivery (screenshots, HAR exports). Artifacts are scoped to this MCP session and expire quickly. Page reads with offset until nextOffset is null, then verify the reassembled bytes against sha256.',
+      inputSchema: {
+        action: z.enum(['read', 'delete']).describe('Artifact operation to perform'),
+        artifactId: z
+          .string()
+          .min(1)
+          .describe('Artifact identifier returned by a capture or HAR export'),
+        offset: z
+          .number()
+          .int()
+          .nonnegative()
+          .optional()
+          .describe('Byte offset to read from (default: 0)'),
+        limit: z
+          .number()
+          .int()
+          .positive()
+          .max(ARTIFACT_CHUNK_BYTES)
+          .optional()
+          .describe(`Maximum bytes to read in this chunk (default/max: ${ARTIFACT_CHUNK_BYTES})`),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+        budgetPreset: z
+          .enum(['quick', 'normal', 'deep'])
+          .optional()
+          .describe(BUDGET_PRESET_DESCRIPTION),
+      },
+    },
+    handleArtifactTool
+  );
+
+  registerTool(
+    'browser_intercept',
+    {
+      title: 'Browser Network Intercept',
+      description:
+        'Manage CDP Fetch request interception rules: add (block, fulfill, or continue matching requests), list, remove, or clear. Debugger-backed; rules persist until removed or cleared.',
+      inputSchema: {
+        action: z
+          .enum(['add', 'list', 'remove', 'clear'])
+          .describe('Intercept operation to perform'),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
+        destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
+        budgetPreset: z
+          .enum(['quick', 'normal', 'deep'])
+          .optional()
+          .describe(BUDGET_PRESET_DESCRIPTION),
+        urlPattern: z
+          .string()
+          .min(1)
+          .max(2_048)
+          .optional()
+          .describe('URL substring to match (required for add)'),
+        ruleAction: z
+          .enum(['block', 'fulfill', 'continue'])
+          .optional()
+          .describe('How to handle matched requests (default: continue)'),
+        statusCode: z
+          .number()
+          .int()
+          .min(100)
+          .max(599)
+          .optional()
+          .describe('HTTP status for fulfill responses'),
+        body: z.string().optional().describe('Response body for fulfill'),
+        headers: z
+          .record(z.string(), z.string())
+          .optional()
+          .describe('Response headers for fulfill'),
+        ruleId: z.string().min(1).optional().describe('Rule ID (required for remove)'),
+      },
+    },
+    handleInterceptTool
+  );
+
+  registerTool(
     'browser_batch',
     {
       title: 'Browser Bridge Batch',
@@ -790,7 +993,7 @@ export function createBridgeMcpServer() {
     handleBatchTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_call',
     {
       title: 'Raw Browser Bridge Call',
@@ -813,7 +1016,7 @@ export function createBridgeMcpServer() {
     handleRawCallTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_skill',
     {
       title: 'Browser Bridge Runtime Context',
@@ -826,7 +1029,7 @@ export function createBridgeMcpServer() {
     handleSkillTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_access',
     {
       title: 'Request Browser Bridge Access',
@@ -839,19 +1042,11 @@ export function createBridgeMcpServer() {
     handleAccessTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_investigate',
     {
       title: 'Browser Investigate',
-      description:
-        'Investigate a page to answer a question or verify a condition. ' +
-        'Pass a natural-language objective and an optional scope (quick/normal/deep). ' +
-        'DELEGATION HINT: Prefer delegating this to a smaller, low-cost subagent ' +
-        'that starts with structured reads via browser_dom, browser_page, ' +
-        'browser_styles_layout, and browser_batch. Escalate to browser_capture only ' +
-        'when structured reads are insufficient. ' +
-        'If subagent delegation is not available, a deterministic heuristic fallback ' +
-        'runs a scripted inspection sequence and returns a best-effort summary.',
+      description: getInvestigateToolDescription(),
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -859,7 +1054,7 @@ export function createBridgeMcpServer() {
         openWorldHint: true,
       },
       _meta: {
-        delegationHint: INVESTIGATE_DELEGATION_HINT,
+        delegationHint: createInvestigateDelegationHint(),
       },
       inputSchema: {
         objective: z
@@ -884,6 +1079,29 @@ export function createBridgeMcpServer() {
     handleInvestigateTool
   );
 
+  registerTool(
+    'browser_toolset',
+    {
+      title: 'Load Browser Bridge Tool',
+      description:
+        'Load one specialized typed Browser Bridge tool by exact name. The tool appears in tools/list automatically and remains enabled for this MCP session.',
+      inputSchema: {
+        tool: z
+          .enum(LOADABLE_TOOLSET_TOOLS)
+          .describe('Exact specialized Browser Bridge tool to load.'),
+      },
+    },
+    ({ tool }) => {
+      const registration = registrations.get(tool);
+      const newlyEnabled = Boolean(registration && !registration.enabled);
+      if (newlyEnabled) registration?.enable();
+      return createToolResult(newlyEnabled ? `Loaded ${tool}.` : `${tool} is already loaded.`, {
+        tool,
+        newlyEnabled,
+      });
+    }
+  );
+
   return server;
 }
 

package/packages/mcp-server/src/toolset.js

@@ -0,0 +1,48 @@
+// @ts-check
+
+/**
+ * Browser Bridge starts with a compact fixed tool surface. Specialized typed
+ * tools remain registered but disabled until browser_toolset enables one by
+ * exact name. browser_call always keeps the full bridge protocol reachable.
+ */
+
+/** @type {readonly string[]} */
+export const INITIAL_TOOLSET_TOOLS = Object.freeze([
+  'browser_access',
+  'browser_batch',
+  'browser_call',
+  'browser_health',
+  'browser_status',
+  'browser_toolset',
+]);
+
+/** @typedef {'browser_dom' | 'browser_styles_layout' | 'browser_page' | 'browser_logs' | 'browser_input' | 'browser_navigation' | 'browser_tabs' | 'browser_capture' | 'browser_artifact' | 'browser_patch' | 'browser_intercept' | 'browser_investigate' | 'browser_sensitive_read' | 'browser_setup' | 'browser_skill'} LoadableToolName */
+
+/** @type {readonly LoadableToolName[]} */
+export const LOADABLE_TOOLSET_TOOLS = Object.freeze([
+  'browser_dom',
+  'browser_styles_layout',
+  'browser_page',
+  'browser_logs',
+  'browser_input',
+  'browser_navigation',
+  'browser_tabs',
+  'browser_capture',
+  'browser_artifact',
+  'browser_patch',
+  'browser_intercept',
+  'browser_investigate',
+  'browser_sensitive_read',
+  'browser_setup',
+  'browser_skill',
+]);
+
+const INITIAL_TOOLSET = new Set(INITIAL_TOOLSET_TOOLS);
+
+/**
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+export function isInitiallyEnabledTool(toolName) {
+  return INITIAL_TOOLSET.has(toolName);
+}