@mearl/mcp-server 2.0.1 → 2.1.0

package/README.md

@@ -9,18 +9,21 @@
 - 📝 **browser_get_logs**: 获取控制台日志
 - 🎭 **browser_set_mock**: 动态设置 Mock 数据
 - 🌐 **browser_list**: 统一列出普通浏览器和托管浏览器，返回默认目标、类型及连接状态
+- 📴 **browser_release**: 释放 debugger/CDP 控制并保留浏览器与全部标签页
 - 🚀 **browser_launch / browser_close**: 启动或关闭独立 Profile 的托管 Chrome
 - 🌐 **browser_page_snapshot**: 首次获取页面结构和可交互元素
 - ⚡ **browser_page_click/type/hover/scroll/press/upload**: 执行页面动作，默认内置观察，返回通知、可交互控件和焦点等高置信度信号
 
 ## 浏览器交互工作流
 
-首次进入页面时调用 `browser_page_snapshot` 建立结构基线。后续点击、输入、悬停、滚动、按键和上传直接调用 `browser_page_click/type/hover/scroll/press/upload`，它们默认内置观察，动作与异步同步在一次调用内完成；同页结果读取 `effects.notifications`、`effects.interactives` 和 `effects.focus`，导航结果读取新 URL 和就绪状态。仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图。
+首次进入页面时调用 `browser_page_snapshot` 建立结构基线。后续点击、输入、悬停、滚动、按键和上传直接调用 `browser_page_click/type/hover/scroll/press/upload`，它们默认内置观察，动作与异步同步在一次调用内完成；同页结果读取 `effects.notifications`、`effects.interactives` 和 `effects.focus`。新增或变化的可交互节点会尽量携带可直接用于后续动作的 `node.ref`，解析不到 ref 时回退使用 `node.selector`。导航结果读取新 URL 和就绪状态。通常仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`browser_page_eval` 默认裸执行，仅在表达式会修改页面且需要变化信号时显式传 `observe` 对象。
 
-长列表重新感知时优先使用 `browser_page_snapshot(mode: "viewport")`；已知弹层或区域时使用 `rootSelector`；仅需要控件时使用 `mode: "interactive"`，避免整页 AX Tree 占用上下文。页面缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。
+长列表重新感知时优先使用 `browser_page_snapshot(mode: "viewport")`；已知 CSS 区域时使用 `rootSelector`，已有 ref 时使用 `rootRef`，只查找特定文案或角色时使用 `query`；仅需要当前视口内的控件时使用 `mode: "interactive"`，避免整页 AX Tree 占用上下文。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。重复文本点击可用 `scope` 限定子树，滚动子节点所在容器可用 `containerPolicy: "nearest"`。
 
 页面动作传 `observe: false` 可关闭内置观察仅执行裸动作；不需要在每次动作后固定追加 wait、snapshot 或 screenshot。
 
+`browser_page_click.clickMode` 默认 `auto`：可见桌面页使用可信 mouse，移动模拟页使用可信 touch；目标页隐藏时不会切换标签或还原窗口，而是使用 DOM fallback，并返回 `dispatchMode: "dom"`、`fallbackReason: "page-hidden"`。可用 `dom` / `mouse` / `touch` 覆盖自动策略；可信输入返回实际 `pointerType`。
+
 ## 安装
 
 **方式一：使用 npx（推荐，保持最新）**

package/dist/index.js

@@ -22,7 +22,10 @@ import { tmpdir } from 'os';
 import { join, dirname } from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 import { RESPONSE_SIZE_SMALL, RESPONSE_SIZE_MEDIUM, RESPONSE_SIZE_LARGE, RESPONSE_SIZE_MAX, } from './constants.js';
+const require = createRequire(import.meta.url);
+const MCP_SERVER_VERSION = require('../package.json').version;
 // 日志输出到 stderr（不影响 stdio 通信）
 const LOG_FILE = join(tmpdir(), 'mearl-mcp-server.log');
 const log = (...args) => {
@@ -245,35 +248,32 @@ function formatResponseWithSizeCheck(result, toolName, args) {
             },
         ];
     }
