@mearl/mcp-server 2.6.0 → 2.7.0
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 +2 -2
- package/dist/index.js +74 -3
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -12,11 +12,11 @@
|
|
|
12
12
|
- 📴 **browser_release**: 按用户明确要求释放 debugger/CDP 控制和会话级临时效果，并保留浏览器与全部标签页
|
|
13
13
|
- 🚀 **browser_launch / browser_close**: 启动或关闭本地 Chrome / AgentBay CDP 托管浏览器，支持按域复制及跨会话持久化登录态
|
|
14
14
|
- 🌐 **browser_page_snapshot**: 首次获取页面结构和可交互元素
|
|
15
|
-
- ⚡ **browser_page_click/type/hover/scroll/press/upload**: 执行页面动作，默认内置观察，返回通知、可交互控件、焦点、导航或直接打开的新标签页
|
|
15
|
+
- ⚡ **browser_page_click/drag/type/hover/scroll/press/upload**: 执行页面动作，默认内置观察，返回通知、可交互控件、焦点、导航或直接打开的新标签页
|
|
16
16
|
|
|
17
17
|
## 浏览器交互工作流
|
|
18
18
|
|
|
19
|
-
首次进入页面时调用 `browser_page_snapshot`
|
|
19
|
+
首次进入页面时调用 `browser_page_snapshot` 建立结构基线。后续点击、拖动、输入、悬停、滚动、按键和上传直接调用 `browser_page_click/drag/type/hover/scroll/press/upload`，它们默认内置观察，动作与异步同步在一次调用内完成；同页结果读取 `effects.notifications`、`effects.interactives` 和 `effects.focus`。新增或变化的可交互节点会尽量携带可直接用于后续动作的 `node.ref`，解析不到 ref 时回退使用 `node.selector`。导航结果读取新 URL 和就绪状态；动作直接打开新标签页时，`openedTabs` 返回可继续操作的 `tabId`，无需调用 `browser_tab_list`。通常仅在导航后、`fullSnapshotRecommended: true` 或需要视觉判断时重新 snapshot 或截图；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。`browser_page_eval` 默认裸执行，仅在表达式会修改页面且需要变化信号时显式传 `observe` 对象。
|
|
20
20
|
|
|
21
21
|
长列表重新感知时优先使用 `browser_page_snapshot(mode: "viewport")`；已知 CSS 区域时使用 `rootSelector`，已有 ref 时使用 `rootRef`，只查找特定文案或角色时使用 `query`；仅需要当前视口内的控件时使用 `mode: "interactive"`，避免整页 AX Tree 占用上下文。视口内缺少 AX 控件语义时，`interactive` 会自动回退到 viewport，并返回 `fallbackMode: "viewport"`。重复文本点击可用 `scope` 限定子树，滚动子节点所在容器可用 `containerPolicy: "nearest"`。
|
|
22
22
|
|
package/dist/index.js
CHANGED
|
@@ -49,6 +49,7 @@ const MCP_TOOL_ACTIONS = {
|
|
|
49
49
|
browser_tab_close: 'tab_close',
|
|
50
50
|
browser_tab_list: 'tab_list',
|
|
51
51
|
browser_page_click: 'page_click',
|
|
52
|
+
browser_page_drag: 'page_drag',
|
|
52
53
|
browser_page_type: 'page_type',
|
|
53
54
|
browser_page_scroll: 'page_scroll',
|
|
54
55
|
browser_page_hover: 'page_hover',
|
|
@@ -364,7 +365,7 @@ async function main() {
|
|
|
364
365
|
capabilities: {
|
|
365
366
|
tools: {},
|
|
366
367
|
},
|
|
367
|
-
instructions: '浏览器交互默认工作流：首次进入页面时使用 browser_page_snapshot
|
|
368
|
+
instructions: '浏览器交互默认工作流：首次进入页面时使用 browser_page_snapshot 建立页面基线；后续点击、拖动、输入、悬停、滚动、按键和上传直接使用 browser_page_click/drag/type/hover/scroll/press/upload，它们默认内置观察与原子诊断，动作、异步稳定判断、新增 error logs 和业务 requests 在一次调用内完成，返回 { action, observation, diagnostics }；传 observe:false 只关闭 DOM/导航观察并保留诊断，同时传 diagnostics:false 才执行裸动作。观察结果不替代完整页面理解：observation.mode 为 delta 时确认 scope="main-document"，再读取 effects.notifications、effects.interactives 和 effects.focus；interactives/focus 节点有 ref 时优先直接用于后续动作，没有 ref 时使用 selector；notifications 中 change=transient 表示已经消失的 Toast、状态或错误提示。为 navigation 时先检查 ready，ready=true 表示文档、相关业务请求和可见骨架状态已经稳定，可在新页面重建 snapshot。observation.openedTabs 表示动作直接打开的关联标签页，可显式使用返回的 tabId 继续操作，无需调用 browser_tab_list。其他情况下通常仅当 fullSnapshotRecommended 为 true 时根据 snapshotReasons 回退，并选择最小范围：已有区域 ref 用 rootRef，已有 CSS 根节点用 rootSelector，只需查找特定目标时加 query，长列表用 mode="viewport"，只需当前视口内的控件用 mode="interactive"；滚动动作的 moved 只证明位置变化，下一步需要读取新视口内容时可按需获取 viewport 快照。视口内缺少 AX 控件语义时 interactive 会在同一次调用中回退到 viewport，并返回 fallbackMode。重复文本点击用 scope 限定区域，ref 指向滚动容器子节点时用 containerPolicy="nearest"。轮播图、滑块和拖放使用 page_drag；不要用 page_eval 合成 DragEvent/PointerEvent。page_eval 默认裸执行且应作为结构化能力无法表达时的补充；需要页面变化信号时传 observe 对象，需要原子诊断时传 diagnostics:true 或对象。视觉任务再使用 screenshot。不要在每次动作后固定调用 browser_page_wait、snapshot 或 screenshot。',
|
|
368
369
|
});
|
|
369
370
|
// 页面交互工具共享的 observe 参数 schema：默认开启内置观察，传 false 关闭
|
|
370
371
|
const OBSERVE_INPUT_SCHEMA = {
|
|
@@ -1018,7 +1019,7 @@ async function main() {
|
|
|
1018
1019
|
},
|
|
1019
1020
|
{
|
|
1020
1021
|
name: 'browser_launch',
|
|
1021
|
-
description: '启动一个托管浏览器。默认使用本地独立 Chrome；provider=agentbay
|
|
1022
|
+
description: '启动一个托管浏览器。默认使用本地独立 Chrome；provider=agentbay 时可创建或显式复用运行中的 AgentBay 云浏览器，并通过远程 CDP 接入。',
|
|
1022
1023
|
inputSchema: {
|
|
1023
1024
|
type: 'object',
|
|
1024
1025
|
properties: {
|
|
@@ -1032,6 +1033,12 @@ async function main() {
|
|
|
1032
1033
|
description: '浏览器提供方，默认 local；agentbay 需要配置 AGENTBAY_KEY',
|
|
1033
1034
|
default: 'local',
|
|
1034
1035
|
},
|
|
1036
|
+
reuse: {
|
|
1037
|
+
type: 'string',
|
|
1038
|
+
enum: ['never', 'prefer', 'require'],
|
|
1039
|
+
description: 'AgentBay 运行实例复用策略：never 默认不复用；prefer 存在则复用、否则创建；require 只复用、不创建。复用时可通过 copyCookieDomains 热更新 Cookie。',
|
|
1040
|
+
default: 'never',
|
|
1041
|
+
},
|
|
1035
1042
|
imageId: {
|
|
1036
1043
|
type: 'string',
|
|
1037
1044
|
description: 'AgentBay 镜像别名或具体镜像 ID；仅 provider=agentbay 有效，默认使用已验证的 Linux Browser Use 内网镜像',
|
|
@@ -1082,7 +1089,7 @@ async function main() {
|
|
|
1082
1089
|
copyCookieDomains: {
|
|
1083
1090
|
type: 'array',
|
|
1084
1091
|
items: { type: 'string' },
|
|
1085
|
-
description: '
|
|
1092
|
+
description: '从控制浏览器复制到本地新实例或 AgentBay 新建/复用实例的 Cookie 域名列表。保留 HttpOnly/Secure/SameSite/过期时间等属性；非内置域需先授权。Cookie 在打开 URL 前写入；本地 provider 可继续执行 TDBank SSO。',
|
|
1086
1093
|
},
|
|
1087
1094
|
},
|
|
1088
1095
|
required: ['name'],
|
|
@@ -1286,6 +1293,57 @@ async function main() {
|
|
|
1286
1293
|
required: ['tabId'],
|
|
1287
1294
|
},
|
|
1288
1295
|
},
|
|
1296
|
+
{
|
|
1297
|
+
name: 'browser_page_drag',
|
|
1298
|
+
description: '在页面内执行连续可信拖动，并默认内置观察与原子诊断，返回 { action, observation, diagnostics }。from/to 均可传原生 CSS、"@eN" snapshot ref 或 {x,y} 视口坐标；选择器端点需要同时位于当前视口。dragMode 默认 auto：移动模拟页使用 touch，其余使用 mouse；内部按 durationMs 分段派发按下、移动和松开事件，不使用不可靠的 DOM 合成拖拽。适合轮播图滑动、滑块、画布手势和拖放。',
|
|
1299
|
+
inputSchema: {
|
|
1300
|
+
type: 'object',
|
|
1301
|
+
properties: {
|
|
1302
|
+
tabId: {
|
|
1303
|
+
type: 'number',
|
|
1304
|
+
description: '目标标签页 ID（从 browser_tab_open 或 browser_tab_list 获取）',
|
|
1305
|
+
},
|
|
1306
|
+
from: {
|
|
1307
|
+
description: '拖动起点：CSS/@eN selector，或 {x,y} 视口坐标（CSS 像素）',
|
|
1308
|
+
anyOf: [
|
|
1309
|
+
{ type: 'string' },
|
|
1310
|
+
{
|
|
1311
|
+
type: 'object',
|
|
1312
|
+
properties: { x: { type: 'number' }, y: { type: 'number' } },
|
|
1313
|
+
required: ['x', 'y'],
|
|
1314
|
+
},
|
|
1315
|
+
],
|
|
1316
|
+
},
|
|
1317
|
+
to: {
|
|
1318
|
+
description: '拖动终点：CSS/@eN selector，或 {x,y} 视口坐标（CSS 像素）',
|
|
1319
|
+
anyOf: [
|
|
1320
|
+
{ type: 'string' },
|
|
1321
|
+
{
|
|
1322
|
+
type: 'object',
|
|
1323
|
+
properties: { x: { type: 'number' }, y: { type: 'number' } },
|
|
1324
|
+
required: ['x', 'y'],
|
|
1325
|
+
},
|
|
1326
|
+
],
|
|
1327
|
+
},
|
|
1328
|
+
dragMode: {
|
|
1329
|
+
type: 'string',
|
|
1330
|
+
enum: ['auto', 'mouse', 'touch'],
|
|
1331
|
+
description: '输入类型；auto 按设备模拟状态选择 touch 或 mouse',
|
|
1332
|
+
default: 'auto',
|
|
1333
|
+
},
|
|
1334
|
+
durationMs: {
|
|
1335
|
+
type: 'number',
|
|
1336
|
+
minimum: 0,
|
|
1337
|
+
maximum: 5000,
|
|
1338
|
+
description: '拖动持续时间（毫秒），默认 400；内部自动分段移动',
|
|
1339
|
+
default: 400,
|
|
1340
|
+
},
|
|
1341
|
+
observe: OBSERVE_INPUT_SCHEMA,
|
|
1342
|
+
diagnostics: DIAGNOSTICS_INPUT_SCHEMA,
|
|
1343
|
+
},
|
|
1344
|
+
required: ['tabId', 'from', 'to'],
|
|
1345
|
+
},
|
|
1346
|
+
},
|
|
1289
1347
|
{
|
|
1290
1348
|
name: 'browser_page_type',
|
|
1291
1349
|
description: '向输入框填写文本，默认内置观察与原子诊断（校验提示、error logs、业务 requests 等），返回 { action, observation, diagnostics }；传 observe:false 只关闭观察并保留诊断，同时传 diagnostics:false 才执行裸输入。兼容 React 等框架的受控组件，会自动触发 input 和 change 事件。selector 支持原生 CSS 或 "@eN" snapshot ref。',
|
|
@@ -1941,6 +1999,19 @@ async function main() {
|
|
|
1941
1999
|
});
|
|
1942
2000
|
break;
|
|
1943
2001
|
}
|
|
2002
|
+
case 'browser_page_drag': {
|
|
2003
|
+
const { tabId, from, to, dragMode, durationMs, observe, diagnostics } = args;
|
|
2004
|
+
result = await client.pageDrag({
|
|
2005
|
+
tabId,
|
|
2006
|
+
from,
|
|
2007
|
+
to,
|
|
2008
|
+
dragMode,
|
|
2009
|
+
durationMs,
|
|
2010
|
+
observe,
|
|
2011
|
+
diagnostics,
|
|
2012
|
+
});
|
|
2013
|
+
break;
|
|
2014
|
+
}
|
|
1944
2015
|
case 'browser_page_type': {
|
|
1945
2016
|
const { tabId, selector, text, clearFirst = true, observe, diagnostics } = args;
|
|
1946
2017
|
result = await client.pageType({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mearl/mcp-server",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.7.0",
|
|
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",
|
|
@@ -30,8 +30,8 @@
|
|
|
30
30
|
"dependencies": {
|
|
31
31
|
"@modelcontextprotocol/sdk": "^1.0.4",
|
|
32
32
|
"prompts": "^2.4.2",
|
|
33
|
-
"@mearl/client": "2.
|
|
34
|
-
"@mearl/native-host": "2.
|
|
33
|
+
"@mearl/client": "2.7.0",
|
|
34
|
+
"@mearl/native-host": "2.7.0"
|
|
35
35
|
},
|
|
36
36
|
"devDependencies": {
|
|
37
37
|
"@types/node": "^24.9.1",
|