@mearl/mcp-server 2.0.2 → 2.2.0

package/README.md

@@ -9,6 +9,7 @@
 - 📝 **browser_get_logs**: 获取控制台日志
 - 🎭 **browser_set_mock**: 动态设置 Mock 数据
 - 🌐 **browser_list**: 统一列出普通浏览器和托管浏览器，返回默认目标、类型及连接状态
+- 📴 **browser_release**: 按用户明确要求释放 debugger/CDP 控制和会话级临时效果，并保留浏览器与全部标签页
 - 🚀 **browser_launch / browser_close**: 启动或关闭独立 Profile 的托管 Chrome
 - 🌐 **browser_page_snapshot**: 首次获取页面结构和可交互元素
 - ⚡ **browser_page_click/type/hover/scroll/press/upload**: 执行页面动作，默认内置观察，返回通知、可交互控件和焦点等高置信度信号

package/dist/index.js

@@ -22,7 +22,51 @@ import { tmpdir } from 'os';
 import { join, dirname } from 'path';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
+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) => {
@@ -245,35 +289,32 @@ function formatResponseWithSizeCheck(result, toolName, args) {
             },
         ];
     }
-    // 策略 5: 超超大响应（>1MB 压缩）- 截断 + 错误级别建议
-    const truncateSize = RESPONSE_SIZE_MAX;
-    const truncatedStr = compactStr.substring(0, truncateSize);
+    // 策略 5: 超超大响应（>1MB 压缩）- 返回可解析的诊断信息
     const suggestions = getOptimizationSuggestions(toolName, args, result, stats);
-    let header = `🛑 Response too large: ${sizeKB}KB (TRUNCATED to ${Math.round(truncateSize / 1024)}KB)\n`;
-    header += `Original size: ${sizeKB}KB, showing only ${Math.round(truncateSize / 1024)}KB\n`;
-    header += `\n⚠️ This response is unusable at this size. You MUST optimize the request.\n`;
-    if (stats.meta) {
-        header += `\n📊 Data: ${stats.meta.count} items (${stats.meta.totalMatched} matched, ${stats.meta.totalInBuffer} in buffer)`;
-    }
-    if (stats.largestFields && stats.largestFields.length > 0) {
-        header += `\nLargest fields per item:`;
-        stats.largestFields.forEach(f => {
-            header += `\n  • ${f.path}: ~${Math.round(f.size / 1024)}KB (${Math.round((f.size / compactSize) * 100)}% of total)`;
-        });
-    }
-    header += `\n\n🎯 REQUIRED actions:`;
-    if (suggestions.length > 0) {
-        header += suggestions.map((s, i) => `\n  ${i + 1}. ${s}`).join('');
-    }
-    else {
-        header += `\n  1. Significantly reduce the data requested`;
-        header += `\n  2. Use "fields" to extract only essential data`;
-        header += `\n  3. Add filters to narrow down results`;
-    }
+    const diagnostic = {
+        error: {
+            code: 'RESPONSE_TOO_LARGE',
+            message: 'The result exceeded the MCP response limit. Narrow the request and retry.',
+            originalSizeBytes: compactSize,
+            limitBytes: RESPONSE_SIZE_MAX,
+        },
+        meta: stats.meta,
+        largestFields: stats.largestFields?.map(field => ({
+            ...field,
+            percentageOfTotal: Math.round((field.size / compactSize) * 100),
+        })),
+        suggestions: suggestions.length > 0
+            ? suggestions
+            : [
+                'Significantly reduce the data requested',
+                'Use "fields" to extract only essential data',
+                'Add filters to narrow down results',
+            ],
+    };
     return [
         {
             type: 'text',
-            text: `${header}\n\n${'─'.repeat(60)}\n\n${truncatedStr}\n\n... <TRUNCATED ${sizeKB - Math.round(truncateSize / 1024)}KB>`,
+            text: JSON.stringify(diagnostic, null, 2),
         },
     ];
 }
