@browserbridge/bbx 1.10.0 → 1.11.0

package/README.md

@@ -116,7 +116,7 @@ Browser Bridge is optimized for the opposite starting point: **inspect the state
 
 On Ubuntu, Chromium is commonly installed as a strict snap, and Flatpak Chromium is similarly sandboxed. If native messaging stays disconnected there, use a non-sandboxed Chromium-based browser such as Google Chrome, Brave, or Edge.
 
-MCP mode is self-contained: the server exposes tools and startup instructions, so a separate CLI skill is not required for MCP guidance.
+MCP mode is self-contained: the dual-era stdio server supports legacy MCP clients and modern stateless MCP revision `2026-07-28`, and exposes tools and matching startup instructions without requiring a separate CLI skill.
 
 ## How it works
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -73,26 +73,24 @@
     "install-manifest": "node packages/native-host/bin/install-manifest.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.13",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/chrome": "^0.2.2",
-    "@types/node": "^26.1.1",
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@types/chrome": "^0.2.5",
+    "@types/node": "^26.2.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "c8": "^12.0.0",
     "har-schema": "^2.0.0",
-    "oxfmt": "^0.60.0",
-    "oxlint": "^1.75.0",
-    "tsx": "^4.23.1",
+    "oxfmt": "^0.63.0",
+    "oxlint": "^1.78.0",
+    "tsx": "^4.23.12",
     "typescript": "^7.0.2"
   },
-  "overrides": {
-    "@hono/node-server": "2.0.11"
-  },
   "engines": {
     "node": ">=20"
   }

package/packages/agent-client/src/cli-proxy-remote.js

@@ -11,7 +11,7 @@ import {
   readProxyConfig,
 } from '../../native-host/src/config.js';
 import { pingExistingDaemon } from '../../native-host/src/daemon.js';
