@mearl/mcp-server 2.7.1 → 2.7.2

package/dist/index.js

@@ -27,7 +27,7 @@ import { RESPONSE_SIZE_SMALL, RESPONSE_SIZE_MEDIUM, RESPONSE_SIZE_LARGE, RESPONS
 const require = createRequire(import.meta.url);
 const MCP_SERVER_VERSION = require('../package.json').version;
 const MCP_TOOL_ACTIONS = {
-    browser_capture_checkpoint: 'capture_checkpoint',
+    browser_tab_checkpoint: 'tab_checkpoint',
     browser_get_requests: 'get_requests',
     browser_get_events: 'get_events',
     browser_get_logs: 'get_logs',
@@ -365,12 +365,13 @@ async function main() {
         capabilities: {
             tools: {},
         },
-        instructions: '浏览器交互默认工作流：首次进入页面时使用 browser_page_snapshot 建立页面基线；后续点击、拖动、输入、悬停、滚动、按键和上传直接使用 browser_page_click/drag/type/hover/scroll/press/upload，它们默认内置观察与原子诊断，动作、异步稳定判断、新增 error logs 和业务 requests 在一次调用内完成，返回 { action, observation, diagnostics }；传 observe:false 只关闭 DOM/导航观察并保留诊断，同时传 diagnostics: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。observation.openedTabs 表示动作直接打开的关联标签页，可显式使用返回的 tabId 继续操作，无需调用 browser_tab_list。其他情况下通常仅当 fullSnapshotRecommended 为 true 时根据 snapshotReasons 回退，并选择最小范围：已有区域 ref 用 rootRef，已有 CSS 根节点用 rootSelector，只需查找特定目标时加 query，长列表用 mode="viewport"，只需当前视口内的控件用 mode="interactive"；滚动动作的 moved 只证明位置变化，下一步需要读取新视口内容时可按需获取 viewport 快照。视口内缺少 AX 控件语义时 interactive 会在同一次调用中回退到 viewport，并返回 fallbackMode。重复文本点击用 scope 限定区域，ref 指向滚动容器子节点时用 containerPolicy="nearest"。轮播图、滑块和拖放使用 page_drag；不要用 page_eval 合成 DragEvent/PointerEvent。page_eval 默认裸执行且应作为结构化能力无法表达时的补充；需要页面变化信号时传 observe 对象，需要原子诊断时传 diagnostics:true 或对象。视觉任务再使用 screenshot。不要在每次动作后固定调用 browser_page_wait、snapshot 或 screenshot。',
+        instructions: '浏览器交互默认工作流：首次进入页面或导航后用 browser_page_snapshot 建立基线；后续页面动作默认返回 { action, observation }。先检查 action.success；action.stage=precondition 表示尚未派发，应按 error 修正输入或刷新快照，且不读取已省略的 observation/diagnostics。动作成功后再按 observation 处理：delta 读取 effects，navigation 在 ready=true 后重建快照，openedTabs 直接使用其 tabId。仅在 fullSnapshotRecommended=true 或需要读取滚动后的新视口时补最小范围快照；视觉任务使用 screenshot。无需页面观察时传 observe:false；需要动作期间的日志、请求或埋点时显式开启 diagnostics。page_eval 仅作为结构化 action 无法表达时的补充；不要在每次动作后固定追加 wait、snapshot 或 screenshot。',
     });
     // 页面交互工具共享的 observe 参数 schema：默认开启内置观察，传 false 关闭
     const OBSERVE_INPUT_SCHEMA = {
         type: ['object', 'boolean'],
-        description: '观察选项。默认开启内置观察（等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定后返回页面变化信号）；传 false 只关闭 DOM/导航观察，默认诊断增量仍会返回',
+        default: {},
+        description: '观察选项。默认开启内置观察（等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定后返回页面变化信号）；传 false 关闭，不影响显式请求的 diagnostics',
         properties: {
             quietMs: {
                 type: 'number',
@@ -404,7 +405,8 @@ async function main() {
     };
     const DIAGNOSTICS_INPUT_SCHEMA = {
         type: ['object', 'boolean'],
-        description: '页面交互默认在动作真正执行前建立原子边界，并在稳定后返回新增 error logs 和全部业务 requests。传 false 关闭；传 true 使用默认配置；传对象自定义通道与过滤。page_eval 默认关闭',
+        default: false,
+        description: '默认关闭。传 true 在动作执行前建立边界，并返回新增 error logs 和业务 requests；传对象可自定义通道与过滤，并按需开启 events',
         properties: {
             logs: {
                 type: ['object', 'boolean'],
@@ -424,13 +426,23 @@ async function main() {
                     includeHeaders: { type: 'boolean', default: false },
                 },
             },
+            events: {
+                type: ['object', 'boolean'],
+                properties: {
+                    source: { type: 'string', enum: ['rum', 'aplus', 'arms', 'all'] },
+                    event_type: { type: 'string' },
+                    filter: { type: 'string' },
+                    limit: { type: 'number', default: 100 },
+                    includeRaw: { type: 'boolean', default: false },
+                },
+            },
         },
     };
     // 定义工具列表
     const tools = defineMcpTools([
         {
-            name: 'browser_capture_checkpoint',
-            description: '为目标标签页当前已采集的 console/network 建立可靠增量边界。返回的 cursor 可传给 browser_get_logs/browser_get_requests 的 after。',
+            name: 'browser_tab_checkpoint',
+            description: '为目标标签页建立日志、请求和埋点的可靠增量边界，对应 mearl tab_checkpoint。返回的 cursor 可传给 browser_get_logs/browser_get_requests/browser_get_events 的 after。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -466,7 +478,7 @@ async function main() {
                     },
                     after: {
                         type: 'string',
-                        description: 'capture checkpoint 或上一次查询返回的 cursor，仅返回其后的请求',
+                        description: 'tab checkpoint 或上一次查询返回的 cursor，仅返回其后的请求',
                     },
                     includeBody: {
                         type: 'boolean',
@@ -505,7 +517,7 @@ async function main() {
         },
         {
             name: 'browser_get_events',
-            description: '获取目标标签页后台采集的 RUM/aplus/ARMS 埋点事件，无需打开 DevTools panel。包含页面资源性能指标、用户行为埋点、SPM 点击事件等。',
+            description: '获取目标标签页后台采集的 RUM/aplus/ARMS 埋点事件，无需打开 DevTools panel。不传 after 时返回最新事件，传 after 时按完整上报批次从最早未读项开始分页。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -531,6 +543,10 @@ async function main() {
                         type: 'number',
                         description: '从多久之前开始获取（秒）。例如: 60 表示获取最近 1 分钟内的事件',
                     },
+                    after: {
+                        type: 'string',
+                        description: 'tab checkpoint 或上一次查询返回的 cursor，仅返回其后的埋点事件',
+                    },
                     limit: {
                         type: 'number',
                         description: '返回条数上限，默认 20',
@@ -566,7 +582,7 @@ async function main() {
                     },
                     after: {
                         type: 'string',
-                        description: 'capture checkpoint 或上一次查询返回的 cursor，仅返回其后的日志',
+                        description: 'tab checkpoint 或上一次查询返回的 cursor，仅返回其后的日志',
                     },
                     limit: {
                         type: 'number',
@@ -1243,7 +1259,7 @@ async function main() {
         },
         {
             name: 'browser_page_click',
-            description: '点击页面元素，默认内置观察与原子诊断：同一次调用内等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定，返回 { action, observation, diagnostics }；diagnostics 默认包含新增 error logs 和全部业务 requests。点击直接打开新标签页时 observation.openedTabs 返回可继续操作的 tabId、URL、标题和加载状态。传 observe:false 只关闭观察并保留诊断，同时传 diagnostics: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。',
+            description: '点击页面元素；selector、text、point 三种定位方式必须且只能提供一种。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1284,7 +1300,7 @@ async function main() {
                     clickMode: {
                         type: 'string',
                         enum: ['auto', 'dom', 'mouse', 'touch'],
-                        description: '点击模式。auto 在可见页按设备模拟状态选择可信 mouse/touch，在隐藏页使用 DOM fallback，checkbox/radio 使用带状态校验的 DOM 路径；dom/mouse/touch 强制指定派发方式',
+                        description: '默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式',
                         default: 'auto',
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
@@ -1295,7 +1311,7 @@ async function main() {
         },
         {
             name: 'browser_page_drag',
-            description: '在页面内执行连续拖动，并默认内置观察与原子诊断，返回 { action, observation, diagnostics }。from/to 均可传原生 CSS、"@eN" snapshot ref 或 {x,y} 视口坐标；选择器端点需要同时位于当前视口。dragMode 默认 auto：可见页按设备模拟状态使用可信 touch/mouse，隐藏页自动使用不抢焦点的 DOM 模拟；可用 dom 显式强制模拟，mouse/touch 显式强制可信输入。适合轮播图滑动、滑块、画布手势和拖放。',
+            description: '连续拖动页面元素或视口坐标，适用于轮播图、滑块、Canvas 手势和拖放。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1328,7 +1344,7 @@ async function main() {
                     dragMode: {
                         type: 'string',
                         enum: ['auto', 'dom', 'mouse', 'touch'],
-                        description: '输入类型；auto 在可见页选择可信 touch/mouse、隐藏页使用 DOM 模拟；dom 显式强制模拟',
+                        description: '默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式',
                         default: 'auto',
                     },
                     durationMs: {
@@ -1346,7 +1362,7 @@ async function main() {
         },
         {
             name: 'browser_page_type',
-            description: '向输入框填写文本，默认内置观察与原子诊断（校验提示、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸输入。兼容 React 等框架的受控组件，会自动触发 input 和 change 事件。selector 支持原生 CSS 或 "@eN" snapshot ref。',
+            description: '向输入框填写文本，兼容 React 等框架的受控组件。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1375,7 +1391,7 @@ async function main() {
         },
         {
             name: 'browser_page_scroll',
-            description: '滚动页面或指定滚动容器，默认内置观察与原子诊断（懒加载内容、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸滚动。支持 up、down、top、bottom 四个方向；containerPolicy="nearest" 可从目标子节点解析最近可滚动祖先。动作结果包含前后位置、是否移动和边界状态。',
+            description: '按方向滚动页面或指定容器；containerPolicy="nearest" 可从子节点解析最近的可滚动祖先。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1410,7 +1426,7 @@ async function main() {
         },
         {
             name: 'browser_page_hover',
-            description: '将鼠标悬停在元素上，默认内置观察与原子诊断（下拉菜单、提示、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸悬停。使用 CDP Input.dispatchMouseEvent 发送真实鼠标移动事件，selector 支持原生 CSS 或 "@eN" snapshot ref。',
+            description: '将鼠标悬停在页面元素上。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1430,7 +1446,7 @@ async function main() {
         },
         {
             name: 'browser_page_eval',
-            description: '在页面上下文中执行 JavaScript 表达式并返回结果，作为结构化页面能力无法表达时的补充。默认裸执行；需要页面变化信号时显式传 observe 对象，需要原子返回新增 error logs/业务 requests 时传 diagnostics:true 或过滤对象。',
+            description: '在页面上下文中执行 JavaScript 表达式，作为结构化页面 action 无法表达时的补充。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1463,7 +1479,7 @@ async function main() {
         },
         {
             name: 'browser_page_snapshot',
-            description: '获取页面无障碍树，返回角色、名称、值、状态和 @ref。默认 mode="full" 建立完整基线；长列表可用 mode="viewport"，只看当前视口内的表单控件可用 mode="interactive"，已知 CSS 区域可用 rootSelector，已有 ref 可用 rootRef + ancestorDepth 获取局部上下文，只查找特定文本/角色时用 query 服务端裁剪。视口内缺少 AX 控件语义时 interactive 会自动回退到 viewport，并返回 fallbackMode="viewport"。后续交互依赖页面交互工具内置的观察结果，仅在建议回退、导航或 ref 失效时再次调用。',
+            description: '获取带 @ref 的页面无障碍树；支持完整、当前视口、交互控件、指定区域或查询结果。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1527,7 +1543,7 @@ async function main() {
         },
         {
             name: 'browser_page_press',
-            description: '在页面中按下键盘按键，默认内置观察与原子诊断（提交、关闭弹窗、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸按键。支持单个按键和组合键。',
+            description: '在页面中按下键盘按键或组合键。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1616,7 +1632,7 @@ async function main() {
         },
         {
             name: 'browser_page_upload',
-            description: '向 <input type="file"> 上传单个或多个文件（通过 CDP DOM.setFileInputFiles），默认内置观察与原子诊断（上传状态、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸上传。selector 支持原生 CSS 或 "@eN" snapshot ref。',
+            description: '向 <input type="file"> 元素上传一个或多个本地文件。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1641,7 +1657,7 @@ async function main() {
         },
         {
             name: 'browser_page_frames',
-            description: '列出当前页面中所有 frame（主 frame + iframe）。返回每个 frame 的 frameId、URL、名称等信息。适用于：了解页面是否包含 iframe、获取 iframe 的 frameId 以便在 browser_page_eval 中指定执行上下文。',
+            description: '列出主 frame 和 iframe，返回可供 browser_page_eval 使用的 frameId。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1776,16 +1792,19 @@ async function main() {
     });
     // 处理工具调用请求
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name, arguments: args } = request.params;
+        const { arguments: args } = request.params;
+        const name = request.params.name === 'browser_capture_checkpoint'
+            ? 'browser_tab_checkpoint'
+            : request.params.name;
         try {
             if (!(name in MCP_TOOL_ACTIONS))
                 throw new Error(`Unknown tool: ${name}`);
             const toolName = name;
             let result;
             switch (toolName) {
-                case 'browser_capture_checkpoint': {
+                case 'browser_tab_checkpoint': {
                     const { tabId } = args;
-                    result = await client.captureCheckpoint({ tabId });
+                    result = await client.tabCheckpoint({ tabId });
                     break;
                 }
                 case 'browser_get_requests': {
@@ -1806,13 +1825,14 @@ async function main() {
                     break;
                 }
                 case 'browser_get_events': {
-                    const { tabId, source = 'all', event_type, filter, since, limit = 20, includeRaw = false, } = args;
+                    const { tabId, source = 'all', event_type, filter, since, after, limit = 20, includeRaw = false, } = args;
                     result = await client.getEvents({
                         tabId,
                         source,
                         event_type,
                         filter,
                         since,
+                        after,
                         limit,
                         includeRaw,
                     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/mcp-server",
-  "version": "2.7.1",
+  "version": "2.7.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.7.1",
-    "@mearl/native-host": "2.7.1"
+    "@mearl/client": "2.7.2",
+    "@mearl/native-host": "2.7.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",