@mearl/mcp-server 2.1.0 → 2.2.1

package/README.md

@@ -9,14 +9,14 @@
 - 📝 **browser_get_logs**: 获取控制台日志
 - 🎭 **browser_set_mock**: 动态设置 Mock 数据
 - 🌐 **browser_list**: 统一列出普通浏览器和托管浏览器，返回默认目标、类型及连接状态
-- 📴 **browser_release**: 释放 debugger/CDP 控制并保留浏览器与全部标签页
+- 📴 **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

@@ -26,6 +26,47 @@ 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;
+const MCP_TOOL_ACTIONS = {
+    browser_get_requests: 'get_requests',
+    browser_get_events: 'get_events',
+    browser_get_logs: 'get_logs',
+    browser_set_mock: 'set_mock',
+    browser_get_mocks: 'get_mocks',
+    browser_get_api_schema: 'get_api_schema',
+    browser_send_request: 'send_request',
+    browser_send_mtop_request: 'send_mtop_request',
+    browser_set_rule: 'set_rule',
+    browser_get_rules: 'get_rules',
+    browser_page_screenshot: 'page_screenshot',
+    browser_page_selected_element: 'page_selected_element',
+    get_user_info: 'get_user_info',
+    tdbank_account: 'tdbank_account',
+    browser_launch: 'browser_launch',
+    browser_close: 'browser_close',
+    browser_release: 'browser_release',
+    browser_tab_open: 'tab_open',
+    browser_tab_close: 'tab_close',
+    browser_tab_list: 'tab_list',
+    browser_page_click: 'page_click',
+    browser_page_type: 'page_type',
+    browser_page_scroll: 'page_scroll',
+    browser_page_hover: 'page_hover',
+    browser_page_eval: 'page_eval',
+    browser_page_snapshot: 'page_snapshot',
+    browser_page_press: 'page_press',
+    browser_page_wait: 'page_wait',
+    browser_page_navigate: 'page_navigate',
+    browser_page_upload: 'page_upload',
+    browser_page_frames: 'page_frames',
+    browser_set_device_emulation: 'set_device_emulation',
+    browser_set_timezone: 'set_timezone',
+    browser_run_actions: 'run_actions',
+    browser_list: 'browser_list',
+    browser_select_browser: 'browser_select_browser',
+};
+function defineMcpTools(tools) {
+    return tools;
+}
 // 日志输出到 stderr（不影响 stdio 通信）
 const LOG_FILE = join(tmpdir(), 'mearl-mcp-server.log');
 const log = (...args) => {
@@ -322,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 = {
@@ -360,7 +401,7 @@ async function main() {
         },
     };
     // 定义工具列表
-    const tools = [
+    const tools = defineMcpTools([
         {
             name: 'browser_get_requests',
             description: '获取浏览器中最近的 API 请求历史记录，包含完整的请求和响应信息。适用于分析性能、排查问题、查看数据流等场景。无需等待用户操作，立即返回已有数据。',
@@ -568,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: {
@@ -595,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'],
@@ -978,7 +1054,7 @@ async function main() {
         },
         {
             name: 'browser_release',
-            description: '释放 Agent 对当前目标浏览器的 debugger/CDP 控制，停止持续采集和会话级临时效果，但保留浏览器与全部标签页。后续浏览器操作仍可自动重新建立控制。',
+            description: '仅当用户明确要求结束调试、退出接管或清理会话资源时，释放当前目标浏览器的 debugger/CDP 控制；不要作为普通任务收尾。它会停止持续采集，并立即清除设备/时区模拟、会话级 Mock 和录制，但保留浏览器与全部标签页。后续浏览器操作仍可自动重新建立控制。',
             inputSchema: {
                 type: 'object',
                 properties: {},
@@ -999,6 +1075,10 @@ async function main() {
                         description: '是否激活（前台显示）新标签页。默认 false（后台打开）',
                         default: false,
                     },
+                    openerTabId: {
+                        type: 'number',
+                        description: '来源标签页 ID。侧边栏对话继续任务时传入，用于把新开或复用的标签页关联到同一对话',
+                    },
                     closeExisting: {
                         type: 'boolean',
                         description: '打开前是否先关闭 Agent 受控的已有标签页。默认 false',
@@ -1101,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: {
@@ -1455,7 +1535,7 @@ async function main() {
         },
         {
             name: 'browser_set_device_emulation',
-            description: '把目标标签页切换为移动端模拟态：视口尺寸 / DPR / UA / 触摸事件全部按指定设备生效，等价于 Chrome DevTools 设备工具栏，作用域仅限该 tab，会话结束自动还原。适用于：调试 H5 移动页面、让 page_click 在 swiper/fastclick 等只听 touchstart 的页面生效、让服务端按移动 UA 返回数据。启用后默认 reload 一次让页面以移动模式重新初始化。enabled=false 清除模拟。',
+            description: '把目标标签页切换为移动端模拟态：视口尺寸 / DPR / UA / 触摸事件全部按指定设备生效，等价于 Chrome DevTools 设备工具栏，作用域仅限该 tab，释放 debugger/CDP 控制会自动还原。适用于：调试 H5 移动页面、让 page_click 在 swiper/fastclick 等只听 touchstart 的页面生效、让服务端按移动 UA 返回数据。启用后默认 reload 一次让页面以移动模式重新初始化；成功响应中的实际配置可直接验证设置结果，无需固定追加快照。enabled=false 清除模拟。',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1569,7 +1649,7 @@ async function main() {
                 required: ['browser'],
             },
         },
-    ];
+    ]);
     // 处理工具列表请求
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         return { tools };
@@ -1578,8 +1658,11 @@ async function main() {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         try {
+            if (!(name in MCP_TOOL_ACTIONS))
+                throw new Error(`Unknown tool: ${name}`);
+            const toolName = name;
             let result;
-            switch (name) {
+            switch (toolName) {
                 case 'browser_get_requests': {
                     const { tabId, count = 10, filter, since, includeBody = true, includeHeaders = false, maxBodySize = 50000, fields, keysOnly = false, source, } = args;
                     result = await client.getRequests({
@@ -1751,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,
@@ -1906,8 +1990,10 @@ async function main() {
                     result = await client.selectBrowser(args);
                     break;
                 }
-                default:
-                    throw new Error(`Unknown tool: ${name}`);
+                default: {
+                    const unhandledTool = toolName;
+                    throw new Error(`Unknown tool: ${unhandledTool}`);
+                }
             }
             // 使用智能格式化返回结果
             return {

package/package.json

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

package/dist/types.d.ts

@@ -1,120 +0,0 @@
-export interface MtopRequest {
-    id: number;
-    timestamp: string;
-    timestampMs: number;
-    method: string;
-    url: string;
-    apiName: string;
-    status: number;
-    statusText: string;
-    headers: Array<{
-        name: string;
-        value: string;
-    }>;
-    responseHeaders: Array<{
-        name: string;
-        value: string;
-    }>;
-    queryString: Record<string, string>;
-    postData: Record<string, any> | null;
-    responseBody: any;
-    duration?: number;
-    proxyData?: any;
-}
-export interface ConsoleLog {
-    level: 'log' | 'warn' | 'error' | 'info';
-    message: string;
-    timestamp: number;
-    /** 来源文件和行号，格式 "filename.js:42"，仅在可获取时存在 */
-    source?: string;
-    args: any[];
-}
-export interface WaitForRequestParams {
-    pattern: string;
-    timeout?: number;
-    includeExisting?: boolean;
-}
-export interface GetRequestsParams {
-    count?: number;
-    filter?: string;
-    since?: number;
-}
-export interface GetLogsParams {
-    level?: 'log' | 'warn' | 'error' | 'info' | 'all';
-    since?: number;
-    limit?: number;
-    filter?: string;
-}
-export interface SetMockParams {
-    apiName: string;
-    mockData: any;
-    enabled?: boolean;
-    duration?: number;
-    conditions?: Record<string, any>;
-}
-export interface GetApiSchemaParams {
-    api: string;
-    version?: string;
-}
-export interface GetSelectedElementParams {
-    includeOuterHTML?: boolean;
-    includeScreenshot?: boolean;
-}
-export interface RequestsResponse {
-    meta: {
-        /** 实际返回的请求数量 */
-        count: number;
-        /** 缓冲区中符合过滤条件的总请求数 */
-        totalMatched: number;
-        /** 缓冲区中的总请求数（未过滤） */
-        totalInBuffer: number;
-        /** 应用的过滤器（如果有） */
-        filter?: string;
-        /** 时间过滤器（秒） */
-        since?: number;
-        /** 是否包含请求/响应体 */
-        includeBody: boolean;
-        /** 是否包含请求/响应头 */
-        includeHeaders: boolean;
-        /** 提取的字段（如果有） */
-        fields?: string[];
-        /** 是否只返回键结构 */
-        keysOnly: boolean;
-    };
-    /** 请求数据列表 */
-    requests: MtopRequest[];
-}
-export interface LogsResponse {
-    meta: {
-        /** 实际返回的日志数量 */
-        count: number;
-        /** 符合过滤条件的总日志数 */
-        totalMatched: number;
-        /** 应用的日志级别过滤 */
-        level: string;
-        /** 时间过滤器（秒） */
-        since?: number;
-        /** 应用的过滤模式 */
-        filter?: string;
-    };
-    /** 日志数据列表 */
-    logs: ConsoleLog[];
-}
-export interface ScreenshotResponse {
-    meta: {
-        /** 截图格式 */
-        format: 'png' | 'jpeg';
-        /** 截图宽度 */
-        width: number;
-        /** 截图高度 */
-        height: number;
-        /** 截图数据大小（字节） */
-        size: number;
-        /** 截图的页面 URL */
-        url: string;
-        /** 截图的页面标题 */
-        title: string;
-    };
-    /** Base64 编码的截图数据 */
-    data: string;
-}

package/dist/types.js

@@ -1,2 +0,0 @@
-// 消息类型定义
-export {};