@@ -317,7 +358,7 @@ async function main() {
     // 创建 MCP Server
     const server = new Server({
         name: 'mearl',
-        version: '1.0.0',
+        version: MCP_SERVER_VERSION,
     }, {
         capabilities: {
             tools: {},
@@ -360,7 +401,7 @@ async function main() {
         },
     };
     // 定义工具列表
-    const tools = [
+    const tools = defineMcpTools([
         {
             name: 'browser_get_requests',
             description: '获取浏览器中最近的 API 请求历史记录，包含完整的请求和响应信息。适用于分析性能、排查问题、查看数据流等场景。无需等待用户操作，立即返回已有数据。',
@@ -466,6 +507,10 @@ async function main() {
             inputSchema: {
                 type: 'object',
                 properties: {
+                    tabId: {
+                        type: 'number',
+                        description: '目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页',
+                    },
                     level: {
                         type: 'string',
                         enum: ['log', 'warn', 'error', 'info', 'all'],
@@ -494,6 +539,10 @@ async function main() {
             inputSchema: {
                 type: 'object',
                 properties: {
+                    tabId: {
+                        type: 'number',
+                        description: '目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页',
+                    },
                     apiName: {
                         type: 'string',
                         description: 'API 名称或正则表达式模式。例如: "mtop.cart.query" 精确匹配, ".*\\.cart\\..*" 匹配所有购物车接口',
@@ -547,6 +596,10 @@ async function main() {
             inputSchema: {
                 type: 'object',
                 properties: {
+                    tabId: {
+                        type: 'number',
+                        description: '目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页',
+                    },
                     apiName: {
                         type: 'string',
                         description: '过滤指定接口，支持正则表达式。例如: "mtop.cart.query" 或 ".*\\.cart\\..*"。不传则返回所有 Mock',
@@ -964,6 +1017,14 @@ async function main() {
                 required: ['browser'],
             },
         },
+        {
+            name: 'browser_release',
+            description: '仅当用户明确要求结束调试、退出接管或清理会话资源时，释放当前目标浏览器的 debugger/CDP 控制；不要作为普通任务收尾。它会停止持续采集，并立即清除设备/时区模拟、会话级 Mock 和录制，但保留浏览器与全部标签页。后续浏览器操作仍可自动重新建立控制。',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
         {
             name: 'browser_tab_open',
             description: '打开或按 URL 规则复用标签页。默认新建并等待加载完成；reuse=prefer 可优先复用，reuse=require 可限制为只复用。响应的 opened/reused 可用于判断流程结束时是否应关闭该 Tab。',
@@ -1435,7 +1496,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: {
@@ -1549,7 +1610,7 @@ async function main() {
                 required: ['browser'],
             },
         },
-    ];
+    ]);
     // 处理工具列表请求
     server.setRequestHandler(ListToolsRequestSchema, async () => {
         return { tools };
@@ -1558,8 +1619,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({
@@ -1590,13 +1654,13 @@ async function main() {
                     break;
                 }
                 case 'browser_get_logs': {
-                    const { level = 'all', since, limit = 100, filter } = args;
-                    result = await client.getLogs({ level, since, limit, filter });
+                    const { tabId, level = 'all', since, limit = 100, filter } = args;
+                    result = await client.getLogs({ tabId, level, since, limit, filter });
                     break;
                 }
                 case 'browser_set_mock': {
                     const { payloadFile } = args;
-                    let { apiName, mockData, fields, enabled, duration, conditions } = args;
+                    let { tabId, apiName, mockData, fields, enabled, duration, conditions } = args;
                     enabled = enabled ?? true;
                     // 如果提供了 payloadFile，从文件读取 mock 数据
                     if (payloadFile) {
@@ -1605,7 +1669,9 @@ async function main() {
                         }
                         const fileContent = readFileSync(payloadFile, 'utf-8');
                         const fileData = JSON.parse(fileContent);
-                        // 文件内容可以包含 apiName、mockData、fields、enabled、duration、conditions 等参数
+                        // 文件内容可以包含 tabId、apiName、mockData、fields、enabled、duration、conditions 等参数
+                        if (fileData.tabId !== undefined)
+                            tabId = fileData.tabId;
                         if (fileData.apiName)
                             apiName = fileData.apiName;
                         if (fileData.mockData !== undefined)
@@ -1620,6 +1686,7 @@ async function main() {
                             conditions = fileData.conditions;
                     }
                     result = await client.setMock({
+                        tabId,
                         apiName,
                         mockData,
                         fields,
@@ -1630,8 +1697,8 @@ async function main() {
                     break;
                 }
                 case 'browser_get_mocks': {
-                    const { apiName } = args;
-                    result = await client.getMocks({ apiName });
+                    const { tabId, apiName } = args;
+                    result = await client.getMocks({ tabId, apiName });
                     break;
                 }
                 case 'browser_get_api_schema': {
@@ -1723,6 +1790,10 @@ async function main() {
                     result = await client.browserClose(args);
                     break;
                 }
+                case 'browser_release': {
+                    result = await client.browserRelease();
+                    break;
+                }
                 case 'browser_tab_open': {
                     const { url, active = false, closeExisting = false, reuse = 'never', match, restoreFocusOnClose = false, emulation, group, } = args;
                     result = await client.tabOpen({
@@ -1879,8 +1950,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.0.2",
+  "version": "2.2.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/native-host": "2.0.2",
-    "@mearl/client": "2.0.2"
+    "@mearl/client": "2.2.0",
+    "@mearl/native-host": "2.2.0"
   },
   "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 {};