@browserbridge/bbx 1.9.0 → 1.10.0

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

@@ -11,11 +11,13 @@ import * as z from 'zod/v4';
 
 import {
   handleAccessTool,
+  handleArtifactTool,
   handleCaptureTool,
   handleBatchTool,
   handleDomTool,
   handleHealthTool,
   handleInputTool,
+  handleInterceptTool,
   handleLogTool,
   handleNavigationTool,
   handlePageTool,
@@ -28,9 +30,11 @@ import {
   handleStylesLayoutTool,
   handleTabsTool,
   handleInvestigateTool,
+  createToolResult,
   MAX_BATCH_CALLS,
 } from './handlers.js';
 import {
+  ARTIFACT_CHUNK_BYTES,
   BUDGET_PRESETS,
   DEFAULT_CONSOLE_LIMIT,
   DEFAULT_EVAL_TIMEOUT_MS,
@@ -47,7 +51,8 @@ import {
   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 =
@@ -81,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() {
@@ -108,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',
@@ -128,7 +183,7 @@ export function createBridgeMcpServer() {
     handleStatusTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_setup',
     {
       title: 'Browser Bridge Setup Status',
@@ -143,7 +198,7 @@ export function createBridgeMcpServer() {
     handleSetupTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_logs',
     {
       title: 'Browser Bridge Logs',
@@ -165,7 +220,7 @@ export function createBridgeMcpServer() {
     handleLogTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_health',
     {
       title: 'Browser Bridge Health',
@@ -181,7 +236,7 @@ export function createBridgeMcpServer() {
     handleHealthTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_tabs',
     {
       title: 'Browser Tabs',
@@ -208,7 +263,7 @@ export function createBridgeMcpServer() {
     handleTabsTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_dom',
     {
       title: 'Browser DOM',
@@ -337,7 +392,7 @@ export function createBridgeMcpServer() {
     handleDomTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_styles_layout',
     {
       title: 'Browser Styles And Layout',
@@ -376,7 +431,7 @@ export function createBridgeMcpServer() {
     handleStylesLayoutTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_sensitive_read',
     {
       title: 'Sensitive Browser Read',
@@ -395,7 +450,7 @@ export function createBridgeMcpServer() {
     handleSensitiveReadTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_page',
     {
       title: 'Browser Page State',
@@ -538,7 +593,7 @@ export function createBridgeMcpServer() {
     handlePageTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_navigation',
     {
       title: 'Browser Navigation',
@@ -582,7 +637,7 @@ export function createBridgeMcpServer() {
     handleNavigationTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_input',
     {
       title: 'Browser Input',
@@ -694,7 +749,7 @@ export function createBridgeMcpServer() {
     handleInputTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_patch',
     {
       title: 'Browser Patch',
@@ -745,7 +800,7 @@ export function createBridgeMcpServer() {
     handlePatchTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_capture',
     {
       title: 'Browser Capture',
@@ -822,7 +877,86 @@ export function createBridgeMcpServer() {
     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',
@@ -859,7 +993,7 @@ export function createBridgeMcpServer() {
     handleBatchTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_call',
     {
       title: 'Raw Browser Bridge Call',
@@ -882,7 +1016,7 @@ export function createBridgeMcpServer() {
     handleRawCallTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_skill',
     {
       title: 'Browser Bridge Runtime Context',
@@ -895,7 +1029,7 @@ export function createBridgeMcpServer() {
     handleSkillTool
   );
 
-  server.registerTool(
+  registerTool(
     'browser_access',
     {
       title: 'Request Browser Bridge Access',
@@ -908,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,
@@ -928,7 +1054,7 @@ export function createBridgeMcpServer() {
         openWorldHint: true,
       },
       _meta: {
-        delegationHint: INVESTIGATE_DELEGATION_HINT,
+        delegationHint: createInvestigateDelegationHint(),
       },
       inputSchema: {
         objective: z
@@ -953,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);
+}