-    // 策略 5: 超超大响应（>1MB 压缩）- 截断 + 错误级别建议
-    const truncateSize = RESPONSE_SIZE_MAX;
-    const truncatedStr = compactStr.substring(0, truncateSize);
+    // 策略 5: 超超大响应（>1MB 压缩）- 返回可解析的诊断信息
     const suggestions = getOptimizationSuggestions(toolName, args, result, stats);
-    let header = `🛑 Response too large: ${sizeKB}KB (TRUNCATED to ${Math.round(truncateSize / 1024)}KB)\n`;
-    header += `Original size: ${sizeKB}KB, showing only ${Math.round(truncateSize / 1024)}KB\n`;
-    header += `\n⚠️ This response is unusable at this size. You MUST optimize the request.\n`;
-    if (stats.meta) {
-        header += `\n📊 Data: ${stats.meta.count} items (${stats.meta.totalMatched} matched, ${stats.meta.totalInBuffer} in buffer)`;
-    }
-    if (stats.largestFields && stats.largestFields.length > 0) {
-        header += `\nLargest fields per item:`;
-        stats.largestFields.forEach(f => {
-            header += `\n  • ${f.path}: ~${Math.round(f.size / 1024)}KB (${Math.round((f.size / compactSize) * 100)}% of total)`;
-        });
-    }
-    header += `\n\n🎯 REQUIRED actions:`;
-    if (suggestions.length > 0) {
-        header += suggestions.map((s, i) => `\n  ${i + 1}. ${s}`).join('');
-    }
-    else {
-        header += `\n  1. Significantly reduce the data requested`;
-        header += `\n  2. Use "fields" to extract only essential data`;
-        header += `\n  3. Add filters to narrow down results`;
-    }
+    const diagnostic = {
+        error: {
+            code: 'RESPONSE_TOO_LARGE',
+            message: 'The result exceeded the MCP response limit. Narrow the request and retry.',
+            originalSizeBytes: compactSize,
+            limitBytes: RESPONSE_SIZE_MAX,
+        },
+        meta: stats.meta,
+        largestFields: stats.largestFields?.map(field => ({
+            ...field,
+            percentageOfTotal: Math.round((field.size / compactSize) * 100),
+        })),
+        suggestions: suggestions.length > 0
+            ? suggestions
+            : [
+                'Significantly reduce the data requested',
+                'Use "fields" to extract only essential data',
+                'Add filters to narrow down results',
+            ],
+    };
     return [
         {
             type: 'text',
-            text: `${header}\n\n${'─'.repeat(60)}\n\n${truncatedStr}\n\n... <TRUNCATED ${sizeKB - Math.round(truncateSize / 1024)}KB>`,
+            text: JSON.stringify(diagnostic, null, 2),
         },
     ];
 }
