@mearl/mcp-server 2.2.2 → 2.4.0

package/dist/index.js

@@ -27,6 +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_get_requests: 'get_requests',
     browser_get_events: 'get_events',
     browser_get_logs: 'get_logs',
@@ -363,12 +364,12 @@ 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；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_eval 默认裸执行且应作为结构化能力无法表达时的补充，仅在表达式修改页面并需要变化信号时显式传 observe 对象。视觉任务再使用 screenshot。不要在每次动作后固定调用 browser_page_wait、snapshot 或 screenshot。',
+        instructions: '浏览器交互默认工作流：首次进入页面时使用 browser_page_snapshot 建立页面基线；后续点击、输入、悬停、滚动、按键和上传直接使用 browser_page_click/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_eval 默认裸执行且应作为结构化能力无法表达时的补充；需要页面变化信号时传 observe 对象，需要原子诊断时传 diagnostics:true 或对象。视觉任务再使用 screenshot。不要在每次动作后固定调用 browser_page_wait、snapshot 或 screenshot。',
     });
     // 页面交互工具共享的 observe 参数 schema：默认开启内置观察，传 false 关闭
     const OBSERVE_INPUT_SCHEMA = {
         type: ['object', 'boolean'],
-        description: '观察选项。默认开启内置观察（等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定后返回页面变化信号）；传 false 关闭观察，仅执行裸动作并直接返回其结果',
+        description: '观察选项。默认开启内置观察（等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定后返回页面变化信号）；传 false 只关闭 DOM/导航观察，默认诊断增量仍会返回',
         properties: {
             quietMs: {
                 type: 'number',
@@ -400,11 +401,48 @@ async function main() {
             },
         },
     };
+    const DIAGNOSTICS_INPUT_SCHEMA = {
+        type: ['object', 'boolean'],
+        description: '页面交互默认在动作真正执行前建立原子边界，并在稳定后返回新增 error logs 和全部业务 requests。传 false 关闭；传 true 使用默认配置；传对象自定义通道与过滤。page_eval 默认关闭',
+        properties: {
+            logs: {
+                type: ['object', 'boolean'],
+                properties: {
+                    level: { type: 'string', enum: ['log', 'warn', 'error', 'info', 'all'] },
+                    limit: { type: 'number', default: 100 },
+                    filter: { type: 'string' },
+                },
+            },
+            requests: {
+                type: ['object', 'boolean'],
+                properties: {
+                    source: { type: 'string', enum: ['mtop', 'requests', 'all'] },
+                    count: { type: 'number', default: 100 },
+                    filter: { type: 'string' },
+                    includeBody: { type: 'boolean', default: false },
+                    includeHeaders: { type: 'boolean', default: false },
+                },
+            },
+        },
+    };
     // 定义工具列表
     const tools = defineMcpTools([
+        {
+            name: 'browser_capture_checkpoint',
+            description: '为目标标签页当前已采集的 console/network 建立可靠增量边界。返回的 cursor 可传给 browser_get_logs/browser_get_requests 的 after。',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    tabId: {
+                        type: 'number',
+                        description: '目标标签页 ID；不传时使用当前活动标签页',
+                    },
+                },
+            },
+        },
         {
             name: 'browser_get_requests',
-            description: '获取浏览器中最近的 API 请求历史记录，包含完整的请求和响应信息。适用于分析性能、排查问题、查看数据流等场景。无需等待用户操作，立即返回已有数据。',
+            description: '获取指定标签页持续采集的 API 请求历史，包含请求、响应与 pending 状态。无需打开 DevTools panel；不传 after 时返回最新 N 条，传 after 时从最早未读项开始分页。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -425,6 +463,10 @@ async function main() {
                         type: 'number',
                         description: '从多久之前开始获取（秒）。例如: 60 表示获取最近 1 分钟内的请求',
                     },
+                    after: {
+                        type: 'string',
+                        description: 'capture checkpoint 或上一次查询返回的 cursor，仅返回其后的请求',
+                    },
                     includeBody: {
                         type: 'boolean',
                         description: '是否包含请求体和响应体。false 时将省略 postData 和 responseBody 字段以减少数据量。默认 true',
@@ -454,8 +496,8 @@ async function main() {
                     },
                     source: {
                         type: 'string',
-                        enum: ['mtop', 'requests'],
-                        description: '数据源。mtop: mtop 接口（默认）; requests: 普通 XHR/Fetch 请求',
+                        enum: ['mtop', 'requests', 'all'],
+                        description: '数据源。mtop: mtop 接口（默认）; requests: 普通 XHR/Fetch 请求; all: 全部业务请求',
                     },
                 },
             },
