@browserbridge/bbx 1.2.0 → 1.4.0

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

@@ -6,6 +6,7 @@ import {
   applyTreeBudgetPreset,
   dispatchToolAction,
   inferBudgetFromSelector,
+  summarizeToolError,
 } from './handlers-utils.js';
 
 /** @typedef {import('../../protocol/src/types.js').BridgeMethod} BridgeMethod */
@@ -93,6 +94,15 @@ export const DOM_ACTIONS = {
  * @returns {Promise<ToolResult>}
  */
 export async function handleDomTool(args) {
+  if (args.action === 'wait' && !hasText(args.selector) && !hasText(args.text)) {
+    return summarizeToolError('selector or text is required for dom.wait_for.');
+  }
+  if (args.action === 'find_text' && !hasText(args.text)) {
+    return summarizeToolError('text is required for dom.find_by_text.');
+  }
+  if (args.action === 'find_role' && !hasText(args.role)) {
+    return summarizeToolError('role is required for dom.find_by_role.');
+  }
   if (args.action === 'query' || args.action === 'accessibility_tree') {
     const inferred = inferBudgetFromSelector(args);
     const withBudget = inferred ? { ...args, budgetPreset: args.budgetPreset ?? inferred } : args;
@@ -136,6 +146,15 @@ export const STYLES_LAYOUT_ACTIONS = {
  * @returns {Promise<ToolResult>}
  */
 export async function handleStylesLayoutTool(args) {
+  if (
+    args.action === 'hit_test' &&
+    (typeof args.x !== 'number' ||
+      !Number.isFinite(args.x) ||
+      typeof args.y !== 'number' ||
+      !Number.isFinite(args.y))
+  ) {
+    return summarizeToolError('x and y are required for layout.hit_test.');
+  }
   return dispatchToolAction(STYLES_LAYOUT_ACTIONS, args, 'styles/layout');
 }
 
@@ -148,6 +167,7 @@ export const PATCH_ACTIONS = {
       target: { elementRef: r },
       declarations: a.declarations,
       important: a.important,
+      patchId: a.patchId,
       verify: a.verify,
     }),
   },
@@ -160,16 +180,22 @@ export const PATCH_ACTIONS = {
       const opMap = {
         setAttribute: 'set_attribute',
         removeAttribute: 'remove_attribute',
-        addClass: 'toggle_class',
-        removeClass: 'toggle_class',
+        addClass: 'add_class',
+        removeClass: 'remove_class',
         setTextContent: 'set_text',
         setProperty: 'set_attribute',
       };
+      const normalizedOperation = opMap[operation] || operation;
+      const value =
+        normalizedOperation === 'add_class' || normalizedOperation === 'remove_class'
+          ? (a.value ?? a.name)
+          : a.value;
       return {
         target: { elementRef: r },
-        operation: opMap[operation] || operation,
-        value: a.value,
+        operation: normalizedOperation,
+        value,
         name: a.name,
+        patchId: a.patchId,
         verify: a.verify,
       };
     },
@@ -192,5 +218,34 @@ export const PATCH_ACTIONS = {
  * @returns {Promise<ToolResult>}
  */
 export async function handlePatchTool(args) {
+  if (args.action === 'apply_styles' && !hasStringRecord(args.declarations)) {
+    return summarizeToolError('declarations are required for patch.apply_styles.');
+  }
+  if (args.action === 'apply_dom' && !hasText(args.operation)) {
+    return summarizeToolError('operation is required for patch.apply_dom.');
+  }
+  if (args.action === 'rollback' && !hasText(args.patchId)) {
+    return summarizeToolError('patchId is required for patch.rollback.');
+  }
   return dispatchToolAction(PATCH_ACTIONS, args, 'patch');
 }
+
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, string>}
+ */
+function hasStringRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const entries = Object.entries(/** @type {Record<string, unknown>} */ (value));
+  return entries.length > 0 && entries.every(([key, val]) => key.trim() && typeof val === 'string');
+}

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

@@ -61,17 +61,37 @@ export const NAVIGATION_ACTIONS = {
   },
   resize: {
     method: 'viewport.resize',
-    params: (a) => ({ width: a.width, height: a.height, reset: a.reset }),
+    params: (a) => ({
+      width: a.width,
+      height: a.height,
+      deviceScaleFactor: a.deviceScaleFactor,
+      reset: a.reset,
+    }),
   },
 };
 
 /**
- * @param {{ action: string, url?: string, waitForLoad?: boolean, timeoutMs?: number, top?: number, left?: number, behavior?: string, relative?: boolean, width?: number, height?: number, reset?: boolean, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
+ * @param {{ action: string, url?: string, waitForLoad?: boolean, timeoutMs?: number, top?: number, left?: number, behavior?: string, relative?: boolean, width?: number, height?: number, deviceScaleFactor?: number, reset?: boolean, tabId?: number, budgetPreset?: 'quick' | 'normal' | 'deep' }} args
  * @returns {Promise<ToolResult>}
  */
 export async function handleNavigationTool(args) {
   const entry = NAVIGATION_ACTIONS[args.action];
   if (!entry) return summarizeToolError(`Unsupported navigation action "${args.action}".`);
+  if (args.action === 'navigate' && (typeof args.url !== 'string' || !args.url.trim())) {
+    return summarizeToolError('url is required for navigation.navigate.');
+  }
+  if (
+    args.action === 'resize' &&
+    args.reset !== true &&
+    (typeof args.width !== 'number' ||
+      !Number.isFinite(args.width) ||
+      typeof args.height !== 'number' ||
+      !Number.isFinite(args.height))
+  ) {
+    return summarizeToolError(
+      'width and height are required for viewport.resize unless reset=true.'
+    );
+  }
   return callBridgeTool(entry.method, entry.params(args), {
     tabId: typeof args.tabId === 'number' ? args.tabId : null,
     tokenBudget: getToolTokenBudget(args),

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

@@ -8,12 +8,11 @@ import {
 import {
   annotateBridgeSummary,
   applyLimitBudgetPreset,
-  applyTextBudgetPreset,
+  applyPageTextBudgetPreset,
   bridgeMethodNeedsTab,
   callBridgeTool,
   createToolResult,
   getToolTokenBudget,
-  requestBridge,
   requestBridgeWithRetry,
   summarizeBatchErrorItem,
   summarizeBatchResponseItem,
@@ -72,7 +71,7 @@ export const PAGE_ACTIONS = {
 export async function handlePageTool(args) {
   let normalizedArgs = args;
   if (args.action === 'text') {
-    normalizedArgs = applyTextBudgetPreset(args);
+    normalizedArgs = applyPageTextBudgetPreset(args);
   } else if (args.action === 'console') {
     normalizedArgs = applyLimitBudgetPreset(args, {
       quick: 10,
@@ -147,14 +146,10 @@ export async function handleBatchTool(args) {
 
         const startTime = Date.now();
         try {
-          const response = await client.request({
-            method,
-            params: call.params || {},
+          const response = await requestBridgeWithRetry(client, method, call.params || {}, {
             tabId,
-            meta: {
-              source: REQUEST_SOURCE,
-              ...(tokenBudget != null ? { token_budget: tokenBudget } : {}),
-            },
+            source: REQUEST_SOURCE,
+            tokenBudget,
           });
           return summarizeBatchResponseItem({
             method,
@@ -199,7 +194,7 @@ export async function handleRawCallTool(args) {
   }
 
   return withToolClient(async (client) => {
-    const response = await requestBridge(
+    const response = await requestBridgeWithRetry(
       client,
       /** @type {BridgeMethod} */ (args.method),
       args.params || {},

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

@@ -3,6 +3,7 @@
 import {
   bridgeMethodNeedsTab,
   DEFAULT_MAX_HTML_LENGTH,
+  DEFAULT_PAGE_TEXT_BUDGET,
   estimateJsonPayloadCost,
   getBudgetPreset,
   getErrorRecovery,
@@ -23,6 +24,52 @@ import { annotateBridgeSummary, summarizeBridgeResponse } from '../../agent-clie
 
 export const REQUEST_SOURCE = 'mcp';
 
+/** @type {ReadonlySet<BridgeMethod>} */
+const RETRY_SAFE_METHODS = new Set([
+  'skill.get_runtime_context',
+  'setup.get_status',
+  'log.tail',
+  'health.ping',
+  'daemon.metrics',
+  'tabs.list',
+  'page.get_state',
+  'page.get_storage',
+  'page.get_text',
+  'dom.query',
+  'dom.describe',
+  'dom.get_text',
+  'dom.get_attributes',
+  'dom.wait_for',
+  'dom.find_by_text',
+  'dom.find_by_role',
+  'dom.get_html',
+  'dom.get_accessibility_tree',
+  'layout.get_box_model',
+  'layout.hit_test',
+  'styles.get_computed',
+  'styles.get_matched_rules',
+  'screenshot.capture_region',
+  'screenshot.capture_element',
+  'screenshot.capture_full_page',
+  'performance.get_metrics',
+  'cdp.get_document',
+  'cdp.get_dom_snapshot',
+  'cdp.get_box_model',
+  'cdp.get_computed_styles_for_node',
+]);
+
+/**
+ * @param {BridgeMethod} method
+ * @param {Record<string, unknown>} params
+ * @returns {boolean}
+ */
+export function isRetrySafeBridgeMethod(method, params) {
+  if (method === 'page.get_console' || method === 'page.get_network') {
+    return params.clear !== true;
+  }
+  return RETRY_SAFE_METHODS.has(method);
+}
+
 /**
  * @typedef {{
  *   content: Array<{ type: 'text', text: string }>,
@@ -176,6 +223,27 @@ export function applyTextBudgetPreset(args) {
   });
 }
 
+/**
+ * @template {{ budgetPreset?: unknown, textBudget?: unknown }} T
+ * @param {T} args
+ * @returns {T}
+ */
+export function applyPageTextBudgetPreset(args) {
+  const presetName = getBudgetPresetName(args.budgetPreset);
+  if (!presetName) {
+    return args;
+  }
+  const textBudgetByPreset = {
+    quick: 2000,
+    normal: DEFAULT_PAGE_TEXT_BUDGET,
+    deep: DEFAULT_PAGE_TEXT_BUDGET * 2,
+  };
+  return /** @type {T} */ ({
+    ...args,
+    textBudget: args.textBudget ?? textBudgetByPreset[presetName],
+  });
+}
+
 /**
  * @template {{ budgetPreset?: unknown, limit?: unknown }} T
  * @param {T} args
@@ -224,7 +292,7 @@ export function applyHtmlBudgetPreset(args) {
 export async function requestBridgeWithRetry(client, method, params, options) {
   const response = await requestBridge(client, method, params, options);
   const recovery = !response.ok && response.error ? getErrorRecovery(response.error.code) : null;
-  if (!response.ok && recovery?.retry) {
+  if (!response.ok && recovery?.retry && isRetrySafeBridgeMethod(method, params)) {
     const delay = recovery.retryAfterMs ?? 1000;
     process.stderr.write(
       `[bbx-mcp] Retrying ${method} after ${delay}ms (${response.error.code})\n`

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,12 +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()
+          .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)'),
@@ -556,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()
@@ -582,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
@@ -644,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()
@@ -654,6 +735,8 @@ export function createBridgeMcpServer() {
     handleInvestigateTool
   );
 
+  registerBridgeMcpGuidance(server);
+
   return server;
 }