@browserbridge/bbx 1.3.0 → 1.5.0

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

@@ -1,5 +1,7 @@
 // @ts-check
 
+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
@@ -38,11 +40,27 @@ import {
   getMethodsByMaxComplexity,
 } from '../../protocol/src/index.js';
 import { applyWindowsTcpTransportDefaults } from '../../native-host/src/config.js';
+import { MCP_SERVER_INSTRUCTIONS, registerBridgeMcpGuidance } from './guidance.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 =
   'Target a specific tab instead of the active tab in the enabled window.';
 
+const MCP_SERVER_VERSION = loadPackageVersion();
+
+/**
+ * @returns {string}
+ */
+function loadPackageVersion() {
+  try {
+    const raw = fs.readFileSync(new URL('../../../package.json', import.meta.url), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed.version === 'string' ? parsed.version : '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
 /** @type {readonly import('../../protocol/src/types.js').BridgeMethod[]} */
 const INVESTIGATE_SUBAGENT_BRIDGE_METHODS = Object.freeze(
   getMethodsByMaxComplexity('low').filter(
@@ -75,10 +93,15 @@ const INVESTIGATE_DELEGATION_HINT = Object.freeze({
  * @returns {McpServer}
  */
 export function createBridgeMcpServer() {
-  const server = new McpServer({
-    name: 'browser-bridge',
-    version: '1.0.0',
-  });
+  const server = new McpServer(
+    {
+      name: 'browser-bridge',
+      version: MCP_SERVER_VERSION,
+    },
+    {
+      instructions: MCP_SERVER_INSTRUCTIONS,
+    }
+  );
 
   server.registerTool(
     'browser_status',
@@ -114,6 +137,8 @@ export function createBridgeMcpServer() {
       inputSchema: {
         limit: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Maximum log entries to return (default: ${DEFAULT_CONSOLE_LIMIT})`),
         budgetPreset: z
@@ -147,7 +172,7 @@ export function createBridgeMcpServer() {
           .describe('"list" (preferred), "create" (only when needed), or "close"'),
         url: z.string().optional().describe('URL for create action'),
         active: z.boolean().optional().describe('Focus the new tab (default: true)'),
-        tabId: z.number().optional().describe('Tab ID (required for close)'),
+        tabId: z.number().int().positive().optional().describe('Tab ID (required for close)'),
       },
     },
     handleTabsTool
@@ -173,7 +198,7 @@ export function createBridgeMcpServer() {
             'accessibility_tree',
           ])
           .describe('DOM operation to perform'),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -189,14 +214,20 @@ export function createBridgeMcpServer() {
         withinRef: z.string().optional().describe('Scope query to this elementRef subtree'),
         maxNodes: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Maximum nodes to return (default: ${DEFAULT_MAX_NODES})`),
         maxDepth: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Maximum tree depth (default: ${DEFAULT_MAX_DEPTH})`),
         textBudget: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Max chars of text content per node (default: ${DEFAULT_TEXT_BUDGET})`),
         includeBbox: z
@@ -216,7 +247,12 @@ export function createBridgeMcpServer() {
           .boolean()
           .optional()
           .describe('Require exact text match (default: false, substring match)'),
-        maxResults: z.number().optional().describe('Maximum search results (default: 10)'),
+        maxResults: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Maximum search results (default: 10)'),
         role: z.string().optional().describe('ARIA role to search for (for find_role action)'),
         name: z.string().optional().describe('Accessible name to match with role'),
         state: z
@@ -225,6 +261,8 @@ export function createBridgeMcpServer() {
           .describe('Expected element state (for wait action)'),
         timeoutMs: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Timeout for wait operations (default: ${DEFAULT_WAIT_TIMEOUT_MS})`),
         outer: z
@@ -233,6 +271,8 @@ export function createBridgeMcpServer() {
           .describe('Return outerHTML instead of innerHTML (default: false)'),
         maxLength: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Max HTML chars to return (default: ${DEFAULT_MAX_HTML_LENGTH})`),
       },
@@ -250,7 +290,7 @@ export function createBridgeMcpServer() {
         action: z
           .enum(['computed', 'matched_rules', 'box_model', 'hit_test'])
           .describe('Style/layout operation to perform'),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -261,8 +301,16 @@ export function createBridgeMcpServer() {
           .array(z.string())
           .optional()
           .describe('Style properties to fetch (omitting returns all - expensive)'),
-        x: z.number().optional().describe('X coordinate for hit_test (viewport relative)'),
-        y: z.number().optional().describe('Y coordinate for hit_test (viewport relative)'),
+        x: z
+          .number()
+          .nonnegative()
+          .optional()
+          .describe('X coordinate for hit_test (viewport relative)'),
+        y: z
+          .number()
+          .nonnegative()
+          .optional()
+          .describe('Y coordinate for hit_test (viewport relative)'),
       },
     },
     handleStylesLayoutTool
@@ -287,7 +335,7 @@ export function createBridgeMcpServer() {
             'performance',
           ])
           .describe('Page operation to perform'),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -299,6 +347,8 @@ export function createBridgeMcpServer() {
         awaitPromise: z.boolean().optional().describe('Await returned promises (default: false)'),
         timeoutMs: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Timeout for evaluate/wait operations (default: ${DEFAULT_WAIT_TIMEOUT_MS})`),
         returnByValue: z
@@ -312,6 +362,8 @@ export function createBridgeMcpServer() {
         clear: z.boolean().optional().describe('Clear buffer after reading (default: false)'),
         limit: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Maximum entries to return (default: ${DEFAULT_CONSOLE_LIMIT})`),
         type: z
@@ -324,6 +376,8 @@ export function createBridgeMcpServer() {
           .describe('Specific storage keys to fetch (omitting returns all)'),
         textBudget: z
           .number()
+          .int()
+          .positive()
           .optional()
           .describe(`Max chars for page text (default: ${DEFAULT_PAGE_TEXT_BUDGET})`),
         urlPattern: z.string().optional().describe('Filter network entries by URL pattern'),
@@ -342,14 +396,19 @@ export function createBridgeMcpServer() {
         action: z
           .enum(['navigate', 'reload', 'go_back', 'go_forward', 'scroll', 'resize'])
           .describe('Navigation operation to perform'),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
           .describe(BUDGET_PRESET_DESCRIPTION),
         url: z.string().optional().describe('URL to navigate to (for navigate action)'),
         waitForLoad: z.boolean().optional().describe('Wait for load event (default: true)'),
-        timeoutMs: z.number().optional().describe('Timeout for navigation (default: 30000)'),
+        timeoutMs: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('Timeout for navigation (default: 30000)'),
         top: z.number().optional().describe('Scroll target Y position (pixels)'),
         left: z.number().optional().describe('Scroll target X position (pixels)'),
         behavior: z.enum(['auto', 'smooth']).optional().describe('Scroll behavior (default: auto)'),
@@ -357,8 +416,13 @@ export function createBridgeMcpServer() {
           .boolean()
           .optional()
           .describe('Scroll relative to current position (default: false)'),
-        width: z.number().optional().describe('Viewport width in pixels'),
-        height: z.number().optional().describe('Viewport height in pixels'),
+        width: z.number().int().positive().optional().describe('Viewport width in pixels'),
+        height: z.number().int().positive().optional().describe('Viewport height in pixels'),
+        deviceScaleFactor: z
+          .number()
+          .nonnegative()
+          .optional()
+          .describe('Viewport device scale factor (for resize)'),
         reset: z.boolean().optional().describe('Reset viewport to original size (for resize)'),
       },
     },
@@ -386,7 +450,7 @@ export function createBridgeMcpServer() {
             'scroll_into_view',
           ])
           .describe('Input operation to perform'),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -400,7 +464,13 @@ export function createBridgeMcpServer() {
           .enum(['left', 'middle', 'right'])
           .optional()
           .describe('Mouse button for click (default: left)'),
-        clickCount: z.number().optional().describe('Click count (1=single, 2=double)'),
+        clickCount: z
+          .number()
+          .int()
+          .min(1)
+          .max(2)
+          .optional()
+          .describe('Click count (1=single, 2=double)'),
         text: z.string().max(100000).optional().describe('Text to type (for type action)'),
         clear: z.boolean().optional().describe('Clear field before typing (default: false)'),
         submit: z.boolean().optional().describe('Press Enter after typing (default: false)'),
@@ -423,10 +493,15 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Option labels to select (alternative to values)'),
         indexes: z
-          .array(z.number())
+          .array(z.number().int().nonnegative())
           .optional()
           .describe('Option indexes to select (alternative to values/labels)'),
-        duration: z.number().optional().describe('Hover duration in ms (default: 100)'),
+        duration: z
+          .number()
+          .int()
+          .nonnegative()
+          .optional()
+          .describe('Hover duration in ms (default: 100)'),
         sourceElementRef: z.string().optional().describe('Drag source element (for drag action)'),
         sourceSelector: z
           .string()
@@ -457,7 +532,7 @@ export function createBridgeMcpServer() {
         action: z
           .enum(['apply_styles', 'apply_dom', 'list', 'rollback', 'commit_baseline'])
           .describe('Patch operation to perform'),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -517,7 +592,7 @@ export function createBridgeMcpServer() {
           .describe(
             'element (preferred), region (tight crop), full_page (document-level only), or cdp_* for low-level data'
           ),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         budgetPreset: z
           .enum(['quick', 'normal', 'deep'])
           .optional()
@@ -527,13 +602,18 @@ export function createBridgeMcpServer() {
           .optional()
           .describe('Element reference (for element action, preferred)'),
         selector: z.string().optional().describe('CSS selector (used if no elementRef)'),
-        nodeId: z.number().optional().describe('CDP node id for cdp_box_model/cdp_computed_styles'),
+        nodeId: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe('CDP node id for cdp_box_model/cdp_computed_styles'),
         rect: z
           .object({
-            x: z.number().describe('Region left edge (viewport pixels)'),
-            y: z.number().describe('Region top edge (viewport pixels)'),
-            width: z.number().describe('Region width (pixels)'),
-            height: z.number().describe('Region height (pixels)'),
+            x: z.number().nonnegative().describe('Region left edge (viewport pixels)'),
+            y: z.number().nonnegative().describe('Region top edge (viewport pixels)'),
+            width: z.number().positive().describe('Region width (pixels)'),
+            height: z.number().positive().describe('Region height (pixels)'),
           })
           .optional()
           .describe('Viewport region for region action (keep crop tight)'),
@@ -557,7 +637,7 @@ export function createBridgeMcpServer() {
                 .record(z.string(), z.unknown())
                 .optional()
                 .describe('Method params for this call'),
-              tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+              tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
               budgetPreset: z
                 .enum(['quick', 'normal', 'deep'])
                 .optional()
@@ -583,7 +663,7 @@ export function createBridgeMcpServer() {
           .record(z.string(), z.unknown())
           .optional()
           .describe('Method parameters as object'),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
       },
     },
     handleRawCallTool
@@ -645,7 +725,7 @@ export function createBridgeMcpServer() {
               '"normal" (state + DOM + text, default), ' +
               '"deep" (state + DOM + text + console + network).'
           ),
-        tabId: z.number().optional().describe(TAB_ID_DESCRIPTION),
+        tabId: z.number().int().positive().optional().describe(TAB_ID_DESCRIPTION),
         selector: z
           .string()
           .optional()
@@ -655,6 +735,8 @@ export function createBridgeMcpServer() {
     handleInvestigateTool
   );
 
+  registerBridgeMcpGuidance(server);
+
   return server;
 }
 

package/packages/native-host/src/auth-token.js

@@ -0,0 +1,92 @@
+// @ts-check
+
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { getBridgeDir } from './config.js';
+
+const TOKEN_FILENAME = 'daemon.auth';
+const TOKEN_BYTES = 32;
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{32,256}$/u;
+
+/**
+ * @param {NodeJS.ProcessEnv} [env=process.env]
+ * @returns {string}
+ */
+export function getBridgeAuthTokenPath(env = process.env) {
+  return path.join(getBridgeDir(env), TOKEN_FILENAME);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function normalizeBridgeAuthToken(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const token = value.trim();
+  return TOKEN_PATTERN.test(token) ? token : null;
+}
+
+/**
+ * @param {{ tokenPath?: string, readFile?: typeof fs.promises.readFile }} [options={}]
+ * @returns {Promise<string | null>}
+ */
+export async function readBridgeAuthToken(options = {}) {
+  const tokenPath = options.tokenPath ?? getBridgeAuthTokenPath();
+  const readFile = options.readFile ?? fs.promises.readFile.bind(fs.promises);
+  try {
+    return normalizeBridgeAuthToken(await readFile(tokenPath, 'utf8'));
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * @param {{
+ *   tokenPath?: string,
+ *   readFile?: typeof fs.promises.readFile,
+ *   writeFile?: typeof fs.promises.writeFile,
+ *   mkdir?: typeof fs.promises.mkdir,
+ *   chmod?: typeof fs.promises.chmod,
+ *   randomBytesFn?: typeof randomBytes
+ * }} [options={}]
+ * @returns {Promise<string>}
+ */
+export async function ensureBridgeAuthToken(options = {}) {
+  const tokenPath = options.tokenPath ?? getBridgeAuthTokenPath();
+  const readFile = options.readFile ?? fs.promises.readFile.bind(fs.promises);
+  const writeFile = options.writeFile ?? fs.promises.writeFile.bind(fs.promises);
+  const mkdir = options.mkdir ?? fs.promises.mkdir.bind(fs.promises);
+  const chmod = options.chmod ?? fs.promises.chmod.bind(fs.promises);
+  const randomBytesFn = options.randomBytesFn ?? randomBytes;
+  const existing = await readBridgeAuthToken({ tokenPath, readFile });
+  if (existing) {
+    return existing;
+  }
+
+  const token = randomBytesFn(TOKEN_BYTES).toString('base64url');
+  await mkdir(path.dirname(tokenPath), { recursive: true });
+  await writeFile(tokenPath, `${token}\n`, { encoding: 'utf8', mode: 0o600 });
+  if (process.platform !== 'win32') {
+    await chmod(tokenPath, 0o600).catch(() => {});
+  }
+  return token;
+}
+
+/**
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+function isMissingFileError(error) {
+  return Boolean(
+    error &&
+    typeof error === 'object' &&
+    /** @type {{ code?: unknown }} */ (error).code === 'ENOENT'
+  );
+}

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

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 
 import { pingExistingDaemon } from './daemon.js';
 import {
+  applyWindowsTcpTransportDefaults,
   createSocketBridgeTransport,
   formatBridgeTransport,
   getBridgeTransport,
@@ -124,7 +125,7 @@ export async function clearDaemonPidFile(options = {}) {
  */
 export async function stopBridgeDaemon(options = {}) {
   const {
-    transport = getBridgeTransport(),
+    transport = undefined,
     socketPath = undefined,
     pidPath = getDaemonPidPath(),
     timeoutMs = DEFAULT_DAEMON_RESTART_TIMEOUT_MS,
@@ -136,7 +137,7 @@ export async function stopBridgeDaemon(options = {}) {
     rmFn = fs.promises.rm,
     sleepFn = sleep,
   } = options;
-  const resolvedTransport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
+  const resolvedTransport = resolveDaemonTransport({ transport, socketPath });
   const resolvedSocketPath =
     resolvedTransport.type === 'socket' ? resolvedTransport.socketPath : '';
 
@@ -238,7 +239,7 @@ export async function restartBridgeDaemonIfRunning(options = {}) {
  */
 async function restartBridgeDaemonAfterStop(stopResult, options = {}) {
   const {
-    transport = getBridgeTransport(),
+    transport = undefined,
     socketPath = undefined,
     pidPath = getDaemonPidPath(),
     timeoutMs = DEFAULT_DAEMON_RESTART_TIMEOUT_MS,
@@ -248,7 +249,7 @@ async function restartBridgeDaemonAfterStop(stopResult, options = {}) {
     sleepFn = sleep,
     spawnDaemonFn = spawnBridgeDaemonProcess,
   } = options;
-  const resolvedTransport = socketPath ? createSocketBridgeTransport(socketPath) : transport;
+  const resolvedTransport = resolveDaemonTransport({ transport, socketPath });
 
   spawnDaemonFn();
 
@@ -271,6 +272,27 @@ async function restartBridgeDaemonAfterStop(stopResult, options = {}) {
   };
 }
 
+/**
+ * Mirror the daemon entrypoint transport defaults so restart polling targets the
+ * same endpoint the spawned process listens on.
+ *
+ * @param {{ transport?: BridgeTransport, socketPath?: string }} options
+ * @returns {BridgeTransport}
+ */
+function resolveDaemonTransport(options) {
+  const { transport, socketPath } = options;
+  if (socketPath) {
+    return createSocketBridgeTransport(socketPath);
+  }
+  if (transport) {
+    return transport;
+  }
+
+  const env = { ...process.env };
+  applyWindowsTcpTransportDefaults(env);
+  return getBridgeTransport(env);
+}
+
 /**
  * @param {BridgeTransport} transport
  * @returns {Promise<number | null>}