@@ -503,7 +545,7 @@ async function main() {
         },
         {
             name: 'browser_get_logs',
-            description: '获取浏览器控制台日志（console.log/warn/error/info）。适用于排查前端错误、调试代码执行流程、查看调试信息等场景。',
+            description: '获取指定标签页持续采集的 console API、未捕获异常和浏览器日志。无需打开 DevTools panel；不传 after 时返回最新 N 条，传 after 时从最早未读项开始分页。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -521,9 +563,13 @@ async function main() {
                         type: 'number',
                         description: '从多久之前开始获取日志（秒）。例如: 60 表示获取最近 1 分钟内的日志',
                     },
+                    after: {
+                        type: 'string',
+                        description: 'capture checkpoint 或上一次查询返回的 cursor，仅返回其后的日志',
+                    },
                     limit: {
                         type: 'number',
-                        description: '最大返回日志数量，默认 100。避免返回过多数据',
+                        description: '最大返回日志数量，默认 100；快照查询返回最新 N 条',
                         default: 100,
                     },
                     filter: {
@@ -1181,7 +1227,7 @@ async function main() {
         },
         {
             name: 'browser_page_click',
-            description: '点击页面元素，默认内置观察：同一次调用内等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定，返回 { action, observation }；点击直接打开新标签页时 observation.openedTabs 返回可继续操作的 tabId、URL、标题和加载状态。传 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。',
+            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。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1226,13 +1272,14 @@ async function main() {
                         default: 'auto',
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
+                    diagnostics: DIAGNOSTICS_INPUT_SCHEMA,
                 },
                 required: ['tabId'],
             },
         },
         {
             name: 'browser_page_type',
-            description: '向输入框填写文本，默认内置观察（校验提示等异步变化），返回 { action, observation }；传 observe:false 仅执行裸输入。兼容 React 等框架的受控组件，会自动触发 input 和 change 事件。selector 支持原生 CSS 或 "@eN" snapshot ref。',
+            description: '向输入框填写文本，默认内置观察与原子诊断（校验提示、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸输入。兼容 React 等框架的受控组件，会自动触发 input 和 change 事件。selector 支持原生 CSS 或 "@eN" snapshot ref。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1254,13 +1301,14 @@ async function main() {
                         default: true,
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
+                    diagnostics: DIAGNOSTICS_INPUT_SCHEMA,
                 },
                 required: ['tabId', 'selector', 'text'],
             },
         },
         {
             name: 'browser_page_scroll',
-            description: '滚动页面或指定滚动容器，默认内置观察（懒加载内容等变化），返回 { action, observation }；传 observe:false 仅执行裸滚动。支持 up、down、top、bottom 四个方向；containerPolicy="nearest" 可从目标子节点解析最近可滚动祖先。动作结果包含前后位置、是否移动和边界状态。',
+            description: '滚动页面或指定滚动容器，默认内置观察与原子诊断（懒加载内容、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸滚动。支持 up、down、top、bottom 四个方向；containerPolicy="nearest" 可从目标子节点解析最近可滚动祖先。动作结果包含前后位置、是否移动和边界状态。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1288,13 +1336,14 @@ async function main() {
                         description: '默认 self，要求 selector 本身可滚动；nearest 会在其不可滚动时使用最近的可滚动祖先',
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
+                    diagnostics: DIAGNOSTICS_INPUT_SCHEMA,
                 },
                 required: ['tabId', 'direction'],
             },
         },
         {
             name: 'browser_page_hover',
-            description: '将鼠标悬停在元素上，默认内置观察（下拉菜单、提示等变化），返回 { action, observation }；传 observe:false 仅执行裸悬停。使用 CDP Input.dispatchMouseEvent 发送真实鼠标移动事件，selector 支持原生 CSS 或 "@eN" snapshot ref。',
+            description: '将鼠标悬停在元素上，默认内置观察与原子诊断（下拉菜单、提示、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸悬停。使用 CDP Input.dispatchMouseEvent 发送真实鼠标移动事件，selector 支持原生 CSS 或 "@eN" snapshot ref。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1307,13 +1356,14 @@ async function main() {
                         description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e1"，必须带 "@" 前缀）。字段名是 "selector"。不支持 :has-text/:visible 等 Playwright 扩展。',
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
+                    diagnostics: DIAGNOSTICS_INPUT_SCHEMA,
                 },
                 required: ['tabId', 'selector'],
             },
         },
         {
             name: 'browser_page_eval',
-            description: '在页面上下文中执行 JavaScript 表达式并返回结果，作为结构化页面能力无法表达时的补充。默认裸执行；仅在表达式会修改页面且需要变化信号时显式传 observe 对象。',
+            description: '在页面上下文中执行 JavaScript 表达式并返回结果，作为结构化页面能力无法表达时的补充。默认裸执行；需要页面变化信号时显式传 observe 对象，需要原子返回新增 error logs/业务 requests 时传 diagnostics:true 或过滤对象。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1339,6 +1389,7 @@ async function main() {
                         type: 'object',
                         description: '仅在表达式会修改页面且需要观察结果时显式传入；不传时轻量执行并直接返回结果',
                     },