@@ -317,12 +317,12 @@ async function main() {
     // 创建 MCP Server
     const server = new Server({
         name: 'mearl',
-        version: '1.0.0',
+        version: MCP_SERVER_VERSION,
     }, {
         capabilities: {
             tools: {},
         },
-        instructions: '浏览器交互默认工作流：首次进入页面时使用 browser_page_snapshot 建立页面基线；后续点击、输入、悬停、滚动、按键和上传直接使用 browser_page_click/type/hover/scroll/press/upload，它们默认内置观察，动作与异步稳定判断在一次调用内完成，返回 { action, observation }；传 observe:false 可关闭观察仅执行裸动作。观察结果不替代完整页面理解：observation.mode 为 delta 时确认 scope="main-document"，再读取 effects.notifications、effects.interactives 和 effects.focus；notifications 中 change=transient 表示已经消失的 Toast、状态或错误提示。为 navigation 时先检查 ready，ready=true 表示文档、相关业务请求和可见骨架状态已经稳定，可在新页面重建 snapshot。其他情况下仅当 fullSnapshotRecommended 为 true 时根据 snapshotReasons 回退，并选择最小范围：已知区域用 rootSelector，长列表用 mode="viewport"，只需控件用 mode="interactive"；缺少 AX 控件语义时 interactive 会在同一次调用中回退到 viewport，并返回 fallbackMode。视觉任务再使用 screenshot。不要在每次动作后固定调用 browser_page_wait、snapshot 或 screenshot。',
+        instructions: '浏览器交互默认工作流：首次进入页面时使用 browser_page_snapshot 建立页面基线；后续点击、输入、悬停、滚动、按键和上传直接使用 browser_page_click/type/hover/scroll/press/upload，它们默认内置观察，动作与异步稳定判断在一次调用内完成，返回 { action, observation }；传 observe:false 可关闭观察仅执行裸动作。观察结果不替代完整页面理解：observation.mode 为 delta 时确认 scope="main-document"，再读取 effects.notifications、effects.interactives 和 effects.focus；interactives/focus 节点有 ref 时优先直接用于后续动作，没有 ref 时使用 selector；notifications 中 change=transient 表示已经消失的 Toast、状态或错误提示。为 navigation 时先检查 ready，ready=true 表示文档、相关业务请求和可见骨架状态已经稳定，可在新页面重建 snapshot。其他情况下通常仅当 fullSnapshotRecommended 为 true 时根据 snapshotReasons 回退，并选择最小范围：已有区域 ref 用 rootRef，已有 CSS 根节点用 rootSelector，只需查找特定目标时加 query，长列表用 mode="viewport"，只需当前视口内的控件用 mode="interactive"；滚动动作的 moved 只证明位置变化，下一步需要读取新视口内容时可按需获取 viewport 快照。视口内缺少 AX 控件语义时 interactive 会在同一次调用中回退到 viewport，并返回 fallbackMode。重复文本点击用 scope 限定区域，ref 指向滚动容器子节点时用 containerPolicy="nearest"。page_eval 默认裸执行且应作为结构化能力无法表达时的补充，仅在表达式修改页面并需要变化信号时显式传 observe 对象。视觉任务再使用 screenshot。不要在每次动作后固定调用 browser_page_wait、snapshot 或 screenshot。',
     });
     // 页面交互工具共享的 observe 参数 schema：默认开启内置观察，传 false 关闭
     const OBSERVE_INPUT_SCHEMA = {
@@ -452,6 +452,11 @@ async function main() {
                         description: '返回条数上限，默认 20',
                         default: 20,
                     },
+                    includeRaw: {
+                        type: 'boolean',
+                        description: '是否返回完整 tracking URL、_raw 原始载荷和 _context 上下文；默认 false，仅返回解析后的精简字段',
+                        default: false,
+                    },
                 },
             },
         },
