@mearl/mcp-server 2.2.0 → 2.2.1

package/README.md

@@ -12,11 +12,11 @@
 - 📴 **browser_release**: 按用户明确要求释放 debugger/CDP 控制和会话级临时效果，并保留浏览器与全部标签页
 - 🚀 **browser_launch / browser_close**: 启动或关闭独立 Profile 的托管 Chrome
 - 🌐 **browser_page_snapshot**: 首次获取页面结构和可交互元素
-- ⚡ **browser_page_click/type/hover/scroll/press/upload**: 执行页面动作，默认内置观察，返回通知、可交互控件和焦点等高置信度信号
+- ⚡ **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`。新增或变化的可交互节点会尽量携带可直接用于后续动作的 `node.ref`，解析不到 ref 时回退使用 `node.selector`。导航结果读取新 URL 和就绪状态。通常仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`browser_page_eval` 默认裸执行，仅在表达式会修改页面且需要变化信号时显式传 `observe` 对象。
+首次进入页面时调用 `browser_page_snapshot` 建立结构基线。后续点击、输入、悬停、滚动、按键和上传直接调用 `browser_page_click/type/hover/scroll/press/upload`，它们默认内置观察，动作与异步同步在一次调用内完成；同页结果读取 `effects.notifications`、`effects.interactives` 和 `effects.focus`。新增或变化的可交互节点会尽量携带可直接用于后续动作的 `node.ref`，解析不到 ref 时回退使用 `node.selector`。导航结果读取新 URL 和就绪状态；动作直接打开新标签页时，`openedTabs` 返回可继续操作的 `tabId`，无需调用 `browser_tab_list`。通常仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`browser_page_eval` 默认裸执行，仅在表达式会修改页面且需要变化信号时显式传 `observe` 对象。
 
 长列表重新感知时优先使用 `browser_page_snapshot(mode: "viewport")`；已知 CSS 区域时使用 `rootSelector`，已有 ref 时使用 `rootRef`，只查找特定文案或角色时使用 `query`；仅需要当前视口内的控件时使用 `mode: "interactive"`，避免整页 AX Tree 占用上下文。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。重复文本点击可用 `scope` 限定子树，滚动子节点所在容器可用 `containerPolicy: "nearest"`。
 

package/dist/index.js

@@ -363,7 +363,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；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。',
+        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。',
     });
     // 页面交互工具共享的 observe 参数 schema：默认开启内置观察，传 false 关闭
     const OBSERVE_INPUT_SCHEMA = {
@@ -609,7 +609,7 @@ async function main() {
         },
         {
             name: 'browser_send_request',
-            description: '通过浏览器发起 HTTP 代理请求，自动携带目标域名的 Cookie（使用当前浏览器登录态）。支持 GET/POST/PUT/DELETE/PATCH 等方法，适用于需要用户登录态的接口调试、数据爬取、接口测试等场景。',
+            description: '通过浏览器发起 HTTP 代理请求，自动携带目标域名的 Cookie（使用当前浏览器登录态）。支持 GET/POST/PUT/DELETE/PATCH、multipart 文本字段和本地文件上传，适用于需要用户登录态的接口调试、数据爬取、接口测试等场景。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -636,15 +636,50 @@ async function main() {
                     body: {
                         description: '请求体。传入对象时自动序列化为 JSON 并设置 Content-Type: application/json；传入字符串时原样发送',
                     },
+                    formData: {
+                        type: 'object',
+                        description: 'multipart/form-data 文本字段。字段值支持 string、number、boolean；不能与 body 同时使用',
+                        additionalProperties: {
+                            anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }],
+                        },
+                    },
+                    files: {
+                        type: 'array',
+                        description: 'multipart 文件列表，最多 20 个且总计不超过 40 MiB。本地调用优先传绝对 filePath；远程调用可传 base64，并同时提供 filename，Base64 文件内容总计不超过 7 MiB',
+                        maxItems: 20,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                fieldName: {
+                                    type: 'string',
+                                    description: 'multipart 字段名，例如 file',
+                                },
+                                filePath: {
+                                    type: 'string',
+                                    description: 'Mearl native-host 所在机器上的绝对文件路径',
+                                },
+                                base64: {
+                                    type: 'string',
+                                    description: '文件内容的 Base64；与 filePath 二选一',
+                                },
+                                filename: {
+                                    type: 'string',
+                                    description: '上传文件名；使用 base64 时必填',
+                                },
+                                contentType: {
+                                    type: 'string',
+                                    description: '文件 MIME 类型；默认根据文件名推断',
+                                },
+                            },
+                            required: ['fieldName'],
+                            oneOf: [{ required: ['filePath'] }, { required: ['base64', 'filename'] }],
+                        },
+                    },
                     withCookies: {
                         type: 'boolean',
                         description: '是否自动携带浏览器中该域名的 Cookie，默认 true',
                         default: true,
                     },
-                    cookieDomain: {
-                        type: 'string',
-                        description: '指定获取 Cookie 的域名（默认从 url 中自动提取域名）',
-                    },
                     responseType: {
                         type: 'string',
                         enum: ['json', 'text', 'auto'],
@@ -1040,6 +1075,10 @@ async function main() {
                         description: '是否激活（前台显示）新标签页。默认 false（后台打开）',
                         default: false,
                     },
+                    openerTabId: {
+                        type: 'number',
+                        description: '来源标签页 ID。侧边栏对话继续任务时传入，用于把新开或复用的标签页关联到同一对话',
+                    },
                     closeExisting: {
                         type: 'boolean',
                         description: '打开前是否先关闭 Agent 受控的已有标签页。默认 false',
@@ -1142,7 +1181,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，可用 scope 限定子树）、point（视口坐标）。clickMode 默认 auto：可见页按设备模拟状态使用可信 mouse/touch，隐藏页不切换标签或还原窗口并自动使用 DOM fallback；checkbox/radio 使用带状态校验的 DOM 路径。可用 dom/mouse/touch 强制派发方式。响应返回实际 dispatchMode，可信输入还返回 pointerType。',
+            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。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1795,10 +1834,11 @@ async function main() {
                     break;
                 }
                 case 'browser_tab_open': {
-                    const { url, active = false, closeExisting = false, reuse = 'never', match, restoreFocusOnClose = false, emulation, group, } = args;
+                    const { url, active = false, openerTabId, closeExisting = false, reuse = 'never', match, restoreFocusOnClose = false, emulation, group, } = args;
                     result = await client.tabOpen({
                         url,
                         active,
+                        openerTabId,
                         closeExisting,
                         reuse,
                         match,

package/package.json

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