@glittering0717/ai-browser 1.3.1 → 2.1.0

package/src/main/mcp_server.js

@@ -9,15 +9,13 @@ import {
   ListResourcesRequestSchema,
   ListResourceTemplatesRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import net from 'node:net';
-import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-// Shared Electron-binary resolver. npm >= 11 blocks dependency install scripts
-// by default (so plain `npx` leaves electron without its engine); the resolver
-// self-heals by running electron's bundled installer on first launch.
-import electronResolve from '../../scripts/electron_resolve.cjs';
+// 启动逻辑与 CLI 共用一份（scripts/ensure_running.cjs）。曾经这里有一份私有实现，
+// 结果 MCP 能自动拉起浏览器、CLI 不能 —— 同一件事两个行为。
+import ensureMod from '../../scripts/ensure_running.cjs';
 import { MCP_TOOLS } from './mcp_tools.js';
+import { actParams, networkParams } from './mcp_args.js';
 import { evaluateGuardError } from '../shared/guards.js';
 // 截图体积上限（与 WS 侧共用同一把尺）：超过就不把图塞进上下文。
 import screenshotOpts from '../shared/screenshot_opts.cjs';
@@ -32,96 +30,29 @@ const ELECTRON_PORT = config.wsPort;
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// App/package root — identical layout in a git checkout and inside
-// node_modules/@glittering0717/ai-browser: src/main/ → up two levels.
-const APP_ROOT = path.resolve(__dirname, '..', '..');
-const { resolveElectronBinary } = electronResolve;
+const { ensureRunning, checkPort } = ensureMod;
 
 // Persistent WS client — one reused connection with incrementing ids.
 // Lazy launch: no Electron is started at boot. The first browse_* call that
-// fails to connect triggers `ensureRunning`, which spawns Electron on demand
-// (ensureElectronRunning is idempotent). `ensureElectronRunning` is a hoisted
-// function declaration, so referencing it here is safe.
+// fails to connect triggers `ensureRunning`, which starts Electron on demand.
+//
+// 2026-10-20: the launch logic moved to scripts/ensure_running.cjs so the CLI
+// (`ai-browser call` / `ai-browser ensure`) shares ONE implementation with this
+// server. Duplicating it here is what made "install and use" a two-step dance
+// for CLI callers: MCP auto-started the browser, the CLI did not.
 const wsClient = createWsClient({
   url: WS_URL,
   timeout: WS_TIMEOUT,
-  ensureRunning: ensureElectronRunning,
+  ensureRunning: () => ensureBrowser(),
 });
 
-// Probe whether the Electron WS server is already listening on the port.
-function checkPort(port) {
-  return new Promise((resolve) => {
-    const sock = net.connect({ port, host: '127.0.0.1' });
-    let done = false;
-    const finish = (ok) => { if (!done) { done = true; sock.destroy(); resolve(ok); } };
-    sock.once('connect', () => finish(true));
-    sock.once('error', () => finish(false));
-    setTimeout(() => finish(false), 500);
-  });
-}
-
-function waitForPort(port, timeoutMs) {
-  const start = Date.now();
-  return new Promise(async (resolve) => {
-    while (Date.now() - start < timeoutMs) {
-      if (await checkPort(port)) return resolve(true);
-      await new Promise(r => setTimeout(r, 500));
-    }
-    resolve(false);
+/** 拉起浏览器（幂等）。失败时抛带原因的 Error，由 mcp_ws 并进最终错误信息。 */
+async function ensureBrowser() {
+  const info = await ensureRunning({
+    port: ELECTRON_PORT,
+    log: (m) => console.error('[mcp] ' + m),
   });
-}
-
-// Spawn Electron detached so it survives this MCP subprocess.
-//
-// 两个坑都是实测踩出来的（2026-10-12）：
-//
-// ① `ELECTRON_RUN_AS_NODE` 必须删掉。本机 shell 就带着它，此时 `electron .` 会
-//    被当作普通 Node 运行，拿 Node 加载 ESM 入口直接崩，端口永不监听，而报错是
-//    一串 Node 的 ESM 栈 —— 完全不提 Electron。e2e 脚本都删了它，只有这里漏了。
-//    详见 scripts/start.cjs 顶部。
-//
-// ② 启动失败必须**说出来**。此前这里 return false，而 mcp_ws.js 又把它 catch 掉
-//    吞了，于是 agent 先重试 120 秒，最后只拿到 "WS reconnect timeout:
-//    connection refused" —— 没有任何线索表明浏览器根本没起来，更别说为什么。
-//    现在抛一个带原因的 Error，由 mcp_ws 并进最终错误信息。
-async function ensureElectronRunning() {
-  if (await checkPort(ELECTRON_PORT)) return true;
-  console.error('[mcp] port 9223 not listening — spawning the ai-browser Electron app');
-  // Spawn the electron binary directly (resolved from this package's
-  // dependencies), pointed at the app root. Do NOT shell out to `npm start`:
-  // npm is not guaranteed on PATH for MCP clients, and on Windows the
-  // executable is npm.cmd — direct spawn avoids both classes of failure.
-  // AI_BROWSER_LAUNCHED_BY_AGENT：告诉 Electron 它是被 agent 拉起来的，因此
-  // 窗口出现时**不要**抢焦点（showInactive）—— 否则 agent 第一次连上来就会把
-  // 用户正在做的事打断。人手动 `ai-browser` / `npm start` 时没有这个变量。
-  const childEnv = { ...process.env, AI_BROWSER_LAUNCHED_BY_AGENT: '1' };
-  delete childEnv.ELECTRON_RUN_AS_NODE;
-  let child;
-  try {
-    child = spawn(resolveElectronBinary(), [APP_ROOT], {
-      cwd: APP_ROOT,
-      detached: true,
-      stdio: 'ignore',
-      env: childEnv,
-    });
-  } catch (e) {
-    throw new Error(`could not start the browser: ${e.message}`);
-  }
-  child.unref();
-  // 子进程自己提前退出（例如上面那个 Node ESM 崩溃）时，等满 30 秒是纯浪费 ——
-  // 而且会掩盖真实原因。这里挂一个 exit 监听，把退出码留给下面的诊断。
-  let earlyExit = null;
-  child.on('exit', (code, signal) => { earlyExit = { code, signal }; });
-  // Give Electron up to 30s to start the WS server.
-  const ok = await waitForPort(ELECTRON_PORT, 30000);
-  if (!ok) {
-    const why = earlyExit
-      ? `Electron exited early (code=${earlyExit.code}, signal=${earlyExit.signal}) — a common cause is ELECTRON_RUN_AS_NODE being set in the environment, or the electron binary being missing (check node_modules/electron/dist)`
-      : 'Electron did not come up within 30s (slow first-run binary download? try ELECTRON_MIRROR for users behind a slow network)';
-    console.error('[mcp] ' + why);
-    throw new Error(`could not start the browser: ${why}`);
-  }
-  return true;
+  return info.running;
 }
 
 const server = new Server(
@@ -178,39 +109,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
 
     case 'browse_act': {
+      // 参数映射收在 mcp_args.js 单点完成：schema 对 agent 暴露分组，
+      // page_manager 只认扁平。旧扁平参数继续被接受（向后兼容）。
       const result = await wsClient.call('ui.act', {
         action: args.action,
         target: args.target,
-        params: {
-          text: args.text,
-          value: args.value,
-          url: args.url,
-          keep_tab: args.keep_tab,
-          file: args.file,
-          offset: args.offset,
-          limit: args.limit,
-          // drag：终点与端点锚点。to_x/to_y 是绝对视口坐标（用于拖到空白处，
-          // 例如平移画布）；to_target 是落到另一个元素上（例如连线）。
-          // 这些名字与 raw WS 层完全一致 —— 归一由 page_manager._cdpDrag 单点负责，
-          // 这里不再做第二套映射（两套名字 = 迟早有一层不认识）。
-          to_target: args.to_target,
-          dx: args.dx,
-          dy: args.dy,
-          to_x: args.to_x,
-          to_y: args.to_y,
-          from_anchor: args.from_anchor,
-          from: (args.from_x !== undefined && args.from_y !== undefined)
-            ? { x: args.from_x, y: args.from_y }
-            : undefined,
-          to_anchor: args.to_anchor,
-          hold: args.hold,
-          button: args.button,
-          // press：单个键或按键序列
-          key: args.key,
-          keys: args.keys,
-          dx: args.delta_x,
-          dy: args.delta_y,
-        },
+        params: actParams(args),
         tab: args.tab
       });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
@@ -276,54 +180,63 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return { content: [{ type: 'text', text: JSON.stringify(slim) }] };
     }
 
-    case 'browse_list_tabs': {
-      const result = await wsClient.call('ui.list_tabs', {});
-      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
-
-    case 'browse_new_tab': {
-      const result = await wsClient.call('ui.new_tab', { url: args.url || null });
-      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
-
-    case 'browse_close_tab': {
-      const result = await wsClient.call('ui.close_tab', { tab: args.tab });
-      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
-    }
-
-    case 'browse_set_active_tab': {
-      const result = await wsClient.call('ui.set_active_tab', { tab: args.tab });
-      return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    case 'browse_tabs': {
+      // 4 个单动词工具（list/new/close/set_active）合并为一个。
+      // 理由：它们操作同一个实体（标签页），每个只承载一个动词，是工具数量
+      // 膨胀里最没有道理的一种。合并后参数只有 op/tab/url 三个。
+      const op = args.op;
+      if (op === 'list') {
+        const result = await wsClient.call('ui.list_tabs', {});
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      }
+      if (op === 'new') {
+        const result = await wsClient.call('ui.new_tab', { url: args.url || null });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      }
+      if (op === 'close') {
+        const result = await wsClient.call('ui.close_tab', { tab: args.tab });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      }
+      if (op === 'switch') {
+        const result = await wsClient.call('ui.set_active_tab', { tab: args.tab });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+      }
+      return {
+        content: [{ type: 'text', text: `Error: unknown op "${op}" — use list / new / close / switch` }],
+        isError: true
+      };
     }
 
     case 'browse_network': {
-      const result = args.operation === 'list' || args.operation === 'configure' || args.operation === 'clear'
+      const p = networkParams(args);
+      const isListLike =
+        args.operation === 'list' || args.operation === 'configure' || args.operation === 'clear';
+      const result = isListLike
         ? await wsClient.call('ui.network_' + args.operation, {
-            tab: args.tab,
-            method: args.method,
-            url_contains: args.url_contains,
-            status: (args.status_min !== undefined || args.status_max !== undefined)
-              ? { min: args.status_min, max: args.status_max } : undefined,
-            resource_type: args.resource_type,
-            state: args.state,
-            started_after: args.started_after,
-            started_before: args.started_before,
-            limit: args.limit,
-            before_seq: args.before_seq,
-            enabled: args.enabled,
-            capture_bodies: args.capture_bodies,
+            tab: p.tab,
+            method: p.method,
+            url_contains: p.url_contains,
+            status: p.status,
+            resource_type: p.resource_type,
+            state: p.state,
+            started_after: p.started_after,
+            started_before: p.started_before,
+            limit: p.limit,
+            before_seq: p.before_seq,
+            enabled: p.enabled,
+            capture_bodies: p.capture_bodies
           })
         : await wsClient.call('ui.network_get', {
-            tab: args.tab,
-            network_id: args.network_id,
-            include_request_headers: args.include_request_headers,
-            include_request_body: args.include_request_body,
-            include_response_headers: args.include_response_headers,
-            include_response_body: args.include_response_body,
-            include_sensitive_headers: args.include_sensitive_headers,
-            request_body_offset: args.request_body_offset,
-            response_body_offset: args.response_body_offset,
-            body_limit: args.body_limit,
+            tab: p.tab,
+            network_id: p.network_id,
+            include_request_headers: p.include_request_headers,
+            include_request_body: p.include_request_body,
+            include_response_headers: p.include_response_headers,
+            include_response_body: p.include_response_body,
+            include_sensitive_headers: p.include_sensitive_headers,
+            request_body_offset: p.request_body_offset,
+            response_body_offset: p.response_body_offset,
+            body_limit: p.body_limit
           });
       return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     }

package/src/main/mcp_tools.js

@@ -42,37 +42,81 @@ export const MCP_TOOLS = [
   {
     name: 'browse_act',
     title: 'Act on element',
-    description: 'Act on an element by data-ai-id: click, type (append at caret), setContent (replace all), clear, focus, hover, scroll_to, upload, get_value (read-only), drag, press, wheel, paste.',
+    description: 'Act on a data-ai-id element. type appends at caret, setContent replaces all. Verb-specific params live in the group of the same name (click/read/press/wheel/drag).',
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
       properties: {
-        action: { type: 'string', enum: ['click', 'type', 'clear', 'focus', 'hover', 'scroll_to', 'upload', 'get_value', 'drag', 'press', 'wheel', 'paste'], description: 'Action.' },
-        html: { type: 'string', description: 'paste: HTML to inject (preferred). Editors convert it through their own paste pipeline (Draft.js/ProseMirror/Quill), so headings/code blocks/bold/lists survive. Plain text loses all formatting.' },
-        target: { type: 'string', description: 'Element data-ai-id from the semantic tree (e.g. e:button-12, axf-3-1) — NOT the visible label. Omit for press (keys go to the current focus); for drag you may also omit it and pass from_x/from_y to start from a bare point. upload also accepts a CSS selector (descendant selectors with spaces included), which is the only way to reach upload widgets that have no semantic node.' },
-        text: { type: 'string', description: 'Text to type (type/setContent). For paste: plain-text fallback used when html is absent.' },
-        value: { type: 'string', description: 'Value for select.' },
-        offset: { type: 'integer', description: 'get_value: start offset in Unicode code points (default 0).' },
-        limit: { type: 'integer', description: 'get_value: max code points to return (default 20000, hard cap 1000000).' },
-        url: { type: 'string', description: 'For click: click the link whose href matches this URL instead of guessing the target label.' },
-        keep_tab: { type: 'boolean', description: 'For click: keep the current tab active instead of auto-following a newly opened tab.' },
-        file: { type: 'string', description: 'Absolute path to upload (upload only). target may be the file input itself, the control that opens the picker, or — when the control has no semantic node at all — a CSS selector such as ".upload-button". Works inside cross-process iframes.' },
-        timeout_ms: { type: 'integer', description: 'Override the action deadline in ms (default 15000; type/setContent/drag/press scale with text length / duration / repeat; 1s floor, 300s cap). A timeout returns success=false, timed_out=true and warns the action may have partially applied.' },
-        to_target: { type: 'string', description: 'drag: data-ai-id to drop onto (e.g. drag from one node\'s output to another node to connect them).' },
-        dx: { type: 'number', description: 'drag: horizontal distance to move (use with dy instead of to_target).' },
-        dy: { type: 'number', description: 'drag: vertical distance to move.' },
-        to_x: { type: 'number', description: 'drag: absolute viewport x to end at (overrides dx).' },
-        to_y: { type: 'number', description: 'drag: absolute viewport y to end at.' },
-        from_x: { type: 'number', description: 'drag: explicit viewport x to start the drag at (no target needed — e.g. panning empty canvas).' },
-        from_y: { type: 'number', description: 'drag: explicit viewport y to start the drag at.' },
-        from_anchor: { type: 'string', enum: ['center', 'left', 'right', 'top', 'bottom'], description: 'drag: which point of target to grab; a side prefers that node\'s connection handle (default center).' },
-        to_anchor: { type: 'string', enum: ['center', 'left', 'right', 'top', 'bottom'], description: 'drag: which point of to_target to drop on.' },
-        hold: { type: 'array', items: { type: 'string' }, description: 'drag: modifier keys held during the drag (e.g. ["Shift"]).' },
-        button: { type: 'string', enum: ['left', 'middle', 'right'], description: 'drag: mouse button (default left). Canvas apps often pan on middle/right drag.' },
-        key: { type: 'string', description: 'press: a key name such as Delete, Escape, ArrowRight, Enter, or a combo like "Meta+a".' },
-        delta_x: { type: 'number', description: 'wheel: horizontal scroll amount (positive scrolls right).' },
-        delta_y: { type: 'number', description: 'wheel: vertical scroll amount. Negative scrolls up / zooms out; add hold:["Control"] for canvas zoom.' },
-        keys: { type: 'array', items: { type: 'string' }, description: 'press: sequence of keys to press in order.' },
+        action: { type: 'string', enum: ['click', 'type', 'setContent', 'clear', 'focus', 'hover', 'scroll_to', 'upload', 'get_value', 'drag', 'press', 'wheel', 'paste'], description: 'Verb. Verb-specific params live in the group of the same name.' },
+        target: { type: 'string', description: 'data-ai-id from the tree (e.g. e:button-12) — NOT the visible label. Optional for press; drag may use drag.from; upload also takes a CSS selector.' },
+        text: { type: 'string', description: 'type: appended at the caret. setContent: replaces all. paste: plain fallback when html is absent.' },
+        html: { type: 'string', description: 'paste: HTML, preferred — editors keep headings/lists/bold. Plain text loses formatting.' },
+        value: { type: 'string', description: 'Option value for a <select>.' },
+        file: { type: 'string', description: 'upload: absolute path. target may be the input, the trigger, or a CSS selector.' },
+        timeout_ms: { type: 'integer', description: 'Deadline ms (default 15000, 1s..300s). On timeout: success=false, timed_out=true, may have partially applied.' },
+        click: {
+          type: 'object',
+          description: 'click only.',
+          properties: {
+            url: { type: 'string', description: 'Hit the link whose href matches this URL (for composite cards with several links).' },
+            keep_tab: { type: 'boolean', description: 'Stay on this tab instead of following a newly opened one.' },
+            opened_tab_wait_ms: { type: 'integer', description: 'Extra wait ms for a site-opened tab (default 250 on link targets; pass it to force, 0 off).' }
+          }
+        },
+        read: {
+          type: 'object',
+          description: 'get_value only — read-only: does not focus the element or fire input events.',
+          properties: {
+            offset: { type: 'integer', description: 'Start offset in Unicode code points (default 0).' },
+            limit: { type: 'integer', description: 'Max code points to return (default 20000, hard cap 1000000).' }
+          }
+        },
+        press: {
+          type: 'object',
+          description: 'press only. Keys go to the current focus, so target is optional.',
+          properties: {
+            key: { type: 'string', description: 'Delete, Escape, ArrowRight, Enter, or a combo like "Meta+a".' },
+            keys: { type: 'array', items: { type: 'string' }, description: 'Sequence to press in order.' }
+          }
+        },
+        wheel: {
+          type: 'object',
+          description: 'wheel only. Lands on target, or the viewport centre when target is omitted.',
+          properties: {
+            dx: { type: 'number', description: 'Horizontal delta (positive scrolls right).' },
+            dy: { type: 'number', description: 'Vertical delta. Negative scrolls up / zooms out.' },
+            hold: { type: 'array', items: { type: 'string' }, description: 'Modifiers held, e.g. ["Control"] to zoom a canvas.' }
+          }
+        },
+        drag: {
+          type: 'object',
+          description: 'drag only. Give from/to for absolute points, dx/dy for a relative move, or target_to to drop onto another element.',
+          properties: {
+            from: {
+              type: 'object',
+              description: 'Start point. Omit to start from target.',
+              properties: {
+                x: { type: 'number' },
+                y: { type: 'number' },
+                anchor: { type: 'string', enum: ['center', 'left', 'right', 'top', 'bottom'], description: 'A side prefers that node\'s connection handle.' }
+              }
+            },
+            to: {
+              type: 'object',
+              description: 'End point in viewport coords.',
+              properties: {
+                x: { type: 'number' },
+                y: { type: 'number' },
+                anchor: { type: 'string', enum: ['center', 'left', 'right', 'top', 'bottom'] }
+              }
+            },
+            dx: { type: 'number', description: 'Horizontal distance instead of to.x.' },
+            dy: { type: 'number', description: 'Vertical distance instead of to.y.' },
+            target_to: { type: 'string', description: 'data-ai-id to drop onto (e.g. connect one node\'s output to another).' },
+            hold: { type: 'array', items: { type: 'string' }, description: 'Modifiers held during the drag, e.g. ["Shift"].' },
+            button: { type: 'string', enum: ['left', 'middle', 'right'], description: 'Canvas apps often pan on middle/right drag.' }
+          }
+        },
         tab: { type: 'integer', description: 'Tab id (default: active tab).' }
       },
       required: ['action']
@@ -164,81 +208,78 @@ export const MCP_TOOLS = [
     }
   },
   {
-    name: 'browse_list_tabs',
-    title: 'List tabs',
-    description: 'List open tabs (id, url, title, active).',
-    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
-    inputSchema: { type: 'object', properties: {} }
-  },
-  {
-    name: 'browse_new_tab',
-    title: 'New tab',
-    description: 'Open a new tab, optionally at a URL.',
+    name: 'browse_tabs',
+    title: 'Tabs',
+    description: 'Tabs: op=list / new / close / switch. switch makes a tab the default target for later calls, so you rarely pass tab explicitly.',
+    // 合并前是 4 个工具（list / new / close / set_active），每个只承载一个动词。
+    // 合并后 destructiveHint 只能是 false —— 否则 op=list 也会被标成破坏性操作；
+    // close 的破坏性写在 description 里。这是合并的唯一语义代价，接受。
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
     inputSchema: {
       type: 'object',
       properties: {
-        url: { type: 'string', description: 'Optional URL.' }
-      }
-    }
-  },
-  {
-    name: 'browse_close_tab',
-    title: 'Close tab',
-    description: 'Close a tab by id.',
-    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
-    inputSchema: {
-      type: 'object',
-      properties: {
-        tab: { type: 'integer', description: 'Tab id.' }
-      },
-      required: ['tab']
-    }
-  },
-  {
-    name: 'browse_set_active_tab',
-    title: 'Switch active tab',
-    description: 'Switch the active tab.',
-    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
-    inputSchema: {
-      type: 'object',
-      properties: {
-        tab: { type: 'integer', description: 'Tab id.' }
+        op: { type: 'string', enum: ['list', 'new', 'close', 'switch'], description: 'list = id/url/title/active for every tab. switch = make `tab` the default target.' },
+        tab: { type: 'integer', description: 'close / switch: the target tab id.' },
+        url: { type: 'string', description: 'new: open at this URL (default about:blank).' }
       },
-      required: ['tab']
+      required: ['op']
     }
   },
   {
     name: 'browse_network',
     title: 'Inspect network',
-    description: 'Query captured HTTP requests (Chrome Network panel): list/get/clear/configure. Captures method, headers and POST bodies; sensitive headers redacted by default.',
+    description: 'Query captured HTTP requests: list/get/clear/configure. Captures headers and POST bodies; sensitive headers redacted. Each op reads its own group: filters / include / body_offset / configure.',
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
     inputSchema: {
       type: 'object',
       properties: {
         operation: { type: 'string', enum: ['list', 'get', 'clear', 'configure'], description: 'Operation.' },
-        tab: { type: 'integer', description: 'Tab id (default: active tab).' },
         network_id: { type: 'string', description: 'get: id from list.' },
-        method: { type: 'array', items: { type: 'string' }, description: 'list: filter by HTTP method.' },
-        url_contains: { type: 'string', description: 'list: URL substring filter.' },
-        status_min: { type: 'integer', description: 'list: minimum status.' },
-        status_max: { type: 'integer', description: 'list: maximum status.' },
-        resource_type: { type: 'array', items: { type: 'string' }, description: 'list: XHR/Fetch/Document/...' },
-        state: { type: 'array', items: { type: 'string' }, description: 'list: pending/finished/failed.' },
-        started_after: { type: 'string', description: 'list: ISO timestamp.' },
-        started_before: { type: 'string', description: 'list: ISO timestamp.' },
-        limit: { type: 'integer', description: 'list: page size (default 50, max 200).' },
-        before_seq: { type: 'integer', description: 'list: cursor from pagination.next_before_seq.' },
-        include_request_headers: { type: 'boolean' },
-        include_request_body: { type: 'boolean' },
-        include_response_headers: { type: 'boolean' },
-        include_response_body: { type: 'boolean' },
-        include_sensitive_headers: { type: 'boolean', description: 'Requires AI_BROWSER_NETWORK_SENSITIVE=1.' },
-        request_body_offset: { type: 'integer' },
-        response_body_offset: { type: 'integer' },
-        body_limit: { type: 'integer', description: 'Body page size (default 65536, max 262144).' },
-        enabled: { type: 'boolean', description: 'configure: turn capture on/off.' },
-        capture_bodies: { type: 'string', enum: ['none', 'api', 'all'], description: 'configure.' }
+        filters: {
+          type: 'object',
+          description: 'list only.',
+          properties: {
+            method: { type: 'array', items: { type: 'string' }, description: 'HTTP methods.' },
+            url_contains: { type: 'string', description: 'URL substring.' },
+            status_min: { type: 'integer' },
+            status_max: { type: 'integer' },
+            resource_type: { type: 'array', items: { type: 'string' }, description: 'XHR / Fetch / Document / …' },
+            state: { type: 'array', items: { type: 'string' }, description: 'pending / finished / failed.' },
+            started_after: { type: 'string', description: 'ISO timestamp.' },
+            started_before: { type: 'string', description: 'ISO timestamp.' },
+            limit: { type: 'integer', description: 'Page size (default 50, max 200).' },
+            before_seq: { type: 'integer', description: 'Cursor from pagination.next_before_seq.' }
+          }
+        },
+        include: {
+          type: 'object',
+          description: 'get only — what to bring back.',
+          properties: {
+            request_headers: { type: 'boolean' },
+            response_headers: { type: 'boolean' },
+            request_body: { type: 'boolean' },
+            response_body: { type: 'boolean' },
+            sensitive_headers: { type: 'boolean', description: 'Requires AI_BROWSER_NETWORK_SENSITIVE=1.' },
+            body_limit: { type: 'integer', description: 'Body page size (default 65536, max 262144).' }
+          }
+        },
+        body_offset: {
+          type: 'object',
+          description: 'get only — paginate a large body.',
+          properties: {
+            request: { type: 'integer' },
+            response: { type: 'integer' }
+          }
+        },
+        configure: {
+          type: 'object',
+          description: 'configure only.',
+          properties: {
+            enabled: { type: 'boolean', description: 'Turn capture on/off.' },
+            capture_bodies: { type: 'string', enum: ['none', 'api', 'all'] }
+          }
+        },
+        tab: { type: 'integer', description: 'Tab id (default: active tab).' }
       },
       required: ['operation']
     }

package/src/main/mcp_ws.js

@@ -102,7 +102,13 @@ export function createWsClient({
 
         // Attempt failed — release this socket's connect-phase listeners fully so
         // its later error/close can't touch live state (MW-4).
-        try { ws.removeAllListeners(); ws.close(); } catch (_e) {}
+        // ⚠️ close() 一个还在 CONNECTING 的 socket 会异步再发一次 'error'
+        // （"WebSocket was closed before the connection was established"）。
+        // removeAllListeners 把 connect-phase 的 once('error') 也摘了，这个迟到
+        // 的 error 就没有监听器 → EventEmitter 直接 throw → 整个 MCP server 进程
+        // 崩掉，lazy launch 重试循环根本走不到（表现为"首次调用必崩"）。
+        // 挂一个 no-op error 兜底：迟到事件只被吞掉，不影响 MW-4 的状态隔离。
+        try { ws.removeAllListeners(); ws.on('error', () => {}); ws.close(); } catch (_e) {}
         const err = connectionErr || new Error('connection refused');
         // eslint-disable-next-line no-console
         if (attempt > 0 && attempt % 4 === 0) console.error('[mcp] ws reconnect attempt', attempt, '-', err.message);