+                    diagnostics: DIAGNOSTICS_INPUT_SCHEMA,
                 },
                 required: ['tabId', 'expression'],
             },
@@ -1409,7 +1460,7 @@ async function main() {
         },
         {
             name: 'browser_page_press',
-            description: '在页面中按下键盘按键，默认内置观察（提交、关闭弹窗等结果），返回 { action, observation }；传 observe:false 仅执行裸按键。支持单个按键和组合键。',
+            description: '在页面中按下键盘按键，默认内置观察与原子诊断（提交、关闭弹窗、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸按键。支持单个按键和组合键。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1427,6 +1478,7 @@ async function main() {
                         description: '修饰键数组，如 ["Alt", "Shift", "Control", "Meta"]',
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
+                    diagnostics: DIAGNOSTICS_INPUT_SCHEMA,
                 },
                 required: ['tabId', 'key'],
             },
@@ -1497,7 +1549,7 @@ async function main() {
         },
         {
             name: 'browser_page_upload',
-            description: '向 <input type="file"> 上传单个或多个文件（通过 CDP DOM.setFileInputFiles），默认内置观察（上传状态变化），返回 { action, observation }；传 observe:false 仅执行裸上传。selector 支持原生 CSS 或 "@eN" snapshot ref。',
+            description: '向 <input type="file"> 上传单个或多个文件（通过 CDP DOM.setFileInputFiles），默认内置观察与原子诊断（上传状态、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸上传。selector 支持原生 CSS 或 "@eN" snapshot ref。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1515,6 +1567,7 @@ async function main() {
                         description: '要上传的本地文件路径数组，如 ["/Users/me/photo.jpg"]',
                     },
                     observe: OBSERVE_INPUT_SCHEMA,
+                    diagnostics: DIAGNOSTICS_INPUT_SCHEMA,
                 },
                 required: ['tabId', 'selector', 'filePaths'],
             },