-import { restartBridgeDaemon } from '../../native-host/src/daemon-process.js';
+import { restartBridgeDaemon, stopBridgeDaemon } from '../../native-host/src/daemon-process.js';
 import { atomicWriteFile } from './atomic-write.js';
 import { parseIntArg } from './cli-helpers.js';
 import {
@@ -44,6 +44,8 @@ export async function handleProxyCommand(args) {
       randomUUID
     );
     assertProxyBindSafety(existing, options, bindHost);
+    // Stop against the current config before changing its port or auth token.
+    const stopResult = await stopBridgeDaemon();
     await atomicWriteFile(getBridgeAuthTokenPath(), `${token}\n`, {
       encoding: 'utf8',
       mode: 0o600,
@@ -75,7 +77,7 @@ export async function handleProxyCommand(args) {
       '',
       `Token: ${token}${tokenNote}`,
       `Config: ${configPath}`,
-      `Daemon: ${result.previouslyRunning ? 'restarted' : 'started'} (pid ${result.pid})`,
+      `Daemon: ${stopResult.previouslyRunning ? 'restarted' : 'started'} (pid ${result.pid})`,
     ];
     if (tokenSource !== 'existing') {
       if (isLoopbackHost(bindHost)) {
@@ -106,10 +108,11 @@ export async function handleProxyCommand(args) {
 
   if (subcommand === 'disable') {
     const configPath = getProxyConfigPath();
+    const stopResult = await stopBridgeDaemon();
     await fs.promises.rm(configPath, { force: true });
-    const result = await restartBridgeDaemon();
+    await restartBridgeDaemon();
     process.stdout.write(
-      `Browser Bridge proxy disabled. Daemon ${result.previouslyRunning ? 'restarted' : 'started'}.\n`
+      `Browser Bridge proxy disabled. Daemon ${stopResult.previouslyRunning ? 'restarted' : 'started'}.\n`
     );
     return;
   }

package/packages/agent-client/src/command-registry.js

@@ -267,7 +267,7 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       'bbx uninstall                                                      Remove native host manifests, Browser Bridge runtime files, and managed MCP/skill installs',
       'bbx install-skill [targets|all] [--global] [--project <path>]      Install/update the managed Browser Bridge CLI skill',
       'bbx install-mcp [client|all] [--local]                             Write MCP config for codex|claude|cursor|copilot|opencode|antigravity|windsurf|agents',
-      '  MCP starts with common tools; browser_toolset loads one specialized typed tool by name when needed.',
+      '  MCP uses a compact surface: legacy clients can load typed tools; modern stateless clients use browser_call.',
       'bbx status                                                         Check bridge connection',
       'bbx doctor                                                         Consolidated local runtime, setup, protocol, and readiness diagnostics',
       'bbx restart                                                        Restart the local daemon and running MCP servers',

package/packages/agent-client/src/npm-self-update.js

@@ -14,6 +14,8 @@ const DEFAULT_LOCK_TIMEOUT_MS = 120_000;
 const UPDATE_LOCK_PORT_START = 49_152;
 const UPDATE_LOCK_PORT_COUNT = 16_384;
 const UPDATE_LOCK_PORT_ATTEMPTS = 32;
+const UPDATE_LOCK_PORT_STEP = UPDATE_LOCK_PORT_COUNT / UPDATE_LOCK_PORT_ATTEMPTS;
+const UNAVAILABLE_LOCK_PORT_CODES = new Set(['EACCES', 'EADDRINUSE']);
 
 /** @typedef {import('./types.js').NpmUpdateResult} NpmUpdateResult */
 
@@ -113,6 +115,7 @@ export async function runNpmCommand(args, options = {}) {
     ? process.execPath
     : npmExecPath || (process.platform === 'win32' ? 'npm.cmd' : 'npm');
   const commandArgs = useNode && npmExecPath ? [npmExecPath, ...args] : args;
+  const useWindowsShell = process.platform === 'win32' && /\.(?:cmd|bat)$/iu.test(command);
 
   return new Promise((resolve, reject) => {
     execFile(
@@ -124,6 +127,7 @@ export async function runNpmCommand(args, options = {}) {
         timeout: options.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,
         maxBuffer: 4 * 1024 * 1024,
         windowsHide: true,
+        shell: useWindowsShell,
       },
       (error, stdout, stderr) => {
         if (!error) {
@@ -154,7 +158,8 @@ export function getNpmUpdateLockPort(lockKey, offset = 0) {
   const digest = createHash('sha256').update(lockKey).digest();
   return (
     UPDATE_LOCK_PORT_START +
-    ((digest.readUInt32BE(0) + Math.max(0, Math.trunc(offset))) % UPDATE_LOCK_PORT_COUNT)
+    ((digest.readUInt32BE(0) + Math.max(0, Math.trunc(offset)) * UPDATE_LOCK_PORT_STEP) %
+      UPDATE_LOCK_PORT_COUNT)
   );
 }
 
@@ -200,7 +205,9 @@ export async function acquireNpmUpdateLock(lockKey, timeoutMs = DEFAULT_LOCK_TIM
       const server = net.createServer((socket) => socket.end(`${identity}\n`));
       const acquired = await new Promise((resolve, reject) => {
         server.once('error', (error) => {
-          if (/** @type {NodeJS.ErrnoException} */ (error).code === 'EADDRINUSE') {
+          if (
+            UNAVAILABLE_LOCK_PORT_CODES.has(/** @type {NodeJS.ErrnoException} */ (error).code ?? '')
+          ) {
             resolve(false);
             return;
           }

package/packages/agent-client/src/runtime.js

@@ -106,7 +106,7 @@ export async function ensureClientConnected(client) {
  * @param {BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} [params={}]
- * @param {{ tabId?: number | null, source?: BridgeRequestSource, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} [options]
+ * @param {{ tabId?: number | null, source?: BridgeRequestSource, mcpEra?: import('./types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} [options]
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridge(client, method, params = {}, options = {}) {
@@ -127,7 +127,12 @@ export async function requestBridge(client, method, params = {}, options = {}) {
     method,
     params,
     tabId: methodNeedsTab(method) ? (options.tabId ?? null) : null,
-    meta: withRequestMeta(options.source, options.tokenBudget, options.automaticRetry),
+    meta: withRequestMeta(
+      options.source,
+      options.mcpEra,
+      options.tokenBudget,
+      options.automaticRetry
+    ),
     ...(timeoutMs === undefined ? {} : { timeoutMs }),
   });
 }
@@ -168,16 +173,20 @@ export async function resolveRef(client, refOrSelector, tabId = null, source) {
 
 /**
  * @param {BridgeRequestSource | undefined} source
+ * @param {import('./types.js').McpProtocolEra | undefined} mcpEra
  * @param {number | null | undefined} tokenBudget
  * @param {'mcp_second_attempt' | undefined} automaticRetry
  * @returns {BridgeMeta}
  */
-function withRequestMeta(source, tokenBudget, automaticRetry) {
+function withRequestMeta(source, mcpEra, tokenBudget, automaticRetry) {
   /** @type {BridgeMeta} */
   const meta = {};
   if (source) {
     meta.source = source;
   }
+  if (source === 'mcp' && mcpEra) {
+    meta.mcp_era = mcpEra;
+  }
   if (typeof tokenBudget === 'number' && Number.isFinite(tokenBudget)) {
     meta.token_budget = tokenBudget;
   }

package/packages/agent-client/src/types.ts

@@ -4,6 +4,7 @@ import type {
   BridgeMethod,
   BridgeRequestSource,
   BridgeResponse,
+  McpProtocolEra,
   RecoveryEventKind,
   RecoveryTelemetrySummary,
   ScreenshotResult,
@@ -17,6 +18,7 @@ export type {
   BridgeRequestSource,
   BridgeResponse,
   BridgeTransport,
+  McpProtocolEra,
   ScreenshotResult,
 };
 

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

@@ -9,7 +9,7 @@ import { startBridgeMcpServer } from './server.js';
 
 /**
  * @typedef {{
- *   start?: () => Promise<void>,
+ *   start?: () => void | Promise<void>,
  *   startControl?: typeof tryStartMcpProcessControl,
  *   argv?: string[],
  *   stdout?: { write: (chunk: string) => unknown },

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

@@ -29,20 +29,26 @@ const WORKFLOW_INSTRUCTIONS = Object.freeze([
 const SERVER_HEADER =
   "Browser Bridge MCP inspects and interacts with the user's real Chrome tab through a compact tool set.";
 
-const TOOL_RULES = Object.freeze([
+const LEGACY_TOOL_RULES = Object.freeze([
   'The common tools are available immediately. When a specialized typed tool is useful, call browser_toolset with its exact tool name; browser_call always reaches every bridge method without loading another tool.',
   'Use browser_call method protocol.describe with method or group params to load unfamiliar signatures cheaply.',
 ]);
 
+const MODERN_TOOL_RULES = Object.freeze([
+  'The compact tool list is static for stateless MCP. browser_call reaches every bridge method, and browser_skill returns runtime groups and limits.',
+  'Use browser_call method protocol.describe with method or group params to load unfamiliar signatures cheaply.',
+]);
+
 /**
- * Build instructions for progressive tool discovery.
+ * Build instructions for the negotiated MCP era.
  *
+ * @param {'legacy' | 'modern'} [era='legacy']
  * @returns {string}
  */
-export function getMcpServerInstructions() {
-  return [SERVER_HEADER, ...TOOL_RULES, ...SHARED_INSTRUCTIONS, ...WORKFLOW_INSTRUCTIONS].join(
-    '\n'
-  );
+export function getMcpServerInstructions(era = 'legacy') {
+  const toolRules = era === 'modern' ? MODERN_TOOL_RULES : LEGACY_TOOL_RULES;
+  return [SERVER_HEADER, ...toolRules, ...SHARED_INSTRUCTIONS, ...WORKFLOW_INSTRUCTIONS].join('\n');
 }
 
 export const MCP_SERVER_INSTRUCTIONS = getMcpServerInstructions();
+export const MODERN_MCP_SERVER_INSTRUCTIONS = getMcpServerInstructions('modern');

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

@@ -1,5 +1,6 @@
 // @ts-check
 
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomUUID } from 'node:crypto';
 
 import {
@@ -46,6 +47,18 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-clie
 
 export const REQUEST_SOURCE = 'mcp';
 const MCP_CLIENT_ID = `mcp_${randomUUID()}`;
+/** @type {AsyncLocalStorage<import('../../protocol/src/types.js').McpProtocolEra>} */
+const MCP_REQUEST_ERA = new AsyncLocalStorage();
+
+/**
+ * @template T
+ * @param {import('../../protocol/src/types.js').McpProtocolEra} era
+ * @param {() => T} callback
+ * @returns {T}
+ */
+export function runWithMcpRequestEra(era, callback) {
+  return MCP_REQUEST_ERA.run(era, callback);
+}
 
 /** @type {ReadonlySet<BridgeMethod>} */
 const RETRY_SAFE_METHODS = new Set([
@@ -606,14 +619,18 @@ export async function waitForClientReconnect(client, timeoutMs = RECONNECT_WAIT_
  * @param {import('../../agent-client/src/client.js').BridgeClient} client
  * @param {BridgeMethod} method
  * @param {Record<string, unknown>} params
- * @param {{ tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} options
+ * @param {{ tabId?: number | null, source?: import('../../protocol/src/types.js').BridgeRequestSource, mcpEra?: import('../../protocol/src/types.js').McpProtocolEra, tokenBudget?: number | null, automaticRetry?: 'mcp_second_attempt' }} options
  * @returns {Promise<BridgeResponse>}
  */
 export async function requestBridgeWithRetry(client, method, params, options) {
+  const requestOptions = {
+    ...options,
+    mcpEra: options.mcpEra ?? MCP_REQUEST_ERA.getStore(),
+  };
   /** @type {BridgeResponse} */
   let response;
   try {
-    response = await requestBridge(client, method, params, options);
+    response = await requestBridge(client, method, params, requestOptions);
   } catch (error) {
     if (!isConnectionLossError(error) || !isRetrySafeBridgeMethod(method, params)) {
       throw error;
@@ -625,7 +642,7 @@ export async function requestBridgeWithRetry(client, method, params, options) {
       throw error;
     }
     return requestBridge(client, method, params, {
-      ...options,
+      ...requestOptions,
       automaticRetry: 'mcp_second_attempt',
     });
   }
@@ -640,7 +657,7 @@ export async function requestBridgeWithRetry(client, method, params, options) {
     );
     await new Promise((r) => setTimeout(r, delay));
     return requestBridge(client, method, params, {
-      ...options,
+      ...requestOptions,
       automaticRetry: 'mcp_second_attempt',
     });
   }

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

@@ -11,6 +11,7 @@ import {
   getToolTokenBudget,
   getBridgeDestinations,
   applyLimitBudgetPreset,
+  requestBridgeWithRetry,
   summarizeToolError,
   summarizeToolResponse,
   withToolClient,
@@ -34,6 +35,7 @@ export {
   callBridgeTool,
   dispatchToolAction,
   REQUEST_SOURCE,
+  runWithMcpRequestEra,
 } from './handlers-utils.js';
 
 export {
@@ -233,10 +235,14 @@ export async function handleHealthTool(args = {}) {
   const destinationId = typeof args.destinationId === 'string' ? args.destinationId : null;
   return withToolClient(
     async (client) => {
-      const response = await client.request({
-        method: 'health.ping',
-        meta: { source: REQUEST_SOURCE },
-      });
+      const response = await requestBridgeWithRetry(
+        client,
+        'health.ping',
+        {},
+        {
+          source: REQUEST_SOURCE,
+        }
+      );
       return summarizeToolResponse(response, 'health.ping');
     },
     { destinationId }

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

@@ -2,9 +2,9 @@
 
 import fs from 'node:fs';
 
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-// zod is required at runtime by @modelcontextprotocol/sdk for tool parameter schema
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+// zod is required at runtime by @modelcontextprotocol/server for tool parameter schema
 // declarations (z.object, z.string, etc.). It is not used for request/response
 // validation - that is handled by the protocol package.
 import * as z from 'zod/v4';
@@ -32,6 +32,7 @@ import {
   handleInvestigateTool,
   createToolResult,
   MAX_BATCH_CALLS,
+  runWithMcpRequestEra,
 } from './handlers.js';
 import {
   ARTIFACT_CHUNK_BYTES,
@@ -52,7 +53,7 @@ import {
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
 import { getMcpServerInstructions } from './guidance.js';
-import { isInitiallyEnabledTool, LOADABLE_TOOLSET_TOOLS } from './toolset.js';
+import { isToolEnabledForEra, 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 =
@@ -130,18 +131,20 @@ function getInvestigateToolDescription() {
 }
 
 /**
- * Create the MCP server with a compact initial surface and on-demand typed tools.
+ * Create the MCP server for one negotiated protocol era.
  *
+ * @param {{ era?: 'legacy' | 'modern' }} [options]
  * @returns {McpServer}
  */
-export function createBridgeMcpServer() {
+export function createBridgeMcpServer(options = {}) {
+  const { era = 'legacy' } = options;
   const server = new McpServer(
     {
       name: 'browser-bridge',
       version: MCP_SERVER_VERSION,
     },
     {
-      instructions: getMcpServerInstructions(),
+      instructions: getMcpServerInstructions(era),
     }
   );
 
@@ -149,19 +152,31 @@ export function createBridgeMcpServer() {
   const registrations = new Map();
 
   /**
-   * Register a tool, then hide it when it is not part of the initial surface.
+   * Register a tool, then hide it when it is not part of the era's compact 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.
+   * happens before `connect()`, so an excluded tool never reaches `tools/list`.
    *
-   * @type {typeof server.registerTool}
+   * @template {z.ZodObject} InputSchema
+   * @param {string} name
+   * @param {{
+   *   title?: string,
+   *   description?: string,
+   *   inputSchema: InputSchema,
+   *   annotations?: import('@modelcontextprotocol/server').ToolAnnotations,
+   *   _meta?: Record<string, unknown>,
+   * }} config
+   * @param {import('@modelcontextprotocol/server').AnyToolHandler<InputSchema>} handler
+   * @returns {ReturnType<typeof server.registerTool>}
    */
   const registerTool = (name, config, handler) => {
-    const registration = server.registerTool(name, config, handler);
+    const wrappedHandler = /** @type {typeof handler} */ (
+      (args, context) => runWithMcpRequestEra(era, () => handler(args, context))
+    );
+    const registration = server.registerTool(name, config, wrappedHandler);
     registrations.set(name, registration);
-    if (!isInitiallyEnabledTool(name)) {
+    if (!isToolEnabledForEra(name, era)) {
       registration.disable();
     }
     return registration;
@@ -173,12 +188,12 @@ export function createBridgeMcpServer() {
       title: 'Browser Bridge Status',
       description:
         'Check bridge readiness: daemon connectivity, extension state, and window access. Omit destinationId to inspect local and configured remote destinations. If access is not enabled, ask the user to click Enable in the extension popup or side panel, then retry.',
-      inputSchema: {
+      inputSchema: z.object({
         destinationId: z
           .string()
           .optional()
           .describe('Inspect one destination instead of aggregating all configured destinations.'),
-      },
+      }),
     },
     handleStatusTool
   );
@@ -188,12 +203,12 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Bridge Setup Status',
       description: 'Check MCP and CLI skill installation status for agent integration.',
-      inputSchema: {
+      inputSchema: z.object({
         global: z
           .boolean()
           .optional()
           .describe('Check global (true) or local (false) config (default: true)'),
-      },
+      }),
     },
     handleSetupTool
   );
@@ -203,7 +218,7 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Bridge Logs',
       description: 'Tail recent bridge request logs for debugging connection or routing issues.',
-      inputSchema: {
+      inputSchema: z.object({
         limit: z
           .number()
           .int()
@@ -215,7 +230,7 @@ export function createBridgeMcpServer() {
           .optional()
           .describe(BUDGET_PRESET_DESCRIPTION),
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
-      },
+      }),
     },
     handleLogTool
   );
@@ -225,13 +240,13 @@ export function createBridgeMcpServer() {
     {
       title: 'Browser Bridge Health',
       description: 'Ping the bridge to verify daemon and extension connectivity.',
-      inputSchema: {
+      inputSchema: z.object({
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
         intent: z
           .enum(['inspect', 'interact', 'capture', 'navigate', 'debugger', 'general'])
           .optional()
           .describe('Reported operation family shown in the access prompt (defaults to general).'),
-      },
+      }),
     },
     handleHealthTool
   );
@@ -242,7 +257,7 @@ export function createBridgeMcpServer() {
       title: 'Browser Tabs',
       description:
         'List, create, close, or activate browser tabs. List without destinationId aggregates configured destinations; other actions default to local. Only create a page when the user explicitly requests it.',
-      inputSchema: {
+      inputSchema: z.object({
         action: z
           .enum(['list', 'create', 'close', 'activate'])
           .describe('"list" (preferred), "create" (only when needed), "close", or "activate"'),
@@ -258,7 +273,7 @@ export function createBridgeMcpServer() {
           .string()
           .optional()
           .describe('Target one destination; list without it aggregates configured destinations.'),
-      },
+      }),
     },
     handleTabsTool
   );
@@ -269,7 +284,7 @@ export function createBridgeMcpServer() {
       title: 'Browser DOM',
       description:
         'Query, describe, read, search, or wait for DOM elements. Reuse elementRef from prior results. For full-page text, use browser_page action "text". accessibility_tree is debugger-backed and depth-limited - use query/find first.',
-      inputSchema: {
+      inputSchema: z.object({
         action: z
           .enum([
             'query',
@@ -387,7 +402,7 @@ export function createBridgeMcpServer() {
           .positive()
           .optional()
           .describe(`Max HTML chars to return (default: ${DEFAULT_MAX_HTML_LENGTH})`),
-      },
+      }),
     },
     handleDomTool
   );
@@ -398,7 +413,7 @@ export function createBridgeMcpServer() {
       title: 'Browser Styles And Layout',
       description:
         'Read computed styles, matched CSS rules, box model, or hit-test a viewport point. Reuse elementRef from prior queries. For DOM structure, use browser_dom.',
-      inputSchema: {
+      inputSchema: z.object({
         action: z
           .enum(['computed', 'matched_rules', 'box_model', 'hit_test'])
           .describe('Style/layout operation to perform'),
@@ -426,7 +441,7 @@ export function createBridgeMcpServer() {
           .nonnegative()
           .optional()
           .describe('Y coordinate for hit_test (viewport relative)'),
-      },
+      }),
     },
     handleStylesLayoutTool
   );
@@ -437,7 +452,7 @@ export function createBridgeMcpServer() {
       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: {
+      inputSchema: z.object({
         source: z.enum(['local_storage', 'session_storage']).describe('Exact storage source'),
         key: z
           .string()
@@ -445,7 +460,7 @@ export function createBridgeMcpServer() {
           .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
   );
@@ -456,7 +471,7 @@ export function createBridgeMcpServer() {
       title: 'Browser Page State',
       description:
         '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: {
+      inputSchema: z.object({
         action: z
           .enum([
             'state',
@@ -588,7 +603,7 @@ export function createBridgeMcpServer() {
           .enum(['exact', 'contains', 'regex'])
           .optional()
           .describe('URL match mode for wait_for_load (default: exact)'),
-      },
+      }),
     },
     handlePageTool
   );
@@ -599,7 +614,7 @@ export function createBridgeMcpServer() {
       title: 'Browser Navigation',
       description:
         'Navigate to a URL, reload, go back/forward, scroll, or resize the viewport. resize is debugger-backed - use only for exact viewport overrides.',
-      inputSchema: {
+      inputSchema: z.object({
         action: z
           .enum(['navigate', 'reload', 'go_back', 'go_forward', 'scroll', 'resize'])
           .describe('Navigation operation to perform'),
@@ -632,7 +647,7 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Viewport device scale factor (for resize)'),
         reset: z.boolean().optional().describe('Reset viewport to original size (for resize)'),
-      },
+      }),
     },
     handleNavigationTool
   );
@@ -643,7 +658,7 @@ export function createBridgeMcpServer() {
       title: 'Browser Input',
       description:
         'Dispatch browser input. Targeted click, focus, type, fill, press_key, set_checked, select_option, hover, and drag actions perform actionability checks and report resolution/execution metadata. cdp_press_key and scroll_into_view use separate contracts. Reuse elementRef values and verify application state after mutations.',
-      inputSchema: {
+      inputSchema: z.object({
         action: z
           .enum([
             'click',
@@ -744,7 +759,7 @@ export function createBridgeMcpServer() {
           .describe('Drag destination selector (alternative to destinationElementRef)'),
         offsetX: z.number().optional().describe('Drag drop offset X (default: 0)'),
         offsetY: z.number().optional().describe('Drag drop offset Y (default: 0)'),
-      },
+      }),
     },
     handleInputTool
   );
@@ -755,7 +770,7 @@ export function createBridgeMcpServer() {
       title: 'Browser Patch',
       description:
         'Apply or rollback document-local style and DOM patches for live prototyping before editing source. commit_baseline keeps current changes but discards rollback history. Set verify=true to get computed results inline.',
-      inputSchema: {
+      inputSchema: z.object({
         action: z
           .enum(['apply_styles', 'apply_dom', 'list', 'rollback', 'commit_baseline'])
           .describe('Patch operation to perform'),
@@ -795,7 +810,7 @@ export function createBridgeMcpServer() {
           .describe(
             'Return computed result inline after applying, eliminating a verification round-trip'
           ),
-      },
+      }),
     },
     handlePatchTool
   );
@@ -806,7 +821,7 @@ export function createBridgeMcpServer() {
       title: 'Browser Capture',
       description:
         'Capture screenshots or CDP snapshots. Debugger-backed and token-expensive - use only when structured reads (browser_dom, browser_styles_layout) are insufficient. Prefer element, then tight region; full_page only for document-level context.',
-      inputSchema: {
+      inputSchema: z.object({
         action: z
           .enum([
             'element',
@@ -872,7 +887,7 @@ export function createBridgeMcpServer() {
           .max(4)
           .optional()
           .describe('Screenshot capture scale (0.1 to 4)'),
-      },
+      }),
     },
     handleCaptureTool
   );
@@ -882,8 +897,8 @@ export function createBridgeMcpServer() {
     {
       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: {
+        'Read (chunked base64) or delete a daemon-owned artifact produced by artifact delivery (screenshots, HAR exports). Artifacts are scoped to the current local MCP process and expire quickly. Page reads with offset until nextOffset is null, then verify the reassembled bytes against sha256.',
+      inputSchema: z.object({
         action: z.enum(['read', 'delete']).describe('Artifact operation to perform'),
         artifactId: z
           .string()
@@ -907,7 +922,7 @@ export function createBridgeMcpServer() {
           .enum(['quick', 'normal', 'deep'])
           .optional()
           .describe(BUDGET_PRESET_DESCRIPTION),
-      },
+      }),
     },
     handleArtifactTool
   );
@@ -918,7 +933,7 @@ export function createBridgeMcpServer() {
       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: {
+      inputSchema: z.object({
         action: z
           .enum(['add', 'list', 'remove', 'clear'])
           .describe('Intercept operation to perform'),
@@ -951,7 +966,7 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Response headers for fulfill'),
         ruleId: z.string().min(1).optional().describe('Rule ID (required for remove)'),
-      },
+      }),
     },
     handleInterceptTool
   );
@@ -968,7 +983,7 @@ export function createBridgeMcpServer() {
         idempotentHint: true,
         openWorldHint: true,
       },
-      inputSchema: {
+      inputSchema: z.object({
         calls: z
           .array(
             z.object({
@@ -988,7 +1003,7 @@ export function createBridgeMcpServer() {
           .min(1)
           .max(MAX_BATCH_CALLS)
           .describe('Calls to execute in parallel'),
-      },
+      }),
     },
     handleBatchTool
   );
@@ -999,7 +1014,7 @@ export function createBridgeMcpServer() {
       title: 'Raw Browser Bridge Call',
       description:
         'Primary Browser Bridge tool for permission-ask hosts: call any bridge method directly by name so the user can approve one BBX MCP tool instead of each specialized tool separately.',
-      inputSchema: {
+      inputSchema: z.object({
         method: z.string().describe('Bridge method name (e.g., "dom.query", "input.click")'),
         params: z
           .record(z.string(), z.unknown())
@@ -1011,7 +1026,7 @@ export function createBridgeMcpServer() {
           .enum(['quick', 'normal', 'deep'])
           .optional()
           .describe(BUDGET_PRESET_DESCRIPTION),
-      },
+      }),
     },
     handleRawCallTool
   );
@@ -1022,9 +1037,9 @@ export function createBridgeMcpServer() {
       title: 'Browser Bridge Runtime Context',
       description:
         'Return runtime context: budget presets, method groups, and active limits. Call to discover defaults before inspecting a page.',
-      inputSchema: {
+      inputSchema: z.object({
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
-      },
+      }),
     },
     handleSkillTool
   );
@@ -1035,9 +1050,9 @@ export function createBridgeMcpServer() {
       title: 'Request Browser Bridge Access',
       description:
         'Request window access for Browser Bridge. Surfaces an Enable prompt in the extension popup or side panel. Use once per window; if access is already pending, ask the user to enable that window instead of requesting again.',
-      inputSchema: {
+      inputSchema: z.object({
         destinationId: z.string().optional().describe(DESTINATION_ID_DESCRIPTION),
-      },
+      }),
     },
     handleAccessTool
   );
@@ -1056,7 +1071,7 @@ export function createBridgeMcpServer() {
       _meta: {
         delegationHint: createInvestigateDelegationHint(),
       },
-      inputSchema: {
+      inputSchema: z.object({
         objective: z
           .string()
           .describe('What to find, verify, or extract from the current page (natural language).'),
@@ -1074,7 +1089,7 @@ export function createBridgeMcpServer() {
           .string()
           .optional()
           .describe('Optional CSS selector to scope the investigation to a subtree.'),
-      },
+      }),
     },
     handleInvestigateTool
   );
@@ -1084,12 +1099,12 @@ export function createBridgeMcpServer() {
     {
       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: {
+        'Load one specialized typed Browser Bridge tool by exact name. The tool appears in tools/list automatically and remains enabled for this legacy MCP connection.',
+      inputSchema: z.object({
         tool: z
           .enum(LOADABLE_TOOLSET_TOOLS)
           .describe('Exact specialized Browser Bridge tool to load.'),
-      },
+      }),
     },
     ({ tool }) => {
       const registration = registrations.get(tool);
@@ -1106,11 +1121,11 @@ export function createBridgeMcpServer() {
 }
 
 /**
- * @returns {Promise<void>}
+ * @param {{ serve?: typeof serveStdio }} [options]
+ * @returns {void}
  */
-export async function startBridgeMcpServer() {
+export function startBridgeMcpServer(options = {}) {
+  const { serve = serveStdio } = options;
   applyWindowsTcpTransportDefaults();
-  const server = createBridgeMcpServer();
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  serve(({ era }) => createBridgeMcpServer({ era }));
 }

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

@@ -16,6 +16,21 @@ export const INITIAL_TOOLSET_TOOLS = Object.freeze([
   'browser_toolset',
 ]);
 
+/**
+ * Modern MCP tool lists cannot change as a side effect of another request.
+ * Keep the compact surface static and use browser_call for full protocol reach.
+ *
+ * @type {readonly string[]}
+ */
+export const MODERN_TOOLSET_TOOLS = Object.freeze([
+  'browser_access',
+  'browser_batch',
+  'browser_call',
+  'browser_health',
+  'browser_skill',
+  'browser_status',
+]);
+
 /** @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[]} */
@@ -38,6 +53,7 @@ export const LOADABLE_TOOLSET_TOOLS = Object.freeze([
 ]);
 
 const INITIAL_TOOLSET = new Set(INITIAL_TOOLSET_TOOLS);
+const MODERN_TOOLSET = new Set(MODERN_TOOLSET_TOOLS);
 
 /**
  * @param {string} toolName
@@ -46,3 +62,12 @@ const INITIAL_TOOLSET = new Set(INITIAL_TOOLSET_TOOLS);
 export function isInitiallyEnabledTool(toolName) {
   return INITIAL_TOOLSET.has(toolName);
 }
+
+/**
+ * @param {string} toolName
+ * @param {'legacy' | 'modern'} era
+ * @returns {boolean}
+ */
+export function isToolEnabledForEra(toolName, era) {
+  return era === 'modern' ? MODERN_TOOLSET.has(toolName) : INITIAL_TOOLSET.has(toolName);
+}

package/packages/native-host/src/daemon.js

@@ -60,7 +60,7 @@ setProtocolPackageVersion(DAEMON_VERSION);
 /** @typedef {import('./daemon-logger.js').DaemonLoggerLike} DaemonLoggerLike */
 /** @typedef {'agent' | 'extension'} SocketRole */
 /** @typedef {import('node:net').Socket & { readonly __role?: SocketRole, __clientId?: string, __extensionId?: string, __browserName?: string, __profileLabel?: string, __browserExtensionId?: string, __accessEnabled?: boolean, __lastActiveAt?: number }} ClientSocket */
-/** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, method?: string, protocolVersion?: string, baselineId?: string | null, automaticMcpRetry?: boolean, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
+/** @typedef {{ socket: ClientSocket, timeoutId: NodeJS.Timeout, source?: string, mcpEra?: string, method?: string, protocolVersion?: string, baselineId?: string | null, automaticMcpRetry?: boolean, targets: Set<ClientSocket>, lastErrorResponse?: import('../../protocol/src/types.js').BridgeResponse }} PendingEntry */
 /**
  * @typedef {{
  *   installAgentFiles: typeof import('../../agent-client/src/install.js').installAgentFiles,
@@ -1165,6 +1165,7 @@ export class BridgeDaemon {
       method: request.method,
       protocolVersion: request.meta?.protocol_version,
       source: typeof request.meta?.source === 'string' ? request.meta.source : '',
+      mcpEra: typeof request.meta?.mcp_era === 'string' ? request.meta.mcp_era : '',
       baselineId,
       automaticMcpRetry: isAutomaticMcpRetry(request.meta),
       targets: new Set([target]),
@@ -1603,6 +1604,7 @@ export class BridgeDaemon {
         ok: true,
         id: responseMessage.id,
         source: pending.source || null,
+        ...(pending.mcpEra ? { mcpEra: pending.mcpEra } : {}),
       });
       return;
     }
@@ -1702,6 +1704,7 @@ export class BridgeDaemon {
       ok: false,
       id: requestId,
       source: pending.source || null,
+      ...(pending.mcpEra ? { mcpEra: pending.mcpEra } : {}),
     });
 
     await writeJsonLine(pending.socket, {

package/packages/protocol/src/protocol.js

@@ -372,11 +372,21 @@ export function validateBridgeRequest(request) {
         typeof meta.protocol_version === 'string' ? meta.protocol_version : getProtocolVersion(),
       token_budget: typeof meta.token_budget === 'number' ? meta.token_budget : null,
       source: meta.source === 'cli' || meta.source === 'mcp' ? meta.source : undefined,
+      mcp_era: normalizeMcpEra(meta.source, meta.mcp_era),
       automatic_retry: normalizeAutomaticRetryMeta(meta.source, meta.automatic_retry),
     },
   };
 }
 
+/**
+ * @param {unknown} source
+ * @param {unknown} value
+ * @returns {import('./types.js').McpProtocolEra | undefined}
+ */
+function normalizeMcpEra(source, value) {
+  return source === 'mcp' && (value === 'legacy' || value === 'modern') ? value : undefined;
+}
+
 /**
  * @param {unknown} source
  * @param {unknown} value

package/packages/protocol/src/types.ts

@@ -1,4 +1,5 @@
 export type BridgeRequestSource = 'cli' | 'mcp';
+export type McpProtocolEra = 'legacy' | 'modern';
 
 export type AccessIntent = 'inspect' | 'interact' | 'capture' | 'navigate' | 'debugger' | 'general';
 
@@ -153,6 +154,7 @@ export interface BridgeMeta {
   image_approx_tokens?: number;
   image_bytes?: number;
   source?: BridgeRequestSource;
+  mcp_era?: McpProtocolEra;
   response_bytes?: number;
   approx_tokens?: number;
   cost_class?: CostClass;

package/skills/browser-bridge/SKILL.md

@@ -15,7 +15,7 @@ Skill name: `browser-bridge` (also known as `bbx`). In GitHub Copilot, invoke as
 When the runtime supports subagents, delegate bridge inspection to a smaller, lower-cost worker and return only concise findings to the parent.
 For open-ended investigation, start with structured reads (`page.get_state`, `dom.query`, `page.get_text`, `page.extract_content`, `styles.get_computed`, and `bbx batch` for CLI or `browser_batch` for MCP) and escalate to screenshots or debugger-backed methods only when structured evidence is insufficient. `browser_call` accepts one protocol method at a time; `batch` is not a valid `browser_call` method.
 When an unfamiliar method is needed, run `bbx protocol describe <method|group>` before guessing parameters. In MCP mode, call `browser_call` with method `protocol.describe` and params `{ "method": "dom.query" }` or `{ "group": "inspect" }`.
-MCP exposes common tools first. Load one specialized typed tool only when needed by calling `browser_toolset` with its exact name, for example `{ "tool": "browser_dom" }`; `browser_call` remains the universal fallback.
+MCP exposes a compact tool surface. If `browser_toolset` is available on a legacy connection, load one specialized typed tool only when needed, for example `{ "tool": "browser_dom" }`. Modern stateless connections use a fixed surface with `browser_skill` instead. `browser_call` remains the universal path in both eras.
 
 ## CLI