@@ -461,6 +466,10 @@ async function main() {
             inputSchema: {
                 type: 'object',
                 properties: {
+                    tabId: {
+                        type: 'number',
+                        description: '目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页',
+                    },
                     level: {
                         type: 'string',
                         enum: ['log', 'warn', 'error', 'info', 'all'],
@@ -489,6 +498,10 @@ async function main() {
             inputSchema: {
                 type: 'object',
                 properties: {
+                    tabId: {
+                        type: 'number',
+                        description: '目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页',
+                    },
                     apiName: {
                         type: 'string',
                         description: 'API 名称或正则表达式模式。例如: "mtop.cart.query" 精确匹配, ".*\\.cart\\..*" 匹配所有购物车接口',
@@ -542,6 +555,10 @@ async function main() {
             inputSchema: {
                 type: 'object',
                 properties: {
+                    tabId: {
+                        type: 'number',
+                        description: '目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页',
+                    },
                     apiName: {
                         type: 'string',
                         description: '过滤指定接口，支持正则表达式。例如: "mtop.cart.query" 或 ".*\\.cart\\..*"。不传则返回所有 Mock',
@@ -959,6 +976,14 @@ async function main() {
                 required: ['browser'],
             },
         },
+        {
+            name: 'browser_release',
+            description: '释放 Agent 对当前目标浏览器的 debugger/CDP 控制，停止持续采集和会话级临时效果，但保留浏览器与全部标签页。后续浏览器操作仍可自动重新建立控制。',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
         {
             name: 'browser_tab_open',
             description: '打开或按 URL 规则复用标签页。默认新建并等待加载完成；reuse=prefer 可优先复用，reuse=require 可限制为只复用。响应的 opened/reused 可用于判断流程结束时是否应关闭该 Tab。',
@@ -1076,7 +1101,7 @@ async function main() {
         },
         {
             name: 'browser_page_click',
-            description: '点击页面元素，默认内置观察：同一次调用内等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定，返回 { action, observation }；传 observe:false 仅执行裸点击。定位方式三选一：selector（CSS 或 @eN snapshot ref）、text（按可见文本匹配 accessibility name）、point（视口坐标）。selector/@ref 默认走 el.click()；clickType:"cdp" 时改用真实 mouse/touch 事件。text/point 始终使用真实输入事件。',
+            description: '点击页面元素，默认内置观察：同一次调用内等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定，返回 { action, observation }；传 observe:false 仅执行裸点击。定位方式三选一：selector（CSS 或 @eN snapshot ref）、text（按可见文本匹配 accessibility name，可用 scope 限定子树）、point（视口坐标）。clickMode 默认 auto：可见页按设备模拟状态使用可信 mouse/touch，隐藏页不切换标签或还原窗口并自动使用 DOM fallback；checkbox/radio 使用带状态校验的 DOM 路径。可用 dom/mouse/touch 强制派发方式。响应返回实际 dispatchMode，可信输入还返回 pointerType。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1086,7 +1111,7 @@ async function main() {
                     },
                     selector: {
                         type: 'string',
-                        description: '原生 CSS 选择器（如 "[aria-label=\'提交\']"、"#login-btn"）或 snapshot ref（如 "@e3"，必须带 "@" 前缀）。注意字段名是 "selector" 而非 "ref"。不支持 :has-text/:visible 等 Playwright 扩展语法。与 text/point 互斥。',
+                        description: '原生 CSS 选择器（如 "[aria-label=\'提交\']"、"#login-btn"）或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e3"，必须带 "@" 前缀）。注意字段名是 "selector" 而非 "ref"。不支持 :has-text/:visible 等 Playwright 扩展语法。与 text/point 互斥。',
                     },
                     text: {
                         type: 'string',
@@ -1110,11 +1135,15 @@ async function main() {
                         description: '配合 text 使用，默认 true 精确匹配；false 时按子串匹配',
                         default: true,
                     },
-                    clickType: {
+                    scope: {
+                        type: 'string',
+                        description: '配合 text 使用，把 AX 文本匹配限制在指定 CSS 元素或 snapshot ref（如 "@e12"）子树内',
+                    },
+                    clickMode: {
                         type: 'string',
-                        enum: ['js', 'cdp'],
-                        description: '点击方式。默认 js：对 selector/@ref 调用 el.click()；cdp：派发真实 mouse/touch 事件。text/point 始终用 cdp',
-                        default: 'js',
+                        enum: ['auto', 'dom', 'mouse', 'touch'],
+                        description: '点击模式。auto 在可见页按设备模拟状态选择可信 mouse/touch，在隐藏页使用 DOM fallback，checkbox/radio 使用带状态校验的 DOM 路径；dom/mouse/touch 强制指定派发方式',
+                        default: 'auto',
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
                 },
@@ -1133,7 +1162,7 @@ async function main() {
                     },
                     selector: {
                         type: 'string',
-                        description: '原生 CSS 选择器或 snapshot ref（如 "@e6"，必须带 "@" 前缀）。字段名是 "selector"。不支持 :has-text/:visible 等 Playwright 扩展。',
+                        description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e6"，必须带 "@" 前缀）。字段名是 "selector"。不支持 :has-text/:visible 等 Playwright 扩展。',
                     },
                     text: {
                         type: 'string',
@@ -1151,7 +1180,7 @@ async function main() {
         },
         {
             name: 'browser_page_scroll',
-            description: '滚动页面，默认内置观察（懒加载内容等变化），返回 { action, observation }；传 observe:false 仅执行裸滚动。支持 up、down、top、bottom 四个方向。',
+            description: '滚动页面或指定滚动容器，默认内置观察（懒加载内容等变化），返回 { action, observation }；传 observe:false 仅执行裸滚动。支持 up、down、top、bottom 四个方向；containerPolicy="nearest" 可从目标子节点解析最近可滚动祖先。动作结果包含前后位置、是否移动和边界状态。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1169,6 +1198,15 @@ async function main() {
                         description: '滚动距离（像素），仅 up/down 方向有效。默认 600',
                         default: 600,
                     },
+                    selector: {
+                        type: 'string',
+                        description: '目标滚动容器的原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e6"，必须带 "@" 前缀）；不传时滚动页面。',
+                    },
+                    containerPolicy: {
+                        type: 'string',
+                        enum: ['self', 'nearest'],
+                        description: '默认 self，要求 selector 本身可滚动；nearest 会在其不可滚动时使用最近的可滚动祖先',
+                    },
                     observe: OBSERVE_INPUT_SCHEMA,
                 },
                 required: ['tabId', 'direction'],
@@ -1186,7 +1224,7 @@ async function main() {
                     },
                     selector: {
                         type: 'string',
-                        description: '原生 CSS 选择器或 snapshot ref（如 "@e1"，必须带 "@" 前缀）。字段名是 "selector"。不支持 :has-text/:visible 等 Playwright 扩展。',
+                        description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e1"，必须带 "@" 前缀）。字段名是 "selector"。不支持 :has-text/:visible 等 Playwright 扩展。',
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
                 },
@@ -1195,7 +1233,7 @@ async function main() {
         },
         {
             name: 'browser_page_eval',
-            description: '在页面上下文中执行任意 JavaScript 表达式并返回结果。适用于：获取页面数据、操作 DOM、调用页面 API 等。',
+            description: '在页面上下文中执行 JavaScript 表达式并返回结果，作为结构化页面能力无法表达时的补充。默认裸执行；仅在表达式会修改页面且需要变化信号时显式传 observe 对象。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1216,13 +1254,18 @@ async function main() {
                         description: '是否等待表达式返回的 Promise，默认 true',
                         default: true,
                     },
+                    observe: {
+                        ...OBSERVE_INPUT_SCHEMA,
+                        type: 'object',
+                        description: '仅在表达式会修改页面且需要观察结果时显式传入；不传时轻量执行并直接返回结果',
+                    },
                 },
                 required: ['tabId', 'expression'],
             },
         },
         {
             name: 'browser_page_snapshot',
-            description: '获取页面无障碍树，返回角色、名称、值、状态和 @ref。默认 mode="full" 建立完整基线；长列表可用 mode="viewport"，表单可用 mode="interactive"，已知弹层或区域可用 rootSelector 获取局部子树。页面缺少 AX 控件语义时 interactive 会自动回退到 viewport，并返回 fallbackMode="viewport"。后续交互依赖页面交互工具内置的观察结果，仅在建议回退、导航或 ref 失效时再次调用。',
+            description: '获取页面无障碍树，返回角色、名称、值、状态和 @ref。默认 mode="full" 建立完整基线；长列表可用 mode="viewport"，只看当前视口内的表单控件可用 mode="interactive"，已知 CSS 区域可用 rootSelector，已有 ref 可用 rootRef + ancestorDepth 获取局部上下文，只查找特定文本/角色时用 query 服务端裁剪。视口内缺少 AX 控件语义时 interactive 会自动回退到 viewport，并返回 fallbackMode="viewport"。后续交互依赖页面交互工具内置的观察结果，仅在建议回退、导航或 ref 失效时再次调用。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1238,11 +1281,39 @@ async function main() {
                     mode: {
                         type: 'string',
                         enum: ['full', 'interactive', 'viewport'],
-                        description: '输出范围：full 为完整树；interactive 优先保留语义控件，无 AX 控件语义时自动回退到 viewport；viewport 只保留当前可视区域。默认 full',
+                        description: '输出范围：full 为完整树；interactive 只保留当前视口内的语义控件，视口内无 AX 控件语义时自动回退到 viewport；viewport 只保留当前可视区域。默认 full',
                     },
                     rootSelector: {
                         type: 'string',
-                        description: '只获取指定 CSS 元素的 AX 子树，可与 mode 组合',
+                        description: '只获取指定 CSS 元素的 AX 子树，可与 mode 组合；与 rootRef 互斥',
+                    },
+                    rootRef: {
+                        type: 'string',
+                        description: '以已有 snapshot ref（如 "@e8"）为根获取局部 AX 子树',
+                    },
+                    ancestorDepth: {
+                        type: 'number',
+                        description: 'rootRef 向上扩展的 DOM 祖先层数，默认 0，最大 20',
+                        minimum: 0,
+                        maximum: 20,
+                    },
+                    query: {
+                        type: 'object',
+                        description: '服务端过滤 AX 树，只保留按 accessibility name / role 命中的节点及祖先路径',
+                        properties: {
+                            text: {
+                                type: 'string',
+                                description: '要匹配的 accessibility name',
+                            },
+                            role: {
+                                type: 'string',
+                                description: '要匹配的 AX role',
+                            },
+                            exact: {
+                                type: 'boolean',
+                                description: 'text 默认精确匹配；false 时按子串匹配',
+                            },
+                        },
                     },
                     maxNodes: {
                         type: 'number',
@@ -1318,7 +1389,7 @@ async function main() {
         },
         {
             name: 'browser_page_navigate',
-            description: '在指定标签页中导航到新的 URL；或设置 refresh:true 直接重新加载当前页面（无需 url）。返回导航结果，可用于验证页面是否成功加载。',
+            description: '在指定标签页中导航到 URL、设置 refresh:true 重新加载，或用 history:"back"|"forward" 沿浏览历史移动。三种模式互斥，返回最终 URL 和标题。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1328,13 +1399,18 @@ async function main() {
                     },
                     url: {
                         type: 'string',
-                        description: '要导航到的 URL。refresh 为 true 时可省略（此时刷新当前页面）',
+                        description: '要导航到的 URL；与 refresh/history 互斥',
                     },
                     refresh: {
                         type: 'boolean',
-                        description: '为 true 时直接重新加载当前页面（忽略 url），用于刷新页面。默认 false',
+                        description: '为 true 时直接重新加载当前页面；与 url/history 互斥',
                         default: false,
                     },
+                    history: {
+                        type: 'string',
+                        enum: ['back', 'forward'],
+                        description: '沿当前标签页浏览历史后退或前进；与 url/refresh 互斥',
+                    },
                 },
                 required: ['tabId'],
             },
@@ -1351,7 +1427,7 @@ async function main() {
                     },
                     selector: {
                         type: 'string',
-                        description: '原生 CSS 选择器或 snapshot ref（如 "@e5"，必须带 "@" 前缀），用于定位 <input type="file"> 元素。字段名是 "selector"。',
+                        description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e5"，必须带 "@" 前缀），用于定位 <input type="file"> 元素。字段名是 "selector"。',
                     },
                     filePaths: {
                         type: 'array',
@@ -1521,18 +1597,26 @@ async function main() {
                     break;
                 }
                 case 'browser_get_events': {
-                    const { tabId, source = 'all', event_type, filter, since, limit = 20 } = args;
-                    result = await client.getEvents({ tabId, source, event_type, filter, since, limit });
+                    const { tabId, source = 'all', event_type, filter, since, limit = 20, includeRaw = false, } = args;
+                    result = await client.getEvents({
+                        tabId,
+                        source,
+                        event_type,
+                        filter,
+                        since,
+                        limit,
+                        includeRaw,
+                    });
                     break;
                 }
                 case 'browser_get_logs': {
-                    const { level = 'all', since, limit = 100, filter } = args;
-                    result = await client.getLogs({ level, since, limit, filter });
+                    const { tabId, level = 'all', since, limit = 100, filter } = args;
+                    result = await client.getLogs({ tabId, level, since, limit, filter });
                     break;
                 }
                 case 'browser_set_mock': {
                     const { payloadFile } = args;
-                    let { apiName, mockData, fields, enabled, duration, conditions } = args;
+                    let { tabId, apiName, mockData, fields, enabled, duration, conditions } = args;
                     enabled = enabled ?? true;
                     // 如果提供了 payloadFile，从文件读取 mock 数据
                     if (payloadFile) {
@@ -1541,7 +1625,9 @@ async function main() {
                         }
                         const fileContent = readFileSync(payloadFile, 'utf-8');
                         const fileData = JSON.parse(fileContent);
-                        // 文件内容可以包含 apiName、mockData、fields、enabled、duration、conditions 等参数
+                        // 文件内容可以包含 tabId、apiName、mockData、fields、enabled、duration、conditions 等参数
+                        if (fileData.tabId !== undefined)
+                            tabId = fileData.tabId;
                         if (fileData.apiName)
                             apiName = fileData.apiName;
                         if (fileData.mockData !== undefined)
@@ -1556,6 +1642,7 @@ async function main() {
                             conditions = fileData.conditions;
                     }
                     result = await client.setMock({
+                        tabId,
                         apiName,
                         mockData,
                         fields,
@@ -1566,8 +1653,8 @@ async function main() {
                     break;
                 }
                 case 'browser_get_mocks': {
-                    const { apiName } = args;
-                    result = await client.getMocks({ apiName });
+                    const { tabId, apiName } = args;
+                    result = await client.getMocks({ tabId, apiName });
                     break;
                 }
                 case 'browser_get_api_schema': {
@@ -1659,6 +1746,10 @@ async function main() {
                     result = await client.browserClose(args);
                     break;
                 }
+                case 'browser_release': {
+                    result = await client.browserRelease();
+                    break;
+                }
                 case 'browser_tab_open': {
                     const { url, active = false, closeExisting = false, reuse = 'never', match, restoreFocusOnClose = false, emulation, group, } = args;
                     result = await client.tabOpen({
@@ -1683,7 +1774,7 @@ async function main() {
                     break;
                 }
                 case 'browser_page_click': {
-                    const { tabId, selector, text, point, role, exact, clickType, observe } = args;
+                    const { tabId, selector, text, point, role, exact, scope, clickMode, observe } = args;
                     result = await client.pageClick({
                         tabId,
                         selector,
@@ -1691,7 +1782,8 @@ async function main() {
                         point,
                         role,
                         exact,
-                        clickType,
+                        scope,
+                        clickMode,
                         observe,
                     });
                     break;
@@ -1702,8 +1794,15 @@ async function main() {
                     break;
                 }
                 case 'browser_page_scroll': {
-                    const { tabId, direction, distance = 600, observe } = args;
-                    result = await client.pageScroll({ tabId, direction, distance, observe });
+                    const { tabId, direction, distance = 600, selector, containerPolicy, observe, } = args;
+                    result = await client.pageScroll({
+                        tabId,
+                        direction,
+                        distance,
+                        selector,
+                        containerPolicy,
+                        observe,
+                    });
                     break;
                 }
                 case 'browser_page_hover': {
@@ -1712,17 +1811,20 @@ async function main() {
                     break;
                 }
                 case 'browser_page_eval': {
-                    const { tabId, expression, frameId, awaitPromise = true } = args;
-                    result = await client.pageEval({ tabId, expression, frameId, awaitPromise });
+                    const { tabId, expression, frameId, awaitPromise = true, observe } = args;
+                    result = await client.pageEval({ tabId, expression, frameId, awaitPromise, observe });
                     break;
                 }
                 case 'browser_page_snapshot': {
-                    const { tabId, depth = 15, mode, rootSelector, maxNodes, maxChars } = args;
+                    const { tabId, depth = 15, mode, rootSelector, rootRef, ancestorDepth, query, maxNodes, maxChars, } = args;
                     result = await client.pageSnapshot({
                         tabId,
                         depth,
                         mode,
                         rootSelector,
+                        rootRef,
+                        ancestorDepth,
+                        query,
                         maxNodes,
                         maxChars,
                     });
@@ -1746,8 +1848,8 @@ async function main() {
                     break;
                 }
                 case 'browser_page_navigate': {
-                    const { tabId, url, refresh } = args;
-                    result = await client.pageNavigate({ tabId, url, refresh });
+                    const { tabId, url, refresh, history } = args;
+                    result = await client.pageNavigate({ tabId, url, refresh, history });
                     break;
                 }
                 case 'browser_page_upload': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/mcp-server",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "MCP Server for Mearl - enables AI to interact with Chrome browser requests and logs",
   "mcpName": "io.github.F-loat/mearl",
   "type": "module",
@@ -30,8 +30,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "prompts": "^2.4.2",
-    "@mearl/client": "2.0.1",
-    "@mearl/native-host": "2.0.1"
+    "@mearl/client": "2.1.0",
+    "@mearl/native-host": "2.1.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",