@mearl/mcp-server 2.0.1 → 2.0.2

package/README.md

@@ -15,12 +15,14 @@
 
 ## 浏览器交互工作流
 
-首次进入页面时调用 `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

@@ -322,7 +322,7 @@ async function main() {
         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,
+                    },
                 },
             },
         },
@@ -1076,7 +1081,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 +1091,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 +1115,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 +1142,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 +1160,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 +1178,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 +1204,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 +1213,7 @@ async function main() {
         },
         {
             name: 'browser_page_eval',
-            description: '在页面上下文中执行任意 JavaScript 表达式并返回结果。适用于：获取页面数据、操作 DOM、调用页面 API 等。',
+            description: '在页面上下文中执行 JavaScript 表达式并返回结果，作为结构化页面能力无法表达时的补充。默认裸执行；仅在表达式会修改页面且需要变化信号时显式传 observe 对象。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1216,13 +1234,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 +1261,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 +1369,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 +1379,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 +1407,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,8 +1577,16 @@ 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': {
@@ -1683,7 +1747,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 +1755,8 @@ async function main() {
                         point,
                         role,
                         exact,
-                        clickType,
+                        scope,
+                        clickMode,
                         observe,
                     });
                     break;
@@ -1702,8 +1767,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 +1784,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 +1821,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.0.2",
   "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/native-host": "2.0.2",
+    "@mearl/client": "2.0.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",