@@ -1663,13 +1716,19 @@ async function main() {
             const toolName = name;
             let result;
             switch (toolName) {
+                case 'browser_capture_checkpoint': {
+                    const { tabId } = args;
+                    result = await client.captureCheckpoint({ tabId });
+                    break;
+                }
                 case 'browser_get_requests': {
-                    const { tabId, count = 10, filter, since, includeBody = true, includeHeaders = false, maxBodySize = 50000, fields, keysOnly = false, source, } = args;
+                    const { tabId, count = 10, filter, since, after, includeBody = true, includeHeaders = false, maxBodySize = 50000, fields, keysOnly = false, source, } = args;
                     result = await client.getRequests({
                         tabId,
                         count,
                         filter,
                         since,
+                        after,
                         includeBody,
                         includeHeaders,
                         maxBodySize,
@@ -1693,8 +1752,8 @@ async function main() {
                     break;
                 }
                 case 'browser_get_logs': {
-                    const { tabId, level = 'all', since, limit = 100, filter } = args;
-                    result = await client.getLogs({ tabId, level, since, limit, filter });
+                    const { tabId, level = 'all', since, after, limit = 100, filter } = args;
+                    result = await client.getLogs({ tabId, level, since, after, limit, filter });
                     break;
                 }
                 case 'browser_set_mock': {
@@ -1858,7 +1917,7 @@ async function main() {
                     break;
                 }
                 case 'browser_page_click': {
-                    const { tabId, selector, text, point, role, exact, scope, clickMode, observe } = args;
+                    const { tabId, selector, text, point, role, exact, scope, clickMode, observe, diagnostics, } = args;
                     result = await client.pageClick({
                         tabId,
                         selector,
@@ -1869,16 +1928,24 @@ async function main() {
                         scope,
                         clickMode,
                         observe,
+                        diagnostics,
                     });
                     break;
                 }
                 case 'browser_page_type': {
-                    const { tabId, selector, text, clearFirst = true, observe } = args;
-                    result = await client.pageType({ tabId, selector, text, clearFirst, observe });
+                    const { tabId, selector, text, clearFirst = true, observe, diagnostics } = args;
+                    result = await client.pageType({
+                        tabId,
+                        selector,
+                        text,
+                        clearFirst,
+                        observe,
+                        diagnostics,
+                    });
                     break;
                 }
                 case 'browser_page_scroll': {
-                    const { tabId, direction, distance = 600, selector, containerPolicy, observe, } = args;
+                    const { tabId, direction, distance = 600, selector, containerPolicy, observe, diagnostics, } = args;
                     result = await client.pageScroll({
                         tabId,
                         direction,
@@ -1886,17 +1953,25 @@ async function main() {
                         selector,
                         containerPolicy,
                         observe,
+                        diagnostics,
                     });
                     break;
                 }
                 case 'browser_page_hover': {
-                    const { tabId, selector, observe } = args;
-                    result = await client.pageHover({ tabId, selector, observe });
+                    const { tabId, selector, observe, diagnostics } = args;
+                    result = await client.pageHover({ tabId, selector, observe, diagnostics });
                     break;
                 }
                 case 'browser_page_eval': {
-                    const { tabId, expression, frameId, awaitPromise = true, observe } = args;
-                    result = await client.pageEval({ tabId, expression, frameId, awaitPromise, observe });
+                    const { tabId, expression, frameId, awaitPromise = true, observe, diagnostics, } = args;
+                    result = await client.pageEval({
+                        tabId,
+                        expression,
+                        frameId,
+                        awaitPromise,
+                        observe,
+                        diagnostics,
+                    });
                     break;
                 }
                 case 'browser_page_snapshot': {
@@ -1915,8 +1990,8 @@ async function main() {
                     break;
                 }
                 case 'browser_page_press': {
-                    const { tabId, key, modifiers, observe } = args;
-                    result = await client.pagePress({ tabId, key, modifiers, observe });
+                    const { tabId, key, modifiers, observe, diagnostics } = args;
+                    result = await client.pagePress({ tabId, key, modifiers, observe, diagnostics });
                     break;
                 }
                 case 'browser_page_wait': {
@@ -1937,8 +2012,8 @@ async function main() {
                     break;
                 }
                 case 'browser_page_upload': {
-                    const { tabId, selector, filePaths, observe } = args;
-                    result = await client.pageUpload({ tabId, selector, filePaths, observe });
+                    const { tabId, selector, filePaths, observe, diagnostics } = args;
+                    result = await client.pageUpload({ tabId, selector, filePaths, observe, diagnostics });
                     break;
                 }
                 case 'browser_page_frames': {

package/package.json

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