@mearl/mcp-server 2.15.1 → 2.15.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/dist/index.js +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -23,7 +23,7 @@
|
|
|
23
23
|
|
|
24
24
|
页面动作传 `observe: false` 可关闭内置观察仅执行裸动作；不需要在每次动作后固定追加 wait、snapshot 或 screenshot。
|
|
25
25
|
|
|
26
|
-
`browser_page_click.clickMode` 默认 `auto`：可见桌面页使用可信 mouse，移动模拟页使用可信 touch；目标页隐藏时不会切换标签或还原窗口，而是使用 DOM fallback，并返回 `dispatchMode: "dom"`、`fallbackReason: "page-hidden"`。可用 `dom` / `mouse` / `touch`
|
|
26
|
+
`browser_page_click.clickMode` 默认 `auto`：可见桌面页使用可信 mouse，移动模拟页使用可信 touch；目标页隐藏时不会切换标签或还原窗口，而是使用 DOM fallback，并返回 `dispatchMode: "dom"`、`fallbackReason: "page-hidden"`。可用 `dom` / `mouse` / `touch` 覆盖自动策略；显式 `touch` 要求目标页可见，否则会直接返回前置条件错误；可信输入返回实际 `pointerType`。
|
|
27
27
|
|
|
28
28
|
## 安装
|
|
29
29
|
|
package/dist/index.js
CHANGED
|
@@ -97,7 +97,7 @@ Largest fields per item:`,stats.largestFields.forEach(f=>{header+=`
|
|
|
97
97
|
${"─".repeat(60)}
|
|
98
98
|
|
|
99
99
|
${compactStr}`}]}let suggestions=getOptimizationSuggestions(toolName,args,result,stats),diagnostic={error:{code:"RESPONSE_TOO_LARGE",message:"The result exceeded the MCP response limit. Narrow the request and retry.",originalSizeBytes:compactSize,limitBytes:1048576},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:JSON.stringify(diagnostic,null,2)}]}async function main(){let rawArgs=process.argv.slice(2),cliArgs={forwardedArgs:[],mode:"server"};if(rawArgs.length>0)try{let{parseMcpArgs:parseMcpArgs2}=await Promise.resolve().then(()=>(init_cliArgs(),cliArgs_exports));cliArgs=await parseMcpArgs2(rawArgs)}catch(error2){console.error(`Error: ${error2 instanceof Error?error2.message:String(error2)}`),printCliHelp(),process.exitCode=2;return}if(cliArgs.mode==="help"){printCliHelp();return}if(cliArgs.mode==="version"){console.log(MCP_SERVER_VERSION);return}if(cliArgs.mode==="configure"){let __filename=fileURLToPath(import.meta.url),__dirname=dirname(__filename),configureScript=join(__dirname,"configure-bin.js");spawn(process.execPath,[configureScript,...cliArgs.forwardedArgs],{stdio:"inherit"}).on("exit",code=>{process.exit(code||0)});return}if(cliArgs.mode==="uninstall"){let __filename=fileURLToPath(import.meta.url),__dirname=dirname(__filename),uninstallScript=join(__dirname,"uninstall-bin.js");spawn(process.execPath,[uninstallScript,...cliArgs.forwardedArgs],{stdio:"inherit"}).on("exit",code=>{process.exit(code||0)});return}writeFileSync(LOG_FILE,`=== Mearl MCP Server Started at ${new Date().toISOString()} ===
|
|
100
|
-
`),log("Starting Mearl MCP Server..."),log("MCP Server initialized, will connect to Chrome Extension when tools are called");let server=new Server({name:"mearl",version:MCP_SERVER_VERSION},{capabilities:{tools:{}},instructions:"浏览器交互默认工作流：首次进入页面或导航后用 browser_page_snapshot 建立基线；后续页面动作默认返回 { action, observation }。先检查 action.success；action.stage=precondition 表示尚未派发，应按 error 修正输入或刷新快照，且不读取已省略的 observation/diagnostics。动作成功后再按 observation 处理：delta 读取 effects，navigation 在 ready=true 后重建快照，openedTabs 直接使用其 tabId。仅在 fullSnapshotRecommended=true 或需要读取滚动后的新视口时补最小范围快照；视觉任务使用 screenshot。无需页面观察时传 observe:false；需要动作期间的日志、请求或埋点时显式开启 diagnostics。page_eval 仅作为结构化 action 无法表达时的补充；不要在每次动作后固定追加 wait、snapshot 或 screenshot。"}),OBSERVE_INPUT_SCHEMA={type:["object","boolean"],default:{},description:"观察选项。默认开启内置观察（等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定后返回页面变化信号）；传 false 关闭，不影响显式请求的 diagnostics",properties:{quietMs:{type:"number",description:"最后一次 DOM 变化后等待的稳定窗口，默认 100ms"},firstChangeTimeoutMs:{type:"number",description:"没有发生 DOM 变化时最多等待多久，默认 500ms"},timeoutMs:{type:"number",description:"整个观察阶段的最大时间，默认 3000ms"},navigationGraceMs:{type:"number",description:"低信息量点击或按键后等待导航开始的基础宽限时间，默认 1000ms；若仍有网络活动会自动延长，有明确 effects 时不等待"},navigationTimeoutMs:{type:"number",description:"导航开始后等待页面就绪的最大时间，默认 15000ms"},networkIdleMs:{type:"number",description:"文档加载完成且相关 XHR/Fetch/MTop 请求归零后继续保持静默的时间，默认 500ms，用于跳过业务骨架屏"},contentReadyAfterMs:{type:"number",description:"动作开始后允许用结构稳定兜底的保护期，默认 5000ms，并自动限制在导航超时之前；保护期内仍优先等待网络静默"}}},DIAGNOSTICS_INPUT_SCHEMA={type:["object","boolean"],default:!1,description:"默认关闭。传 true 在动作执行前建立边界，并返回新增 error logs 和业务 requests；传对象可自定义通道与过滤，并按需开启 events",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:!1},includeHeaders:{type:"boolean",default:!1}}},events:{type:["object","boolean"],properties:{source:{type:"string",enum:["rum","aplus","arms","all"]},event_type:{type:"string"},filter:{type:"string"},limit:{type:"number",default:100},includeRaw:{type:"boolean",default:!1}}}}},tools=[{name:PLUGIN_TOOL_NAME,description:"调用当前 MCP Server 宿主上的 Mearl Skill 插件；缺失的官方插件会自动安装。插件名、子命令和 input 契约以对应 Skill 为准；BUC 使用 MCP Server 宿主身份，浏览器操作使用当前选择或显式指定的 Browser ID。",inputSchema:{type:"object",properties:{plugin:{type:"string",description:"已注册或 Mearl 官方目录中的插件名"},command:{type:"string",description:"插件注册的子命令名"},input:{type:"object",description:"传给插件 handler 的业务参数，省略时为空对象",additionalProperties:!0},browser:{type:"string",description:"可选目标浏览器 ID 或名称；省略时继承 browser_select_browser 选择的目标"},timeoutSec:{type:"number",description:"可选的浏览器底层调用超时秒数"}},required:["plugin","command"]}},{name:"browser_tab_checkpoint",description:"为目标标签页建立日志、请求和埋点的可靠增量边界，对应 mearl tab_checkpoint。返回的 cursor 可传给 browser_get_logs/browser_get_requests/browser_get_events 的 after。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID；不传时使用当前活动标签页"}}}},{name:"browser_get_requests",description:"获取指定标签页持续采集的 API 请求历史，包含请求、响应与 pending 状态。无需打开 DevTools panel；不传 after 时返回最新 N 条，传 after 时从最早未读项开始分页。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取。不传则使用当前激活标签页"},count:{type:"number",description:"获取的请求数量，默认 10 个。最多可获取最近 1000 个请求",default:10},filter:{type:"string",description:'过滤 API 名称的正则表达式（可选）。例如: ".*\\.cart\\..*" 只返回购物车相关接口'},since:{type:"number",description:"从多久之前开始获取（秒）。例如: 60 表示获取最近 1 分钟内的请求"},after:{type:"string",description:"tab checkpoint 或上一次查询返回的 cursor，仅返回其后的请求"},includeBody:{type:"boolean",description:"是否包含请求体和响应体。false 时将省略 postData 和 responseBody 字段以减少数据量。默认 true",default:!0},includeHeaders:{type:"boolean",description:"是否包含请求头和响应头。false 时将省略 headers 和 responseHeaders 字段以减少数据量。默认 false",default:!1},maxBodySize:{type:"number",description:"单个请求/响应体的最大字节数。超过此大小将被截断。默认 50000（约 50KB）",default:5e4},fields:{type:"array",items:{type:"string"},description:'从响应体中提取指定字段，支持点号路径。例如: ["data.result.list", "data.total"] 只返回这些字段，大幅减少数据量'},keysOnly:{type:"boolean",description:"只返回数据结构（字段路径和类型），不返回实际值。设为 true 可先预览数据结构，再决定提取哪些字段。默认 false",default:!1},source:{type:"string",enum:["mtop","requests","all"],description:"数据源。mtop: mtop 接口（默认）; requests: 普通 XHR/Fetch 请求; all: 全部业务请求"}}}},{name:"browser_get_events",description:"获取目标标签页后台采集的 RUM/aplus/ARMS 埋点事件，无需打开 DevTools panel。不传 after 时返回最新事件，传 after 时按完整上报批次从最早未读项开始分页。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取。不传则使用当前激活标签页"},source:{type:"string",enum:["rum","aplus","arms","all"],description:"事件来源。rum: RUM 性能监控事件; aplus: aplus 埋点事件; arms: ARMS 前端监控事件; all: 全部（默认）",default:"all"},event_type:{type:"string",description:'事件类型正则过滤。例如: "view" 匹配页面 view 事件, "CLK" 匹配点击埋点'},filter:{type:"string",description:"正则过滤，匹配事件的 name 或 url 字段"},since:{type:"number",description:"从多久之前开始获取（秒）。例如: 60 表示获取最近 1 分钟内的事件"},after:{type:"string",description:"tab checkpoint 或上一次查询返回的 cursor，仅返回其后的埋点事件"},limit:{type:"number",description:"返回条数上限，默认 20",default:20},includeRaw:{type:"boolean",description:"是否返回完整 tracking URL、_raw 原始载荷和 _context 上下文；默认 false，仅返回解析后的精简字段",default:!1}}}},{name:"browser_get_logs",description:"获取指定标签页持续采集的 console API、未捕获异常和浏览器日志。无需打开 DevTools panel；不传 after 时返回最新 N 条，传 after 时从最早未读项开始分页。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页"},level:{type:"string",enum:["log","warn","error","info","all"],description:"日志级别过滤。log: 普通日志, warn: 警告, error: 错误, info: 信息, all: 所有级别。默认 all",default:"all"},since:{type:"number",description:"从多久之前开始获取日志（秒）。例如: 60 表示获取最近 1 分钟内的日志"},after:{type:"string",description:"tab checkpoint 或上一次查询返回的 cursor，仅返回其后的日志"},limit:{type:"number",description:"最大返回日志数量，默认 100；快照查询返回最新 N 条",default:100},filter:{type:"string",description:'过滤日志内容的正则表达式或字符串（可选）。支持正则表达式模式（不区分大小写），若正则无效则回退到字符串包含匹配。例如: "error|warning" 匹配包含 error 或 warning 的日志'}}}},{name:"browser_set_mock",description:"动态设置 API 接口的 Mock 数据，用于测试不同数据场景。修改后，浏览器中对该接口的所有请求都会返回 Mock 数据。适用于前端开发测试、边界情况验证、UI 状态测试等。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页"},apiName:{type:"string",description:'API 名称或正则表达式模式。例如: "mtop.cart.query" 精确匹配, ".*\\.cart\\..*" 匹配所有购物车接口'},mockData:{type:["object","string"],description:'【方式一】直接设置完整 Mock 响应数据（JSON 对象）。传入后该接口将完全返回此数据，不再请求真实服务端。示例: {"data":{"result":{"list":[]}},"ret":["SUCCESS"]}。注意：mockData 和 fields 二选一，同时提供时优先使用 fields。大体积响应体可传文件引用字符串 "@/abs/resp.json"（从该文件读取，建议绝对路径）以减少上下文占用'},fields:{type:"array",description:"【方式二】基于真实响应修改指定字段。系统会先获取该接口的原始响应数据，然后按指定路径修改字段值。适合在真实数据基础上做微调",items:{type:"object",properties:{path:{type:"string",description:'字段路径，支持点号和数组索引。例如: "data.result.passengerList[0].name.text"'},value:{description:"要设置的值，可以是任意类型（字符串、数字、对象、数组等）"}},required:["path","value"]}},enabled:{type:"boolean",description:"是否启用 Mock。true: 启用 Mock, false: 禁用 Mock 恢复真实数据。默认 true",default:!0},duration:{type:"number",description:"完整响应时长（毫秒）。可选，mock 生效时的总耗时，绕过真实服务器精确控制（用于测试加载状态、超时等场景）"},conditions:{type:"object",additionalProperties:!0,description:"请求 query/body 字段的子集匹配规则；保留字段 $index 从 0 开始指定同一场景的调用顺序。相同 $index 再次设置会原地覆盖，超过最后一项后持续使用最后一项"},payloadFile:{type:"string",description:"从文件读取 mock 数据（JSON 格式）。当 mockData 很大时，可将完整 JSON 写入文件，通过此参数指定文件路径。文件内容会被解析为 mockData。注意：此参数与 mockData/fields 互斥，优先级最高"}},required:["apiName"]}},{name:"browser_get_mocks",description:"查看当前所有已设置的 Mock 配置，包括接口名称、是否启用、以及 Mock 数据内容。用于排查 Mock 是否生效、Mock 数据是否正确等问题。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页"},apiName:{type:"string",description:'过滤指定接口，支持正则表达式。例如: "mtop.cart.query" 或 ".*\\.cart\\..*"。不传则返回所有 Mock'}}}},{name:"browser_send_request",description:"通过浏览器发起 HTTP 代理请求，自动携带目标域名的 Cookie（使用当前浏览器登录态）。支持 GET/POST/PUT/DELETE/PATCH、multipart 文本字段和本地文件上传，适用于需要用户登录态的接口调试、数据爬取、接口测试等场景。",inputSchema:{type:"object",properties:{url:{type:"string",description:"目标请求 URL，必须是完整 URL（含 http:// 或 https://）"},method:{type:"string",enum:["GET","POST","PUT","DELETE","PATCH","HEAD","OPTIONS"],description:"HTTP 请求方法，默认 GET",default:"GET"},headers:{type:"object",description:"自定义请求头（键值对），会与自动生成的 Cookie 头合并",additionalProperties:{type:"string"}},params:{type:"object",description:"URL 查询参数（键值对），会追加到 URL 中",additionalProperties:{type:"string"}},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:!0},responseType:{type:"string",enum:["json","text","auto"],description:'响应格式。auto: 自动检测（默认）; json: 强制解析为 JSON; text: 返回原始文本。注意：auto 模式下若 Content-Type 为图片/音视频/PDF/压缩包等二进制类型，body 将以 base64 字符串返回，bodyType 为 "base64"',default:"auto"},timeout:{type:"number",description:"请求超时时间（毫秒），默认 30000（30 秒）",default:3e4}},required:["url"]}},{name:"browser_send_mtop_request",description:"在当前浏览器页面上下文中发起 mtop API 请求。自动处理签名计算（md5）、Cookie 中的 token 提取、时间戳生成等，无需手动构造签名。适用于：调试 mtop 接口、验证接口返回数据、测试不同参数组合等场景。注意：需要当前页面已登录（有对应的 Cookie），且 DevTools 面板已打开。",inputSchema:{type:"object",properties:{api:{type:"string",description:'mtop API 名称，例如: "mtop.trade.order.create"、"mtop.fliggy.flyrs.render"。以 "mopen." 开头的会使用 mopen 签名算法'},data:{description:'请求数据（JSON 对象），即 mtop 请求中的 data 参数。例如: {"itemId": "12345"}'},version:{type:"string",description:'API 版本号，默认 "1.0"',default:"1.0"},method:{type:"string",enum:["GET","POST"],description:"HTTP 请求方法，默认 GET。POST 时 data 参数放在请求体中",default:"GET"},appKey:{type:"string",description:'appKey，默认 "12574478"'},env:{type:"string",enum:["online","pre"],description:"请求环境。online: 线上（默认，h5api.m.taobao.com）; pre: 预发（h5api.wapa.taobao.com）",default:"online"},timeout:{type:"number",description:"请求超时时间（毫秒），默认 10000（10 秒）",default:1e4}},required:["api"]}},{name:"browser_set_rule",description:"添加 Chrome declarativeNetRequest 规则，用于拦截、重定向或修改请求。规则持久化保存，浏览器重启后仍生效。支持：重定向请求到另一地址、修改请求/响应头、阻止请求、升级到 HTTPS 等。适用于：本地开发时代理到本地服务、修改请求头调试、拦截特定请求等。",inputSchema:{type:"object",properties:{actionType:{type:"string",enum:["redirect","block","allow","upgradeScheme","modifyHeaders"],description:"规则类型。redirect: 重定向请求到另一地址; block: 阻止请求; allow: 允许请求; upgradeScheme: 升级到 HTTPS; modifyHeaders: 修改请求/响应头"},filter:{type:"string",description:'URL 匹配规则（正则表达式）。例如: "^https://h5api\\.m\\.taobao\\.com/.*" 匹配所有淘宝 h5api 请求'},redirectUrl:{type:"string",description:"【redirect 类型必填】重定向目标 URL。支持正则替换占位符 \\1 \\2 等（引用 filter 中的捕获组）"},requestHeaders:{type:"array",description:"【modifyHeaders 类型】要修改的请求头列表",items:{type:"object",properties:{header:{type:"string",description:'请求头名称，如 "x-custom-header"'},operation:{type:"string",enum:["set","append","remove"],description:"set: 设置/覆盖; append: 追加; remove: 删除"},value:{type:"string",description:"请求头值（remove 时可省略）"}},required:["header","operation"]}},responseHeaders:{type:"array",description:"【modifyHeaders 类型】要修改的响应头列表",items:{type:"object",properties:{header:{type:"string",description:"响应头名称"},operation:{type:"string",enum:["set","append","remove"],description:"set: 设置/覆盖; append: 追加; remove: 删除"},value:{type:"string",description:"响应头值（remove 时可省略）"}},required:["header","operation"]}},initiatorDomains:{type:"string",description:'发起请求的域名限制（逗号分隔）。只有从这些域名发起的请求才会匹配此规则。例如: "taobao.com,tmall.com"'},resourceTypes:{type:"array",description:"资源类型限制。不填则匹配所有类型",items:{type:"string",enum:["main_frame","sub_frame","script","stylesheet","image","xmlhttprequest","websocket","other"]}},priority:{type:"number",description:"规则优先级，数字越大优先级越高。多个规则匹配同一请求时，优先级高的生效。默认 1",default:1},description:{type:"string",description:"规则描述，便于识别规则用途"}},required:["actionType","filter"]}},{name:"browser_get_rules",description:"查看当前存储的全部请求规则（含用户在插件 Options 面板手动配置的）。返回规则总开关状态和规则列表，字段结构与 browser_set_rule 入参对齐，用于确认规则是否生效或排查请求被意外重定向/修改的问题。",inputSchema:{type:"object",properties:{}}},{name:"browser_page_screenshot",description:'获取当前浏览器活动标签页的视觉截图，以 Base64 编码返回。支持全页截图或指定 CSS 选择器截取单个元素（类似 DevTools "Capture node screenshot"）。适用于视觉判断、Canvas、跨域 iframe、UI 排查和保存快照；常规页面动作后优先读取其内置观察的增量结果，不要固定在每次动作后截图。',inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",description:"CSS 选择器。提供后只截取该元素区域（会自动滚动元素到可见区域），不提供则截取整个页面"},format:{type:"string",enum:["png","jpeg"],description:"截图格式。png: PNG 格式（无损，默认）; jpeg: JPEG 格式（有损压缩，体积更小）",default:"png"},quality:{type:"number",description:"JPEG 质量（仅 format 为 jpeg 时有效）。范围 0-100，默认 80。数值越高质量越好但文件越大",default:80}},required:["tabId"]}},{name:"browser_page_selected_element",description:"获取 Chrome DevTools Elements 面板中当前选中元素的详细信息，包含布局尺寸、CSS 计算样式、属性、DOM 结构等。适用于：分析布局问题、排查样式异常、了解元素几何信息、辅助 UI 优化等场景。使用前需要在 Elements 面板中选中目标元素（点击面板元素或使用 inspect 工具点击页面元素）。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},includeOuterHTML:{type:"boolean",description:"是否包含元素的 outerHTML（最多 3000 字符）。设为 false 可减少数据量。默认 true",default:!0},includeScreenshot:{type:"boolean",description:"是否返回选中元素截图。开启后会自动滚动到元素并按默认策略截图（PNG、8px 边距），返回 image 类型内容。默认 false",default:!1}},required:["tabId"]}},{name:"browser_launch",description:"启动浏览器实例。默认使用本地独立 Chrome；传已注册的 Provider ID 时，把该 Provider 声明的创建参数放在 providerOptions。配对实例会直接返回 pairing URL。具体 Provider 用法可运行 mearl <providerId> 查看。",inputSchema:{type:"object",properties:{name:{type:"string",description:"本地实例名称；使用默认 local Provider 时必填"},provider:{type:"string",description:"浏览器提供方，默认 local；也可传已注册的外部 Provider ID"},providerOptions:{type:"object",additionalProperties:!0,description:"所选外部 Provider 声明的结构化创建参数"},headless:{type:"boolean",description:"本地 Provider 是否使用 headless=new，默认 true"},userAgentMode:{type:"string",enum:["default","desktop"],description:"本地 UA 模式：default 使用默认 UA；desktop 使用匹配本机 Chrome 的 UA",default:"default"},persistent:{type:"boolean",description:"本地实例关闭后是否保留独立 Profile，默认 false",default:!1},url:{type:"string",description:"新浏览器打开的初始 URL"},executablePath:{type:"string",description:"Chrome 可执行文件路径；省略时自动发现，也可用环境变量配置"},copyCookieDomains:{oneOf:[{type:"array",items:{type:"string"}},{type:"string",enum:["mearl-services"]}],description:"从控制浏览器复制 Cookie。传域名数组时复制指定域；传 mearl-services 时同步 Mearl 依赖平台登录态。保留 HttpOnly/Secure/SameSite/过期时间等属性；域名数组中的非内置域需先授权。"}},anyOf:[{required:["name"]},{required:["provider"]}]}},{name:"browser_close",description:"关闭一个 Provider 托管浏览器；持久化数据默认按 Provider 策略保留，deleteProfile=true 时一并删除。名称有歧义时使用完整 browserId。",inputSchema:{type:"object",properties:{browser:{type:"string",description:"browser_launch 返回的 browserId 或实例名称"},deleteProfile:{type:"boolean",description:"是否强制删除 Provider 持久化数据，默认 false",default:!1}},required:["browser"]}},{name:"browser_release",description:"仅在用户明确要求结束调试、退出接管或清理会话资源时调用，不作为普通任务收尾。它会释放 debugger/CDP 控制和会话级临时效果，后续浏览器操作可自动重新建立控制；Provider 实例的生命周期操作由 Browser Manager 处理。",inputSchema:{type:"object",properties:{}}},{name:"browser_tab_open",description:"打开或按 URL 规则复用标签页。默认新建并等待加载完成；reuse=prefer 可优先复用，reuse=require 可限制为只复用。响应的 opened/reused 可用于判断流程结束时是否应关闭该 Tab。",inputSchema:{type:"object",properties:{url:{type:"string",description:"要打开的页面 URL"},active:{type:"boolean",description:"是否激活（前台显示）新标签页。默认 false（后台打开）",default:!1},openerTabId:{type:"number",description:"来源标签页 ID。侧边栏对话继续任务时传入，用于把新开或复用的标签页关联到同一对话"},closeExisting:{type:"boolean",description:"打开前是否先关闭 Agent 受控的已有标签页。默认 false",default:!1},group:{type:"string",description:"把新标签页加入指定标题的标签页分组（同窗口同名分组存在则加入，否则新建）。仅扩展模式支持，CDP 模式忽略"},reuse:{type:"string",enum:["never","prefer","require"],description:"never 始终新建；prefer 匹配到则复用、否则新建；require 只允许复用。默认 never",default:"never"},match:{type:"object",description:"复用标签页时的 URL 匹配规则",properties:{urlPattern:{type:"string",description:"支持 * 的完整 URL glob；省略时精确匹配 url"},ignoreSearch:{type:"boolean",description:"匹配时是否忽略 URL query，默认 false"},ignoreHash:{type:"boolean",description:"匹配时是否忽略 URL hash，默认 false"},onMultiple:{type:"string",enum:["error","first"],description:"匹配多个 Tab 时默认报错；first 显式取第一个"}}},restoreFocusOnClose:{type:"boolean",description:"新建 active Tab 关闭后是否恢复原活动标签页，默认 false",default:!1},emulation:{type:"object",description:"开 tab 即进入移动端模拟态，等价于随后立即调用 browser_set_device_emulation，但在导航前生效。deviceShell=true 时首屏就在 iframe WebView 与设备系统外壳中渲染。字段规则一致（无 enabled/reload）。",properties:{preset:{type:"string",enum:[...BROWSER_DEVICE_PRESET_NAMES],description:"内置设备预设，一键提供 viewport/DPR/UA。当前机型在前，旧机型 ID 继续兼容；可与下面字段组合，显式字段覆盖预设值"},width:{type:"number",description:"视口宽度（覆盖 preset）"},height:{type:"number",description:"视口高度（覆盖 preset）"},deviceScaleFactor:{type:"number",description:"devicePixelRatio（覆盖 preset）"},scale:{type:"number",exclusiveMinimum:0,description:"画面视觉比例，不改变视口 CSS 尺寸或 devicePixelRatio；必须为有限正数，默认 1"},mobile:{type:"boolean",description:"是否启用移动渲染模式。默认从 preset 推断，无 preset 默认 true"},userAgent:{type:"string",description:"自定义 User-Agent（覆盖 preset）。无 preset 时必填"},orientation:{type:"string",enum:["portrait","landscape"],description:"横竖屏，landscape 会对调宽高。默认 portrait"},touch:{type:"boolean",description:"是否启用触摸事件并把鼠标事件转成 touch。默认从 preset 推断；无 preset 时跟随 mobile"},deviceShell:{type:"boolean",description:"是否使用 iframe WebView 并渲染顶部状态栏与底部操作区，默认 false"}}},appProfile:{type:"string",enum:[...client.APP_PROFILE_NAMES],description:"开 tab 即注入 App 客户端环境与 JSBridge（等价于随后调用 browser_set_app_profile，但在首次导航前生效）。不创建根 iframe；需要设备外壳时同时传 emulation.deviceShell=true"},os:{type:"string",enum:["ios","android"],description:"与 appProfile 配合；容器系统，默认 ios"},bridgeConfig:{type:"object",description:"与 appProfile 配合；声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}，不执行配置脚本"}},required:["url"]}},{name:"browser_tab_close",description:"关闭指定的浏览器标签页。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"要关闭的标签页 ID（从 tab_open 或 tab_list 获取）"}},required:["tabId"]}},{name:"browser_tab_list",description:"列出当前浏览器窗口中所有标签页的信息，包括 ID、URL、标题和是否活动。",inputSchema:{type:"object",properties:{}}},{name:"browser_page_click",description:"点击页面元素；selector、text、point 三种定位方式必须且只能提供一种。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",description:`原生 CSS 选择器（如 "[aria-label='提交']"、"#login-btn"）或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e3"，必须带 "@" 前缀）。注意字段名是 "selector" 而非 "ref"。不支持 :has-text/:visible 等 Playwright 扩展语法。与 text/point 互斥。`},text:{type:"string",description:'按可见文本（accessibility name）定位。例如 "退款明细"。匹配到多个时会报错并列出候选——可加 role 或 exact:true 收敛，或用 page_snapshot 拿 @ref。与 selector/point 互斥。'},point:{type:"object",description:"按视口坐标点击（CSS 像素，左上角为原点）。selector 和 text 都不适用时使用。与 selector/text 互斥。",properties:{x:{type:"number",description:"横坐标（CSS 像素）"},y:{type:"number",description:"纵坐标（CSS 像素）"}},required:["x","y"]},role:{type:"string",description:'配合 text 使用，按 AX role 过滤消歧（如 "button"、"link"、"heading"、"StaticText"）'},exact:{type:"boolean",description:"配合 text 使用，默认 true 精确匹配；false 时按子串匹配",default:!0},scope:{type:"string",description:'配合 text 使用，把 AX 文本匹配限制在指定 CSS 元素或 snapshot ref（如 "@e12"）子树内'},clickMode:{type:"string",enum:["auto","dom","mouse","touch"],description:"默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式",default:"auto"},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId"]}},{name:"browser_page_drag",description:"连续拖动页面元素或视口坐标，适用于轮播图、滑块、Canvas 手势和拖放。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},from:{description:"拖动起点：CSS/@eN selector，或 {x,y} 视口坐标（CSS 像素）",anyOf:[{type:"string"},{type:"object",properties:{x:{type:"number"},y:{type:"number"}},required:["x","y"]}]},to:{description:"拖动终点：CSS/@eN selector，或 {x,y} 视口坐标（CSS 像素）",anyOf:[{type:"string"},{type:"object",properties:{x:{type:"number"},y:{type:"number"}},required:["x","y"]}]},dragMode:{type:"string",enum:["auto","dom","mouse","touch"],description:"默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式",default:"auto"},durationMs:{type:"number",minimum:0,maximum:5e3,description:"拖动持续时间（毫秒），默认 400；内部自动分段移动",default:400},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","from","to"]}},{name:"browser_page_type",description:"向输入框填写文本，兼容 React 等框架的受控组件。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",description:'原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e6"，必须带 "@" 前缀）。字段名是 "selector"。不支持 :has-text/:visible 等 Playwright 扩展。'},text:{type:"string",description:"要输入的文本内容"},clearFirst:{type:"boolean",description:"是否先清空输入框原有内容。默认 true",default:!0},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","selector","text"]}},{name:"browser_page_scroll",description:'按方向滚动页面或指定容器；containerPolicy="nearest" 可从子节点解析最近的可滚动祖先。',inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},direction:{type:"string",enum:["up","down","top","bottom"],description:"滚动方向"},distance:{type:"number",description:"滚动距离（像素），仅 up/down 方向有效。默认 600",default:600},selector:{type:"string",description:'目标滚动容器的原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e6"，必须带 "@" 前缀）；不传时滚动页面。'},containerPolicy:{type:"string",enum:["self","nearest"],description:"默认 self，要求 selector 本身可滚动；nearest 会在其不可滚动时使用最近的可滚动祖先"},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","direction"]}},{name:"browser_page_hover",description:"将鼠标悬停在页面元素上。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",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 表达式，作为结构化页面 action 无法表达时的补充。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},expression:{type:"string",description:"要执行的 JavaScript 表达式"},frameId:{type:"string",description:"目标 frame 的 CDP frameId。不传则在主 frame 中执行。可通过 browser_page_frames 获取"},awaitPromise:{type:"boolean",description:"是否等待表达式返回的 Promise，默认 true",default:!0},observe:{...OBSERVE_INPUT_SCHEMA,type:"object",description:"仅在表达式会修改页面且需要观察结果时显式传入；不传时轻量执行并直接返回结果"},diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","expression"]}},{name:"browser_page_snapshot",description:"获取带 @ref 的页面无障碍树；支持完整、当前视口、交互控件、指定区域或查询结果。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},depth:{type:"number",description:"无障碍树的最大深度。默认 15，增大可获取更深层元素",default:15},mode:{type:"string",enum:["full","interactive","viewport"],description:"输出范围：full 为完整树；interactive 只保留当前视口内的语义控件，视口内无 AX 控件语义时自动回退到 viewport；viewport 只保留当前可视区域。默认 full"},rootSelector:{type:"string",description:"只获取指定 CSS 元素的 AX 子树，可与 mode 组合；与 rootRef 互斥"},rootRef:{type:"string",description:'以已有 snapshot ref（如 "@e8"）为根获取局部 AX 子树'},ancestorDepth:{type:"number",description:"rootRef 向上扩展的 DOM 祖先层数，默认 0，最大 20",minimum:0,maximum:20},query:{type:"object",description:"服务端过滤 AX 树，只保留按 accessibility name / role 命中的节点及祖先路径",properties:{text:{type:"string",description:"要匹配的 accessibility name"},role:{type:"string",description:"要匹配的 AX role"},exact:{type:"boolean",description:"text 默认精确匹配；false 时按子串匹配"}}},maxNodes:{type:"number",description:"最多输出节点数；超出时保留首尾。0 表示不限制"},maxChars:{type:"number",description:"最多输出字符数，默认 60000；超出时保留首尾。0 表示不限制"}},required:["tabId"]}},{name:"browser_page_press",description:"在页面中按下键盘按键或组合键。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},key:{type:"string",description:"按键名称。支持：Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Space"},modifiers:{type:"array",items:{type:"string"},description:'修饰键数组，如 ["Alt", "Shift", "Control", "Meta"]'},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","key"]}},{name:"browser_page_wait",description:"独立等待接口：仅用于没有前置动作时等待指定时间、已知 selector 或页面 condition。三种模式必须且只能提供一个；点击、输入后的异步稳定判断由页面交互工具内置的观察完成。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},time:{type:"number",description:"固定等待毫秒数，与 selector/condition 三选一"},selector:{type:"string",description:"CSS 选择器，等待该元素出现在 DOM 中，与 time/condition 三选一"},condition:{type:"string",description:"在页面主上下文轮询的 JavaScript 表达式，返回 truthy 时结束，支持 Promise；与 time/selector 三选一"},timeout:{type:"number",description:"等待超时时间（毫秒），默认 10000ms",default:1e4},interval:{type:"number",description:"selector/condition 的轮询间隔（毫秒），默认 200ms",default:200}},required:["tabId"]}},{name:"browser_page_navigate",description:'在指定标签页中导航到 URL、设置 refresh:true 重新加载，或用 history:"back"|"forward" 沿浏览历史移动。三种模式互斥，返回最终 URL 和标题。',inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},url:{type:"string",description:"要导航到的 URL；与 refresh/history 互斥"},refresh:{type:"boolean",description:"为 true 时直接重新加载当前页面；与 url/history 互斥",default:!1},history:{type:"string",enum:["back","forward"],description:"沿当前标签页浏览历史后退或前进；与 url/refresh 互斥"}},required:["tabId"]}},{name:"browser_page_upload",description:'向 <input type="file"> 元素上传一个或多个本地文件。',inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",description:'原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e5"，必须带 "@" 前缀），用于定位 <input type="file"> 元素。字段名是 "selector"。'},filePaths:{type:"array",items:{type:"string"},description:'要上传的本地文件路径数组，如 ["/Users/me/photo.jpg"]'},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","selector","filePaths"]}},{name:"browser_page_frames",description:"列出主 frame 和 iframe，返回可供 browser_page_eval 使用的 frameId。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"}},required:["tabId"]}},{name:"browser_set_device_emulation",description:"把目标标签页切换为移动端模拟态：视口尺寸 / DPR / UA / 触摸事件按指定设备生效，并可独立调整视觉比例。deviceShell=true 时把业务页放入 iframe WebView，并在外层渲染顶部状态栏与底部操作区；false/省略时保持纯 CDP 模拟。作用域仅限该 tab，启用后默认 reload，enabled=false 清除模拟与设备外壳。",inputSchema:{type:"object",properties:{enabled:{type:"boolean",description:"必填。true=启用模拟（按 preset/参数生效），false=清除模拟回到桌面态"},preset:{type:"string",enum:[...BROWSER_DEVICE_PRESET_NAMES],description:"内置设备预设，一键提供 viewport/DPR/UA。当前机型在前，旧机型 ID 继续兼容；可与下面的字段组合，显式字段会覆盖预设值"},width:{type:"number",description:"视口宽度（覆盖 preset）"},height:{type:"number",description:"视口高度（覆盖 preset）"},deviceScaleFactor:{type:"number",description:"devicePixelRatio（覆盖 preset）"},scale:{type:"number",exclusiveMinimum:0,description:"画面视觉比例，不改变视口 CSS 尺寸或 devicePixelRatio；必须为有限正数，默认 1"},mobile:{type:"boolean",description:"是否启用移动渲染模式（影响 hover/pointer media query、viewport meta 行为）。默认从 preset 推断，无 preset 默认 true"},userAgent:{type:"string",description:"自定义 User-Agent（覆盖 preset）"},orientation:{type:"string",enum:["portrait","landscape"],description:"横竖屏，landscape 会对调宽高。默认 portrait"},touch:{type:"boolean",description:"是否启用触摸事件并把鼠标事件转成 touch。默认从 preset 推断；无 preset 时跟随 mobile"},deviceShell:{type:"boolean",description:"是否使用 iframe WebView 并渲染顶部状态栏与底部操作区，默认 false"},reload:{type:"boolean",description:"启用模拟后是否重载页面（让 JS 读到新的 navigator.userAgent / window.innerWidth）。默认 true"},tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"}},required:["tabId","enabled"]}},{name:"browser_set_app_profile",description:"设置目标标签页的 App 客户端 UA、环境变量、JSBridge 与桥协议。传 emulation 时由同一个调用联动设备模拟与 iframe 系统外壳；省略 emulation 时不改变设备状态。enabled=false 同理：仅在传 emulation 时一起清除设备模拟。",inputSchema:{type:"object",properties:{enabled:{type:"boolean",description:"必填。true=启用容器模拟，false=清除并还原设备模拟"},profile:{type:"string",enum:[...client.APP_PROFILE_NAMES],description:"容器档案名（enabled=true 时必填），决定 UA/桥对象/环境判断特征"},os:{type:"string",enum:["ios","android"],description:"容器系统，默认 ios"},appVersion:{type:"string",description:"覆盖档案默认 App 版本号"},deviceModel:{type:"string",description:"Android 机型名（拼入 UA 与 __DEVICE_MODEL__）"},bridgeConfig:{type:"object",description:"声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；扩展本地同档案配置会先合并"},emulation:{type:"object",description:"可选设备联动参数；字段覆盖档案推荐设备，空对象使用推荐设备，deviceShell 默认 true。省略时不设置或清除设备。",properties:{preset:{type:"string",enum:[...BROWSER_DEVICE_PRESET_NAMES]},width:{type:"number"},height:{type:"number"},deviceScaleFactor:{type:"number"},scale:{type:"number",exclusiveMinimum:0},mobile:{type:"boolean"},userAgent:{type:"string"},orientation:{type:"string",enum:["portrait","landscape"]},touch:{type:"boolean"},deviceShell:{type:"boolean",description:"是否使用根 iframe WebView 并显示系统栏；在 emulation 内默认 true"}}},reload:{type:"boolean",description:"应用/清除后是否重载页面，默认 true"},tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"}},required:["tabId","enabled"]}},{name:"browser_set_timezone",description:"覆盖目标标签页的时区，作用域仅限该 tab，立即影响 Date / Intl 等页面时间 API。timezone 使用 IANA 时区标识（如 Asia/Shanghai、America/New_York）；传空字符串恢复浏览器默认时区。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},timezone:{type:"string",description:"IANA 时区标识；空字符串表示清除覆盖"}},required:["tabId","timezone"]}},{name:"browser_get_cookie",description:"从目标浏览器读取一个指定非分区 Cookie，用于验证页面分支、实验或当前账号标识。必须明确传 Cookie 名，不支持列举全部 Cookie；HttpOnly Cookie 会被拒绝，禁止读取认证 Token。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},name:{type:"string",description:"Cookie 名称"},url:{type:"string",description:"可选 Cookie 查询 URL；省略时使用当前标签页 URL"},domain:{type:"string",description:"可选精确域过滤，只允许 Cookie 查询 URL 的 host 或它的父域"},path:{type:"string",description:"可选精确 path 过滤"}},required:["tabId","name"]}},{name:"browser_set_cookie",description:"修改当前标签页使用的一个指定非分区 session Cookie。不枚举、不读取其它 Cookie；未传 domain 时只写当前 host，显式传域时只允许当前 host 或它的父域。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},name:{type:"string",description:"Cookie 名称"},value:{type:"string",description:"Cookie 值，可传空字符串；空字符串不会删除 Cookie"},domain:{type:"string",description:"Cookie 域，默认当前 host；只允许当前 host 或它的父域"},path:{type:"string",description:"Cookie path，默认 /"},reload:{type:"boolean",description:"设置后是否刷新当前页面，默认 false"}},required:["tabId","name","value"]}},{name:"browser_run_actions",description:"批量顺序执行多个无需中间判断的原子操作，适合 hover→click 等必须紧密连续的序列。步骤内的页面动作不带内置观察；遇到第一个失败步骤立即停止，且不能嵌套 run_actions。若下一步需要根据页面变化决定，优先逐步使用带观察的页面交互工具；不要用本工具固化「点击→等待→截图」循环。",inputSchema:{type:"object",properties:{actions:{type:"array",description:"要依次执行的 action 列表",items:{type:"object",properties:{action:{type:"string",description:"action 名称（不带 browser_ 前缀），如 page_hover、page_click；仅组合无需中间判断的步骤"},data:{type:"object",description:"该 action 的参数（与单独调用时相同）"}},required:["action"]}},tabId:{type:"number",description:"所有步骤共享的目标标签页 ID。步骤自身指定的 tabId 优先级更高"}},required:["tabId","actions"]}},{name:"browser_list",description:"列出所有浏览器。返回普通浏览器和 Provider 托管浏览器的 browserId、名称、类型、连接状态、稳定元数据及当前默认目标，但不返回带临时凭据的浏览器访问地址。只有 status=connected 的浏览器可用于后续操作。",inputSchema:{type:"object",properties:{}}},{name:"browser_select_browser",description:"选择后续所有浏览器操作的默认目标浏览器（有多个浏览器连接时）。传入 browser_list 返回且 status=connected 的 browserId 或名称即可锁定；传空字符串则清除锁定，回到自动模式（操作最近聚焦的浏览器）。",inputSchema:{type:"object",properties:{browser:{type:"string",description:"目标浏览器的 browserId / 名称；空字符串表示清除锁定、恢复自动选择"}},required:["browser"]}},{name:"browser_request_domain_permission",description:"申请访问指定域名的权限。调用后浏览器会弹出确认窗口让用户授权（90 秒超时），返回 granted 表示是否已获得授权。扩展模式下发送非内置域的 HTTP 请求（browser_send_request）前需先获得用户授权。",inputSchema:{type:"object",properties:{domain:{type:"string",description:"需要授权的域名，如 example.com"}},required:["domain"]}}];server.setRequestHandler(ListToolsRequestSchema,async()=>({tools})),server.setRequestHandler(CallToolRequestSchema,async request=>{let{arguments:args}=request.params,name=request.params.name==="browser_capture_checkpoint"?"browser_tab_checkpoint":request.params.name;try{if(name!==PLUGIN_TOOL_NAME&&!(name in MCP_TOOL_ACTIONS))throw new Error(`Unknown tool: ${name}`);let toolName=name,result;switch(toolName){case PLUGIN_TOOL_NAME:{result=await invokeMearlPluginTool(args,client.invokePlugin);break}case"browser_tab_checkpoint":{let{tabId}=args;result=await client.tabCheckpoint({tabId});break}case"browser_get_requests":{let{tabId,count=10,filter,since,after,includeBody=!0,includeHeaders=!1,maxBodySize=5e4,fields,keysOnly=!1,source}=args;result=await client.getRequests({tabId,count,filter,since,after,includeBody,includeHeaders,maxBodySize,fields,keysOnly,source});break}case"browser_get_events":{let{tabId,source="all",event_type,filter,since,after,limit=20,includeRaw=!1}=args;result=await client.getEvents({tabId,source,event_type,filter,since,after,limit,includeRaw});break}case"browser_get_logs":{let{tabId,level="all",since,after,limit=100,filter}=args;result=await client.getLogs({tabId,level,since,after,limit,filter});break}case"browser_set_mock":{let{payloadFile}=args,{tabId,apiName,mockData,fields,enabled,duration:duration3,conditions}=args;if(enabled=enabled??!0,payloadFile){if(!existsSync(payloadFile))throw new Error(`Payload file not found: ${payloadFile}`);let fileContent=readFileSync(payloadFile,"utf-8"),fileData=JSON.parse(fileContent);fileData.tabId!==void 0&&(tabId=fileData.tabId),fileData.apiName&&(apiName=fileData.apiName),fileData.mockData!==void 0&&(mockData=fileData.mockData),fileData.fields!==void 0&&(fields=fileData.fields),fileData.enabled!==void 0&&(enabled=fileData.enabled),fileData.duration!==void 0&&(duration3=fileData.duration),fileData.conditions!==void 0&&(conditions=fileData.conditions)}result=await client.setMock({tabId,apiName,mockData,fields,enabled,duration:duration3,conditions});break}case"browser_get_mocks":{let{tabId,apiName}=args;result=await client.getMocks({tabId,apiName});break}case"browser_send_request":{result=await client.sendRequest(args);break}case"browser_send_mtop_request":{let{api,data,version:version2,method,appKey,env,timeout}=args;result=await client.sendMtopRequest({api,data,version:version2,method,appKey,env,timeout});break}case"browser_set_rule":{result=await client.setRule(args);break}case"browser_get_rules":{result=await client.getRules();break}case"browser_page_screenshot":{let{format="png",quality=80,selector,tabId}=args;return result=await client.pageScreenshot({format,quality,selector,tabId}),{content:[{type:"image",data:result.data,mimeType:result.meta.format==="jpeg"?"image/jpeg":"image/png"},{type:"text",text:`Screenshot captured: ${result.meta.width}x${result.meta.height} ${result.meta.format.toUpperCase()} (${Math.round(result.meta.size/1024)}KB)
|
|
100
|
+
`),log("Starting Mearl MCP Server..."),log("MCP Server initialized, will connect to Chrome Extension when tools are called");let server=new Server({name:"mearl",version:MCP_SERVER_VERSION},{capabilities:{tools:{}},instructions:"浏览器交互默认工作流：首次进入页面或导航后用 browser_page_snapshot 建立基线；后续页面动作默认返回 { action, observation }。先检查 action.success；action.stage=precondition 表示尚未派发，应按 error 修正输入或刷新快照，且不读取已省略的 observation/diagnostics。动作成功后再按 observation 处理：delta 读取 effects，navigation 在 ready=true 后重建快照，openedTabs 直接使用其 tabId。仅在 fullSnapshotRecommended=true 或需要读取滚动后的新视口时补最小范围快照；视觉任务使用 screenshot。无需页面观察时传 observe:false；需要动作期间的日志、请求或埋点时显式开启 diagnostics。page_eval 仅作为结构化 action 无法表达时的补充；不要在每次动作后固定追加 wait、snapshot 或 screenshot。"}),OBSERVE_INPUT_SCHEMA={type:["object","boolean"],default:{},description:"观察选项。默认开启内置观察（等待相关 DOM、XHR/Fetch/MTop 请求或导航稳定后返回页面变化信号）；传 false 关闭，不影响显式请求的 diagnostics",properties:{quietMs:{type:"number",description:"最后一次 DOM 变化后等待的稳定窗口，默认 100ms"},firstChangeTimeoutMs:{type:"number",description:"没有发生 DOM 变化时最多等待多久，默认 500ms"},timeoutMs:{type:"number",description:"整个观察阶段的最大时间，默认 3000ms"},navigationGraceMs:{type:"number",description:"低信息量点击或按键后等待导航开始的基础宽限时间，默认 1000ms；若仍有网络活动会自动延长，有明确 effects 时不等待"},navigationTimeoutMs:{type:"number",description:"导航开始后等待页面就绪的最大时间，默认 15000ms"},networkIdleMs:{type:"number",description:"文档加载完成且相关 XHR/Fetch/MTop 请求归零后继续保持静默的时间，默认 500ms，用于跳过业务骨架屏"},contentReadyAfterMs:{type:"number",description:"动作开始后允许用结构稳定兜底的保护期，默认 5000ms，并自动限制在导航超时之前；保护期内仍优先等待网络静默"}}},DIAGNOSTICS_INPUT_SCHEMA={type:["object","boolean"],default:!1,description:"默认关闭。传 true 在动作执行前建立边界，并返回新增 error logs 和业务 requests；传对象可自定义通道与过滤，并按需开启 events",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:!1},includeHeaders:{type:"boolean",default:!1}}},events:{type:["object","boolean"],properties:{source:{type:"string",enum:["rum","aplus","arms","all"]},event_type:{type:"string"},filter:{type:"string"},limit:{type:"number",default:100},includeRaw:{type:"boolean",default:!1}}}}},tools=[{name:PLUGIN_TOOL_NAME,description:"调用当前 MCP Server 宿主上的 Mearl Skill 插件；缺失的官方插件会自动安装。插件名、子命令和 input 契约以对应 Skill 为准；BUC 使用 MCP Server 宿主身份，浏览器操作使用当前选择或显式指定的 Browser ID。",inputSchema:{type:"object",properties:{plugin:{type:"string",description:"已注册或 Mearl 官方目录中的插件名"},command:{type:"string",description:"插件注册的子命令名"},input:{type:"object",description:"传给插件 handler 的业务参数，省略时为空对象",additionalProperties:!0},browser:{type:"string",description:"可选目标浏览器 ID 或名称；省略时继承 browser_select_browser 选择的目标"},timeoutSec:{type:"number",description:"可选的浏览器底层调用超时秒数"}},required:["plugin","command"]}},{name:"browser_tab_checkpoint",description:"为目标标签页建立日志、请求和埋点的可靠增量边界，对应 mearl tab_checkpoint。返回的 cursor 可传给 browser_get_logs/browser_get_requests/browser_get_events 的 after。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID；不传时使用当前活动标签页"}}}},{name:"browser_get_requests",description:"获取指定标签页持续采集的 API 请求历史，包含请求、响应与 pending 状态。无需打开 DevTools panel；不传 after 时返回最新 N 条，传 after 时从最早未读项开始分页。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取。不传则使用当前激活标签页"},count:{type:"number",description:"获取的请求数量，默认 10 个。最多可获取最近 1000 个请求",default:10},filter:{type:"string",description:'过滤 API 名称的正则表达式（可选）。例如: ".*\\.cart\\..*" 只返回购物车相关接口'},since:{type:"number",description:"从多久之前开始获取（秒）。例如: 60 表示获取最近 1 分钟内的请求"},after:{type:"string",description:"tab checkpoint 或上一次查询返回的 cursor，仅返回其后的请求"},includeBody:{type:"boolean",description:"是否包含请求体和响应体。false 时将省略 postData 和 responseBody 字段以减少数据量。默认 true",default:!0},includeHeaders:{type:"boolean",description:"是否包含请求头和响应头。false 时将省略 headers 和 responseHeaders 字段以减少数据量。默认 false",default:!1},maxBodySize:{type:"number",description:"单个请求/响应体的最大字节数。超过此大小将被截断。默认 50000（约 50KB）",default:5e4},fields:{type:"array",items:{type:"string"},description:'从响应体中提取指定字段，支持点号路径。例如: ["data.result.list", "data.total"] 只返回这些字段，大幅减少数据量'},keysOnly:{type:"boolean",description:"只返回数据结构（字段路径和类型），不返回实际值。设为 true 可先预览数据结构，再决定提取哪些字段。默认 false",default:!1},source:{type:"string",enum:["mtop","requests","all"],description:"数据源。mtop: mtop 接口（默认）; requests: 普通 XHR/Fetch 请求; all: 全部业务请求"}}}},{name:"browser_get_events",description:"获取目标标签页后台采集的 RUM/aplus/ARMS 埋点事件，无需打开 DevTools panel。不传 after 时返回最新事件，传 after 时按完整上报批次从最早未读项开始分页。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取。不传则使用当前激活标签页"},source:{type:"string",enum:["rum","aplus","arms","all"],description:"事件来源。rum: RUM 性能监控事件; aplus: aplus 埋点事件; arms: ARMS 前端监控事件; all: 全部（默认）",default:"all"},event_type:{type:"string",description:'事件类型正则过滤。例如: "view" 匹配页面 view 事件, "CLK" 匹配点击埋点'},filter:{type:"string",description:"正则过滤，匹配事件的 name 或 url 字段"},since:{type:"number",description:"从多久之前开始获取（秒）。例如: 60 表示获取最近 1 分钟内的事件"},after:{type:"string",description:"tab checkpoint 或上一次查询返回的 cursor，仅返回其后的埋点事件"},limit:{type:"number",description:"返回条数上限，默认 20",default:20},includeRaw:{type:"boolean",description:"是否返回完整 tracking URL、_raw 原始载荷和 _context 上下文；默认 false，仅返回解析后的精简字段",default:!1}}}},{name:"browser_get_logs",description:"获取指定标签页持续采集的 console API、未捕获异常和浏览器日志。无需打开 DevTools panel；不传 after 时返回最新 N 条，传 after 时从最早未读项开始分页。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页"},level:{type:"string",enum:["log","warn","error","info","all"],description:"日志级别过滤。log: 普通日志, warn: 警告, error: 错误, info: 信息, all: 所有级别。默认 all",default:"all"},since:{type:"number",description:"从多久之前开始获取日志（秒）。例如: 60 表示获取最近 1 分钟内的日志"},after:{type:"string",description:"tab checkpoint 或上一次查询返回的 cursor，仅返回其后的日志"},limit:{type:"number",description:"最大返回日志数量，默认 100；快照查询返回最新 N 条",default:100},filter:{type:"string",description:'过滤日志内容的正则表达式或字符串（可选）。支持正则表达式模式（不区分大小写），若正则无效则回退到字符串包含匹配。例如: "error|warning" 匹配包含 error 或 warning 的日志'}}}},{name:"browser_set_mock",description:"动态设置 API 接口的 Mock 数据，用于测试不同数据场景。修改后，浏览器中对该接口的所有请求都会返回 Mock 数据。适用于前端开发测试、边界情况验证、UI 状态测试等。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页"},apiName:{type:"string",description:'API 名称或正则表达式模式。例如: "mtop.cart.query" 精确匹配, ".*\\.cart\\..*" 匹配所有购物车接口'},mockData:{type:["object","string"],description:'【方式一】直接设置完整 Mock 响应数据（JSON 对象）。传入后该接口将完全返回此数据，不再请求真实服务端。示例: {"data":{"result":{"list":[]}},"ret":["SUCCESS"]}。注意：mockData 和 fields 二选一，同时提供时优先使用 fields。大体积响应体可传文件引用字符串 "@/abs/resp.json"（从该文件读取，建议绝对路径）以减少上下文占用'},fields:{type:"array",description:"【方式二】基于真实响应修改指定字段。系统会先获取该接口的原始响应数据，然后按指定路径修改字段值。适合在真实数据基础上做微调",items:{type:"object",properties:{path:{type:"string",description:'字段路径，支持点号和数组索引。例如: "data.result.passengerList[0].name.text"'},value:{description:"要设置的值，可以是任意类型（字符串、数字、对象、数组等）"}},required:["path","value"]}},enabled:{type:"boolean",description:"是否启用 Mock。true: 启用 Mock, false: 禁用 Mock 恢复真实数据。默认 true",default:!0},duration:{type:"number",description:"完整响应时长（毫秒）。可选，mock 生效时的总耗时，绕过真实服务器精确控制（用于测试加载状态、超时等场景）"},conditions:{type:"object",additionalProperties:!0,description:"请求 query/body 字段的子集匹配规则；保留字段 $index 从 0 开始指定同一场景的调用顺序。相同 $index 再次设置会原地覆盖，超过最后一项后持续使用最后一项"},payloadFile:{type:"string",description:"从文件读取 mock 数据（JSON 格式）。当 mockData 很大时，可将完整 JSON 写入文件，通过此参数指定文件路径。文件内容会被解析为 mockData。注意：此参数与 mockData/fields 互斥，优先级最高"}},required:["apiName"]}},{name:"browser_get_mocks",description:"查看当前所有已设置的 Mock 配置，包括接口名称、是否启用、以及 Mock 数据内容。用于排查 Mock 是否生效、Mock 数据是否正确等问题。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID，从 browser_tab_list 获取；不传时使用当前活动标签页"},apiName:{type:"string",description:'过滤指定接口，支持正则表达式。例如: "mtop.cart.query" 或 ".*\\.cart\\..*"。不传则返回所有 Mock'}}}},{name:"browser_send_request",description:"通过浏览器发起 HTTP 代理请求，自动携带目标域名的 Cookie（使用当前浏览器登录态）。支持 GET/POST/PUT/DELETE/PATCH、multipart 文本字段和本地文件上传，适用于需要用户登录态的接口调试、数据爬取、接口测试等场景。",inputSchema:{type:"object",properties:{url:{type:"string",description:"目标请求 URL，必须是完整 URL（含 http:// 或 https://）"},method:{type:"string",enum:["GET","POST","PUT","DELETE","PATCH","HEAD","OPTIONS"],description:"HTTP 请求方法，默认 GET",default:"GET"},headers:{type:"object",description:"自定义请求头（键值对），会与自动生成的 Cookie 头合并",additionalProperties:{type:"string"}},params:{type:"object",description:"URL 查询参数（键值对），会追加到 URL 中",additionalProperties:{type:"string"}},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:!0},responseType:{type:"string",enum:["json","text","auto"],description:'响应格式。auto: 自动检测（默认）; json: 强制解析为 JSON; text: 返回原始文本。注意：auto 模式下若 Content-Type 为图片/音视频/PDF/压缩包等二进制类型，body 将以 base64 字符串返回，bodyType 为 "base64"',default:"auto"},timeout:{type:"number",description:"请求超时时间（毫秒），默认 30000（30 秒）",default:3e4}},required:["url"]}},{name:"browser_send_mtop_request",description:"在当前浏览器页面上下文中发起 mtop API 请求。自动处理签名计算（md5）、Cookie 中的 token 提取、时间戳生成等，无需手动构造签名。适用于：调试 mtop 接口、验证接口返回数据、测试不同参数组合等场景。注意：需要当前页面已登录（有对应的 Cookie），且 DevTools 面板已打开。",inputSchema:{type:"object",properties:{api:{type:"string",description:'mtop API 名称，例如: "mtop.trade.order.create"、"mtop.fliggy.flyrs.render"。以 "mopen." 开头的会使用 mopen 签名算法'},data:{description:'请求数据（JSON 对象），即 mtop 请求中的 data 参数。例如: {"itemId": "12345"}'},version:{type:"string",description:'API 版本号，默认 "1.0"',default:"1.0"},method:{type:"string",enum:["GET","POST"],description:"HTTP 请求方法，默认 GET。POST 时 data 参数放在请求体中",default:"GET"},appKey:{type:"string",description:'appKey，默认 "12574478"'},env:{type:"string",enum:["online","pre"],description:"请求环境。online: 线上（默认，h5api.m.taobao.com）; pre: 预发（h5api.wapa.taobao.com）",default:"online"},timeout:{type:"number",description:"请求超时时间（毫秒），默认 10000（10 秒）",default:1e4}},required:["api"]}},{name:"browser_set_rule",description:"添加 Chrome declarativeNetRequest 规则，用于拦截、重定向或修改请求。规则持久化保存，浏览器重启后仍生效。支持：重定向请求到另一地址、修改请求/响应头、阻止请求、升级到 HTTPS 等。适用于：本地开发时代理到本地服务、修改请求头调试、拦截特定请求等。",inputSchema:{type:"object",properties:{actionType:{type:"string",enum:["redirect","block","allow","upgradeScheme","modifyHeaders"],description:"规则类型。redirect: 重定向请求到另一地址; block: 阻止请求; allow: 允许请求; upgradeScheme: 升级到 HTTPS; modifyHeaders: 修改请求/响应头"},filter:{type:"string",description:'URL 匹配规则（正则表达式）。例如: "^https://h5api\\.m\\.taobao\\.com/.*" 匹配所有淘宝 h5api 请求'},redirectUrl:{type:"string",description:"【redirect 类型必填】重定向目标 URL。支持正则替换占位符 \\1 \\2 等（引用 filter 中的捕获组）"},requestHeaders:{type:"array",description:"【modifyHeaders 类型】要修改的请求头列表",items:{type:"object",properties:{header:{type:"string",description:'请求头名称，如 "x-custom-header"'},operation:{type:"string",enum:["set","append","remove"],description:"set: 设置/覆盖; append: 追加; remove: 删除"},value:{type:"string",description:"请求头值（remove 时可省略）"}},required:["header","operation"]}},responseHeaders:{type:"array",description:"【modifyHeaders 类型】要修改的响应头列表",items:{type:"object",properties:{header:{type:"string",description:"响应头名称"},operation:{type:"string",enum:["set","append","remove"],description:"set: 设置/覆盖; append: 追加; remove: 删除"},value:{type:"string",description:"响应头值（remove 时可省略）"}},required:["header","operation"]}},initiatorDomains:{type:"string",description:'发起请求的域名限制（逗号分隔）。只有从这些域名发起的请求才会匹配此规则。例如: "taobao.com,tmall.com"'},resourceTypes:{type:"array",description:"资源类型限制。不填则匹配所有类型",items:{type:"string",enum:["main_frame","sub_frame","script","stylesheet","image","xmlhttprequest","websocket","other"]}},priority:{type:"number",description:"规则优先级，数字越大优先级越高。多个规则匹配同一请求时，优先级高的生效。默认 1",default:1},description:{type:"string",description:"规则描述，便于识别规则用途"}},required:["actionType","filter"]}},{name:"browser_get_rules",description:"查看当前存储的全部请求规则（含用户在插件 Options 面板手动配置的）。返回规则总开关状态和规则列表，字段结构与 browser_set_rule 入参对齐，用于确认规则是否生效或排查请求被意外重定向/修改的问题。",inputSchema:{type:"object",properties:{}}},{name:"browser_page_screenshot",description:'获取当前浏览器活动标签页的视觉截图，以 Base64 编码返回。支持全页截图或指定 CSS 选择器截取单个元素（类似 DevTools "Capture node screenshot"）。适用于视觉判断、Canvas、跨域 iframe、UI 排查和保存快照；常规页面动作后优先读取其内置观察的增量结果，不要固定在每次动作后截图。',inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",description:"CSS 选择器。提供后只截取该元素区域（会自动滚动元素到可见区域），不提供则截取整个页面"},format:{type:"string",enum:["png","jpeg"],description:"截图格式。png: PNG 格式（无损，默认）; jpeg: JPEG 格式（有损压缩，体积更小）",default:"png"},quality:{type:"number",description:"JPEG 质量（仅 format 为 jpeg 时有效）。范围 0-100，默认 80。数值越高质量越好但文件越大",default:80}},required:["tabId"]}},{name:"browser_page_selected_element",description:"获取 Chrome DevTools Elements 面板中当前选中元素的详细信息，包含布局尺寸、CSS 计算样式、属性、DOM 结构等。适用于：分析布局问题、排查样式异常、了解元素几何信息、辅助 UI 优化等场景。使用前需要在 Elements 面板中选中目标元素（点击面板元素或使用 inspect 工具点击页面元素）。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},includeOuterHTML:{type:"boolean",description:"是否包含元素的 outerHTML（最多 3000 字符）。设为 false 可减少数据量。默认 true",default:!0},includeScreenshot:{type:"boolean",description:"是否返回选中元素截图。开启后会自动滚动到元素并按默认策略截图（PNG、8px 边距），返回 image 类型内容。默认 false",default:!1}},required:["tabId"]}},{name:"browser_launch",description:"启动浏览器实例。默认使用本地独立 Chrome；传已注册的 Provider ID 时，把该 Provider 声明的创建参数放在 providerOptions。配对实例会直接返回 pairing URL。具体 Provider 用法可运行 mearl <providerId> 查看。",inputSchema:{type:"object",properties:{name:{type:"string",description:"本地实例名称；使用默认 local Provider 时必填"},provider:{type:"string",description:"浏览器提供方，默认 local；也可传已注册的外部 Provider ID"},providerOptions:{type:"object",additionalProperties:!0,description:"所选外部 Provider 声明的结构化创建参数"},headless:{type:"boolean",description:"本地 Provider 是否使用 headless=new，默认 true"},userAgentMode:{type:"string",enum:["default","desktop"],description:"本地 UA 模式：default 使用默认 UA；desktop 使用匹配本机 Chrome 的 UA",default:"default"},persistent:{type:"boolean",description:"本地实例关闭后是否保留独立 Profile，默认 false",default:!1},url:{type:"string",description:"新浏览器打开的初始 URL"},executablePath:{type:"string",description:"Chrome 可执行文件路径；省略时自动发现，也可用环境变量配置"},copyCookieDomains:{oneOf:[{type:"array",items:{type:"string"}},{type:"string",enum:["mearl-services"]}],description:"从控制浏览器复制 Cookie。传域名数组时复制指定域；传 mearl-services 时同步 Mearl 依赖平台登录态。保留 HttpOnly/Secure/SameSite/过期时间等属性；域名数组中的非内置域需先授权。"}},anyOf:[{required:["name"]},{required:["provider"]}]}},{name:"browser_close",description:"关闭一个 Provider 托管浏览器；持久化数据默认按 Provider 策略保留，deleteProfile=true 时一并删除。名称有歧义时使用完整 browserId。",inputSchema:{type:"object",properties:{browser:{type:"string",description:"browser_launch 返回的 browserId 或实例名称"},deleteProfile:{type:"boolean",description:"是否强制删除 Provider 持久化数据，默认 false",default:!1}},required:["browser"]}},{name:"browser_release",description:"仅在用户明确要求结束调试、退出接管或清理会话资源时调用，不作为普通任务收尾。它会释放 debugger/CDP 控制和会话级临时效果，后续浏览器操作可自动重新建立控制；Provider 实例的生命周期操作由 Browser Manager 处理。",inputSchema:{type:"object",properties:{}}},{name:"browser_tab_open",description:"打开或按 URL 规则复用标签页。默认新建并等待加载完成；reuse=prefer 可优先复用，reuse=require 可限制为只复用。响应的 opened/reused 可用于判断流程结束时是否应关闭该 Tab。",inputSchema:{type:"object",properties:{url:{type:"string",description:"要打开的页面 URL"},active:{type:"boolean",description:"是否激活（前台显示）新标签页。默认 false（后台打开）",default:!1},openerTabId:{type:"number",description:"来源标签页 ID。侧边栏对话继续任务时传入，用于把新开或复用的标签页关联到同一对话"},closeExisting:{type:"boolean",description:"打开前是否先关闭 Agent 受控的已有标签页。默认 false",default:!1},group:{type:"string",description:"把新标签页加入指定标题的标签页分组（同窗口同名分组存在则加入，否则新建）。仅扩展模式支持，CDP 模式忽略"},reuse:{type:"string",enum:["never","prefer","require"],description:"never 始终新建；prefer 匹配到则复用、否则新建；require 只允许复用。默认 never",default:"never"},match:{type:"object",description:"复用标签页时的 URL 匹配规则",properties:{urlPattern:{type:"string",description:"支持 * 的完整 URL glob；省略时精确匹配 url"},ignoreSearch:{type:"boolean",description:"匹配时是否忽略 URL query，默认 false"},ignoreHash:{type:"boolean",description:"匹配时是否忽略 URL hash，默认 false"},onMultiple:{type:"string",enum:["error","first"],description:"匹配多个 Tab 时默认报错；first 显式取第一个"}}},restoreFocusOnClose:{type:"boolean",description:"新建 active Tab 关闭后是否恢复原活动标签页，默认 false",default:!1},emulation:{type:"object",description:"开 tab 即进入移动端模拟态，等价于随后立即调用 browser_set_device_emulation，但在导航前生效。deviceShell=true 时首屏就在 iframe WebView 与设备系统外壳中渲染。字段规则一致（无 enabled/reload）。",properties:{preset:{type:"string",enum:[...BROWSER_DEVICE_PRESET_NAMES],description:"内置设备预设，一键提供 viewport/DPR/UA。当前机型在前，旧机型 ID 继续兼容；可与下面字段组合，显式字段覆盖预设值"},width:{type:"number",description:"视口宽度（覆盖 preset）"},height:{type:"number",description:"视口高度（覆盖 preset）"},deviceScaleFactor:{type:"number",description:"devicePixelRatio（覆盖 preset）"},scale:{type:"number",exclusiveMinimum:0,description:"画面视觉比例，不改变视口 CSS 尺寸或 devicePixelRatio；必须为有限正数，默认 1"},mobile:{type:"boolean",description:"是否启用移动渲染模式。默认从 preset 推断，无 preset 默认 true"},userAgent:{type:"string",description:"自定义 User-Agent（覆盖 preset）。无 preset 时必填"},orientation:{type:"string",enum:["portrait","landscape"],description:"横竖屏，landscape 会对调宽高。默认 portrait"},touch:{type:"boolean",description:"是否启用触摸事件并把鼠标事件转成 touch。默认从 preset 推断；无 preset 时跟随 mobile"},deviceShell:{type:"boolean",description:"是否使用 iframe WebView 并渲染顶部状态栏与底部操作区，默认 false"},splitScreen:{type:"boolean",description:"是否在横屏设备外壳中将首页与业务页分置左右 WebView；仅与 appProfile、deviceShell=true、orientation=landscape 同时生效，默认 false"}}},appProfile:{type:"string",enum:[...client.APP_PROFILE_NAMES],description:"开 tab 即注入 App 客户端环境与 JSBridge（等价于随后调用 browser_set_app_profile，但在首次导航前生效）。不创建根 iframe；需要设备外壳时同时传 emulation.deviceShell=true"},os:{type:"string",enum:["ios","android"],description:"与 appProfile 配合；容器系统，默认 ios"},bridgeConfig:{type:"object",description:"与 appProfile 配合；声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}，不执行配置脚本"}},required:["url"]}},{name:"browser_tab_close",description:"关闭指定的浏览器标签页。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"要关闭的标签页 ID（从 tab_open 或 tab_list 获取）"}},required:["tabId"]}},{name:"browser_tab_list",description:"列出当前浏览器窗口中所有标签页的信息，包括 ID、URL、标题和是否活动。",inputSchema:{type:"object",properties:{}}},{name:"browser_page_click",description:"点击页面元素；selector、text、point 三种定位方式必须且只能提供一种。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",description:`原生 CSS 选择器（如 "[aria-label='提交']"、"#login-btn"）或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e3"，必须带 "@" 前缀）。注意字段名是 "selector" 而非 "ref"。不支持 :has-text/:visible 等 Playwright 扩展语法。与 text/point 互斥。`},text:{type:"string",description:'按可见文本（accessibility name）定位。例如 "退款明细"。匹配到多个时会报错并列出候选——可加 role 或 exact:true 收敛，或用 page_snapshot 拿 @ref。与 selector/point 互斥。'},point:{type:"object",description:"按视口坐标点击（CSS 像素，左上角为原点）。selector 和 text 都不适用时使用。与 selector/text 互斥。",properties:{x:{type:"number",description:"横坐标（CSS 像素）"},y:{type:"number",description:"纵坐标（CSS 像素）"}},required:["x","y"]},role:{type:"string",description:'配合 text 使用，按 AX role 过滤消歧（如 "button"、"link"、"heading"、"StaticText"）'},exact:{type:"boolean",description:"配合 text 使用，默认 true 精确匹配；false 时按子串匹配",default:!0},scope:{type:"string",description:'配合 text 使用，把 AX 文本匹配限制在指定 CSS 元素或 snapshot ref（如 "@e12"）子树内'},clickMode:{type:"string",enum:["auto","dom","mouse","touch"],description:"默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式",default:"auto"},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId"]}},{name:"browser_page_drag",description:"连续拖动页面元素或视口坐标，适用于轮播图、滑块、Canvas 手势和拖放。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},from:{description:"拖动起点：CSS/@eN selector，或 {x,y} 视口坐标（CSS 像素）",anyOf:[{type:"string"},{type:"object",properties:{x:{type:"number"},y:{type:"number"}},required:["x","y"]}]},to:{description:"拖动终点：CSS/@eN selector，或 {x,y} 视口坐标（CSS 像素）",anyOf:[{type:"string"},{type:"object",properties:{x:{type:"number"},y:{type:"number"}},required:["x","y"]}]},dragMode:{type:"string",enum:["auto","dom","mouse","touch"],description:"默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式",default:"auto"},durationMs:{type:"number",minimum:0,maximum:5e3,description:"拖动持续时间（毫秒），默认 400；内部自动分段移动",default:400},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","from","to"]}},{name:"browser_page_type",description:"向输入框填写文本，兼容 React 等框架的受控组件。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",description:'原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e6"，必须带 "@" 前缀）。字段名是 "selector"。不支持 :has-text/:visible 等 Playwright 扩展。'},text:{type:"string",description:"要输入的文本内容"},clearFirst:{type:"boolean",description:"是否先清空输入框原有内容。默认 true",default:!0},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","selector","text"]}},{name:"browser_page_scroll",description:'按方向滚动页面或指定容器；containerPolicy="nearest" 可从子节点解析最近的可滚动祖先。',inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},direction:{type:"string",enum:["up","down","top","bottom"],description:"滚动方向"},distance:{type:"number",description:"滚动距离（像素），仅 up/down 方向有效。默认 600",default:600},selector:{type:"string",description:'目标滚动容器的原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e6"，必须带 "@" 前缀）；不传时滚动页面。'},containerPolicy:{type:"string",enum:["self","nearest"],description:"默认 self，要求 selector 本身可滚动；nearest 会在其不可滚动时使用最近的可滚动祖先"},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","direction"]}},{name:"browser_page_hover",description:"将鼠标悬停在页面元素上。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",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 表达式，作为结构化页面 action 无法表达时的补充。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},expression:{type:"string",description:"要执行的 JavaScript 表达式"},frameId:{type:"string",description:"目标 frame 的 CDP frameId。不传则在主 frame 中执行。可通过 browser_page_frames 获取"},awaitPromise:{type:"boolean",description:"是否等待表达式返回的 Promise，默认 true",default:!0},observe:{...OBSERVE_INPUT_SCHEMA,type:"object",description:"仅在表达式会修改页面且需要观察结果时显式传入；不传时轻量执行并直接返回结果"},diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","expression"]}},{name:"browser_page_snapshot",description:"获取带 @ref 的页面无障碍树；支持完整、当前视口、交互控件、指定区域或查询结果。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},depth:{type:"number",description:"无障碍树的最大深度。默认 15，增大可获取更深层元素",default:15},mode:{type:"string",enum:["full","interactive","viewport"],description:"输出范围：full 为完整树；interactive 只保留当前视口内的语义控件，视口内无 AX 控件语义时自动回退到 viewport；viewport 只保留当前可视区域。默认 full"},rootSelector:{type:"string",description:"只获取指定 CSS 元素的 AX 子树，可与 mode 组合；与 rootRef 互斥"},rootRef:{type:"string",description:'以已有 snapshot ref（如 "@e8"）为根获取局部 AX 子树'},ancestorDepth:{type:"number",description:"rootRef 向上扩展的 DOM 祖先层数，默认 0，最大 20",minimum:0,maximum:20},query:{type:"object",description:"服务端过滤 AX 树，只保留按 accessibility name / role 命中的节点及祖先路径",properties:{text:{type:"string",description:"要匹配的 accessibility name"},role:{type:"string",description:"要匹配的 AX role"},exact:{type:"boolean",description:"text 默认精确匹配；false 时按子串匹配"}}},maxNodes:{type:"number",description:"最多输出节点数；超出时保留首尾。0 表示不限制"},maxChars:{type:"number",description:"最多输出字符数，默认 60000；超出时保留首尾。0 表示不限制"}},required:["tabId"]}},{name:"browser_page_press",description:"在页面中按下键盘按键或组合键。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},key:{type:"string",description:"按键名称。支持：Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown, Space"},modifiers:{type:"array",items:{type:"string"},description:'修饰键数组，如 ["Alt", "Shift", "Control", "Meta"]'},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","key"]}},{name:"browser_page_wait",description:"独立等待接口：仅用于没有前置动作时等待指定时间、已知 selector 或页面 condition。三种模式必须且只能提供一个；点击、输入后的异步稳定判断由页面交互工具内置的观察完成。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},time:{type:"number",description:"固定等待毫秒数，与 selector/condition 三选一"},selector:{type:"string",description:"CSS 选择器，等待该元素出现在 DOM 中，与 time/condition 三选一"},condition:{type:"string",description:"在页面主上下文轮询的 JavaScript 表达式，返回 truthy 时结束，支持 Promise；与 time/selector 三选一"},timeout:{type:"number",description:"等待超时时间（毫秒），默认 10000ms",default:1e4},interval:{type:"number",description:"selector/condition 的轮询间隔（毫秒），默认 200ms",default:200}},required:["tabId"]}},{name:"browser_page_navigate",description:'在指定标签页中导航到 URL、设置 refresh:true 重新加载，或用 history:"back"|"forward" 沿浏览历史移动。三种模式互斥，返回最终 URL 和标题。',inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},url:{type:"string",description:"要导航到的 URL；与 refresh/history 互斥"},refresh:{type:"boolean",description:"为 true 时直接重新加载当前页面；与 url/history 互斥",default:!1},history:{type:"string",enum:["back","forward"],description:"沿当前标签页浏览历史后退或前进；与 url/refresh 互斥"}},required:["tabId"]}},{name:"browser_page_upload",description:'向 <input type="file"> 元素上传一个或多个本地文件。',inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},selector:{type:"string",description:'原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 ref（如 "@e5"，必须带 "@" 前缀），用于定位 <input type="file"> 元素。字段名是 "selector"。'},filePaths:{type:"array",items:{type:"string"},description:'要上传的本地文件路径数组，如 ["/Users/me/photo.jpg"]'},observe:OBSERVE_INPUT_SCHEMA,diagnostics:DIAGNOSTICS_INPUT_SCHEMA},required:["tabId","selector","filePaths"]}},{name:"browser_page_frames",description:"列出主 frame 和 iframe，返回可供 browser_page_eval 使用的 frameId。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"}},required:["tabId"]}},{name:"browser_set_device_emulation",description:"把目标标签页切换为移动端模拟态：视口尺寸 / DPR / UA / 触摸事件按指定设备生效，并可独立调整视觉比例。deviceShell=true 时把业务页放入 iframe WebView，并在外层渲染顶部状态栏与底部操作区；false/省略时保持纯 CDP 模拟。作用域仅限该 tab，启用后默认 reload，enabled=false 清除模拟与设备外壳。",inputSchema:{type:"object",properties:{enabled:{type:"boolean",description:"必填。true=启用模拟（按 preset/参数生效），false=清除模拟回到桌面态"},preset:{type:"string",enum:[...BROWSER_DEVICE_PRESET_NAMES],description:"内置设备预设，一键提供 viewport/DPR/UA。当前机型在前，旧机型 ID 继续兼容；可与下面的字段组合，显式字段会覆盖预设值"},width:{type:"number",description:"视口宽度（覆盖 preset）"},height:{type:"number",description:"视口高度（覆盖 preset）"},deviceScaleFactor:{type:"number",description:"devicePixelRatio（覆盖 preset）"},scale:{type:"number",exclusiveMinimum:0,description:"画面视觉比例，不改变视口 CSS 尺寸或 devicePixelRatio；必须为有限正数，默认 1"},mobile:{type:"boolean",description:"是否启用移动渲染模式（影响 hover/pointer media query、viewport meta 行为）。默认从 preset 推断，无 preset 默认 true"},userAgent:{type:"string",description:"自定义 User-Agent（覆盖 preset）"},orientation:{type:"string",enum:["portrait","landscape"],description:"横竖屏，landscape 会对调宽高。默认 portrait"},touch:{type:"boolean",description:"是否启用触摸事件并把鼠标事件转成 touch。默认从 preset 推断；无 preset 时跟随 mobile"},deviceShell:{type:"boolean",description:"是否使用 iframe WebView 并渲染顶部状态栏与底部操作区，默认 false"},splitScreen:{type:"boolean",description:"是否在横屏 App 容器中将首页与业务页分置左右 WebView；仅在当前已启用 App 档案、deviceShell=true、orientation=landscape 时生效，默认 false"},reload:{type:"boolean",description:"启用模拟后是否重载页面（让 JS 读到新的 navigator.userAgent / window.innerWidth）。默认 true"},tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"}},required:["tabId","enabled"]}},{name:"browser_set_app_profile",description:"设置目标标签页的 App 客户端 UA、环境变量、JSBridge 与桥协议。传 emulation 时由同一个调用联动设备模拟与 iframe 系统外壳；省略 emulation 时不改变设备状态。enabled=false 同理：仅在传 emulation 时一起清除设备模拟。",inputSchema:{type:"object",properties:{enabled:{type:"boolean",description:"必填。true=启用容器模拟，false=清除并还原设备模拟"},profile:{type:"string",enum:[...client.APP_PROFILE_NAMES],description:"容器档案名（enabled=true 时必填），决定 UA/桥对象/环境判断特征"},os:{type:"string",enum:["ios","android"],description:"容器系统，默认 ios"},appVersion:{type:"string",description:"覆盖档案默认 App 版本号"},deviceModel:{type:"string",description:"Android 机型名（拼入 UA 与 __DEVICE_MODEL__）"},bridgeConfig:{type:"object",description:"声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；扩展本地同档案配置会先合并"},emulation:{type:"object",description:"可选设备联动参数；字段覆盖档案推荐设备，空对象使用推荐设备，deviceShell 默认 true。省略时不设置或清除设备。",properties:{preset:{type:"string",enum:[...BROWSER_DEVICE_PRESET_NAMES]},width:{type:"number"},height:{type:"number"},deviceScaleFactor:{type:"number"},scale:{type:"number",exclusiveMinimum:0},mobile:{type:"boolean"},userAgent:{type:"string"},orientation:{type:"string",enum:["portrait","landscape"]},touch:{type:"boolean"},deviceShell:{type:"boolean",description:"是否使用根 iframe WebView 并显示系统栏；在 emulation 内默认 true"},splitScreen:{type:"boolean",description:"是否在横屏设备外壳中将首页与业务页分置左右 WebView；仅与 deviceShell=true、orientation=landscape 同时生效，默认 false"}}},reload:{type:"boolean",description:"应用/清除后是否重载页面，默认 true"},tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"}},required:["tabId","enabled"]}},{name:"browser_set_timezone",description:"覆盖目标标签页的时区，作用域仅限该 tab，立即影响 Date / Intl 等页面时间 API。timezone 使用 IANA 时区标识（如 Asia/Shanghai、America/New_York）；传空字符串恢复浏览器默认时区。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},timezone:{type:"string",description:"IANA 时区标识；空字符串表示清除覆盖"}},required:["tabId","timezone"]}},{name:"browser_get_cookie",description:"从目标浏览器读取一个指定非分区 Cookie，用于验证页面分支、实验或当前账号标识。必须明确传 Cookie 名，不支持列举全部 Cookie；HttpOnly Cookie 会被拒绝，禁止读取认证 Token。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},name:{type:"string",description:"Cookie 名称"},url:{type:"string",description:"可选 Cookie 查询 URL；省略时使用当前标签页 URL"},domain:{type:"string",description:"可选精确域过滤，只允许 Cookie 查询 URL 的 host 或它的父域"},path:{type:"string",description:"可选精确 path 过滤"}},required:["tabId","name"]}},{name:"browser_set_cookie",description:"修改当前标签页使用的一个指定非分区 session Cookie。不枚举、不读取其它 Cookie；未传 domain 时只写当前 host，显式传域时只允许当前 host 或它的父域。",inputSchema:{type:"object",properties:{tabId:{type:"number",description:"目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）"},name:{type:"string",description:"Cookie 名称"},value:{type:"string",description:"Cookie 值，可传空字符串；空字符串不会删除 Cookie"},domain:{type:"string",description:"Cookie 域，默认当前 host；只允许当前 host 或它的父域"},path:{type:"string",description:"Cookie path，默认 /"},reload:{type:"boolean",description:"设置后是否刷新当前页面，默认 false"}},required:["tabId","name","value"]}},{name:"browser_run_actions",description:"批量顺序执行多个无需中间判断的原子操作，适合 hover→click 等必须紧密连续的序列。步骤内的页面动作不带内置观察；遇到第一个失败步骤立即停止，且不能嵌套 run_actions。若下一步需要根据页面变化决定，优先逐步使用带观察的页面交互工具；不要用本工具固化「点击→等待→截图」循环。",inputSchema:{type:"object",properties:{actions:{type:"array",description:"要依次执行的 action 列表",items:{type:"object",properties:{action:{type:"string",description:"action 名称（不带 browser_ 前缀），如 page_hover、page_click；仅组合无需中间判断的步骤"},data:{type:"object",description:"该 action 的参数（与单独调用时相同）"}},required:["action"]}},tabId:{type:"number",description:"所有步骤共享的目标标签页 ID。步骤自身指定的 tabId 优先级更高"}},required:["tabId","actions"]}},{name:"browser_list",description:"列出所有浏览器。返回普通浏览器和 Provider 托管浏览器的 browserId、名称、类型、连接状态、稳定元数据及当前默认目标，但不返回带临时凭据的浏览器访问地址。只有 status=connected 的浏览器可用于后续操作。",inputSchema:{type:"object",properties:{}}},{name:"browser_select_browser",description:"选择后续所有浏览器操作的默认目标浏览器（有多个浏览器连接时）。传入 browser_list 返回且 status=connected 的 browserId 或名称即可锁定；传空字符串则清除锁定，回到自动模式（操作最近聚焦的浏览器）。",inputSchema:{type:"object",properties:{browser:{type:"string",description:"目标浏览器的 browserId / 名称；空字符串表示清除锁定、恢复自动选择"}},required:["browser"]}},{name:"browser_request_domain_permission",description:"申请访问指定域名的权限。调用后浏览器会弹出确认窗口让用户授权（90 秒超时），返回 granted 表示是否已获得授权。扩展模式下发送非内置域的 HTTP 请求（browser_send_request）前需先获得用户授权。",inputSchema:{type:"object",properties:{domain:{type:"string",description:"需要授权的域名，如 example.com"}},required:["domain"]}}];server.setRequestHandler(ListToolsRequestSchema,async()=>({tools})),server.setRequestHandler(CallToolRequestSchema,async request=>{let{arguments:args}=request.params,name=request.params.name==="browser_capture_checkpoint"?"browser_tab_checkpoint":request.params.name;try{if(name!==PLUGIN_TOOL_NAME&&!(name in MCP_TOOL_ACTIONS))throw new Error(`Unknown tool: ${name}`);let toolName=name,result;switch(toolName){case PLUGIN_TOOL_NAME:{result=await invokeMearlPluginTool(args,client.invokePlugin);break}case"browser_tab_checkpoint":{let{tabId}=args;result=await client.tabCheckpoint({tabId});break}case"browser_get_requests":{let{tabId,count=10,filter,since,after,includeBody=!0,includeHeaders=!1,maxBodySize=5e4,fields,keysOnly=!1,source}=args;result=await client.getRequests({tabId,count,filter,since,after,includeBody,includeHeaders,maxBodySize,fields,keysOnly,source});break}case"browser_get_events":{let{tabId,source="all",event_type,filter,since,after,limit=20,includeRaw=!1}=args;result=await client.getEvents({tabId,source,event_type,filter,since,after,limit,includeRaw});break}case"browser_get_logs":{let{tabId,level="all",since,after,limit=100,filter}=args;result=await client.getLogs({tabId,level,since,after,limit,filter});break}case"browser_set_mock":{let{payloadFile}=args,{tabId,apiName,mockData,fields,enabled,duration:duration3,conditions}=args;if(enabled=enabled??!0,payloadFile){if(!existsSync(payloadFile))throw new Error(`Payload file not found: ${payloadFile}`);let fileContent=readFileSync(payloadFile,"utf-8"),fileData=JSON.parse(fileContent);fileData.tabId!==void 0&&(tabId=fileData.tabId),fileData.apiName&&(apiName=fileData.apiName),fileData.mockData!==void 0&&(mockData=fileData.mockData),fileData.fields!==void 0&&(fields=fileData.fields),fileData.enabled!==void 0&&(enabled=fileData.enabled),fileData.duration!==void 0&&(duration3=fileData.duration),fileData.conditions!==void 0&&(conditions=fileData.conditions)}result=await client.setMock({tabId,apiName,mockData,fields,enabled,duration:duration3,conditions});break}case"browser_get_mocks":{let{tabId,apiName}=args;result=await client.getMocks({tabId,apiName});break}case"browser_send_request":{result=await client.sendRequest(args);break}case"browser_send_mtop_request":{let{api,data,version:version2,method,appKey,env,timeout}=args;result=await client.sendMtopRequest({api,data,version:version2,method,appKey,env,timeout});break}case"browser_set_rule":{result=await client.setRule(args);break}case"browser_get_rules":{result=await client.getRules();break}case"browser_page_screenshot":{let{format="png",quality=80,selector,tabId}=args;return result=await client.pageScreenshot({format,quality,selector,tabId}),{content:[{type:"image",data:result.data,mimeType:result.meta.format==="jpeg"?"image/jpeg":"image/png"},{type:"text",text:`Screenshot captured: ${result.meta.width}x${result.meta.height} ${result.meta.format.toUpperCase()} (${Math.round(result.meta.size/1024)}KB)
|
|
101
101
|
Page: ${result.meta.title}
|
|
102
102
|
URL: ${result.meta.url}`}]}}case"browser_page_selected_element":{let{includeOuterHTML=!0,includeScreenshot=!1,tabId}=args;if(result=await client.pageSelectedElement({includeOuterHTML,includeScreenshot,tabId}),includeScreenshot&&result?.screenshot?.data)return{content:[{type:"image",data:result.screenshot.data,mimeType:result.screenshot.meta?.format==="jpeg"?"image/jpeg":"image/png"},{type:"text",text:`Selected element screenshot captured: ${result.screenshot.meta?.width}x${result.screenshot.meta?.height} ${String(result.screenshot.meta?.format||"").toUpperCase()}
|
|
103
103
|
Element: ${result.tagName||"unknown"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mearl/mcp-server",
|
|
3
|
-
"version": "2.15.
|
|
3
|
+
"version": "2.15.3",
|
|
4
4
|
"description": "MCP Server for Mearl - enables AI to interact with Chrome browser requests and logs",
|
|
5
5
|
"mcpName": "io.github.F-loat/mearl",
|
|
6
6
|
"type": "module",
|
|
@@ -34,8 +34,8 @@
|
|
|
34
34
|
"dependencies": {
|
|
35
35
|
"commander": "^15.0.0",
|
|
36
36
|
"prompts": "^2.4.2",
|
|
37
|
-
"@mearl/client": "2.15.
|
|
38
|
-
"@mearl/native-host": "2.15.
|
|
37
|
+
"@mearl/client": "2.15.3",
|
|
38
|
+
"@mearl/native-host": "2.15.3"
|
|
39
39
|
},
|
|
40
40
|
"devDependencies": {
|
|
41
41
|
"@modelcontextprotocol/sdk": "^1.0.4",
|