@pyrokine/mcp-chrome 2.4.1 → 3.0.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 +546 -192
- package/README_zh.md +490 -192
- package/dist/anti-detection/behavior.js +1 -1
- package/dist/anti-detection/behavior.js.map +1 -1
- package/dist/anti-detection/injection.d.ts.map +1 -1
- package/dist/anti-detection/injection.js +5 -4
- package/dist/anti-detection/injection.js.map +1 -1
- package/dist/cdp/client.d.ts +2 -2
- package/dist/cdp/client.d.ts.map +1 -1
- package/dist/cdp/client.js +24 -10
- package/dist/cdp/client.js.map +1 -1
- package/dist/cdp/launcher.d.ts +2 -3
- package/dist/cdp/launcher.d.ts.map +1 -1
- package/dist/cdp/launcher.js +84 -24
- package/dist/cdp/launcher.js.map +1 -1
- package/dist/core/auto-wait.d.ts +3 -3
- package/dist/core/auto-wait.d.ts.map +1 -1
- package/dist/core/auto-wait.js +45 -20
- package/dist/core/auto-wait.js.map +1 -1
- package/dist/core/browser-driver.d.ts +104 -14
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js +1 -0
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/errors.d.ts +25 -0
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +93 -1
- package/dist/core/errors.js.map +1 -1
- package/dist/core/locator.d.ts.map +1 -1
- package/dist/core/locator.js +6 -4
- package/dist/core/locator.js.map +1 -1
- package/dist/core/os-mouse.d.ts +78 -0
- package/dist/core/os-mouse.d.ts.map +1 -0
- package/dist/core/os-mouse.js +378 -0
- package/dist/core/os-mouse.js.map +1 -0
- package/dist/core/session.d.ts +46 -21
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +724 -175
- package/dist/core/session.js.map +1 -1
- package/dist/core/types.d.ts +12 -0
- package/dist/core/types.d.ts.map +1 -1
- package/dist/core/types.js +2 -0
- package/dist/core/types.js.map +1 -1
- package/dist/core/unified-session.d.ts +117 -21
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +619 -129
- package/dist/core/unified-session.js.map +1 -1
- package/dist/core/utils.d.ts +5 -0
- package/dist/core/utils.d.ts.map +1 -1
- package/dist/core/utils.js +475 -54
- package/dist/core/utils.js.map +1 -1
- package/dist/extension/bridge.d.ts +61 -35
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +290 -106
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts +3 -0
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +25 -3
- package/dist/extension/http-server.js.map +1 -1
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -1
- package/dist/tools/browse.d.ts +1 -1
- package/dist/tools/browse.d.ts.map +1 -1
- package/dist/tools/browse.js +291 -175
- package/dist/tools/browse.js.map +1 -1
- package/dist/tools/challenge.d.ts +153 -0
- package/dist/tools/challenge.d.ts.map +1 -0
- package/dist/tools/challenge.js +611 -0
- package/dist/tools/challenge.js.map +1 -0
- package/dist/tools/cookies.d.ts.map +1 -1
- package/dist/tools/cookies.js +13 -7
- package/dist/tools/cookies.js.map +1 -1
- package/dist/tools/diagnostics.d.ts +5 -5
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +39 -20
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +106 -23
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +199 -208
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts +1 -1
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +523 -175
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/logs.d.ts.map +1 -1
- package/dist/tools/logs.js +7 -7
- package/dist/tools/logs.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +400 -64
- package/dist/tools/manage.js.map +1 -1
- package/dist/tools/network-sanitizer.d.ts.map +1 -1
- package/dist/tools/network-sanitizer.js +1 -0
- package/dist/tools/network-sanitizer.js.map +1 -1
- package/dist/tools/page-context.d.ts +17 -0
- package/dist/tools/page-context.d.ts.map +1 -0
- package/dist/tools/page-context.js +103 -0
- package/dist/tools/page-context.js.map +1 -0
- package/dist/tools/png.d.ts +5 -0
- package/dist/tools/png.d.ts.map +1 -1
- package/dist/tools/png.js +89 -22
- package/dist/tools/png.js.map +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +17 -5
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/schema.d.ts +9 -0
- package/dist/tools/schema.d.ts.map +1 -1
- package/dist/tools/schema.js +15 -0
- package/dist/tools/schema.js.map +1 -1
- package/dist/tools/target-diagnostics.d.ts +7 -0
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +47 -17
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +52 -56
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/content.ts-C4imZ6A9.js +13 -0
- package/extension/dist/assets/content.ts-loader-CnJuCGhl.js +13 -0
- package/extension/dist/assets/{index.ts-GG6dPUPX.js → index.ts-GeHNZBml.js} +2156 -1950
- package/extension/dist/assets/page-scripts-CMIY1zhd.js +1379 -0
- package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-CgtWL6Py.js} +48 -1
- package/extension/dist/manifest.json +4 -3
- package/extension/dist/service-worker-loader.js +1 -1
- package/extension/dist/src/popup/popup.html +54 -44
- package/package.json +11 -8
- package/scripts/start-chrome.ps1 +58 -0
- package/dist/extension/native-host-installer.d.ts +0 -21
- package/dist/extension/native-host-installer.d.ts.map +0 -1
- package/dist/extension/native-host-installer.js +0 -147
- package/dist/extension/native-host-installer.js.map +0 -1
- package/dist/extension/socket-server.d.ts +0 -32
- package/dist/extension/socket-server.d.ts.map +0 -1
- package/dist/extension/socket-server.js +0 -177
- package/dist/extension/socket-server.js.map +0 -1
- package/dist/extension/ws-server.d.ts +0 -40
- package/dist/extension/ws-server.d.ts.map +0 -1
- package/dist/extension/ws-server.js +0 -246
- package/dist/extension/ws-server.js.map +0 -1
- package/dist/native-host/index.js +0 -280
- package/dist/native-host/mcp-chrome-host +0 -2
- package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
package/README_zh.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.md) | 中文
|
|
4
4
|
|
|
5
|
-
Chrome 浏览器自动化 MCP Server
|
|
5
|
+
Chrome 浏览器自动化 MCP Server,双模式架构: **Extension 模式**(推荐)操控现有浏览器, **CDP 模式**(回退)启动独立实例
|
|
6
6
|
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
[](https://nodejs.org/)
|
|
@@ -12,7 +12,7 @@ Chrome 浏览器自动化 MCP Server,双模式架构:**Extension 模式**(
|
|
|
12
12
|
|
|
13
13
|
- **双模式**:Extension 模式共享登录状态;CDP 模式用于无头/隔离场景
|
|
14
14
|
- **8 个统一工具**:基于 action 的设计,覆盖浏览、输入、提取、等待、执行、管理、Cookie、日志
|
|
15
|
-
-
|
|
15
|
+
- **多页面定位**:`targetId` 在两种 backend 中指定操作页面,无需切换浏览器焦点;`tabId` 保留为兼容别名
|
|
16
16
|
- **iframe 穿透**:`frame` 参数支持操作 iframe 内元素(CSS 选择器或索引,Extension 模式)
|
|
17
17
|
- **语义化定位**:11 种元素定位方式(role、text、label、css、css+文本组合、xpath、坐标等)
|
|
18
18
|
- **自动等待**:内置可点击性、可输入性检测,基于 deadline 的超时预算机制
|
|
@@ -22,15 +22,26 @@ Chrome 浏览器自动化 MCP Server,双模式架构:**Extension 模式**(
|
|
|
22
22
|
- **反检测**:可选的指纹伪装和行为模拟
|
|
23
23
|
- **结构化错误**:每个错误包含 code、message、suggestion、context
|
|
24
24
|
|
|
25
|
+
## 迁移到 3.0
|
|
26
|
+
|
|
27
|
+
- `manage(action="closePage")` 必须显式传入 `targetId`,不再关闭缺省页面
|
|
28
|
+
- Extension 模式显式 `adoptPage`
|
|
29
|
+
后,已有页面获得与新建受控页相同的读取、输入、脚本、截图、debugger 和日志能力,受控页面无需 popup 普通只读授权
|
|
30
|
+
- 单页普通读取授权覆盖 text、HTML、attribute、computed
|
|
31
|
+
style 与 state,不开放任意 JavaScript、CDP/debugger、input 或 screenshot
|
|
32
|
+
- `tmp:` 文件只属于当前 MCP server 会话;重启后需重新生成,需保留的文件应在服务器退出前保存到 `cwd:`
|
|
33
|
+
|
|
34
|
+
本地零配置自动连接保持不变,刷新 Extension 或重启 MCP client 后不需要手动点击“连接”
|
|
35
|
+
|
|
25
36
|
## 兼容客户端
|
|
26
37
|
|
|
27
|
-
| 客户端
|
|
28
|
-
|
|
29
|
-
| Claude Code
|
|
30
|
-
| Claude Desktop
|
|
31
|
-
| Cursor
|
|
32
|
-
| Windsurf
|
|
33
|
-
| 其他 MCP 兼容客户端
|
|
38
|
+
| 客户端 | 状态 |
|
|
39
|
+
| ------------------- | ---- |
|
|
40
|
+
| Claude Code | ✅ |
|
|
41
|
+
| Claude Desktop | ✅ |
|
|
42
|
+
| Cursor | ✅ |
|
|
43
|
+
| Windsurf | ✅ |
|
|
44
|
+
| 其他 MCP 兼容客户端 | ✅ |
|
|
34
45
|
|
|
35
46
|
## 安装
|
|
36
47
|
|
|
@@ -44,7 +55,8 @@ claude mcp add chrome -- mcp-chrome
|
|
|
44
55
|
npm root -g
|
|
45
56
|
```
|
|
46
57
|
|
|
47
|
-
Extension 模式需要打开 `chrome://extensions/`,启用开发者模式,点击“加载已解压的扩展程序”,选择
|
|
58
|
+
Extension 模式需要打开 `chrome://extensions/`,启用开发者模式,点击“加载已解压的扩展程序”,选择
|
|
59
|
+
`<npm-root>/@pyrokine/mcp-chrome/extension/dist`。
|
|
48
60
|
|
|
49
61
|
### 从源码安装
|
|
50
62
|
|
|
@@ -60,6 +72,20 @@ claude mcp add chrome -- node "$PWD/dist/index.js"
|
|
|
60
72
|
|
|
61
73
|
Extension 模式需要在 Chrome 中加载 `extension/dist`。
|
|
62
74
|
|
|
75
|
+
### Windows CDP 启动
|
|
76
|
+
|
|
77
|
+
Chrome 自动查找 Windows App Paths、`PATH`、已安装的 Chrome channels、Chromium、Chrome for Testing,以及
|
|
78
|
+
`MCP_CHROME_PORTABLE_DIR` 或 `%USERPROFILE%\\.mcp-chrome\\portable`,也可以在 PowerShell 中启动独立的 CDP 浏览器:
|
|
79
|
+
|
|
80
|
+
```powershell
|
|
81
|
+
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
|
|
82
|
+
# 也可显式指定便携版可执行文件和独立 profile:
|
|
83
|
+
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 -ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
随后调用
|
|
87
|
+
`browse(action="connect", port=9222)`。脚本让 Chrome 进程保持前台运行,并报告退出码;使用独立 profile,避免请求被已有 Chrome 实例接管。
|
|
88
|
+
|
|
63
89
|
## 快速开始
|
|
64
90
|
|
|
65
91
|
### 模式一:Extension 模式(推荐)
|
|
@@ -87,20 +113,22 @@ Claude Desktop / 其他客户端:
|
|
|
87
113
|
|
|
88
114
|
```json
|
|
89
115
|
{
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
]
|
|
116
|
+
"mcpServers": {
|
|
117
|
+
"chrome": {
|
|
118
|
+
"command": "node",
|
|
119
|
+
"args": ["/path/to/mcp-chrome/dist/index.js"]
|
|
120
|
+
}
|
|
96
121
|
}
|
|
97
|
-
}
|
|
98
122
|
}
|
|
99
123
|
```
|
|
100
124
|
|
|
101
125
|
**第三步:连接**
|
|
102
126
|
|
|
103
|
-
Extension 通过 HTTP/WebSocket 自动连接 MCP Server(端口 19222-19299
|
|
127
|
+
Extension 通过 HTTP/WebSocket 自动连接 MCP Server(端口 19222-19299),点击工具栏图标可查看连接状态,
|
|
128
|
+
`browse(action="connect")` 和本地 `/api/info`
|
|
129
|
+
会返回当前活动 Extension 后台 bundle 的 hash,并与 server 附带的 bundle 比较, `bundleStatus="stale"`
|
|
130
|
+
表示 Chrome 仍在执行旧的已解压 Extension,需要在 `chrome://extensions/` 刷新该 Extension。旧版 Extension 缺少
|
|
131
|
+
`network_challenge_state` 时会回退为 tab 标题和 DOM 的 Challenge 检测,bundle identity 不会关闭零配置自动连接,
|
|
104
132
|
|
|
105
133
|
```
|
|
106
134
|
browse(action="list") // 列出所有 Tab
|
|
@@ -110,13 +138,16 @@ extract(type="screenshot")
|
|
|
110
138
|
|
|
111
139
|
**配对 token**
|
|
112
140
|
|
|
113
|
-
Extension 模式默认保留零配置本地自动连接,在多用户机器、CI runner、或不可信本地进程可访问 `127.0.0.1:19222-19299`
|
|
141
|
+
Extension 模式默认保留零配置本地自动连接,在多用户机器、CI runner、或不可信本地进程可访问 `127.0.0.1:19222-19299`
|
|
142
|
+
的容器环境中,启动 MCP server 时设置 `MCP_CHROME_PAIRING_TOKEN`,再在 Extension popup 中输入同一个 token:
|
|
114
143
|
|
|
115
144
|
```bash
|
|
116
145
|
MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
|
|
117
146
|
```
|
|
118
147
|
|
|
119
|
-
需要强制配对 token 时,在 server 设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,并在 Extension
|
|
148
|
+
需要强制配对 token 时,在 server 设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`,并在 Extension
|
|
149
|
+
popup 关闭“允许无 token 本地连接”。关闭后会立即取消进行中的 health
|
|
150
|
+
check、WebSocket 握手和已安排的重连,旧的无 token 连接尝试不会在策略更新后重新连入,
|
|
120
151
|
|
|
121
152
|
### 模式二:CDP 模式(回退)
|
|
122
153
|
|
|
@@ -132,171 +163,389 @@ browse(action="connect", port=9222)
|
|
|
132
163
|
browse(action="open", url="https://example.com")
|
|
133
164
|
```
|
|
134
165
|
|
|
135
|
-
>
|
|
166
|
+
> 已连接的 Extension 是所有工具的默认模式,Extension 不可用时才回退到 CDP。`browse(action="connect", port=9222)`
|
|
167
|
+
> 会为后续工具显式选择 CDP;调用不带 port 的 `browse(action="connect")`
|
|
168
|
+
> 会回到 Extension。仅因回退而建立的 CDP 连接会在 Extension 重连后让出默认模式,
|
|
136
169
|
|
|
137
170
|
## 可用工具(8 个)
|
|
138
171
|
|
|
139
172
|
### browse - 浏览器管理与导航
|
|
140
173
|
|
|
141
|
-
| Action | 描述
|
|
142
|
-
|
|
143
|
-
| `launch` |
|
|
144
|
-
| `connect` |
|
|
145
|
-
| `list` | 列出所有页面/Tab
|
|
146
|
-
| `attach` | 附加到指定页面/Tab
|
|
147
|
-
| `open` | 导航到 URL
|
|
148
|
-
| `back` | 后退
|
|
149
|
-
| `forward` | 前进
|
|
150
|
-
| `refresh` | 刷新
|
|
151
|
-
| `close` |
|
|
152
|
-
|
|
153
|
-
Extension 特有:`list` 返回 flat `targets` 数组和树状 `windows`,每个 target 含 `managed`(Tab 是否由 MCP
|
|
154
|
-
|
|
155
|
-
`
|
|
156
|
-
|
|
174
|
+
| Action | 描述 |
|
|
175
|
+
| --------- | -------------------------------------------- |
|
|
176
|
+
| `launch` | Extension 可用时创建受控 Tab,否则启动 CDP |
|
|
177
|
+
| `connect` | 默认确认 Extension,传 `port` 时显式选择 CDP |
|
|
178
|
+
| `list` | 列出所有页面/Tab |
|
|
179
|
+
| `attach` | 附加到指定页面/Tab |
|
|
180
|
+
| `open` | 导航到 URL |
|
|
181
|
+
| `back` | 后退 |
|
|
182
|
+
| `forward` | 前进 |
|
|
183
|
+
| `refresh` | 刷新 |
|
|
184
|
+
| `close` | 关闭 `targetId` 指定的页面 |
|
|
185
|
+
|
|
186
|
+
Extension 特有:`list` 返回 flat `targets` 数组和树状 `windows`,每个 target 含 `managed`(Tab 是否由 MCP
|
|
187
|
+
Chrome 受控)、`isActive`(该窗口中 Chrome 的活动 Tab)、`windowId`、`index`、`pinned`、`incognito`、`status`(`loading`/`complete`),树状结构含
|
|
188
|
+
`windowCount`、`focusedWindowId`、`activeTargetId` 和每个窗口按顺序排列的 `tabs`。`defaultTargetId`
|
|
189
|
+
是默认操作目标,CDP 不用选中的操作目标推断浏览器前台页面,`open`
|
|
157
190
|
自动创建 Tab 分组(cyan 色),`open`、`back`、`forward`、`refresh` 支持 `diagnostics=true`,返回动作期间新增的 console
|
|
158
|
-
warning/error 和失败网络请求摘要,也覆盖首次 `open`
|
|
191
|
+
warning/error 和失败网络请求摘要,也覆盖首次 `open` 自动创建页面的场景。两个 driver 的 `open` 和 `refresh` 都支持
|
|
192
|
+
`wait="load"`、`wait="domcontentloaded"` 和
|
|
193
|
+
`wait="networkidle"`。等待器会在命令前建立,并绑定命令产生的新主文档,上一导航的迟到生命周期事件不会提前完成等待。CDP模式的
|
|
194
|
+
`networkidle` 等待当前主 frame loader 的 `networkIdle`
|
|
195
|
+
事件;Extension 模式会等待当前文档完成、所有已跟踪响应 body 结束和 500
|
|
196
|
+
ms 静默窗口。请求跟踪发生丢失时返回超时,不会误报空闲。`close` 必须传
|
|
197
|
+
`targetId`,且只关闭该页面,不会关闭整个 CDP 连接,
|
|
198
|
+
|
|
199
|
+
Extension 模式的 `back/forward`
|
|
200
|
+
优先使用浏览器原生历史,只有原生 API 明确报告无历史时才允许尝试页面脚本;受限 URL 和浏览器错误页不注入没有可用历史时返回
|
|
201
|
+
`navigated=false`,其他原生错误保留;execution
|
|
202
|
+
context 失效或浏览器拒绝向错误页注入时,仍返回操作失败,Extension 将其记录为预期操作警告;任意 debugger 命令不自动重放
|
|
203
|
+
|
|
204
|
+
`open`、`back`、`forward`、`refresh` 的 `timeout`
|
|
205
|
+
从请求入口开始计时,页面准备、排队、协议请求、加载、Challenge 检查与点击、诊断和目标恢复共用剩余预算,导航 RPC 不额外增加传输时间队列中的动作到期后不再派发,后续请求仍等待原在途动作结束;显式
|
|
206
|
+
`timeout=0` 在导航派发前拒绝,页面创建保留独立的加载等待与传输余量合同
|
|
207
|
+
|
|
208
|
+
超时不会撤回已经派发的 Chrome 操作,结果未知时返回 `TIMEOUT`、`actionExecuted="unknown"`、`actionStatus="unknown"` 和
|
|
209
|
+
`retryable=false`,应读取实际页面状态,不重放导航 `pageContext.after` 使用实时快照,无法取得时为 null 并附
|
|
210
|
+
`contextError`;恢复预算耗尽时单独报告恢复失败,保留主动作结果 CDP 历史等待接受当前 session 主 frame 的 BFCache 恢复或同文档事件,普通 frame
|
|
211
|
+
commit、子 frame 和其他 session 的事件不作为完成信号
|
|
212
|
+
|
|
213
|
+
Challenge 点击、detach 和检查 RPC 携带剩余 deadline,排队或页面校验耗尽预算后不再派发;系统鼠标移动与 fallback 进程使用同一 deadline
|
|
214
|
+
CDP 已开始的按下始终尝试向原连接、原 session 释放,清理最多等待 1 秒,不向后来选择的目标发送只读 Challenge 检查到期返回
|
|
215
|
+
`CHALLENGE_TIMEOUT`,保留已知主动作状态;点击结果未知时返回 `TIMEOUT`、已知主动作状态、
|
|
216
|
+
`verificationStatus="unknown"`、`verificationActionExecuted` 和 `retryable=false`,不自动重放导航或点击
|
|
217
|
+
|
|
218
|
+
evaluate 在成功、动作失败、后置验证不匹配和输出失败时保留 Challenge 结果字段 `originResponsePending=true`
|
|
219
|
+
表示验证成功但源站尚未响应,不表示目标内容已加载
|
|
220
|
+
|
|
221
|
+
页面类工具在两种 backend 中都接受 `targetId`,旧版 `tabId`
|
|
222
|
+
仍可用;同时提供时两者必须一致。显式目标只作用于当前操作,结束后恢复原默认目标。`browse.close` 和 `manage.closePage`
|
|
223
|
+
必须显式指定 ID。页面动作成功或失败时,响应中的 `pageContext`
|
|
224
|
+
包含实际目标及来源(`explicit`、`default`、`created`、`reused`、`unconfirmed`)、前后 URL/revision、默认目标前后状态,以及 Extension 报告的浏览器活动目标;创建页面失败且未返回创建 ID 时标为
|
|
225
|
+
`unconfirmed`。CDP 的活动状态标为不可用,不把操作目标当作前台页面
|
|
226
|
+
|
|
227
|
+
旧 Extension 缺少 `page_snapshot` 时,无条件页面动作仍可使用实时页面列表中的 URL,`pageContext.before` 和 `after`
|
|
228
|
+
的快照返回 `revision=null`,并通过 `warning` 说明 revision 与原子条件不可用,传入 `expectedUrl` 或 `expectedRevision`
|
|
229
|
+
时在派发前返回 `DRIVER_CAPABILITY_ERROR`、`actionExecuted=false` 和
|
|
230
|
+
`actionStatus="not_started"`,更新 Extension 后才能使用这些条件 evaluate 和 input 保留
|
|
231
|
+
`failureStage="precondition"`,顶层状态与错误上下文一致,不派发脚本或输入事件其他快照错误仍阻止动作,兼容读取共用原 timeout 预算
|
|
232
|
+
|
|
233
|
+
Extension 页面快照确认目标 tab 已不存在时返回 `TARGET_NOT_FOUND`,保留 `context.targetId` 和原始
|
|
234
|
+
`context.nativeMessage`;输入派发前被拒绝时保留
|
|
235
|
+
`eventsExecuted=0`、`actionExecuted=false`,不改用其他页面或重放动作,用户脚本主动抛出同文案不归类为缺页
|
|
236
|
+
|
|
237
|
+
Chrome 已返回创建标识后,失败响应保留 `error.context.createdTargetId`、窗口 ID、实际 `managed`、`actionExecuted`、
|
|
238
|
+
`actionStatus="partial"` 和 `failureStage`;RPC 结果未知时,`actionStatus` 与 `actionExecuted` 均为 `"unknown"`
|
|
239
|
+
未取得创建标识的失败响应中 `pageContext.targetId=null`,不指向原默认页,不自动重复创建或删除
|
|
240
|
+
|
|
241
|
+
临时目标的恢复结果通过 `pageContext.targetRestoration` 单独报告,`restored` 表示恢复原默认目标,`cleared`
|
|
242
|
+
表示原先无默认目标并清除临时选择,`previous_target_closed` 表示原默认页已关闭并清除选择,`failed`
|
|
243
|
+
表示恢复或清理失败并清除临时选择;`error` 与 `cleanupError` 分别保存对应错误信息
|
|
244
|
+
|
|
245
|
+
主动作结果或原错误保留,已完成的输入不会重放,也不会报为未执行;`browse attach` 与 `manage adoptPage`
|
|
246
|
+
继续持久选择默认目标,并发响应记录各自实际操作的页面
|
|
247
|
+
|
|
248
|
+
`browse.list` 返回各页面的 revision 和元数据。revision 由 backend
|
|
249
|
+
epoch 与单页计数构成;Extension 跟踪主 frame 导航和 MCP 动作,CDP 跟踪已附加页面的导航,并保守计入发出的变更命令,包括 evaluate。网页自身的任意 DOM 更改不在跟踪范围内,条件动作前应重新获取 URL/revision。`browse`
|
|
250
|
+
导航/关闭、`input`、`evaluate` 及适用的 `manage` 页面动作接受 `expectedUrl` 和
|
|
251
|
+
`expectedRevision`;backend 检查不符时返回
|
|
252
|
+
`ACTION_PRECONDITION_FAILED`,不发送对应页面动作,复合动作在首个变更命令前检查,不在每个事件前重复检查;失败或超时后如已产生部分效果,revision 仍可能变化
|
|
253
|
+
|
|
254
|
+
`browse` 仅 `open`、`back`、`forward`、`refresh`、`close` 接受这两个条件,`attach` 等其他动作在改变目标前返回
|
|
255
|
+
`INVALID_ARGUMENT`
|
|
256
|
+
|
|
257
|
+
显式 `manage(action="adoptPage", targetId=...)` 将已有页面设为完整受控页,不聚焦或导航,`browse attach`
|
|
258
|
+
只选择目标;创建来源、分组归属和颜色不决定页面权限,`releasePage`
|
|
259
|
+
撤销完整权限,保留页面、窗口归属和分组,清理 MCP 日志状态、debugger 和 console 采集资源;Chrome 阻止资源清理时返回
|
|
260
|
+
`warnings`,完整权限仍被撤销
|
|
261
|
+
|
|
262
|
+
受控页在 Service Worker 重启后可继续使用本 Extension 已有的调试连接,其他调试器占用仍返回 `DEBUGGER_BLOCKED`
|
|
263
|
+
|
|
264
|
+
通过 `manage(action="grantReadAccess", targetId=...)` 授予普通读取权限,用 `revokeReadAccess`
|
|
265
|
+
撤销,无需点击 popup;两个动作必须显式指定目标,可传
|
|
266
|
+
`expectedUrl`/`expectedRevision`;授权限定当前调用服务器实例、documentId、URL 和 revision,存储失败返回错误,不报告授权成功;popup 保留为可选入口,同一连接和文档未变化时,Service
|
|
267
|
+
Worker 重启后仍可读取;导航、关闭页面或断开连接后授权失效,仅指定 `targetId`
|
|
268
|
+
不授予读取权限;普通只读授权覆盖定向文本、HTML、属性、计算样式及页面状态读取,任意脚本、debugger、截图、输入和 Cookie 访问不继承授权,现有 Cookie 工具仍按独立的 URL/name 过滤规则执行
|
|
269
|
+
|
|
270
|
+
页面管理或导航因缺少受控权限而被拒绝时,不更新 revision,已有有效的普通只读授权保持不变
|
|
271
|
+
|
|
272
|
+
`manage(action="pageMetadata", targetId=...)` 可以读取或更新
|
|
273
|
+
`taskHint`、`note`,列表还会显示创建与最近使用时间;读取和更新都支持 `expectedUrl`/`expectedRevision`,不匹配时返回
|
|
274
|
+
`ACTION_PRECONDITION_FAILED`,不读取或更新备注;这些元数据只在服务器进程中保存,关闭页面时删除,不参与内容读取授权
|
|
275
|
+
|
|
276
|
+
### 访问验证
|
|
277
|
+
|
|
278
|
+
`open`、`back`、`forward`、`refresh`、`input` 和 `evaluate` 之后,MCP Chrome 会等待 Cloudflare JS Challenge 或 Turnstile
|
|
279
|
+
checkbox。Extension 模式下,导航先不启用 debugger 日志采集,连续八秒被动读取真实 tab 标题。interstitial 持续存在时,才检查可见 Turnstile 控件,找到后才点击。Extension
|
|
280
|
+
inspect 走 isolated world,检查前先卸掉 debugger。同页测试按钮走页面点击;出现 Cloudflare Turnstile
|
|
281
|
+
iframe 时,把 inspect 的 CSS 坐标换成屏幕坐标,系统鼠标沿路径移动、悬停后再按下抬起:Linux 用 `xdotool` 读取活动 Chrome
|
|
282
|
+
client 窗口几何,用 `xprop` 读取 GTK frame
|
|
283
|
+
extents,窗口标题必须对应该测试页缺少工具、窗口数据无效或与页面视口不符时停止点击,不用 Chrome `screenX` 或
|
|
284
|
+
`outerHeight - innerHeight` 猜测内容原点;macOS 用 `cliclick` 或 System Events;Windows 用 PowerShell
|
|
285
|
+
`mouse_event`。widget 点 compact
|
|
286
|
+
Turnstile 卡片左侧 checkbox,宿主 wrapper 比卡片宽时也只点左侧卡片,不点文案。DOM 里已有 Cloudflare
|
|
287
|
+
iframe 时,即使 iframe 尺寸为 0,也走系统鼠标,不改用页面点击,后续宿主页 `Verify you are human` / `请验证您是真人`
|
|
288
|
+
按钮同样走系统鼠标。系统鼠标只在受控测试页已经是已聚焦窗口的活动 tab 时使用,混合窗口不会调用 `focusWindow`。
|
|
289
|
+
|
|
290
|
+
系统点击前会卸掉 debugger,再读一次视口。缺少系统鼠标工具或窗口未聚焦时返回可见错误,不会静默改用 CDP 点击。
|
|
291
|
+
|
|
292
|
+
widget 要连续两次 inspect 到同一坐标才点,不以普通元素的尺寸认定 widget;系统鼠标从远处过来时从控件附近起步。同一类 checkbox 或 compact
|
|
293
|
+
widget 在同一次等待里最多点一次;Cloudflare 随后换成可见的 `Verify you are human` 或 `请验证您是真人`
|
|
294
|
+
按钮时,inspect 判成 `verify` 后再点一次。访问受 Cloudflare 保护的页面默认保持
|
|
295
|
+
`diagnostics=false`,因为 diagnostics 会启用 debugger 的 console 和 network 采集。
|
|
296
|
+
|
|
297
|
+
检测覆盖 `Just a moment...`、`请稍候…` 等标题、Challenge DOM、正文标记和 `Verify you are human` / `请验证您是真人`
|
|
298
|
+
控件,包括精确匹配这两种文案的可见 `button` 元素;没有 Cloudflare iframe 时,同页按钮使用页面点击 CDP 用
|
|
299
|
+
`Target.getTargetInfo` 读取实时标题。页面恢复后残留的 Cloudflare iframe 不算等待中,缓存标题不参与判定。不会调用 CAPTCHA
|
|
300
|
+
solver、不会自动重试导航,也不会导出 `cf_clearance`
|
|
301
|
+
的值。CDP 超时不代表网站在用户真实 Chrome 中无法通过,排查网站前先检查返回的 `mode`。
|
|
302
|
+
|
|
303
|
+
过盾成功时返回 `challengeResolved=true`、`challengeKind`、`waitedMs`、`clickedTurnstile` 和 `clearanceCookiePresent`
|
|
304
|
+
(只表示 cookie 名是否存在)。页面可见文案显示验证成功、正在等待源站时,响应还会含
|
|
305
|
+
`originResponsePending=true`,表示已过盾但目标页面尚未加载。隐藏的成功文案(例如 `display:none`
|
|
306
|
+
的标题)不算过盾,可见 Turnstile 勾选框仍视为等待中。Challenge 成功和失败响应都含 `mode`。超时返回 `CHALLENGE_TIMEOUT`
|
|
307
|
+
且 `retryable=true`,并带 `clickedTurnstile` 和实际观察到的 `challengeKind`(点过 Turnstile 时不会报成 `js`)。Access
|
|
308
|
+
denied 返回 `CHALLENGE_DENIED`。交互式验证码、Bot Fight
|
|
309
|
+
Mode 和 IP 声誉检查无法靠等待或点击 checkbox 完成。之后的正常主文档响应才会清掉 header 标记,普通 iframe 文档响应和清空网络日志都不会清掉它,
|
|
159
310
|
|
|
160
311
|
### input - 键鼠输入
|
|
161
312
|
|
|
162
313
|
事件序列模型,支持任意组合:
|
|
163
314
|
|
|
164
|
-
| 事件类型
|
|
165
|
-
|
|
166
|
-
| `keydown` / `keyup` | 按键按下/释放
|
|
167
|
-
| `click` | 点击(含可操作性检查:可见性、是否启用、遮挡检测、自动滚动)
|
|
168
|
-
| `mousedown` / `mouseup` | 鼠标按下/释放
|
|
169
|
-
| `mousemove` | 鼠标移动
|
|
170
|
-
| `wheel` | 滚轮滚动
|
|
171
|
-
| `touchstart` / `touchmove` / `touchend` | 触摸事件
|
|
172
|
-
| `type` | 输入文本
|
|
173
|
-
| `wait` | 事件间暂停
|
|
174
|
-
| `select` | 按内容选中文本(鼠标模拟)
|
|
175
|
-
| `replace` | 查找并替换文本
|
|
315
|
+
| 事件类型 | 描述 |
|
|
316
|
+
| --------------------------------------- | ------------------------------------------------------------- |
|
|
317
|
+
| `keydown` / `keyup` | 按键按下/释放 |
|
|
318
|
+
| `click` | 点击(含可操作性检查:可见性、是否启用、遮挡检测、自动滚动) |
|
|
319
|
+
| `mousedown` / `mouseup` | 鼠标按下/释放 |
|
|
320
|
+
| `mousemove` | 鼠标移动 |
|
|
321
|
+
| `wheel` | 滚轮滚动 |
|
|
322
|
+
| `touchstart` / `touchmove` / `touchend` | 触摸事件 |
|
|
323
|
+
| `type` | 输入文本 |
|
|
324
|
+
| `wait` | 事件间暂停 |
|
|
325
|
+
| `select` | 按内容选中文本(鼠标模拟) |
|
|
326
|
+
| `replace` | 查找并替换文本 |
|
|
176
327
|
| `drag` | HTML5 拖放(MAIN 世界 DragEvent,需 `target` 源 + `to` 目标) |
|
|
177
|
-
| `editorContext` | 读取当前编辑器和选区上下文
|
|
178
|
-
| `editorInsert` | 在当前编辑器选区插入文本
|
|
328
|
+
| `editorContext` | 读取当前编辑器和选区上下文 |
|
|
329
|
+
| `editorInsert` | 在当前编辑器选区插入文本 |
|
|
179
330
|
| `editorCommand` | 执行 `bold`、`insertOrderedList` 等浏览器编辑命令 |
|
|
180
331
|
|
|
181
|
-
|
|
182
|
-
`postCondition`
|
|
183
|
-
|
|
184
|
-
|
|
332
|
+
`events` 至少需要一个事件。参数:`humanize` 启用贝塞尔曲线移动和随机延迟,`diagnostics=true` 返回动作后新增 console
|
|
333
|
+
warning/error 和失败网络请求, `postCondition`
|
|
334
|
+
会在事件发送后等待页面状态,便于区分输入事件已发送和页面业务状态已完成,`postCondition.timeout` 默认 3000 ms、最大 60000
|
|
335
|
+
ms,`postCondition.interval` 默认 100 ms、范围 50-5000 ms。`postCondition.script` 可传表达式、函数、async
|
|
336
|
+
function 或 Promise 表达式;函数会被调用,最终 Promise 值会被等待后再判定,抛错或 reject 会让检查失败。`targetId`(或旧版
|
|
337
|
+
`tabId`)在两种 backend 中指定页面;`frame`
|
|
338
|
+
在 Extension 模式中指定 iframe(CSS 选择器或索引),传入任一作用域时,动作、诊断和 post-condition 使用该目标作用域选定的同一个 backend,
|
|
339
|
+
|
|
340
|
+
键盘 `type` 的 `timeout` 包含 Challenge 等待、焦点准备、字符输入和 `delay`/`humanize` 延迟,Extension
|
|
341
|
+
precise/stealth 与 CDP 使用本次剩余预算,显式预算如 `timeout=45000`
|
|
342
|
+
允许合法输入持续超过默认的 30000ms,到期后停止后续字符与事件;已派发的输入不能撤回,超时可能留下部分输入,响应为
|
|
343
|
+
`actionExecuted=true`、`actionStatus="unknown"` 和 `retryable=false` 时,应独立读取页面确认实际值,不重放整个事件序列
|
|
344
|
+
|
|
345
|
+
鼠标目标查找、分步移动和 `humanize`
|
|
346
|
+
延迟也共用 input 剩余预算,每次移动和后续点击前检查截止时间,到期后停止后续移动和点击;已派发的原生事件不能撤回,结果为 unknown 时独立读取页面,不重放操作
|
|
185
347
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
`
|
|
348
|
+
命令聚焦、文本选择和替换共用事件剩余预算,到期后停止后续动作;Shift 按下后仍尝试释放,释放失败不隐藏原动作错误,CDP 分步触摸移动到期后也停止后续触摸点与事件
|
|
349
|
+
|
|
350
|
+
Stealth 的 `delay` 只作用于字符之间,首字符不额外等待;后台页面受定时器节流时,后续间隔会延长,本次预算仍限制后续输入
|
|
351
|
+
|
|
352
|
+
Extension precise 与 CDP 的键盘输入使用当前光标和选区,提供 `target`
|
|
353
|
+
会先点击目标并改变插入位置,向 contenteditable 末尾追加时,先聚焦并将光标放到末尾,再发送不带 `target` 的
|
|
354
|
+
`type`,避免再次点击改变位置
|
|
355
|
+
|
|
356
|
+
后台 CDP 点击和键盘输入无需激活页面,仍检查元素是否可见、可用且位置和尺寸稳定,必要时滚动到视口;点击还会检查遮挡目标查找、可操作性检查和最终坐标读取共用事件剩余预算,任一阶段耗尽预算后不派发鼠标或键盘事件
|
|
357
|
+
|
|
358
|
+
**`click` 专属参数**:`force: true` 必须提供 `forceReason` 和非坐标型元素
|
|
359
|
+
`target`,它会跳过可操作性检查(适用于测试隐藏元素等场景),但仍只分发标准 DOM 鼠标事件序列,不会直接调用框架私有 handler 中键、右键和多击采用同一检查规则,坐标型或省略 target 的点击不能使用 force,可操作性失败返回
|
|
360
|
+
`ACTIONABILITY_FAILED`,包含 `rect`、`clickPoint`、遮挡元素、候选遮挡物和修复建议, **`type`
|
|
361
|
+
专属参数**:`mode="controlled"` 或 `dispatch: true` 直接设置 `.value` 并触发 `input`/`change`
|
|
362
|
+
事件,兼容 React/Vue 等框架的受控组件(键盘事件无法触发状态更新时使用),需要非坐标型
|
|
363
|
+
`target`,仅限 Extension 模式,受控输入和目标查找失败时返回结构化 context,包含
|
|
364
|
+
`locator`、`matchCount`、`nth`、有数量上限的 `candidates` 和不含输入值的 `activeElement`
|
|
365
|
+
摘要,焦点不可取得时返回 null,DOM 查询失败时还返回 `diagnosticError` 选区相关错误另含编辑器与选区状态,password
|
|
366
|
+
input 的 value 不进入失败诊断,失败响应也会脱敏 input 事件传入的 `find` 和替换 `text`,`select` 和 `replace` 的事件级
|
|
367
|
+
`nth` 表示文本第 N 次出现,嵌套的 `target.nth` 表示第 N 个目标元素,两者都从 0 开始并可同时使用,CDP 模式的 locator
|
|
368
|
+
target 不依赖 Extension refId,
|
|
193
369
|
|
|
194
370
|
**`keydown` 专属参数**:
|
|
195
371
|
|
|
196
|
-
- `commands`:触发浏览器原生编辑命令(如 `["selectAll"]`、`["copy"]`、`["paste"]`、`["cut"]`、`["undo"]`、`["redo"]
|
|
197
|
-
`postCondition` 或 `extract`
|
|
372
|
+
- `commands`:触发浏览器原生编辑命令(如 `["selectAll"]`、`["copy"]`、`["paste"]`、`["cut"]`、`["undo"]`、`["redo"]`
|
|
373
|
+
),成功表示浏览器已接受命令分发,页面结果需用 `postCondition` 或 `extract`
|
|
374
|
+
验证,仅 precise 模式可用,stealth 模式下抛错(CDP commands API 没有 JS 事件等价物)
|
|
198
375
|
- 连续 `keydown` 同一 key 自动切换为 `rawKeyDown` + `autoRepeat`,模拟长按重复(与 Puppeteer 一致)
|
|
199
376
|
|
|
200
377
|
### extract - 内容提取
|
|
201
378
|
|
|
202
|
-
| Type | 描述
|
|
203
|
-
|
|
204
|
-
| `text` | 提取文本内容
|
|
205
|
-
| `html` | 提取 HTML 源码
|
|
206
|
-
| `frameHtml` | 提取指定 iframe 的 HTML
|
|
207
|
-
| `attribute` | 提取元素属性
|
|
208
|
-
| `screenshot` | 截图(支持 `target` 元素裁剪)
|
|
209
|
-
| `state` | 获取页面状态(URL、标题、可交互元素)
|
|
379
|
+
| Type | 描述 |
|
|
380
|
+
| ------------ | -------------------------------------- |
|
|
381
|
+
| `text` | 提取文本内容 |
|
|
382
|
+
| `html` | 提取 HTML 源码 |
|
|
383
|
+
| `frameHtml` | 提取指定 iframe 的 HTML |
|
|
384
|
+
| `attribute` | 提取元素属性 |
|
|
385
|
+
| `screenshot` | 截图(支持 `target` 元素裁剪) |
|
|
386
|
+
| `state` | 获取页面状态(URL、标题、可交互元素) |
|
|
210
387
|
| `metadata` | 提取页面元信息(标题、OG、JSON-LD 等) |
|
|
211
388
|
|
|
389
|
+
文本提取对整页和所选 HTML 元素使用浏览器的 `innerText`,已渲染区域不包含后代 `style`/`script`
|
|
390
|
+
源码或隐藏后代文本;显式选择不可渲染的 HTML 元素时遵循浏览器 `innerText` 规则,SVG/XML 节点使用
|
|
391
|
+
`textContent`,源码请使用 `html`
|
|
392
|
+
|
|
212
393
|
参数:`output` 将结果保存到文件(`images=data` 时为输出目录),`images`(`info`/`data`)提取 HTML 中的图片元信息或数据,
|
|
213
394
|
`frameHtml` 在 `frame` 路由后提取当前 iframe 文档,截图支持 `clip` 坐标区域、`compareWith` PNG 基准对比和 `diffOutput`
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
`
|
|
218
|
-
|
|
219
|
-
|
|
395
|
+
差异图输出,`diffOutput` 必须同时传 `compareWith`。指定 `target` 的截图未匹配、`nth`
|
|
396
|
+
越界或尺寸为零时返回目标错误,不会静默返回视口截图,截图响应包含
|
|
397
|
+
`metadata.format`、`width`、`height`、`dimensionSource`、`byteSize`、`fullPage`、`scale`、`clip` 和
|
|
398
|
+
`capabilities`。截图在执行前限制单边 16,384 像素、总计 12,000,000 像素、预计 RGBA 内存 48 MiB 和编码数据 25
|
|
399
|
+
MiB;基准 PNG 在读取前检查文件大小,对比在解码前限制单个 PNG 25
|
|
400
|
+
MiB 和 12,000,000 像素,解压时按已校验尺寸限制输出,并要求 scanline 长度精确匹配;损坏或异常膨胀的 PNG 会被拒绝,较大截图应使用
|
|
401
|
+
`clip` 或 `scale` 缩小,截图与 diagnosticBundle 在 Extension 和 CDP 模式中都返回
|
|
402
|
+
`hiddenTabScreenshot=false`,Extension 隐藏页截图返回 `HIDDEN_TAB_SCREENSHOT`,不自动激活,`state` 返回
|
|
403
|
+
`interactiveElements`,Extension 和 CDP 模式下 `metadata` 都返回 `frames` 和实际文档 `url`,Extension 指定 `frame`
|
|
404
|
+
时返回该 iframe 文档地址;CDP 无法取得的已声明帧字段保留为 `null`,包括 DOM
|
|
405
|
+
selector 和所属元素 rect,帧树顺序与 ID 保持不变;元信息还返回页面当前的 `managed` 状态与 `metadata` 对象,其
|
|
406
|
+
`createdBy`、`createdAt`、`lastUsedAt`、`taskHint` 和 `note` 与 `browse list`、`manage pageMetadata`
|
|
407
|
+
一致,inline 与文件输出包含相同字段;`frame` 指定 iframe 文档时,备注仍属于该页面,`managed`
|
|
408
|
+
表示 Extension 页面托管状态,CDP 返回 false,不限制已连接 CDP 的正常操作,备注只保存在当前 Server 进程,未知创建来源返回
|
|
409
|
+
`unknown`,其他 Server 不继承这些备注,不能据此判断跨会话归属或取得权限;如果其他 debugger 占用 precise 截图路径,可视区域 fallback 会返回
|
|
410
|
+
`degraded`、`fallback` 和 `limitations`;fallback 不支持的参数返回结构化
|
|
411
|
+
`SCREENSHOT_FALLBACK_UNSUPPORTED`,`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame`
|
|
412
|
+
仅在 Extension 模式中指定 iframe,
|
|
220
413
|
|
|
221
414
|
**`attribute` 特殊前缀**:`computed:<属性名>` 返回 computed CSS 样式值(如 `computed:color`、`computed:font-size`),
|
|
222
415
|
`computed:*` 返回全部计算样式(300+ 属性,建议配合 `output` 写文件),
|
|
223
416
|
|
|
224
|
-
**`state` 专属参数**:`depth` 控制 DOM 遍历深度(默认 15),减小可降低大页面的返回数据量,
|
|
225
|
-
`
|
|
226
|
-
|
|
417
|
+
**`state` 专属参数**:`depth` 控制 DOM 遍历深度(默认 15),减小可降低大页面的返回数据量, `mode` 选择数据源 —
|
|
418
|
+
`accessibility`(默认,从无障碍树派生)或 `domsnapshot`(CDP `DOMSnapshot.captureSnapshot`,仅 CDP 模式,返回带 computed
|
|
419
|
+
style 的扁平节点数组,便于二次处理),
|
|
227
420
|
|
|
228
421
|
### wait - 等待条件
|
|
229
422
|
|
|
230
|
-
| For | 描述
|
|
231
|
-
|
|
423
|
+
| For | 描述 |
|
|
424
|
+
| ------------ | -------------------------------------------- |
|
|
232
425
|
| `element` | 等待元素(visible/hidden/attached/detached) |
|
|
233
426
|
| `navigation` | 等待导航完成 |
|
|
234
|
-
| `time` | 固定延迟
|
|
235
|
-
| `idle` |
|
|
427
|
+
| `time` | 固定延迟 |
|
|
428
|
+
| `idle` | 等待 DOM 或网络静默期 |
|
|
236
429
|
|
|
237
|
-
参数:`tabId
|
|
430
|
+
参数:`targetId`(或旧版 `tabId`)在两种 backend 中指定页面,`frame` 在 Extension 模式中指定 iframe,
|
|
238
431
|
|
|
239
|
-
|
|
240
|
-
`
|
|
432
|
+
CDP 模式的 `visible` 要求 DOM 矩形宽高非零,且 CSS 不隐藏元素(`display:none` 或 `visibility:hidden/collapse`) `hidden`
|
|
433
|
+
接受这些隐藏状态或元素不存在,`attached` 和 `detached` 只检查元素是否存在
|
|
434
|
+
|
|
435
|
+
**`idle` 说明**:Extension 模式会在 `readyState === 'complete'` 后注入 `MutationObserver`,等待 `ms`
|
|
436
|
+
毫秒内无 DOM 变更;CDP 模式等待网络静默。两种模式的默认 `ms` 都是 500ms,响应返回 `idleKind` 和
|
|
437
|
+
`idlePeriodMs`,Extension 响应还返回 `domStable`,
|
|
241
438
|
|
|
242
439
|
### evaluate - JavaScript 执行
|
|
243
440
|
|
|
244
441
|
在页面上下文执行 JavaScript,
|
|
245
442
|
|
|
246
|
-
| 参数
|
|
247
|
-
|
|
248
|
-
| `script`
|
|
249
|
-
| `scriptFile`
|
|
250
|
-
| `args`
|
|
251
|
-
| `mode`
|
|
252
|
-
| `staleContextRetry`
|
|
253
|
-
| `output`
|
|
254
|
-
| `tabId`
|
|
255
|
-
| `frame`
|
|
256
|
-
| `timeout`
|
|
257
|
-
| `diagnostics`
|
|
258
|
-
| `postCondition`
|
|
443
|
+
| 参数 | 描述 |
|
|
444
|
+
| -------------------- | ------------------------------------------------------- |
|
|
445
|
+
| `script` | JavaScript 代码,裸 `return` 语句自动包裹 IIFE |
|
|
446
|
+
| `scriptFile` | 从本地文件读取脚本,与 `script` 二选一 |
|
|
447
|
+
| `args` | 函数参数,`[]` 调用零参函数;省略时按原脚本语义执行 |
|
|
448
|
+
| `mode` | `precise`(默认,debugger API)或 `stealth`(JS 注入) |
|
|
449
|
+
| `staleContextRetry` | iframe stale context 策略,`never`(默认)或 `readOnly` |
|
|
450
|
+
| `output` | 将结果保存到文件 |
|
|
451
|
+
| `targetId` / `tabId` | 在两种 backend 中指定页面(`tabId` 为兼容别名) |
|
|
452
|
+
| `frame` | 指定目标 iframe(CSS 选择器或索引,Extension 模式) |
|
|
453
|
+
| `timeout` | 端到端超时预算(毫秒) |
|
|
454
|
+
| `diagnostics` | 执行后返回新增 console warning/error 和失败网络请求摘要 |
|
|
455
|
+
| `postCondition` | 执行后等待文本、selector、URL 片段或脚本结果匹配 |
|
|
259
456
|
|
|
260
457
|
`script` 和 `scriptFile` 至少提供一个,互斥使用,相对 `scriptFile` 和 `output` 路径默认写到 `mcp-chrome`
|
|
261
|
-
管理的系统临时目录,需要把文件留在当前工作目录时,用 `cwd:relative/path` 显式指定,相对路径会拒绝
|
|
262
|
-
`:`,避免落到 NTFS alternate data stream,
|
|
263
|
-
|
|
264
|
-
结果超过 100KB 时自动写入文件到受控的系统临时目录,返回文件路径和大小,返回 DOM 节点、`NodeList` 或 `HTMLCollection`
|
|
265
|
-
`NON_SERIALIZABLE_EVALUATE_RESULT`,并提示改为返回 `textContent`、`outerHTML`
|
|
266
|
-
`actionExecuted=true`、`actionStatus="completed"` 和
|
|
267
|
-
`inputMode=stealth` 时也默认使用 `precise`,其
|
|
268
|
-
`
|
|
269
|
-
|
|
270
|
-
|
|
458
|
+
管理的系统临时目录,需要把文件留在当前工作目录时,用 `cwd:relative/path` 显式指定,相对路径会拒绝
|
|
459
|
+
`..`,Windows 下也会拒绝 `:`,避免落到 NTFS alternate data stream,`output` 对字符串写原始文本,对其他类型写 JSON,
|
|
460
|
+
|
|
461
|
+
结果超过 100KB 时自动写入文件到受控的系统临时目录,返回文件路径和大小,返回 DOM 节点、`NodeList` 或 `HTMLCollection`
|
|
462
|
+
时返回 `NON_SERIALIZABLE_EVALUATE_RESULT`,并提示改为返回 `textContent`、`outerHTML`
|
|
463
|
+
等简单字段,结果展开或序列化失败时返回 `actionExecuted=true`、`actionStatus="completed"` 和
|
|
464
|
+
`failureStage="output"`,因为页面脚本已经完成,evaluate 即使在全局 `inputMode=stealth` 时也默认使用 `precise`,其
|
|
465
|
+
`postCondition` 检查与主动作使用相同 evaluate mode,`postCondition` 不传时, `success=true`
|
|
466
|
+
只表示脚本完成执行并返回;传入后如果超时仍不匹配,返回 `POST_CONDITION_FAILED` 和最后一次检查结果,iframe
|
|
467
|
+
precise 执行默认不在 execution context 失效后重放脚本,只有脚本无副作用时才应传
|
|
468
|
+
`staleContextRetry="readOnly"`,Extension 会在剩余 timeout 内重新解析 context,并最多重放一次,`Runtime.evaluate`
|
|
469
|
+
发出后发生 stale context 时返回
|
|
470
|
+
`actionExecuted=true`、`actionStatus="unknown"`,因为脚本可能已经产生部分副作用,但无法取得最终结果,
|
|
471
|
+
|
|
472
|
+
Extension precise 主 frame 的对象结果,显式指定 `output` 时字符预算为 16
|
|
473
|
+
Mi(16777216),未指定时保留 1000000,自动保存仍受该上限约束。两条路径均保留深度 8、节点 2000 和不可序列化结果拒绝,字符预算按 UTF-16
|
|
474
|
+
code units 计,不等于输出文件的 UTF-8 字节数;`tmp:`
|
|
475
|
+
文件还受临时输出配额约束。超限返回当前上限,并保留脚本已完成、输出失败的状态,不重放脚本。
|
|
271
476
|
|
|
272
477
|
### manage - 页面与环境管理
|
|
273
478
|
|
|
274
|
-
| Action
|
|
275
|
-
|
|
276
|
-
| `newPage`
|
|
277
|
-
| `
|
|
278
|
-
| `
|
|
279
|
-
| `
|
|
280
|
-
| `
|
|
281
|
-
| `
|
|
282
|
-
| `
|
|
283
|
-
| `
|
|
284
|
-
| `
|
|
285
|
-
| `
|
|
286
|
-
| `
|
|
287
|
-
| `
|
|
288
|
-
| `
|
|
289
|
-
| `
|
|
290
|
-
| `
|
|
291
|
-
| `
|
|
292
|
-
| `
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
`
|
|
299
|
-
`
|
|
479
|
+
| Action | 描述 |
|
|
480
|
+
| ------------------ | ------------------------------------------------ |
|
|
481
|
+
| `newPage` | 新建受控页面/Tab |
|
|
482
|
+
| `pageMetadata` | 读取或设置页面的 `taskHint`、`note` |
|
|
483
|
+
| `closePage` | 关闭受控页面并返回 `affected.before/after` |
|
|
484
|
+
| `adoptPage` | 授予已有 Tab 完整受控能力,不改变前台 |
|
|
485
|
+
| `releasePage` | 将受控页移出管理,不关闭页面 |
|
|
486
|
+
| `grantReadAccess` | 为当前调用实例授予显式页面的普通只读权限 |
|
|
487
|
+
| `revokeReadAccess` | 撤销当前调用实例的普通只读授权 |
|
|
488
|
+
| `updatePage` | 更新原生 tab 属性并返回实际状态 |
|
|
489
|
+
| `movePage` | 将受控 Tab 移到指定窗口或 index |
|
|
490
|
+
| `reorderPage` | 调整受控 Tab 在当前窗口内的顺序 |
|
|
491
|
+
| `pinPage` | 固定受控 Tab |
|
|
492
|
+
| `unpinPage` | 取消固定受控 Tab |
|
|
493
|
+
| `activatePage` | 激活受控 Tab 并聚焦所在窗口 |
|
|
494
|
+
| `focusWindow` | 聚焦显式指定的窗口 |
|
|
495
|
+
| `resizeWindow` | 调整显式指定窗口的尺寸或状态 |
|
|
496
|
+
| `newWindow` | 新建受控窗口 |
|
|
497
|
+
| `closeWindow` | 仅当窗口内全是 managed tab 时关闭窗口 |
|
|
498
|
+
| `updateWindow` | 更新原生窗口位置、状态、焦点或提醒 |
|
|
499
|
+
| `groupPages` | 创建分组或将受控页加入已有分组 |
|
|
500
|
+
| `ungroupPages` | 解除分组归属,保留受控权限 |
|
|
501
|
+
| `updateGroup` | 更新分组名称、颜色和折叠状态 |
|
|
502
|
+
| `moveGroup` | 将分组及其成员移动到指定窗口或位置 |
|
|
503
|
+
| `clearCache` | 清除缓存/存储(清除 Cookie 请用 `cookies` 工具) |
|
|
504
|
+
| `viewport` | 设置视口大小 |
|
|
505
|
+
| `userAgent` | 设置 User-Agent |
|
|
506
|
+
| `emulate` | 设备模拟(iPhone、iPad 等) |
|
|
507
|
+
| `inputMode` | 查询或设置输入模式(`precise` / `stealth`) |
|
|
508
|
+
| `stealth` | 注入反检测脚本 |
|
|
509
|
+
| `cdp` | 发送原始 CDP 命令(高级,如 `Runtime.evaluate`) |
|
|
510
|
+
|
|
511
|
+
原生 tab/window/group 配置仅支持 Extension 模式,操作已有对象时用 `targetId`、`targetIds`、`windowId` 或 `groupId`
|
|
512
|
+
明确指定目标,返回 `affected.before/after`,分组结果还返回 `tabsBefore/tabsAfter`,`ungroupPages`
|
|
513
|
+
由 Chrome 删除空组,不撤销成员的受控权限分组名称、颜色、折叠更新和整组移动要求所有成员受控,窗口更新、调整和聚焦要求窗口内所有 tab 受控,缓存的 MCP
|
|
514
|
+
window ID 不改变此规则 Extension 模式不支持 `clearCache`,会返回 `UNSUPPORTED_MODE` 且不清除任何内容;清 Cookie 请用带
|
|
515
|
+
`url` 或 `domain` 过滤的 `cookies(action="clear")`,清 storage 或 cache 请改用 CDP 模式。`focusWindow`
|
|
516
|
+
只有在观测到目标窗口已聚焦后才返回成功,否则返回 `WINDOW_FOCUS_NOT_OBSERVED`,`closeWindow`
|
|
517
|
+
遇到混有非托管 tab 的窗口会返回 `WINDOW_HAS_UNMANAGED_TABS`。持久的 `adoptPage`、`releasePage`
|
|
518
|
+
目标变更与指定 tab 的操作串行执行,并发多事件 input 会始终留在指定 tab,持久目标变更会在该操作结束后生效
|
|
519
|
+
|
|
520
|
+
| 动作 | 原生参数 | 行为 |
|
|
521
|
+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
522
|
+
| `newPage` | `url`、`windowId`、`index`、`active`、`pinned`、`openerTabId`、`groupId`、`timeout` | `active` 默认 false,`groupId=-1` 不分组,显式位置不受默认显示分组改变 |
|
|
523
|
+
| `updatePage` | `url`、`active`、`pinned`、`highlighted`、`muted`、`autoDiscardable`、`openerTabId` | 必须传 `targetId`,只支持 `active=true` 且不聚焦窗口,`active=false` 在任何更新前拒绝 |
|
|
524
|
+
| `groupPages` | `targetIds`、`groupId`、`windowId`、`title`、`color`、`collapsed` | 省略 `groupId` 时在成员原窗口创建分组,跨窗口成员须指定 `windowId`,加入已有组仅传 `targetIds/groupId` |
|
|
525
|
+
| `ungroupPages` | `targetIds` | 解除分组,保留受控能力 |
|
|
526
|
+
| `updateGroup` | `groupId`、`title`、`color`、`collapsed` | 空名称及 false 折叠值按原值设置 |
|
|
527
|
+
| `moveGroup` | `groupId`、`windowId`、`index` | 移动全部成员,`index=-1` 表示窗口末尾 |
|
|
528
|
+
| `newWindow` | `url` 或 `urls`、`targetId`、`windowType`、`focused`、`incognito`、`left`、`top`、`width`、`height`、`windowState`、`setSelfAsOpener` | normal 支持多 URL 及同时移入已有受控页,popup 只接受一个页面,所有新建页受控且分别记录创建来源 |
|
|
529
|
+
| `updateWindow` / `resizeWindow` | `windowId`、`left`、`top`、`width`、`height`、`windowState`、`focused`、`drawAttention` | 应用 Chrome 支持的窗口配置并返回观测状态 |
|
|
530
|
+
|
|
531
|
+
`updateWindow` 与 `resizeWindow` 修改状态或几何后等待浏览器观测稳定,非 normal 窗口同时请求 `windowState="normal"`
|
|
532
|
+
和 bounds 时,状态转换完成后才应用一次几何参数,OS 调整后的几何按实际值返回有界等待内仍未观测到稳定状态时,`WINDOW_UPDATE_NOT_OBSERVED`
|
|
533
|
+
返回部分执行状态及最后观测的窗口信息,再次更新前用 `browse list` 检查实际状态
|
|
534
|
+
|
|
535
|
+
`browse list` 默认 `details="summary"`,返回页面标识、URL/标题、位置、managed/revision 和元数据传 `details="full"`
|
|
536
|
+
获取选中、静音、自动丢弃、来源 tab ID 和可用原生只读属性,false 值保留 `targetIds` 与 `managedOnly=true`
|
|
537
|
+
筛选页面及所属窗口、分组;`totalTargetCount`、`totalWindowCount` 和 `totalTabCount` 区分总量与选中数量窗口通过
|
|
538
|
+
`targetIds` 引用页面,不重复完整对象;favicon data URL 不内联,完整结果用 `favIconInline=true`
|
|
539
|
+
标明存在分组保留名称、颜色、折叠/共享、窗口、首个成员位置和成员 ID,颜色只属于分组,只读属性只回显,不作为写入参数列表操作不读取页面正文,不导航或改变焦点
|
|
540
|
+
|
|
541
|
+
页面和分组移动接受
|
|
542
|
+
`index=-1`,新建页的 index 非负,来源 tab 与显式分组、窗口必须位于同一窗口,固定页不能在分组中创建窗口状态与位置/尺寸的冲突、动作不支持的字段在修改前拒绝,CDP 明确拒绝不支持的 Chrome
|
|
543
|
+
UI 配置,不静默忽略 `newWindow` 的 `url` 与 `urls` 是两种互斥输入方式,在 normal 窗口中可与 `targetId`
|
|
544
|
+
同时使用 popup 只接受单个 URL 或一个已有页面,不能同时创建额外 URL 页面,明确的创建前拒绝保留
|
|
545
|
+
`actionExecuted=false`、`actionStatus="not_started"`、`failureStage="preflight"`,更新在执行前拒绝时保留原 revision,原生更新已派发后的失败仍使 revision 失效
|
|
546
|
+
|
|
547
|
+
`emulate` 在两个 backend 中设置设备视口、像素密度、触摸能力和 User-Agent,`viewport`
|
|
548
|
+
恢复桌面视口与页面缩放并关闭触摸模拟,User-Agent 通过 `userAgent` 单独恢复
|
|
300
549
|
|
|
301
550
|
**Stealth 模式档位**(CDP launch 参数,通过 `browse action=launch stealth=...` 设置):
|
|
302
551
|
|
|
@@ -306,28 +555,40 @@ Tab/window 管理动作仅支持 Extension 模式,改变浏览器可见状态
|
|
|
306
555
|
|
|
307
556
|
### logs - 浏览器日志
|
|
308
557
|
|
|
309
|
-
| Type | 描述
|
|
310
|
-
|
|
311
|
-
| `console` | 控制台日志(支持级别过滤)
|
|
558
|
+
| Type | 描述 |
|
|
559
|
+
| --------- | ----------------------------- |
|
|
560
|
+
| `console` | 控制台日志(支持级别过滤) |
|
|
312
561
|
| `network` | 网络请求日志(支持 URL 过滤) |
|
|
313
562
|
|
|
314
563
|
参数:`output` 将结果保存到文件,console 日志统一返回公开级别 `error`、`warning`、`info`、`debug`,浏览器原始的 `warn`、
|
|
315
|
-
`log`
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
564
|
+
`log` 等级会在过滤和返回前转换。清空 fallback
|
|
565
|
+
console 日志会保留 hook。debugger 采集恢复后,fallback 采集会停用;仍指向 MCP
|
|
566
|
+
wrapper 的 console 方法会恢复,页面之后安装的 wrapper 保持不变。network 日志在 `loadingFinished` 或 `loadingFailed`
|
|
567
|
+
时才完成记录,不会在收到 headers 时提前结束,因此 body 失败会同时保留 HTTP status 和
|
|
568
|
+
`errorText`,传输中的 body 也会继续计入 `networkidle`。日志尽量返回 `method`、
|
|
569
|
+
`url`、`status`、`timestamp`、`duration`,URL
|
|
570
|
+
query 中常见的认证、签名、密码和 token 参数会在内联响应、diagnostics 和 显式 `output` 文件中替换为 `[REDACTED]`,并返回
|
|
571
|
+
`urlRedacted`、`urlOriginalLength` 和
|
|
572
|
+
`redactedQueryParameters`,内联 network 结果会把脱敏后的单条 URL 限制为 2048 字符,截断时返回 `urlLength` 和
|
|
573
|
+
`urlTruncated: true`,`urlPattern` 支持 `*` 匹配任意长度字符、`?` 匹配单个字符,`tabId`
|
|
574
|
+
指定目标 Tab(Extension 模式),`frame` 不适用于日志,
|
|
575
|
+
|
|
576
|
+
Extension debugger 不可用时,network 每次读取都会刷新 performance 记录并标记
|
|
577
|
+
`source="performance"`;状态使用浏览器提供的 `responseStatus`,无法取得时为
|
|
578
|
+
`0`,未知请求方法保留空值,重复读取保留记录序列号;`clear`
|
|
579
|
+
清除 MCP 记录并推进当前文档的读取边界,不清除网页共享的 performance 数据,新文档重新建立边界,读取失败返回错误,不冒充空日志
|
|
320
580
|
|
|
321
581
|
### cookies - Cookie 管理
|
|
322
582
|
|
|
323
|
-
| Action | 描述
|
|
324
|
-
|
|
325
|
-
| `get` | 获取 Cookie
|
|
326
|
-
| `set` | 设置 Cookie
|
|
327
|
-
| `delete` | 删除 Cookie
|
|
328
|
-
| `clear` |
|
|
583
|
+
| Action | 描述 |
|
|
584
|
+
| -------- | ------------------------------------------------------ |
|
|
585
|
+
| `get` | 获取 Cookie |
|
|
586
|
+
| `set` | 设置 Cookie |
|
|
587
|
+
| `delete` | 删除 Cookie |
|
|
588
|
+
| `clear` | 在 URL 或域名范围内删除 Cookie,可用 `name` 进一步过滤 |
|
|
329
589
|
|
|
330
|
-
**说明**:`clear` 必须指定 `
|
|
590
|
+
**说明**:`clear` 必须指定 `url` 或 `domain`。`name` 只能在该范围内进一步过滤,避免误删其他站点的同名 Cookie。返回的
|
|
591
|
+
`count` 只统计 Chrome 确认已删除的 Cookie;列出后、删除前已消失的 Cookie 不计数
|
|
331
592
|
|
|
332
593
|
## Target:统一元素定位器
|
|
333
594
|
|
|
@@ -335,57 +596,43 @@ network 结果会把脱敏后的单条 URL 限制为 2048 字符,截断时返
|
|
|
335
596
|
|
|
336
597
|
```typescript
|
|
337
598
|
// 按可访问性(推荐 - 最稳定)
|
|
338
|
-
{ role:
|
|
599
|
+
const byRole = { role: 'button', name: '提交' }
|
|
339
600
|
|
|
340
601
|
// 按可访问性精确匹配名称
|
|
341
|
-
{ role:
|
|
602
|
+
const byExactRole = { role: 'button', name: '提交', exact: true }
|
|
342
603
|
|
|
343
604
|
// 按文本内容
|
|
344
|
-
{ text:
|
|
605
|
+
const byText = { text: '点击这里', exact: true }
|
|
345
606
|
|
|
346
607
|
// 按表单 label
|
|
347
|
-
{
|
|
348
|
-
label: "邮箱"
|
|
349
|
-
}
|
|
608
|
+
const byLabel = { label: '邮箱' }
|
|
350
609
|
|
|
351
610
|
// 按 placeholder
|
|
352
|
-
{
|
|
353
|
-
placeholder: "请输入姓名"
|
|
354
|
-
}
|
|
611
|
+
const byPlaceholder = { placeholder: '请输入姓名' }
|
|
355
612
|
|
|
356
613
|
// 按 title 属性
|
|
357
|
-
{
|
|
358
|
-
title: "关闭对话框"
|
|
359
|
-
}
|
|
614
|
+
const byTitle = { title: '关闭对话框' }
|
|
360
615
|
|
|
361
616
|
// 按 alt 文本(图片)
|
|
362
|
-
{
|
|
363
|
-
alt: "头像"
|
|
364
|
-
}
|
|
617
|
+
const byAlt = { alt: '头像' }
|
|
365
618
|
|
|
366
619
|
// 按 test ID
|
|
367
|
-
{
|
|
368
|
-
testId: "submit-button"
|
|
369
|
-
}
|
|
620
|
+
const byTestId = { testId: 'submit-button' }
|
|
370
621
|
|
|
371
622
|
// 按 CSS 选择器
|
|
372
|
-
{
|
|
373
|
-
css: "#login-form .submit-btn"
|
|
374
|
-
}
|
|
623
|
+
const byCss = { css: '#login-form .submit-btn' }
|
|
375
624
|
|
|
376
625
|
// 多匹配消歧(从 0 开始)
|
|
377
|
-
{ css:
|
|
626
|
+
const secondMatch = { css: '.ant-select-input', nth: 1 }
|
|
378
627
|
|
|
379
628
|
// 按 CSS + 文本(按文本内容过滤)
|
|
380
|
-
{ css:
|
|
629
|
+
const byCssText = { css: 'button', text: '提交', exact: true }
|
|
381
630
|
|
|
382
631
|
// 按 XPath
|
|
383
|
-
{
|
|
384
|
-
xpath: "//button[@type='submit']"
|
|
385
|
-
}
|
|
632
|
+
const byXPath = { xpath: "//button[@type='submit']" }
|
|
386
633
|
|
|
387
634
|
// 按坐标
|
|
388
|
-
{ x: 100, y: 200 }
|
|
635
|
+
const byCoordinates = { x: 100, y: 200 }
|
|
389
636
|
```
|
|
390
637
|
|
|
391
638
|
## 使用示例
|
|
@@ -449,12 +696,27 @@ extract(type="html", target={ css: ".article" }, images="info")
|
|
|
449
696
|
|
|
450
697
|
// 获取 HTML + 图片数据,保存到目录
|
|
451
698
|
extract(type="html", images="data", output="tmp:page")
|
|
452
|
-
// 生成:<系统临时目录>/claude-tools/mcp-chrome/page/content.html, images/*, index.json
|
|
699
|
+
// 生成:<系统临时目录>/claude-tools/mcp-chrome/session-<id>/page/content.html, images/*, index.json
|
|
453
700
|
|
|
454
701
|
// 获取 HTML + 图片数据(内联返回,最多 20 张)
|
|
455
702
|
extract(type="html", target={ css: ".card" }, images="data")
|
|
456
703
|
```
|
|
457
704
|
|
|
705
|
+
`tmp:` 路径属于当前 server 会话。临时输出整个会话最多 256 项、128
|
|
706
|
+
MiB;启动时只清理超过 24 小时且所属进程已退出的带归属标记目录。成功写入 `tmp:` 文件或目录的响应会返回 `retention`
|
|
707
|
+
清理条件,`cwd:` 响应不带此字段。重启后仍需通过 MCP 访问的文件使用
|
|
708
|
+
`cwd:`。输出路径拒绝 Windows 保留设备名、ADS、非法字符以及末尾空格或点号;Windows 上写入敏感内容前须验证私有 DACL。
|
|
709
|
+
|
|
710
|
+
路径语法错误返回 `INVALID_ARGUMENT`,允许 `.` 组件,继续拒绝 `..` 组件根目录外的路径及链接越界返回
|
|
711
|
+
`PATH_NOT_ALLOWED`,两类错误均在 `error.context.cwd` 返回 server 的实际工作目录,范围拒绝另返回 `allowedRoots` 使用
|
|
712
|
+
`cwd:` 指定相对于该目录的路径,或使用 `tmp:` 保存会话输出,`scriptFile` 与 `compareWith` 遵循相同校验
|
|
713
|
+
|
|
714
|
+
配额拒绝返回 `TEMP_OUTPUT_QUOTA_EXCEEDED`,`error.context` 包含 `limits`、`usage`、`remaining`、`requested` 和
|
|
715
|
+
`projected`。 `usage.complete=false` 时,占用只为已观察下界,`remaining`/`projected`
|
|
716
|
+
为 null;已有输出保留。evaluate 的输出失败保留
|
|
717
|
+
`actionExecuted=true`、`actionStatus=completed`、`failureStage=output`、`retryable=false`,不重放脚本。后续输出可使用
|
|
718
|
+
`cwd:` 指定仓库内路径。
|
|
719
|
+
|
|
458
720
|
### 页面元信息
|
|
459
721
|
|
|
460
722
|
```
|
|
@@ -479,7 +741,18 @@ input(events=[
|
|
|
479
741
|
], frame="iframe.login-frame")
|
|
480
742
|
```
|
|
481
743
|
|
|
482
|
-
CSS 选择器和数字索引按父文档的 DOM
|
|
744
|
+
CSS 选择器和数字索引按父文档的 DOM
|
|
745
|
+
iframe 顺序定位,DOM 中不存在的子 frame(包括其他 Extension 加入的 frame)不会改变索引,也不会成为候选目标,所选元素无法对应到唯一 Chrome
|
|
746
|
+
frame 时返回 `FRAME_IDENTITY_UNAVAILABLE`,不会选择其他 frame;precise
|
|
747
|
+
evaluate 按含 query 和 fragment 的完整 URL 定位,并按所选 DOM iframe 区分 URL 相同的 frame,包括
|
|
748
|
+
`about:srcdoc`,无法确认身份时拒绝执行
|
|
749
|
+
|
|
750
|
+
frame 定位失败分别返回 `INVALID_FRAME_SELECTOR`、`FRAME_NOT_IFRAME` 或 `FRAME_NOT_FOUND`,读取注入区分
|
|
751
|
+
`INVALID_SELECTOR`、`FRAME_STALE_CONTEXT`、`FRAME_INJECTION_DENIED`、`FRAME_SCRIPT_FAILED`、 `FRAME_INJECTION_FAILED` 和
|
|
752
|
+
`FRAME_SCRIPT_NO_RESULT`,并报告注入或脚本结果阶段,无结果不等于 selector 非法,空文本、空元素数组、null 属性值和 void 脚本调用保持原语义,错误不会重放脚本;成功定位后的读取失败在
|
|
753
|
+
`pageContext.frameContext` 保留 DOM 索引、Chrome frame ID 和可取得的文档身份;frame
|
|
754
|
+
URL 诊断去掉认证、query 和 fragment,长度限制为 500 字符,`data:` 与 `javascript:` 只返回协议;无法解析的 URL 返回
|
|
755
|
+
`url=null` 和 `urlStatus="unavailable"`
|
|
483
756
|
|
|
484
757
|
### 等待元素
|
|
485
758
|
|
|
@@ -570,8 +843,8 @@ mcp-chrome/
|
|
|
570
843
|
## 安全说明
|
|
571
844
|
|
|
572
845
|
- **信任边界**:Extension 模式默认自动连接本地 MCP server,在多用户系统、CI runner、`--net=host` 容器等不可信代码可访问
|
|
573
|
-
`127.0.0.1:19222-19299` 的环境中,应使用 `MCP_CHROME_PAIRING_TOKEN`,或设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0
|
|
574
|
-
Origin 头,可挡掉浏览器页面和 curl,但拦不住同 UID 的本地恶意进程
|
|
846
|
+
`127.0.0.1:19222-19299` 的环境中,应使用 `MCP_CHROME_PAIRING_TOKEN`,或设置 `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`
|
|
847
|
+
,WebSocket 握手要求 `chrome-extension://` Origin 头,可挡掉浏览器页面和 curl,但拦不住同 UID 的本地恶意进程
|
|
575
848
|
- Extension 模式:共享浏览器会话,请仅在受信任的机器上使用
|
|
576
849
|
- CDP 模式:通过 DevTools Protocol 提供完整浏览器控制能力
|
|
577
850
|
- 默认端口仅绑定到 127.0.0.1(本地访问)
|
|
@@ -584,10 +857,10 @@ mcp-chrome/
|
|
|
584
857
|
`stealth` 模式(`safe` / `aggressive`)仅覆盖少量指纹面:
|
|
585
858
|
|
|
586
859
|
- **覆盖**:`navigator.webdriver`、`cdc_*` 属性、User-Agent 字符串、若干 WebGL vendor/renderer 值、Chrome runtime 属性
|
|
587
|
-
- **不覆盖**:Canvas 指纹、AudioContext 指纹、Font 枚举、TLS 层指纹(JA3/JA4)、CDP
|
|
588
|
-
)、扩展自身存在的探测
|
|
589
|
-
-
|
|
590
|
-
|
|
860
|
+
- **不覆盖**:Canvas 指纹、AudioContext 指纹、Font 枚举、TLS 层指纹(JA3/JA4)、CDP
|
|
861
|
+
attach 横幅("Chrome 正受自动化软件控制")、扩展自身存在的探测
|
|
862
|
+
- **警告**:这些修补不能过 Cloudflare。JS Challenge 和 Turnstile
|
|
863
|
+
checkbox 由导航、input、evaluate 之后在真实浏览器里等待处理,不覆盖 Akamai、DataDome、PerimeterX、交互式验证码或 IP 声誉
|
|
591
864
|
|
|
592
865
|
## 已知限制
|
|
593
866
|
|
|
@@ -605,9 +878,34 @@ MIT 许可证 - 详见 [LICENSE](LICENSE)
|
|
|
605
878
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 规范
|
|
606
879
|
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP 文档
|
|
607
880
|
|
|
608
|
-
|
|
609
881
|
## 操作状态与诊断
|
|
610
882
|
|
|
611
|
-
input 和 evaluate 返回值追加 `actionExecuted`、`actionStatus`、`verificationStatus`、`failureStage` 和
|
|
612
|
-
|
|
613
|
-
`
|
|
883
|
+
input 和 evaluate 返回值追加 `actionExecuted`、`actionStatus`、`verificationStatus`、`failureStage` 和
|
|
884
|
+
`retryable`。验证状态分为
|
|
885
|
+
`matched`、`not_matched`、`unavailable`、`error`;debugger 超时且无法证明脚本已停止时,动作状态为
|
|
886
|
+
`unknown`。页面脚本抛异常时返回 `actionExecuted=true` 和 `actionStatus="failed"`;结果展开或序列化失败时返回
|
|
887
|
+
`actionStatus="completed"` 和 `failureStage="output"`。页面前置条件不符时,input 和 evaluate 返回
|
|
888
|
+
`actionExecuted=false`、`actionStatus="not_started"`。diagnostics 是附加能力,失败时返回
|
|
889
|
+
`diagnosticsStatus`,不会覆盖主动作结果。browse 和 wait 的主动作失败时,也会保留失败前已收集的 diagnostics。目标诊断会读取当前 tab 的实时状态,不依赖 attach 时缓存的 URL 和标题。
|
|
890
|
+
|
|
891
|
+
原生脚本终止,以及 CDP `Runtime` 脚本命令返回 `Internal error` 时,evaluate 和 `manage cdp` 保留原错误码,返回
|
|
892
|
+
`actionExecuted=true`、`actionStatus="unknown"`、`retryable=false`,不重放命令;evaluate 的执行中 RPC 超时或过期 execution
|
|
893
|
+
context 导致结果未知时也不可直接重试;执行开始前的超时仍可重试;页面主动抛出的同名异常仍按动作失败处理
|
|
894
|
+
|
|
895
|
+
Extension 的 accessibility state 不读取 password
|
|
896
|
+
value 生成元素名称,标签、placeholder、title 和普通输入值保留;显式脚本、HTML 和属性读取保持原有行为
|
|
897
|
+
|
|
898
|
+
`replace` 仅对 `textarea` 以及 `text`、`search`、`tel`、`url`、`password`
|
|
899
|
+
类型的 input 使用文本选区。其他 input 类型通过原生完整 value 更新,并返回请求值与浏览器规范化后的实际值。对不支持选区的类型单独执行
|
|
900
|
+
`select` 会返回 `UNSUPPORTED_SELECTION`。CDP模式下,`select` 和 `replace` 的 locator target 通过 CDP
|
|
901
|
+
locator 聚焦,不调用 Extension refId。password value 不进入 input 失败 context 和 text
|
|
902
|
+
post-condition 观测值,失败响应还会脱敏传入的 `find` 和替换 `text`。password 的 `select`/`replace`
|
|
903
|
+
成功和失败响应均隐藏 console 与 network 诊断正文,返回 `diagnostics.redacted=true` 和
|
|
904
|
+
`reason="sensitive_input_or_unresolved_target"`;无法安全确认选择目标时也隐藏这些正文普通输入保留诊断,密码保护仅持续到当前 input 请求结束目标超时返回限量的locator、tab、frame、匹配数和候选上下文。显式
|
|
905
|
+
`tabId` 或 `frame`
|
|
906
|
+
作用域会在 input、wait、logs、extract 开始前确定活动 backend,动作和验证使用同一个目标 backend。precise iframe
|
|
907
|
+
evaluate 默认使用 `staleContextRetry="never"`,context 失效时不重放脚本; `readOnly` 允许 Extension 校验 frame
|
|
908
|
+
identity 并解析新 execution context 后重放一次。响应包含策略、`retryAttempted`、限量的 `retryReason`,以及最终 Extension
|
|
909
|
+
frame、parent frame、URL、CDP frame 和 execution context ID 组成的 `frameContext`,URL 相同的 frame 仅在所选 DOM
|
|
910
|
+
iframe 无法唯一确认目标时拒绝执行;Extension 重载后可继续访问原页面中的 iframe,无需刷新或重新导航端口扫描会把普通的 WebSocket
|
|
911
|
+
open 前失败聚合为 debug;已识别 MCP server 的认证或协议拒绝只在摘要变化时输出一条限量 warning
|