@mearl/mcp-server 2.0.2 → 2.1.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,10 @@ 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;
 // 日志输出到 stderr（不影响 stdio 通信）
 const LOG_FILE = join(tmpdir(), 'mearl-mcp-server.log');
 const log = (...args) => {
@@ -245,35 +248,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 +317,7 @@ async function main() {
     // 创建 MCP Server
     const server = new Server({
         name: 'mearl',
-        version: '1.0.0',
+        version: MCP_SERVER_VERSION,
     }, {
         capabilities: {
             tools: {},
@@ -466,6 +466,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 +498,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 +555,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 +976,14 @@ async function main() {
                 required: ['browser'],
             },
         },
+        {
+            name: 'browser_release',
+            description: '释放 Agent 对当前目标浏览器的 debugger/CDP 控制，停止持续采集和会话级临时效果，但保留浏览器与全部标签页。后续浏览器操作仍可自动重新建立控制。',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
         {
             name: 'browser_tab_open',
             description: '打开或按 URL 规则复用标签页。默认新建并等待加载完成；reuse=prefer 可优先复用，reuse=require 可限制为只复用。响应的 opened/reused 可用于判断流程结束时是否应关闭该 Tab。',
@@ -1590,13 +1610,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 +1625,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 +1642,7 @@ async function main() {
                             conditions = fileData.conditions;
                     }
                     result = await client.setMock({
+                        tabId,
                         apiName,
                         mockData,
                         fields,
@@ -1630,8 +1653,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 +1746,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({

package/package.json

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