@pyrokine/mcp-chrome 3.1.0 → 3.1.2
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 +599 -307
- package/README_zh.md +526 -341
- package/dist/cdp/client.d.ts +1 -0
- package/dist/cdp/client.d.ts.map +1 -1
- package/dist/cdp/client.js +16 -8
- package/dist/cdp/client.js.map +1 -1
- package/dist/core/browser-driver.d.ts +2 -1
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/browser-events.d.ts +9 -3
- package/dist/core/browser-events.d.ts.map +1 -1
- package/dist/core/browser-events.js +365 -195
- package/dist/core/browser-events.js.map +1 -1
- package/dist/core/challenge-page.d.ts.map +1 -1
- package/dist/core/challenge-page.js +6 -1
- package/dist/core/challenge-page.js.map +1 -1
- package/dist/core/error-sanitizer.d.ts.map +1 -1
- package/dist/core/error-sanitizer.js +2 -1
- package/dist/core/error-sanitizer.js.map +1 -1
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +7 -3
- package/dist/core/errors.js.map +1 -1
- package/dist/core/file-upload.js +1 -1
- package/dist/core/file-upload.js.map +1 -1
- package/dist/core/locator.d.ts +1 -0
- package/dist/core/locator.d.ts.map +1 -1
- package/dist/core/locator.js +19 -11
- package/dist/core/locator.js.map +1 -1
- package/dist/core/os-mouse.d.ts +1 -0
- package/dist/core/os-mouse.d.ts.map +1 -1
- package/dist/core/os-mouse.js +10 -4
- package/dist/core/os-mouse.js.map +1 -1
- package/dist/core/session.d.ts +4 -3
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +164 -75
- package/dist/core/session.js.map +1 -1
- package/dist/core/unified-session.d.ts +10 -5
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +138 -59
- package/dist/core/unified-session.js.map +1 -1
- package/dist/core/utils.d.ts +5 -1
- package/dist/core/utils.d.ts.map +1 -1
- package/dist/core/utils.js +8 -2
- package/dist/core/utils.js.map +1 -1
- package/dist/extension/bridge.d.ts +3 -3
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +58 -17
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts +1 -0
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +14 -14
- package/dist/extension/http-server.js.map +1 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/tools/browser-event-output.js.map +1 -1
- package/dist/tools/challenge.d.ts +1 -0
- package/dist/tools/challenge.d.ts.map +1 -1
- package/dist/tools/challenge.js +113 -17
- package/dist/tools/challenge.js.map +1 -1
- package/dist/tools/cookies.d.ts.map +1 -1
- package/dist/tools/cookies.js +2 -1
- package/dist/tools/cookies.js.map +1 -1
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +2 -1
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +4 -2
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +152 -58
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +225 -86
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/logs.js +1 -1
- package/dist/tools/logs.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +18 -8
- package/dist/tools/manage.js.map +1 -1
- package/dist/tools/network-sanitizer.d.ts +1 -0
- package/dist/tools/network-sanitizer.d.ts.map +1 -1
- package/dist/tools/network-sanitizer.js +23 -9
- package/dist/tools/network-sanitizer.js.map +1 -1
- package/dist/tools/page-context.d.ts +1 -1
- package/dist/tools/page-context.d.ts.map +1 -1
- package/dist/tools/page-context.js +2 -1
- package/dist/tools/page-context.js.map +1 -1
- package/dist/tools/png.d.ts.map +1 -1
- package/dist/tools/png.js +12 -3
- package/dist/tools/png.js.map +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +57 -33
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/schema.d.ts +1 -1
- package/dist/tools/schema.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +53 -33
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +4 -4
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/{content.ts-BAMOcF3R.js → content.ts-C9QgtUYe.js} +1 -1
- package/extension/dist/assets/{content.ts-loader-4F9a1EWZ.js → content.ts-loader-yqB_P8vu.js} +1 -1
- package/extension/dist/assets/{index.ts-B79g2ikq.js → index.ts-DBFNh8mZ.js} +8650 -8195
- package/extension/dist/assets/{page-scripts-CSxn58h1.js → page-scripts-BjqQ0zXt.js} +1 -1
- package/extension/dist/manifest.json +4 -4
- package/extension/dist/service-worker-loader.js +1 -1
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -15,8 +15,8 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
|
|
|
15
15
|
- **8 Unified Tools**: Action-based design covering browse, input, extract, wait, evaluate, manage, cookies, logs
|
|
16
16
|
- **Multi-Page Targeting**: `targetId` selects a page in either backend without changing browser focus; `tabId` remains
|
|
17
17
|
an alias
|
|
18
|
-
- **Frames and Shadow DOM**: `frame` selects a child frame or a nested selector/index path in either backend;
|
|
19
|
-
|
|
18
|
+
- **Frames and Shadow DOM**: `frame` selects a child frame or a nested selector/index path in either backend; CSS, text
|
|
19
|
+
and semantic queries enter open shadow roots
|
|
20
20
|
- **Semantic Targeting**: 11 ways to locate elements (role, text, label, CSS, CSS+text combo, XPath, coordinates, etc.)
|
|
21
21
|
- **Auto-Wait**: Built-in clickability and input-ready detection with deadline-based timeout budget
|
|
22
22
|
- **Dual Input Mode**: `precise` (debugger API, bypasses CSP) or `stealth` (JS injection, no debug banner)
|
|
@@ -68,6 +68,21 @@ claude mcp add chrome -- node "$PWD/dist/index.js"
|
|
|
68
68
|
|
|
69
69
|
For Extension mode, load `extension/dist` in Chrome.
|
|
70
70
|
|
|
71
|
+
### Other MCP clients
|
|
72
|
+
|
|
73
|
+
For Claude Desktop and other clients, use this configuration with the actual Server entry path:
|
|
74
|
+
|
|
75
|
+
```json
|
|
76
|
+
{
|
|
77
|
+
"mcpServers": {
|
|
78
|
+
"chrome": {
|
|
79
|
+
"command": "node",
|
|
80
|
+
"args": ["/path/to/mcp-chrome/dist/index.js"]
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
71
86
|
### Windows CDP launch
|
|
72
87
|
|
|
73
88
|
Chrome discovery checks Windows App Paths, `PATH`, installed Chrome channels, Chromium, Chrome for Testing, and
|
|
@@ -88,80 +103,22 @@ launch.
|
|
|
88
103
|
|
|
89
104
|
### Mode 1: Extension Mode (Recommended)
|
|
90
105
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
1. Open `chrome://extensions/` in Chrome
|
|
96
|
-
2. Enable "Developer mode" (top-right toggle)
|
|
97
|
-
3. Click "Load unpacked" → select `mcp-chrome/extension/dist/` directory
|
|
98
|
-
4. The MCP Chrome icon appears in the toolbar
|
|
99
|
-
|
|
100
|
-
**Step 2: Configure MCP Client**
|
|
101
|
-
|
|
102
|
-
```bash
|
|
103
|
-
# npm installation
|
|
104
|
-
claude mcp add chrome -- mcp-chrome
|
|
105
|
-
|
|
106
|
-
# source build
|
|
107
|
-
claude mcp add chrome -- node /path/to/mcp-chrome/dist/index.js
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
Claude Desktop / Other Clients:
|
|
111
|
-
|
|
112
|
-
```json
|
|
113
|
-
{
|
|
114
|
-
"mcpServers": {
|
|
115
|
-
"chrome": {
|
|
116
|
-
"command": "node",
|
|
117
|
-
"args": ["/path/to/mcp-chrome/dist/index.js"]
|
|
118
|
-
}
|
|
119
|
-
}
|
|
120
|
-
}
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
**Step 3: Connect**
|
|
124
|
-
|
|
125
|
-
The Extension auto-connects to the MCP Server via HTTP/WebSocket (port 19222-19299). Click the toolbar icon to verify
|
|
126
|
-
connection status. `browse(action="connect")` and the local `/api/info` endpoint report the active Extension background
|
|
127
|
-
bundle hash and compare it with the bundle shipped beside the server. `bundleStatus="stale"` means Chrome is still
|
|
128
|
-
running an older unpacked Extension bundle; reload the Extension in `chrome://extensions/`. A legacy Extension that
|
|
129
|
-
lacks `network_challenge_state` falls back to tab-title and DOM challenge detection. Bundle identity never disables
|
|
130
|
-
zero-config auto-connect.
|
|
131
|
-
|
|
132
|
-
```
|
|
133
|
-
browse(action="list") // List all tabs
|
|
134
|
-
browse(action="open", url="https://example.com")
|
|
135
|
-
extract(type="screenshot")
|
|
136
|
-
```
|
|
106
|
+
After [installation](#installation), the Extension connects to local MCP servers automatically over HTTP/WebSocket on
|
|
107
|
+
ports 19222-19299. It uses your existing Chrome sessions and cookies; ordinary local use needs no manual pairing or
|
|
108
|
+
Connect click.
|
|
137
109
|
|
|
138
|
-
|
|
110
|
+
List pages first and reuse a suitable managed page by its task name and notes. If none exists, create a temporary
|
|
111
|
+
example page in an existing window. Use its returned `targetId` for the read and close only that created page:
|
|
139
112
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
|
|
113
|
+
```text
|
|
114
|
+
browse(action="list")
|
|
115
|
+
manage(action="newPage", url="https://example.com", taskHint="Read example", note="Temporary example page")
|
|
116
|
+
extract(type="text", targetId="CREATED_TARGET_ID")
|
|
117
|
+
manage(action="closePage", targetId="CREATED_TARGET_ID")
|
|
146
118
|
```
|
|
147
119
|
|
|
148
|
-
|
|
149
|
-
and
|
|
150
|
-
health checks, WebSocket handshakes, and scheduled reconnects, so an older no-token attempt cannot connect afterward.
|
|
151
|
-
|
|
152
|
-
Token connections require authentication protocol v2 on both sides. Each command, response, cancellation and heartbeat
|
|
153
|
-
is authenticated with direction-separated session keys and an increasing sequence number. Health proofs bind the nonces,
|
|
154
|
-
server instance and port. The Extension waits for an authenticated ready message; the server waits for an authenticated
|
|
155
|
-
hello. Older strict-token peers are rejected with a protocol diagnostic. Default no-token discovery and automatic
|
|
156
|
-
reconnection retain their existing behavior.
|
|
157
|
-
|
|
158
|
-
The popup Disconnect action pauses connections for the current Extension session, including Service Worker recovery.
|
|
159
|
-
Connect resumes discovery. Reloading the Extension or restarting Chrome clears the pause and restores auto-connect.
|
|
160
|
-
When one MCP Server restarts, the Extension retries that server with the existing backoff while keeping other server connections active. Explicit Disconnect cancels these retries.
|
|
161
|
-
|
|
162
|
-
Discovery reports the initial server-port set and changes, including an empty set. Unchanged scans and automatic reconnects do not repeat that summary; each scan still checks the full port range. Explicit disconnect starts a new reporting cycle. Ordinary pre-open failures remain debug-level. Authentication or protocol rejections from identified MCP servers produce one bounded warning when their summary changes.
|
|
163
|
-
|
|
164
|
-
Popup settings report storage failures, and delayed old values cannot overwrite a newer choice. A temporary saved-pause read failure can recover on a later connection attempt in the same Worker. Explicit Disconnect stops local connections immediately; a pause-write failure remains visible. Default local auto-connect needs no manual pairing or Connect click.
|
|
120
|
+
See [Connection status and recovery](#connection-status-and-recovery) for build identity and reconnection, and
|
|
121
|
+
[Pairing and local access](#pairing-and-local-access) for token-enforced environments.
|
|
165
122
|
|
|
166
123
|
### Mode 2: CDP Mode (Fallback)
|
|
167
124
|
|
|
@@ -185,12 +142,12 @@ browse(action="open", url="https://example.com")
|
|
|
185
142
|
|
|
186
143
|
## Target: Unified Element Locator
|
|
187
144
|
|
|
188
|
-
All tools use a unified `Target` type for element location. CSS, text, role and label queries traverse open shadow
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
145
|
+
All tools use a unified `Target` type for element location. CSS, text, role and label queries traverse open shadow roots
|
|
146
|
+
in stable order; XPath retains native document-tree semantics. `aria-labelledby` uses IDs from the element's own tree,
|
|
147
|
+
preserves multiple-reference order and takes precedence over `aria-label`. Content-named roles such as `tab`, `checkbox`
|
|
148
|
+
and `menuitem` include visible descendant text, including nested spans. State names use the same rules; ordinary inputs
|
|
149
|
+
retain their current values in `value` and `pageContent`, separately from their names. Password, hidden and file input
|
|
150
|
+
values are not read by state extraction. Closed shadow roots remain outside Extension DOM queries.
|
|
194
151
|
|
|
195
152
|
Examples:
|
|
196
153
|
|
|
@@ -235,7 +192,9 @@ const byXPath = { xpath: "//button[@type='submit']" }
|
|
|
235
192
|
const byCoordinates = { x: 100, y: 200 }
|
|
236
193
|
```
|
|
237
194
|
|
|
238
|
-
Text-only targets choose the innermost complete-text match, including nested text nodes. Explicit XPath preserves
|
|
195
|
+
Text-only targets choose the innermost complete-text match, including nested text nodes. Explicit XPath preserves
|
|
196
|
+
document order. Both backends use display, visibility and nonzero dimensions for visibility; an initially absent
|
|
197
|
+
hidden/detached target succeeds on its first query.
|
|
239
198
|
|
|
240
199
|
In both backends, target lookup failures from `input`, `extract`, and `wait` report the failed locator, zero-based
|
|
241
200
|
`nth`, URL, tab/frame scope, managed state, last locator state, and at most 10 candidate summaries within the request
|
|
@@ -259,10 +218,10 @@ unavailable rather than treating the selected operation target as foreground.
|
|
|
259
218
|
|
|
260
219
|
Page URL fields in these snapshots, browse results, page/window management, state, metadata, and diagnostic bundles
|
|
261
220
|
redact credential query parameters, including `ticket`, and report `urlRedacted`, `urlOriginalLength`, and
|
|
262
|
-
`redactedQueryParameters`. Native `pendingUrl` and `favIconUrl` fields use equivalent field-prefixed markers.
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
221
|
+
`redactedQueryParameters`. Native `pendingUrl` and `favIconUrl` fields use equivalent field-prefixed markers. Navigation
|
|
222
|
+
waits and navigation error messages use the same display redaction. Navigation and `expectedUrl` comparisons use the
|
|
223
|
+
original URL; page content and user-script results retain their requested content. Use `expectedRevision` or an original
|
|
224
|
+
URL you hold for conditions; a redacted display URL cannot serve as `expectedUrl`.
|
|
266
225
|
|
|
267
226
|
When an older Extension lacks `page_snapshot`, unconditional page actions can still use a fresh page-list URL. Their
|
|
268
227
|
`pageContext.before` and `after` snapshots report `revision=null` with a `warning` about the unavailable revision and
|
|
@@ -300,43 +259,84 @@ had partial effects.
|
|
|
300
259
|
|
|
301
260
|
## Request scope and failure handling
|
|
302
261
|
|
|
303
|
-
An input sequence keeps its backend and page through execution and target restoration. CDP binds frame execution to its
|
|
262
|
+
An input sequence keeps its backend and page through execution and target restoration. CDP binds frame execution to its
|
|
263
|
+
context and OOPIF session; Extension checks the document and native iframe owner, so same-URL iframe reordering
|
|
264
|
+
preserves the selected identity. Concurrent `browse(action="connect")` waits for that request scope.
|
|
304
265
|
|
|
305
|
-
Input and evaluate share one budget across queueing, page selection, preparation, dispatch and verification.
|
|
266
|
+
Input and evaluate share one budget across queueing, page selection, preparation, dispatch and verification.
|
|
267
|
+
Cancellation or budget settlement stops queued scripts, remaining events and later context or diagnostic reads. Keys
|
|
268
|
+
newly held by that request are released with a separate bounded cleanup budget. Confirmed final events retain
|
|
269
|
+
`actionStatus="completed"` if later response handling exceeds the deadline; dispatched actions without confirmation
|
|
270
|
+
retain `unknown` and `retryable=false`. Read the current page before deciding on another action.
|
|
306
271
|
|
|
307
|
-
Coordinate input waits for synchronous scroll cascades, including open Shadow roots created during preparation, then
|
|
272
|
+
Coordinate input waits for synchronous scroll cascades, including open Shadow roots created during preparation, then
|
|
273
|
+
reads the current frame-local rectangle. Unrelated requestAnimationFrame scrolling does not keep a stable target
|
|
274
|
+
waiting. Continuous synchronous self-scrolling is bounded by the request deadline, even when the target stays still.
|
|
308
275
|
|
|
309
|
-
MCP cancellation also stops queued window and group changes. The Extension checks the request after asynchronous
|
|
276
|
+
MCP cancellation also stops queued window and group changes. The Extension checks the request after asynchronous
|
|
277
|
+
preflight and before native changes or uncommitted ownership, read-grant and metadata updates. A successful storage
|
|
278
|
+
commit is synchronized to memory; required registration after creation and cleanup after closing still finish. Event-ref
|
|
279
|
+
controls remain available while another page action is waiting.
|
|
310
280
|
|
|
311
|
-
Extract uses the same signal for queueing, page reads and exports. Cookie, log, event, evaluate and extract outputs
|
|
281
|
+
Extract uses the same signal for queueing, page reads and exports. Cookie, log, event, evaluate and extract outputs
|
|
282
|
+
check the signal and deadline during preparation and before publication. Cancellation stops later reads, unpublished
|
|
283
|
+
files and later log manifests; published files remain available and temporary-file cleanup finishes. A completed script
|
|
284
|
+
retains its execution state if its output is stopped.
|
|
312
285
|
|
|
313
286
|
## Operation status and diagnostics
|
|
314
287
|
|
|
315
288
|
Input and evaluate expose execution and verification separately:
|
|
316
289
|
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
| `actionStatus` | `not_started`, `completed`, `failed`, `unknown` | Principal-action outcome |
|
|
321
|
-
| `verificationStatus` | `matched`, `not_matched`, `unavailable`, `error` | Post-condition observation |
|
|
322
|
-
| `failureStage` | Context, precondition, queue, action, verification or output | Stage that failed |
|
|
323
|
-
| `retryable` | Boolean | Whether the principal action can be retried |
|
|
324
|
-
| `diagnosticsStatus` | Status of supplemental diagnostics | Diagnostics keep the primary result and observations collected before failure |
|
|
290
|
+
- `actionExecuted`
|
|
291
|
+
- Values: `false`, `true`, `"unknown"`
|
|
292
|
+
- Meaning: Known principal-action execution fact
|
|
325
293
|
|
|
326
|
-
|
|
294
|
+
- `actionStatus`
|
|
295
|
+
- Values: `not_started`, `completed`, `failed`, `unknown`
|
|
296
|
+
- Meaning: Principal-action outcome
|
|
327
297
|
|
|
328
|
-
|
|
298
|
+
- `verificationStatus`
|
|
299
|
+
- Values: `matched`, `not_matched`, `unavailable`, `error`
|
|
300
|
+
- Meaning: Post-condition observation
|
|
329
301
|
|
|
330
|
-
|
|
302
|
+
- `failureStage`
|
|
303
|
+
- Values: Context, precondition, queue, action, verification or output
|
|
304
|
+
- Meaning: Stage that failed
|
|
305
|
+
|
|
306
|
+
- `retryable`
|
|
307
|
+
- Values: Boolean
|
|
308
|
+
- Meaning: Whether the principal action can be retried
|
|
309
|
+
|
|
310
|
+
- `diagnosticsStatus`
|
|
311
|
+
- Values: Status of supplemental diagnostics
|
|
312
|
+
- Meaning: Diagnostics keep the primary result and observations collected before failure
|
|
313
|
+
|
|
314
|
+
Page-thrown exceptions retain their message text, including empty strings, JSON-shaped text and primitive values, with
|
|
315
|
+
`actionExecuted=true` and `actionStatus="failed"`. Existing exception descriptions and stacks are preserved. Once the
|
|
316
|
+
script's result has resolved, failures during type inspection, diagnostic summaries, or JSON encoding and decoding of
|
|
317
|
+
results and error details report `actionExecuted=true`, `actionStatus="completed"`, `failureStage="output"` and
|
|
318
|
+
`retryable=false`, including in stealth mode. Promise rejection while adopting the return value remains an action
|
|
319
|
+
failure. If an encoded error summary cannot be decoded, `error.context.originalOutputError` retains the first output
|
|
320
|
+
diagnostic.
|
|
321
|
+
|
|
322
|
+
An initial snapshot failure reports `false/not_started`, `failureStage="context"` and
|
|
323
|
+
`pageContext.contextPhase="before"`. A snapshot checking `expectedUrl` or `expectedRevision` uses `precondition` for
|
|
324
|
+
both stage fields. If a target, frame, Challenge, argument or per-event preparation RPC has an unknown receipt or an
|
|
325
|
+
internal evaluate output failure before the principal action is dispatched, the top-level action remains
|
|
326
|
+
`false/not_started/context`; the auxiliary operation keeps its own facts in the error context. Confirmed earlier input
|
|
327
|
+
events remain counted. Late replies do not dispatch or replay the principal action.
|
|
328
|
+
|
|
329
|
+
A page precondition mismatch reports `false/not_started/precondition`. Target diagnostics read the current tab instead
|
|
330
|
+
of cached attach metadata.
|
|
331
331
|
|
|
332
332
|
### Native failures and diagnostics
|
|
333
333
|
|
|
334
|
-
Native script termination, `Internal error`, `Object couldn't be returned by value`, and
|
|
334
|
+
Native browser script termination, `Internal error`, `Object couldn't be returned by value`, and
|
|
335
335
|
`Object reference chain is too long` responses from CDP `Runtime` script commands preserve the original error code.
|
|
336
336
|
evaluate and `manage cdp` return `actionExecuted=true`, `actionStatus="unknown"`, and `retryable=false` without
|
|
337
337
|
replaying the command. evaluate also returns `retryable=false` when an in-flight RPC timeout or stale execution context
|
|
338
|
-
leaves the result unknown; failures before dispatch use their reported `retryable` field. Page-thrown exceptions with
|
|
339
|
-
remain non-retryable action failures.
|
|
338
|
+
leaves the result unknown; failures before dispatch use their reported `retryable` field. Page-thrown exceptions with
|
|
339
|
+
the same text remain non-retryable action failures.
|
|
340
340
|
|
|
341
341
|
Recognized Extension CDP rejections return `CDP_ERROR` with the method, target, native message and available protocol
|
|
342
342
|
code. The context distinguishes a disabled Debugger domain, stale script ID, browser-level command restriction, missing
|
|
@@ -345,6 +345,10 @@ failure does not imply that the entire domain is unsupported. These remain faile
|
|
|
345
345
|
unknown errors retain error-level reporting. A closed tab found during a native snapshot or permission check remains a
|
|
346
346
|
target failure, separate from page-thrown exceptions with matching text.
|
|
347
347
|
|
|
348
|
+
The Extension logs known refusals for restricted-page diagnostics, closed dialogs, expired or mismatched event refs,
|
|
349
|
+
conflicting Cookie partitions, and removed frames as warnings. Each call keeps its original failed response. Page-script
|
|
350
|
+
exceptions and unknown failures stay at error level.
|
|
351
|
+
|
|
348
352
|
## Available Tools (8 Tools)
|
|
349
353
|
|
|
350
354
|
### browse - Browser Management & Navigation
|
|
@@ -368,38 +372,51 @@ creating or closing a browser; supplied launch settings are applied or rejected.
|
|
|
368
372
|
Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
|
|
369
373
|
(whether the tab is controlled by MCP Chrome), `isActive` (Chrome's active tab within its window), `windowId`, `index`,
|
|
370
374
|
`pinned`, `incognito`, and `status` (`loading`/`complete`). Summary mode returns `windowCount` and each window's ordered
|
|
371
|
-
`targetIds`; `details="full"` includes the full native target and window properties. When Chrome has a focused window,
|
|
372
|
-
identifies it and `activeTargetId` identifies its active tab. With no focused Chrome window, both
|
|
373
|
-
each window still reports its own `activeTabId`. `defaultTargetId` identifies the selected operation
|
|
374
|
-
does not infer Chrome's foreground tab from this selection. `open`
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
375
|
+
`targetIds`; `details="full"` includes the full native target and window properties. When Chrome has a focused window,
|
|
376
|
+
`focusedWindowId` identifies it and `activeTargetId` identifies its active tab. With no focused Chrome window, both
|
|
377
|
+
fields are omitted; each window still reports its own `activeTabId`. `defaultTargetId` identifies the selected operation
|
|
378
|
+
target; CDP does not infer Chrome's foreground tab from this selection. When `open` creates a page, it reuses this
|
|
379
|
+
connection's trusted work group. A new group gets a bounded purpose name, cyan color and an expanded state so its pages can run. Independent active connections use separate groups.
|
|
380
|
+
`open`, `back`, `forward`, and `refresh` accept `diagnostics=true` to return new console warnings/errors and failed
|
|
381
|
+
network requests observed during the action, including the first `open` that creates a page automatically. `open` and
|
|
382
|
+
`refresh` honor `wait="load"`, `wait="domcontentloaded"`, and `wait="networkidle"` in both drivers. The wait is
|
|
383
|
+
registered before the command and bound to the new main document, so late lifecycle events from an earlier navigation
|
|
384
|
+
are ignored. CDP `networkidle` waits for the current main-frame loader's `networkIdle` event. Extension `networkidle`
|
|
385
|
+
waits for the current document to complete, all tracked response bodies to finish, and a 500 ms quiet period. Lost
|
|
386
|
+
request tracking causes a timeout instead of a false idle result. `close` requires `targetId` and closes only that page.
|
|
387
|
+
It never closes the entire CDP connection.
|
|
388
|
+
|
|
389
|
+
In Extension mode, `back` and `forward` visit the adjacent history entry in an accessible main document, including
|
|
390
|
+
entries created by earlier `open` calls without user interaction. Traversal uses the browser History API in an isolated
|
|
391
|
+
world and keeps the tab in the background without attaching a debugger. A known direction boundary returns
|
|
392
|
+
`navigated=false` immediately; the Navigation API's direction flags establish a boundary only when its entries cover the
|
|
393
|
+
full browser history. Uncommitted navigations, restricted URLs, browser error pages, and missing main frames retain
|
|
394
|
+
native browser UI history selection without script injection. Native failures and injection failures are preserved, and
|
|
395
|
+
navigation is dispatched at most once. A dispatched traversal with no observed navigation signal returns a timeout with
|
|
396
|
+
an unknown action status. A destroyed execution context or a browser refusing injection into an error page returns an operation
|
|
397
|
+
failure, recorded as a warning in the Extension. Arbitrary debugger commands are never automatically replayed.
|
|
398
|
+
|
|
399
|
+
If a CDP history-navigation command is rejected, the original error is returned and that navigation wait ends
|
|
400
|
+
immediately, keeping later requests available.
|
|
391
401
|
|
|
392
402
|
For `open`, `back`, `forward`, and `refresh`, `timeout` starts at request entry. Target preparation, queueing, protocol
|
|
393
403
|
calls, page loading, Challenge inspection and clicks, diagnostics, and target restoration share the remaining budget;
|
|
394
404
|
navigation RPCs do not add transport time. An expired queued action is not dispatched, and later requests still wait for
|
|
395
405
|
an earlier in-flight action to settle. Explicit `timeout=0` rejects before navigation dispatch. Page creation retains
|
|
396
|
-
its separate load-wait and transport-time contract. When the navigation wait exhausts the request deadline, later
|
|
406
|
+
its separate load-wait and transport-time contract. When the navigation wait exhausts the request deadline, later
|
|
407
|
+
metadata and diagnostic reads stop. A shorter wait timeout leaves the enclosing request's remaining budget available.
|
|
397
408
|
|
|
398
|
-
MCP cancellation stops queued browse actions before dispatch and ends active navigation or Challenge waits. The same
|
|
409
|
+
MCP cancellation stops queued browse actions before dispatch and ends active navigation or Challenge waits. The same
|
|
410
|
+
signal stops later OS mouse commands and CDP launch steps after an interrupted wait; launch cleanup terminates only a
|
|
411
|
+
process created by that request and not yet delivered.
|
|
399
412
|
|
|
400
|
-
If a mouse button was already pressed, the request retains the tab lock until its necessary release completes or the
|
|
413
|
+
If a mouse button was already pressed, the request retains the tab lock until its necessary release completes or the
|
|
414
|
+
independent 5000 ms cleanup budget ends. Subsequent navigation and input remain queued during release. A failed or
|
|
415
|
+
timed-out release reports `releaseStatus="unknown"` with an explicit error; check and release the mouse button before
|
|
416
|
+
continuing.
|
|
401
417
|
|
|
402
|
-
A confirmed navigation keeps `actionExecuted=true` and `actionStatus="completed"` when its later state read fails, with
|
|
418
|
+
A confirmed navigation keeps `actionExecuted=true` and `actionStatus="completed"` when its later state read fails, with
|
|
419
|
+
`failureStage="metadata"` and `retryable=false`; page verification retains its own result.
|
|
403
420
|
|
|
404
421
|
A timeout does not undo a Chrome operation already dispatched. When its result is unknown, the response reports
|
|
405
422
|
`TIMEOUT`, `actionExecuted="unknown"`, `actionStatus="unknown"`, and `retryable=false`; read the actual page state
|
|
@@ -448,30 +465,50 @@ refused for lack of managed access, the revision and any valid ordinary-read gra
|
|
|
448
465
|
`expectedUrl`/`expectedRevision` conditions. A mismatch returns `ACTION_PRECONDITION_FAILED` before reading or updating
|
|
449
466
|
notes. Extension persists `origin=created/adopted/unknown`, creation time and task notes. Existing v1 pages migrate to
|
|
450
467
|
unknown and remain managed. Extension metadata is authoritative after Server restart; storage failures return errors.
|
|
451
|
-
CDP metadata remains local to the Server process. Origin, document identity and trusted native relationships
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
468
|
+
CDP metadata remains local to the Server process. Origin, document identity and trusted native relationships are
|
|
469
|
+
maintained by Extension; notes never grant content access.
|
|
470
|
+
|
|
471
|
+
Start each task with `browse list`, select a suitable page by task name and notes, and attach in the background to reuse
|
|
472
|
+
it. Call `newPage` only when no suitable page exists, supplying `taskHint` and a `note` that identifies temporary,
|
|
473
|
+
output or reusable use. `newPage` always creates a new page.
|
|
474
|
+
|
|
475
|
+
Name the specific object and action or goal in `taskHint`, such as `Fix lane lookup`, `Debug build` or `Test login`.
|
|
476
|
+
Keep the complete meaning: this name identifies pages for reuse and is stored in page metadata, independently of the
|
|
477
|
+
native group title. Keep the same name across pages, sites and stages of one task, and distinguish different tasks by
|
|
478
|
+
purpose. Put HIL/simulation, task IDs, versions, progress and page-specific use in `note`.
|
|
479
|
+
|
|
480
|
+
By default, `newPage` uses an existing normal window and keeps continuous work in the same trusted group across steps.
|
|
481
|
+
Independent active connections use separate groups. After a restart, list and attach a previous work page before
|
|
482
|
+
creating another; its trusted records, native membership and active connection ownership determine group recovery.
|
|
483
|
+
User-created and mixed user groups stay in place.
|
|
484
|
+
|
|
485
|
+
Choose a short purpose name for the work group with the existing `updateGroup` action, such as `MCP · Release`, and
|
|
486
|
+
reuse it for internal subtasks. Keep complete task details in page metadata. A new group initially uses `MCP` plus a
|
|
487
|
+
bounded task hint, URL hostname or `浏览` (Browse); duplicate initial names receive a number. New groups start
|
|
488
|
+
expanded. Page work expands a frozen trusted tool group without selecting a tab; user, mixed and other active connection
|
|
489
|
+
groups stay unchanged. Later creation and metadata changes preserve existing titles, colors and collapsed state. Native moves,
|
|
490
|
+
closure and membership changes clear invalid relationships. With no normal window, creation returns an error; lost
|
|
491
|
+
caches never create a window.
|
|
463
492
|
|
|
464
493
|
At task completion, use the existing close/release actions on an explicit page set. Default cleanup closes only pages
|
|
465
494
|
created for this task whose notes explicitly identify temporary use. Preserve adopted/unknown pages, outputs, reusable
|
|
466
495
|
test pages and mixed user groups; release unused temporary permissions through existing actions. Explicitly authorized
|
|
467
|
-
closure retains the existing managed-page contract. Disconnects and idle periods never close pages. Native
|
|
468
|
-
|
|
469
|
-
Extension; CDP accepts metadata-only `taskHint/note` options.
|
|
496
|
+
closure retains the existing managed-page contract. Disconnects and idle periods never close pages. Native groups
|
|
497
|
+
require Extension; CDP accepts metadata-only `taskHint/note` options.
|
|
470
498
|
|
|
471
|
-
Explicit `networkidle` starts Network observation before navigation
|
|
499
|
+
Explicit `networkidle` starts Network observation before navigation, including URL loading for a new page, and requires
|
|
500
|
+
500 ms of quiet after tracked requests finish. Missing or interrupted observation returns an error. The default `load`
|
|
501
|
+
path does not attach a debugger for network-idle tracking.
|
|
472
502
|
|
|
473
503
|
### Access challenges
|
|
474
504
|
|
|
505
|
+
An incomplete read-only inspection keeps `challengeState="unverified"`. Ordinary titles and headers still wait for the
|
|
506
|
+
visible-content check, with read-only retries within the original request deadline. Expiry without challenge evidence
|
|
507
|
+
returns `TIMEOUT`, `verificationStatus="unavailable"` and `autoRetry=false`; an unknown native inspection
|
|
508
|
+
acknowledgement remains unknown in `verificationActionExecuted` and `verificationActionStatus`. An observed challenge
|
|
509
|
+
retains `CHALLENGE_TIMEOUT` and its observed kind. Completed navigation stays completed; inspection retries do not
|
|
510
|
+
replay navigation or the business action.
|
|
511
|
+
|
|
475
512
|
After `open`, `back`, `forward`, `refresh`, `input`, and `evaluate`, MCP Chrome waits for a Cloudflare JS Challenge or
|
|
476
513
|
Turnstile checkbox. When Extension mode is active, navigation starts without debugger logging. While a Challenge title
|
|
477
514
|
persists, MCP Chrome reads the live tab title passively for the first eight seconds. If the interstitial persists, it
|
|
@@ -487,16 +524,17 @@ clicks target the checkbox on the left of the compact Turnstile card, including
|
|
|
487
524
|
card, not the label. If a Cloudflare iframe is already in the DOM, the OS mouse is used even when that iframe reports a
|
|
488
525
|
zero-size rect, including the later host `Verify you are human` / `请验证您是真人` button. The OS click runs only when
|
|
489
526
|
the managed test tab is already the active tab in an already-focused window; mixed windows are not focused. Debugger is
|
|
490
|
-
detached before the OS click. After movement and hover, the control position, viewport and active window are checked
|
|
491
|
-
before pressing. On Linux, a 1 px native round trip calibrates the current content origin while the debugger
|
|
492
|
-
animates. If the
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
527
|
+
detached before the OS click. After movement and hover, the control position, viewport and active window are checked
|
|
528
|
+
again before pressing. On Linux, a 1 px native round trip calibrates the current content origin while the debugger
|
|
529
|
+
banner animates. If the pointer crosses elements during the animation, calibration samples again within the original
|
|
530
|
+
timeout and accepts an origin only after both trusted events target the same element. If the control moves, the mouse
|
|
531
|
+
repeats the path, hover and calibration before pressing. A changed page, control stage or focus stops the click. Missing OS mouse tools or an unfocused window return a visible
|
|
532
|
+
error instead of a silent CDP click. A Turnstile widget is clicked only after two inspections report the same click
|
|
533
|
+
point; unrelated elements do not become widgets just because their sizes match. Distant OS-mouse paths start near the
|
|
534
|
+
control instead of flying across the screen. The same checkbox or compact widget is clicked at most once; if Cloudflare
|
|
535
|
+
then shows a visible `Verify you are human` or `请验证您是真人` button, that button is inspected as `verify` and clicked
|
|
536
|
+
at most once in the same wait. Use the default `diagnostics=false` for challenge-protected pages because diagnostics
|
|
537
|
+
starts debugger console and network collection.
|
|
500
538
|
|
|
501
539
|
Detection covers titles such as `Just a moment...` and `请稍候…`, visible challenge DOM or body-text markers, and
|
|
502
540
|
`Verify you are human` / `请验证您是真人` controls, including visible `button` elements with that exact text. A normal
|
|
@@ -508,24 +546,25 @@ titles do not decide the result. MCP Chrome does not call a CAPTCHA solver, retr
|
|
|
508
546
|
values. A CDP timeout does not prove that the site fails in a user Chrome session; check the returned `mode` before
|
|
509
547
|
diagnosing the site.
|
|
510
548
|
|
|
511
|
-
A completed embedded widget can retain its container. An associated nonempty response marks that widget complete;
|
|
512
|
-
|
|
513
|
-
|
|
549
|
+
A completed embedded widget can retain its container. An associated nonempty response marks that widget complete; reset
|
|
550
|
+
or expiry returns it to pending. Each widget is checked separately, and a response in another form cannot complete it.
|
|
551
|
+
Detection returns completion state without returning the response value.
|
|
514
552
|
|
|
515
553
|
Input and evaluate check for a new challenge after the action returns, using the remaining budget. A verification
|
|
516
554
|
failure retains the action's completed state and never replays it. If the confirmed final event exhausts the budget,
|
|
517
|
-
`challengeVerificationStatus="unavailable"` explains that no post-action challenge check could run. A post-action
|
|
518
|
-
returns `retryable=false` and `nextAction="wait_and_verify"`; wait for verification and inspect the business
|
|
555
|
+
`challengeVerificationStatus="unavailable"` explains that no post-action challenge check could run. A post-action
|
|
556
|
+
timeout returns `retryable=false` and `nextAction="wait_and_verify"`; wait for verification and inspect the business
|
|
557
|
+
result.
|
|
519
558
|
|
|
520
559
|
A resolved challenge returns `challengeResolved=true`, `challengeKind`, `waitedMs`, `clickedTurnstile`, and
|
|
521
560
|
`clearanceCookiePresent` (name presence only). If the visible page text says verification succeeded and Cloudflare is
|
|
522
561
|
waiting for the origin, the result also has `originResponsePending=true`; verification passed, but the destination page
|
|
523
562
|
is not loaded yet. Hidden template text such as a `display:none` success heading does not count, and a visible Turnstile
|
|
524
563
|
checkbox still counts as pending. Challenge results and errors include `mode`. Before-action timeout returns
|
|
525
|
-
`CHALLENGE_TIMEOUT` with `retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is
|
|
526
|
-
Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP
|
|
527
|
-
cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears
|
|
528
|
-
ordinary iframe document responses and clearing network logs do not.
|
|
564
|
+
`CHALLENGE_TIMEOUT` with `retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is
|
|
565
|
+
not reported as `js`). Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP
|
|
566
|
+
reputation checks cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears
|
|
567
|
+
the header flag; ordinary iframe document responses and clearing network logs do not.
|
|
529
568
|
|
|
530
569
|
### input - Keyboard, Mouse & File Input
|
|
531
570
|
|
|
@@ -549,10 +588,11 @@ Event sequence model supporting arbitrary combinations:
|
|
|
549
588
|
| `editorInsert` | Insert text at the current editor selection |
|
|
550
589
|
| `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
|
|
551
590
|
|
|
552
|
-
On background Extension tabs, a default unmodified left
|
|
553
|
-
`warnings` entry with `isTrusted=false`, without selecting the tab. On a rendered active
|
|
554
|
-
|
|
555
|
-
`manage(action="inputMode",inputMode="stealth")`;
|
|
591
|
+
On background Extension and CDP tabs, a default unmodified click with the left mouse button on an element uses checked
|
|
592
|
+
synthetic events and returns a `warnings` entry with `isTrusted=false`, without selecting the tab. On a rendered active
|
|
593
|
+
tab, precise mode uses native input. Humanized clicks retain their mouse movement. Background Extension coordinate
|
|
594
|
+
clicks, movement, or modified/multiple clicks require explicit `manage(action="inputMode",inputMode="stealth")`;
|
|
595
|
+
mouse-button cleanup remains available.
|
|
556
596
|
|
|
557
597
|
Special-case parameters:
|
|
558
598
|
|
|
@@ -571,33 +611,81 @@ waits for a page state after the events so callers can distinguish dispatched in
|
|
|
571
611
|
`postCondition.timeout` defaults to 3000 ms and is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
|
|
572
612
|
accepts 50-5000 ms. A `postCondition.script` may be an expression, function, async function, or Promise expression;
|
|
573
613
|
functions are invoked and the final Promise value is awaited before matching, while thrown or rejected errors fail the
|
|
574
|
-
check. `targetId` (or legacy `tabId`) selects a page in either backend; `frame` selects an iframe (CSS selector or
|
|
575
|
-
|
|
576
|
-
selected for that target scope.
|
|
577
|
-
|
|
578
|
-
Text, selector and URL checks recover a transient lost context within the remaining input and verification deadlines. A
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
614
|
+
check. `targetId` (or legacy `tabId`) selects a page in either backend; `frame` selects an iframe (CSS selector or index
|
|
615
|
+
or a nested path) in either backend. When either scope is provided, the action, diagnostics, and post-condition use the
|
|
616
|
+
backend selected for that target scope.
|
|
617
|
+
|
|
618
|
+
Text, selector and URL checks recover a transient lost context within the remaining input and verification deadlines. A
|
|
619
|
+
context that stays unavailable, a closed native connection, or an exhausted read budget returns
|
|
620
|
+
`verificationStatus="unavailable"`. Script checks report native context failures immediately. Native execution
|
|
621
|
+
termination and engine execution timeouts during verification return `unavailable` in both Extension and CDP. Selector
|
|
622
|
+
syntax errors and page-thrown or rejected errors return `error`, including when an exception's string conversion also
|
|
623
|
+
throws. Error text mentioning a frame or timeout does not change the source. A completed input keeps
|
|
624
|
+
`actionStatus="completed"`, `failureStage="verification"` and top-level `retryable=false`. Use `postCondition.retryable`
|
|
625
|
+
to retry the check on its own. Verification shares the action's total deadline; an exhausted total budget starts no new
|
|
626
|
+
check.
|
|
627
|
+
|
|
628
|
+
Cancellation interrupts verification reads and polling waits. Input then attempts a bounded release of keys newly
|
|
629
|
+
pressed by that request before the next queued action starts. Keys held before the request remain held; release failures
|
|
630
|
+
retain a diagnostic.
|
|
631
|
+
|
|
632
|
+
Text checks match rendered page text and visible, non-password form values. The bounded `actual` excerpt includes the
|
|
633
|
+
matched text. Clicks on a Shadow host accept its own shadow descendants; synthetic click, key and input events reach
|
|
634
|
+
host and document listeners, while mouseenter and change retain their local event semantics.
|
|
635
|
+
|
|
636
|
+
Coordinate targets use the selected frame's viewport coordinates. Native precise input accounts for the frame's content
|
|
637
|
+
boundary, scaling, rotation, skew and nested placement; input whose coordinates cannot be mapped reliably fails before
|
|
638
|
+
the affected event. Earlier completed events retain their progress. Stealth events keep frame-local coordinates.
|
|
639
|
+
|
|
640
|
+
Target-based coordinate preparation follows assigned slots and Shadow hosts to the actual scroll container. On visible
|
|
641
|
+
pages, it checks the target rectangle and ancestor scroll positions across consecutive renders, including cascades
|
|
642
|
+
triggered by page listeners that stop event propagation. A stable target remains actionable beside a looping, unrelated
|
|
643
|
+
scroller. A page hidden during this wait uses its current layout without waiting for paused animation frames; a page
|
|
644
|
+
that becomes visible resumes render checks. Continuous target motion or ancestor scrolling can exhaust the shared
|
|
645
|
+
request deadline, leaving that event undispatched.
|
|
646
|
+
|
|
647
|
+
An omitted wheel target keeps the current mouse position. Extension wheel helper setup and input target the same
|
|
648
|
+
resolved documentId; replacement or removal before input returns not_started without selecting the new document.
|
|
649
|
+
|
|
650
|
+
Wheel and mouse events carry the currently held Ctrl, Shift, Alt and Meta fields, including combined modifiers and
|
|
651
|
+
precise right-click events that use synthetic dispatch. Synthetic events retain `isTrusted=false`; application listeners
|
|
652
|
+
can inspect the modifier fields and cancel their default scroll.
|
|
653
|
+
|
|
654
|
+
Extension coordinate wheel follows each axis's effective scroll range, including reverse Flex layouts and vertical
|
|
655
|
+
writing modes. Fractional deltas accumulate across consecutive inputs to the same scroll container, including changes to
|
|
656
|
+
the hit descendant and scrolling performed by that wheel listener. Position changes between inputs reset that
|
|
657
|
+
container's pending fraction; another container or document starts its own sequence. Native scroll progress identifies
|
|
658
|
+
fractional endpoints under CSS zoom. When native progress is unavailable, a console warning identifies the CSSOM-bounds
|
|
659
|
+
compatibility path. Element scroll distances account for effective CSS zoom; ordinary transform scale keeps its existing
|
|
660
|
+
wheel-distance semantics. Viewport scrolling uses its own units.
|
|
661
|
+
|
|
662
|
+
Scroll-container eligibility accounts for the namespace, principal box and text-editing controls. MathML math layouts,
|
|
663
|
+
flow-root and inline flow-root list items, block ruby and Chrome-supported `-webkit-box`/`-webkit-inline-box` layouts
|
|
664
|
+
retain their scrolling and boundary behavior. A text input can scroll its internal text even when Chrome reports
|
|
665
|
+
computed overflow as clip. A block SVG viewport does not become a CSS scroll boundary from hidden/contain declarations;
|
|
666
|
+
a foreignObject with a scrolling box retains its own auto scrolling and hidden contain/none boundary, and embedded HTML
|
|
667
|
+
retains its own scrolling behavior. At a real container boundary, `overscroll-behavior-x/y: contain` or `none` stops
|
|
668
|
+
that axis, including zero-range containers; `auto` lets an unconsumed axis continue along the original chain. A nested
|
|
669
|
+
`overflow:hidden` container keeps its boundary policy without scrolling itself; ordinary clip/visible, non-atomic inline
|
|
670
|
+
and display:contents nodes do not add that boundary.
|
|
671
|
+
|
|
672
|
+
The viewport follows root/body overflow propagation. A body with no principal box, including display:contents, does not
|
|
673
|
+
supply its overflow. Effective containment on html/body, including content-visibility or container-type, keeps the body
|
|
674
|
+
independent. A body supplying viewport overflow is not a separate boundary, and hidden/clip viewport axes do not scroll.
|
|
675
|
+
A scrollable target consumes its own input first. Absolute/fixed targets then follow the nearest applicable positioning
|
|
676
|
+
containing block through the composed tree, including slots and foreignObject content. Transform, filter, containment,
|
|
677
|
+
3D/motion conditions and applicable will-change names keep their own box-eligibility rules.
|
|
678
|
+
|
|
679
|
+
The composed, cancelable wheel event reaches Shadow host and document listeners. Effective `preventDefault()` suppresses
|
|
680
|
+
the simulated default scroll; the event still reports `actionStatus="completed"` and counts as one executed input. Each
|
|
681
|
+
axis selects its scroll route from the boundary at input start. A listener that resizes or repositions a scroll
|
|
682
|
+
container retains its own changes; the default action uses the resulting position on the selected route. A container
|
|
683
|
+
that loses its scroll range lets unconsumed input continue along the original chain under its overscroll policy.
|
|
684
|
+
Removing or moving the hit element does not redirect that wheel to a newly inserted ancestor or an unrelated viewport.
|
|
685
|
+
|
|
686
|
+
Extension wheel uses programmatic scrolling for its default action. Scroll snapping follows that programmatic endpoint,
|
|
687
|
+
which can differ from native wheel intent. Mandatory and proximity snap layouts retain their declared snapping; native
|
|
688
|
+
wheel endpoint differences are an accepted compatibility behavior.
|
|
601
689
|
|
|
602
690
|
For keyboard `type`, `timeout` includes Challenge waiting, focus preparation, character input, and `delay`/`humanize`
|
|
603
691
|
delays. Extension precise/stealth and CDP use the remaining budget. An explicit budget such as `timeout=45000` allows
|
|
@@ -610,9 +698,15 @@ Mouse target lookup, stepped movement, and `humanize` delays also share the rema
|
|
|
610
698
|
the subsequent click check the deadline; expiry stops further movement and clicking. Already dispatched native events
|
|
611
699
|
cannot be undone. Read the page independently after an unknown result instead of replaying the action.
|
|
612
700
|
|
|
613
|
-
|
|
701
|
+
Extension precise `type` in keyboard mode and `keydown`/`keyup` events use native keyboard input. Focus preparation
|
|
702
|
+
shares the remaining request budget. When focus emulation is needed, response `warnings` explains that the document temporarily reports
|
|
703
|
+
`visible`; the actual tab and window focus stay unchanged. The original setting is restored before `postCondition` runs.
|
|
614
704
|
|
|
615
|
-
A recovered debugger session with an unknown original focus setting on a background tab returns
|
|
705
|
+
A recovered debugger session with an unknown original focus setting on a background tab returns
|
|
706
|
+
`KEYBOARD_FOCUS_STATE_UNKNOWN` and `not_started`, preserving that setting. Explicit stealth or an independent CDP
|
|
707
|
+
session remain available. Restoration failures return `keyboardFocusCleanup`; completed events retain `completed`, and
|
|
708
|
+
unconfirmed dispatch retains `unknown`. Failure, cancellation or expiry attempts to release keys newly pressed by this
|
|
709
|
+
request. Successful requests preserve intentionally held keys.
|
|
616
710
|
|
|
617
711
|
Command focus, text selection, and replacement share the remaining event budget. Expiry stops subsequent actions; Shift
|
|
618
712
|
release is still attempted without hiding an earlier action error. Stepped CDP touch movement also stops at the
|
|
@@ -625,8 +719,8 @@ events follow the same button mapping.
|
|
|
625
719
|
In stealth mode, `delay` separates characters; the first character has no initial wait. Background page timer throttling
|
|
626
720
|
can lengthen subsequent intervals, but the same deadline still stops further input.
|
|
627
721
|
|
|
628
|
-
Default precise keyboard `type` in Extension and CDP mode dispatches Enter for each newline (CRLF is normalized).
|
|
629
|
-
|
|
722
|
+
Default precise keyboard `type` in Extension and CDP mode dispatches Enter for each newline (CRLF is normalized). An
|
|
723
|
+
editor that submits on Enter can therefore submit part of a multiline input. For multiline replacement in Extension
|
|
630
724
|
mode, use `mode="controlled"` (or `dispatch=true`) with a `target`: it replaces the complete value or contenteditable
|
|
631
725
|
text and dispatches input/change without Enter. Form controls keep their native value setters.
|
|
632
726
|
|
|
@@ -640,15 +734,28 @@ them. Visibility, enabled-state, viewport, and click coverage checks still apply
|
|
|
640
734
|
and the final coordinate read share the remaining event budget. If any of these stages exhausts it, no mouse or keyboard
|
|
641
735
|
event is dispatched.
|
|
642
736
|
|
|
643
|
-
**`click`-specific**: `force: true` requires `forceReason` and a non-coordinate element `target`. It skips actionability
|
|
737
|
+
**`click`-specific**: `force: true` requires `forceReason` and a non-coordinate element `target`. It skips actionability
|
|
738
|
+
checks while dispatching standard DOM mouse events. Middle/right and multiple clicks use the same rules; a coordinate or
|
|
739
|
+
omitted target cannot use force. Failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering elements,
|
|
740
|
+
candidate blockers and suggestions.
|
|
644
741
|
|
|
645
|
-
**`type`-specific**: `mode="controlled"` or `dispatch:true` replaces the value or contenteditable text and sends
|
|
742
|
+
**`type`-specific**: `mode="controlled"` or `dispatch:true` replaces the value or contenteditable text and sends
|
|
743
|
+
`input`/`change` without Enter. It requires a non-coordinate `target` and Extension mode. Targets must be HTML `input`,
|
|
744
|
+
`textarea`, `select` or contenteditable; effectively disabled controls, readonly controls, unsupported containers and
|
|
745
|
+
file inputs are rejected before focus or input events. Disabled fieldsets follow HTML rules, including the first-legend
|
|
746
|
+
exception. Use `upload` for a file input. Ordinary controls, customized built-ins and same-origin controls adopted from
|
|
747
|
+
another document use the native value setter for their actual form interface; an unavailable setter returns an error
|
|
748
|
+
before focus.
|
|
646
749
|
|
|
647
|
-
Controlled input and target-lookup failures return `locator`, `matchCount`, `nth`, bounded `candidates` and an
|
|
750
|
+
Controlled input and target-lookup failures return `locator`, `matchCount`, `nth`, bounded `candidates` and an
|
|
751
|
+
`activeElement` summary without input values. Unavailable focus is `null`; a failed DOM query adds `diagnosticError`.
|
|
648
752
|
|
|
649
|
-
Cancellation or expiry after a confirmed Extension precise character or Enter event preserves executed progress and
|
|
753
|
+
Cancellation or expiry after a confirmed Extension precise character or Enter event preserves executed progress and
|
|
754
|
+
invalidates the old page revision. Cancellation before the first dispatch keeps the not-started state. Read the current
|
|
755
|
+
value and revision before another action.
|
|
650
756
|
|
|
651
|
-
For a tag field that commits on Enter, send the text and explicit Enter events, then check the created tag. This `input`
|
|
757
|
+
For a tag field that commits on Enter, send the text and explicit Enter events, then check the created tag. This `input`
|
|
758
|
+
example uses `#tag-entry` for the field and `#tags` for its tag list; use the selectors from the page:
|
|
652
759
|
|
|
653
760
|
```json
|
|
654
761
|
{
|
|
@@ -663,11 +770,25 @@ For a tag field that commits on Enter, send the text and explicit Enter events,
|
|
|
663
770
|
|
|
664
771
|
#### Text selection and sensitive input
|
|
665
772
|
|
|
666
|
-
`replace` uses text selection for `textarea` and input types `text`, `search`, `tel`, `url` and `password`. Other input
|
|
773
|
+
`replace` uses text selection for `textarea` and input types `text`, `search`, `tel`, `url` and `password`. Other input
|
|
774
|
+
types use a native full-value update and return requested and actual browser-normalized values. Standalone `select` on
|
|
775
|
+
an unsupported type returns `UNSUPPORTED_SELECTION`. CDP locator targets are focused through CDP rather than Extension
|
|
776
|
+
ref IDs.
|
|
777
|
+
|
|
778
|
+
Event-level `nth` selects a text occurrence; nested `target.nth` selects a matching element. Both are zero-based and can
|
|
779
|
+
be combined. Selection errors include editor and selection state.
|
|
667
780
|
|
|
668
|
-
|
|
781
|
+
Coordinate `select`/`replace` uses the control or text scope hit at that point, independently of the previous focus.
|
|
782
|
+
Replacement rechecks the selected element and selection ownership immediately before writing. Removal, focus moving to
|
|
783
|
+
another control or a selection leaving the target stops the write. A changed full-value target returns
|
|
784
|
+
`TARGET_FOCUS_FAILED`; a changed text selection returns `TEXT_SELECTION_CHANGED`. Readonly, disabled and unsupported
|
|
785
|
+
selection controls retain their rejection rules; matching text and selections in other controls stay unchanged.
|
|
669
786
|
|
|
670
|
-
Password values are omitted from failure context and text post-condition observations; failed input responses also
|
|
787
|
+
Password values are omitted from failure context and text post-condition observations; failed input responses also
|
|
788
|
+
redact supplied `find` and replacement `text`, including locator details in `error.logs`. Password `select`/`replace`
|
|
789
|
+
hides console and network diagnostic bodies on success and failure, returning `diagnostics.redacted=true` and
|
|
790
|
+
`reason="sensitive_input_or_unresolved_target"`. An unresolved selection target receives the same protection. Ordinary
|
|
791
|
+
input keeps its diagnostics, and password protection ends with the current input request.
|
|
671
792
|
|
|
672
793
|
#### Upload local files
|
|
673
794
|
|
|
@@ -700,9 +821,10 @@ Use multiple paths for an input with the `multiple` attribute. Use `files:[]` to
|
|
|
700
821
|
```
|
|
701
822
|
|
|
702
823
|
The target must be an `input[type=file]`. Hidden file inputs work without clicking or opening a system file chooser.
|
|
703
|
-
Existing element locators and `target.nth` select the input; `frame` selects a child or nested iframe in either backend.
|
|
704
|
-
Extension or CDP connection and the selected input mode. Default precise mode supports strict
|
|
705
|
-
the page's CSP restrictions. Extension upload requires managed-page access, checked before any
|
|
824
|
+
Existing element locators and `target.nth` select the input; `frame` selects a child or nested iframe in either backend.
|
|
825
|
+
Uploads use the current Extension or CDP connection and the selected input mode. Default precise mode supports strict
|
|
826
|
+
CSP pages; stealth keeps the page's CSP restrictions. Extension upload requires managed-page access, checked before any
|
|
827
|
+
local file read.
|
|
706
828
|
|
|
707
829
|
The result summarizes the selected file names, sizes, MIME types, and dispatched events. The input receives `input`
|
|
708
830
|
followed by `change`, using synthetic events. Sites requiring trusted events need site-specific verification. A page
|
|
@@ -730,23 +852,65 @@ Text extraction uses the browser's `innerText` for HTML pages and selected eleme
|
|
|
730
852
|
`style`/`script` source and hidden descendants. Explicitly selected non-rendered HTML follows the browser's `innerText`
|
|
731
853
|
rules; SVG/XML nodes use `textContent`. Use `html` for source markup.
|
|
732
854
|
|
|
733
|
-
####
|
|
855
|
+
#### Text windows
|
|
734
856
|
|
|
735
|
-
`
|
|
857
|
+
`extract(type="text", maxChars=12000, offset=0)` returns that UTF-16 text window with `totalLength`, `nextOffset` and
|
|
858
|
+
`truncated`. Use `nextOffset` for the next read. Each request reads the current page; changing page text can change
|
|
859
|
+
subsequent offsets. With `output`, the file contains the requested window. Omitting both parameters retains the
|
|
860
|
+
full-text response and full-text file behavior.
|
|
736
861
|
|
|
737
|
-
####
|
|
862
|
+
#### HTML and images
|
|
738
863
|
|
|
739
|
-
|
|
864
|
+
`output` saves to a file, or a directory for `images=data`. `images=info|data` includes image metadata or bytes with
|
|
865
|
+
HTML. Image data is limited to 2 MiB per image and 8 MiB per request. Directory export reads and writes one image at a
|
|
866
|
+
time; each index entry records an `omitted` reason for unavailable or over-budget data. Inline output keeps the first 20
|
|
867
|
+
images with the same reasons and byte budgets. `frameHtml` reads the current document after `frame` routing. HTML with
|
|
868
|
+
images applies the full semantic locator, exact match and nth index to its final element selection.
|
|
740
869
|
|
|
741
|
-
|
|
870
|
+
#### Screenshots
|
|
742
871
|
|
|
743
|
-
|
|
872
|
+
Use `clip` for a coordinate region, `compareWith` for a PNG baseline and `diffOutput` for a PNG difference image.
|
|
873
|
+
`diffOutput` requires `compareWith`. An unmatched, out-of-range or zero-sized target returns a target error. Responses
|
|
874
|
+
contain `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip` and
|
|
875
|
+
`capabilities`.
|
|
876
|
+
|
|
877
|
+
Capture limits are 16,384 pixels per side, 12,000,000 pixels total, 48 MiB estimated RGBA memory and 25 MiB encoded
|
|
878
|
+
data. Oversized captures return `SCREENSHOT_BUDGET_EXCEEDED` with the applicable limits. PNG baselines are checked
|
|
879
|
+
before reading. Comparison limits each PNG to 25 MiB and 12,000,000 pixels; inflate output and scanline lengths must
|
|
880
|
+
match the validated dimensions. Malformed or expansion-heavy PNGs are rejected. Use `clip` or `scale` for larger
|
|
881
|
+
captures.
|
|
882
|
+
|
|
883
|
+
Screenshot and diagnostic-bundle capabilities report `hiddenTabScreenshot=false` in both backends. A hidden Extension
|
|
884
|
+
tab returns `HIDDEN_TAB_SCREENSHOT`. Full-page capture preserves viewport and device emulation. If another debugger
|
|
885
|
+
blocks precise capture, viewport fallback reports `metadata.degraded`, `metadata.fallback` and `metadata.limitations` in
|
|
886
|
+
inline and file output. A window-level capture is discarded when the active tab changes, including A-to-B-to-A.
|
|
887
|
+
Unsupported fallback options return `SCREENSHOT_FALLBACK_UNSUPPORTED`.
|
|
888
|
+
|
|
889
|
+
Element screenshots use the painted intersection with overflow ancestors according to the actual positioning containing
|
|
890
|
+
block, including direct absolute targets and normal-flow descendants inside absolute/fixed ancestors. Scroll positions
|
|
891
|
+
and viewport size stay unchanged. Cropped captures report `clippedToVisibleArea=true`; an entirely clipped target
|
|
892
|
+
returns `ELEMENT_NOT_VISIBLE`. Unmappable transformed overflow geometry returns `FRAME_GEOMETRY_UNAVAILABLE`.
|
|
893
|
+
|
|
894
|
+
Extension automatic iframe crops require an available translation-only offset. Motion-path rotation on the iframe or
|
|
895
|
+
its composed ancestors returns `FRAME_GEOMETRY_UNAVAILABLE`; a motion path with explicit zero rotation keeps the
|
|
896
|
+
translation mapping. CDP maps all target corners through native frame geometry; unavailable or non-affine mappings
|
|
897
|
+
return `FRAME_GEOMETRY_UNAVAILABLE`. Both backends add
|
|
898
|
+
root-page scrolling to the root-viewport rectangle to obtain the page-coordinate clip, then restore the previous frame;
|
|
899
|
+
Extension also restores its documentId. Explicit `clip` uses root-page coordinates.
|
|
744
900
|
|
|
745
901
|
#### State and metadata
|
|
746
902
|
|
|
747
|
-
`state` returns `interactiveElements`. Both backends return metadata `frames` and the actual document `url`; Extension
|
|
903
|
+
`state` returns `interactiveElements`. Both backends return metadata `frames` and the actual document `url`; Extension
|
|
904
|
+
`frame` routing returns the selected document's URL. Unavailable declared CDP frame fields remain `null`, including DOM
|
|
905
|
+
selectors and owner rectangles. Frame-tree order and IDs are preserved.
|
|
748
906
|
|
|
749
|
-
Metadata includes current `managed` state and `createdBy`, `createdAt`, `lastUsedAt`, `taskHint` and `note`, matching
|
|
907
|
+
Metadata includes current `managed` state and `createdBy`, `createdAt`, `lastUsedAt`, `taskHint` and `note`, matching
|
|
908
|
+
`browse list` and `manage pageMetadata` in both inline and file output. Notes belong to the page even when `frame`
|
|
909
|
+
selects an iframe document. Extension preserves creation records, notes and trusted group relationships across Server
|
|
910
|
+
and Extension reloads, checking live identity during restoration. Another Extension Server reads the same saved
|
|
911
|
+
metadata. CDP notes belong to the current Server process; a new CDP Server starts with unknown provenance and no task
|
|
912
|
+
notes. Unknown provenance stays `unknown`; notes grant no access or cross-session ownership. CDP returns `managed=false` while
|
|
913
|
+
retaining normal operations through its connection.
|
|
750
914
|
|
|
751
915
|
Page selection uses `targetId` or legacy `tabId`; `frame` selects a child or nested document in either backend.
|
|
752
916
|
|
|
@@ -761,13 +925,18 @@ page/frame preparation, target waiting, content reads, and page-context metadata
|
|
|
761
925
|
**`state`-specific**: `depth` controls accessibility-tree traversal depth (default 15). Reduce it to limit response size
|
|
762
926
|
on large pages. `mode` selects `accessibility` (default, derived from the a11y tree) or `domsnapshot` (raw
|
|
763
927
|
`DOMSnapshot.captureSnapshot`, available through CDP or a managed Extension page). DOMSnapshot captures the whole page
|
|
764
|
-
and rejects `target`, `frame`, and `depth`. Ordinary read grants cover accessibility state; Extension DOMSnapshot
|
|
765
|
-
Unavailable sibling iframe probes are listed in metadata as
|
|
766
|
-
`unavailableReason`; a uniquely verified selected iframe remains usable.
|
|
928
|
+
and rejects `target`, `frame`, and `depth`. Ordinary read grants cover accessibility state; Extension DOMSnapshot
|
|
929
|
+
requires full managed access to use the debugger. Unavailable sibling iframe probes are listed in metadata as
|
|
930
|
+
`unavailableFrames` and per-frame `unavailableReason`; a uniquely verified selected iframe remains usable.
|
|
767
931
|
|
|
768
|
-
`target` restricts accessibility state to the selected element and its descendants in both backends. `depth` is relative
|
|
932
|
+
`target` restricts accessibility state to the selected element and its descendants in both backends. `depth` is relative
|
|
933
|
+
to that subtree. On background CDP documents, role/name lookup uses the browser's accessibility snapshot for the selected
|
|
934
|
+
frame and preserves substring, exact-name and `nth` matching without selecting the tab.
|
|
769
935
|
|
|
770
|
-
Accessibility state does not read hidden/password/file input value getters for element names or state text, including
|
|
936
|
+
Accessibility state does not read hidden/password/file input value getters for element names or state text, including
|
|
937
|
+
default `all`, subtrees and file output. Hidden controls retain their labels and `visible=false`. Labels, placeholders
|
|
938
|
+
and titles provide names; ordinary inputs retain current values separately in `value` and `pageContent`, including named
|
|
939
|
+
inputs. Submit labels retain their full text. Explicit script, HTML and attribute reads keep their existing behavior.
|
|
771
940
|
|
|
772
941
|
### wait - Wait for Conditions
|
|
773
942
|
|
|
@@ -778,7 +947,8 @@ Accessibility state does not read hidden/password/file input value getters for e
|
|
|
778
947
|
| `time` | Fixed delay |
|
|
779
948
|
| `idle` | Wait for DOM or network quiet period |
|
|
780
949
|
|
|
781
|
-
Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects a child document or nested path in
|
|
950
|
+
Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects a child document or nested path in
|
|
951
|
+
either backend.
|
|
782
952
|
|
|
783
953
|
In CDP mode, `visible` requires a nonzero DOM rectangle and CSS that does not hide the element (`display:none` or
|
|
784
954
|
`visibility:hidden/collapse`). `hidden` accepts these hidden states or a missing element; `attached` and `detached` only
|
|
@@ -788,7 +958,9 @@ check whether the element exists.
|
|
|
788
958
|
a quiet period with no DOM changes. In CDP mode, it waits for network quiet instead. `ms` controls the relevant quiet
|
|
789
959
|
period (default 500ms). The response returns `idleKind` and `idlePeriodMs`; Extension responses also return `domStable`.
|
|
790
960
|
|
|
791
|
-
CDP idle includes requests already in flight. Independent idle and same-document `networkidle` exclude Worker requests
|
|
961
|
+
CDP idle includes requests already in flight. Independent idle and same-document `networkidle` exclude Worker requests
|
|
962
|
+
with an empty `loaderId`, whose terminal events can be absent from the page session; page Fetch and Script requests
|
|
963
|
+
remain pending until completion.
|
|
792
964
|
|
|
793
965
|
### evaluate - JavaScript Execution
|
|
794
966
|
|
|
@@ -817,31 +989,49 @@ such as `textContent` or `outerHTML`. Result materialization and serialization f
|
|
|
817
989
|
`actionStatus="completed"`, and `failureStage="output"` because the page script has already finished. Evaluate defaults
|
|
818
990
|
to `precise` even when global `inputMode` is `stealth`, and its `postCondition` checks use the same evaluate mode as the
|
|
819
991
|
action. `postCondition` is optional; when it is not provided, `success=true` only means the script executed and
|
|
820
|
-
returned. With a post-condition, `verificationStatus` distinguishes `matched`, `not_matched`, `unavailable` and `error`,
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
`
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
992
|
+
returned. With a post-condition, `verificationStatus` distinguishes `matched`, `not_matched`, `unavailable` and `error`,
|
|
993
|
+
with the last observed checks. A completed script keeps `actionStatus="completed"` and top-level `retryable=false`;
|
|
994
|
+
`postCondition.retryable` applies only to an independent verification read. Precise iframe evaluation does not replay a
|
|
995
|
+
script after a stale execution context by default. Set `staleContextRetry="readOnly"` only when the script has no side
|
|
996
|
+
effects; the Extension may then resolve a new context and replay it once within the remaining timeout budget. If Chrome
|
|
997
|
+
still reports the removed document while resolving that retry, the Extension waits for the current document within the
|
|
998
|
+
same budget; this does not add script executions. Permission failures stop immediately. CDP iframe execution supports
|
|
999
|
+
`never`; requesting `readOnly` returns `DRIVER_CAPABILITY_ERROR` with `actionExecuted=false` and
|
|
1000
|
+
`actionStatus="not_started"` before script dispatch. A stale-context error after `Runtime.evaluate` reports
|
|
1001
|
+
`actionExecuted=true`, `actionStatus="unknown"` and `retryable=false` in both backends, because earlier side effects may
|
|
1002
|
+
already have happened even though the final result is unavailable. CDP preserves its native `CDP_ERROR`. Built-in
|
|
1003
|
+
post-condition reads use `never` on CDP and `readOnly` on Extension; the verifier polls stale read contexts
|
|
1004
|
+
independently of the completed action.
|
|
1005
|
+
|
|
1006
|
+
The total evaluate timeout also limits post-condition checks. If it expires after the action completes, the action stays
|
|
1007
|
+
completed and verification returns unavailable. A queue timeout before script dispatch preserves `actionExecuted=false`
|
|
1008
|
+
and the queue stage; a dispatched script with an unknown acknowledgement stays unknown. Read the page independently to
|
|
1009
|
+
determine its effects.
|
|
831
1010
|
|
|
832
1011
|
For object results in the main frame with Extension precise mode, an explicit `output` uses a 16 Mi (16777216) character
|
|
833
|
-
budget. Without `output`, the 1000000-character
|
|
834
|
-
|
|
835
|
-
units, not the output file's UTF-8 bytes; `tmp:` files also remain subject to the temporary output quota.
|
|
836
|
-
result limit reports the current limit and the completed script's output failure without replaying it.
|
|
1012
|
+
budget, a depth limit of 64 and a 100000-node budget. Without `output`, the 1000000-character, depth-8 and 2000-node
|
|
1013
|
+
budgets still apply, including automatic saving. Both paths reject non-serializable results. The character budget counts
|
|
1014
|
+
UTF-16 code units, not the output file's UTF-8 bytes; `tmp:` files also remain subject to the temporary output quota.
|
|
1015
|
+
Exceeding a result limit reports the current limit and the completed script's output failure without replaying it.
|
|
837
1016
|
|
|
838
|
-
|
|
1017
|
+
Request summaries retain in-flight completion and failure records across temporary target selection.
|
|
839
1018
|
|
|
840
|
-
|
|
1019
|
+
Absolute `scriptFile` and `output` paths must resolve inside the Server working directory or this Server session's
|
|
1020
|
+
controlled temporary directory. The operating system's whole temp directory and Downloads are not automatic allowed
|
|
1021
|
+
roots. `PATH_NOT_ALLOWED` reports the actual `error.context.allowedRoots`; use `cwd:` or `tmp:` paths within them.
|
|
841
1022
|
|
|
842
|
-
|
|
1023
|
+
Responses include the stale-context policy, `retryAttempted`, bounded `retryReason` and the final `frameContext`:
|
|
1024
|
+
Extension frame, parent frame, URL, CDP frame and execution-context IDs. Same-URL frames are rejected only when the
|
|
1025
|
+
selected DOM iframe cannot identify one target. Existing iframe targets remain usable after an Extension reload without
|
|
1026
|
+
refreshing or navigating the page. Invalidated probe contexts report a warning and stop listening.
|
|
843
1027
|
|
|
844
|
-
|
|
1028
|
+
Sibling frames still loading do not delay selection of an available iframe. Background-page timer throttling does not
|
|
1029
|
+
extend the frame-probe wait. Cancellation or timeout before script dispatch releases the probes and leaves that script
|
|
1030
|
+
unexecuted.
|
|
1031
|
+
|
|
1032
|
+
A trusted Function-compilation policy rejection reports `CSP_BLOCKED` with the script not executed. Page `throw` or
|
|
1033
|
+
Promise rejection keeps its original error and executed state even when the text contains `CSP`,
|
|
1034
|
+
`Content Security Policy` or `unsafe-eval`.
|
|
845
1035
|
|
|
846
1036
|
### manage - Page & Environment Management
|
|
847
1037
|
|
|
@@ -888,11 +1078,10 @@ results also include `tabsBefore/tabsAfter`; `ungroupPages` removes an empty gro
|
|
|
888
1078
|
tabs' managed state. Window display changes and group title/color/collapse updates use the explicit `windowId` or
|
|
889
1079
|
`groupId`, including containers with unmanaged members. They do not grant page permissions. Group moves and window
|
|
890
1080
|
closure still require every affected member to be managed. Grouping or ungrouping selected pages checks those pages;
|
|
891
|
-
unrelated sibling changes do not invalidate a valid selection. Default page creation uses an existing normal
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
`focusWindow` only returns success after the target window is observed as focused; otherwise it returns
|
|
1081
|
+
unrelated sibling changes do not invalidate a valid selection. Default page creation uses an existing normal window in
|
|
1082
|
+
the background, including windows with unmanaged tabs. `clearCache` is unavailable in Extension mode and returns
|
|
1083
|
+
`UNSUPPORTED_MODE` without clearing anything. Use scoped `cookies(action="clear")` for cookies or CDP mode for storage
|
|
1084
|
+
and cache. `focusWindow` only returns success after the target window is observed as focused; otherwise it returns
|
|
896
1085
|
`WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with unmanaged tabs and returns
|
|
897
1086
|
`WINDOW_HAS_UNMANAGED_TABS`. Persistent `adoptPage` and `releasePage` target changes are serialized with scoped tab
|
|
898
1087
|
operations, so a concurrent multi-event input remains on its requested tab and the persistent target is applied
|
|
@@ -907,25 +1096,24 @@ conditions.
|
|
|
907
1096
|
|
|
908
1097
|
#### `newPage`
|
|
909
1098
|
|
|
910
|
-
Parameters: `url`, `windowId`, `index`, `active`, `pinned`, `openerTabId`, `groupId`, `timeout`, `taskHint`,
|
|
911
|
-
`note`
|
|
1099
|
+
Parameters: `url`, `windowId`, `index`, `active`, `pinned`, `openerTabId`, `groupId`, `timeout`, `taskHint`, `note`
|
|
912
1100
|
|
|
913
|
-
`active` defaults to false; `groupId=-1` disables grouping; explicit placement is not changed by the default
|
|
914
|
-
|
|
1101
|
+
`active` defaults to false; `groupId=-1` disables grouping; explicit placement is not changed by the default visual
|
|
1102
|
+
group
|
|
915
1103
|
|
|
916
1104
|
#### `updatePage`
|
|
917
1105
|
|
|
918
1106
|
Parameters: `url`, `active`, `pinned`, `highlighted`, `muted`, `autoDiscardable`, `openerTabId`
|
|
919
1107
|
|
|
920
|
-
Requires `targetId`; only `active=true` is supported and does not focus the window; `active=false` is rejected
|
|
921
|
-
|
|
1108
|
+
Requires `targetId`; only `active=true` is supported and does not focus the window; `active=false` is rejected before
|
|
1109
|
+
any update
|
|
922
1110
|
|
|
923
1111
|
#### `groupPages`
|
|
924
1112
|
|
|
925
1113
|
Parameters: `targetIds`, `groupId`, `windowId`, `title`, `color`, `collapsed`
|
|
926
1114
|
|
|
927
|
-
Omit `groupId` to create a group in the members' window; mixed-window members require `windowId`; joining an
|
|
928
|
-
|
|
1115
|
+
Omit `groupId` to create a group in the members' window; mixed-window members require `windowId`; joining an existing
|
|
1116
|
+
group accepts only `targetIds/groupId`
|
|
929
1117
|
|
|
930
1118
|
#### `ungroupPages`
|
|
931
1119
|
|
|
@@ -947,11 +1135,11 @@ Moves all members; `index=-1` means the end of the window
|
|
|
947
1135
|
|
|
948
1136
|
#### `newWindow`
|
|
949
1137
|
|
|
950
|
-
Parameters: `url` or `urls`, `targetId`, `windowType`, `focused`, `incognito`, `left`, `top`, `width`,
|
|
951
|
-
`
|
|
1138
|
+
Parameters: `url` or `urls`, `targetId`, `windowType`, `focused`, `incognito`, `left`, `top`, `width`, `height`,
|
|
1139
|
+
`windowState`, `setSelfAsOpener`
|
|
952
1140
|
|
|
953
|
-
`normal` supports multiple URL tabs and an existing controlled tab; `popup` accepts only one page; created
|
|
954
|
-
|
|
1141
|
+
`normal` supports multiple URL tabs and an existing controlled tab; `popup` accepts only one page; created tabs are
|
|
1142
|
+
managed with distinct provenance
|
|
955
1143
|
|
|
956
1144
|
#### `updateWindow` / `resizeWindow`
|
|
957
1145
|
|
|
@@ -990,6 +1178,7 @@ revision. Once a native update has been dispatched, a failure still invalidates
|
|
|
990
1178
|
|
|
991
1179
|
`emulate` applies the device viewport, pixel density, touch support, and User-Agent in both backends. `viewport`
|
|
992
1180
|
restores desktop metrics, page scale, and disabled touch emulation; restore the User-Agent separately with `userAgent`.
|
|
1181
|
+
`manage(action="userAgent", userAgent="")` clears the page override.
|
|
993
1182
|
|
|
994
1183
|
**Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
|
|
995
1184
|
|
|
@@ -997,23 +1186,36 @@ restores desktop metrics, page scale, and disabled touch emulation; restore the
|
|
|
997
1186
|
- `safe` (default) — minimal patches (remove `navigator.webdriver`, clean CDP traces)
|
|
998
1187
|
- `aggressive` — adds a few WebGL/plugin/language fingerprint patches (does NOT equal full masking)
|
|
999
1188
|
|
|
1000
|
-
Management operations share a 30000 ms request deadline; `newPage` uses a supplied `timeout`. An expired queued change
|
|
1189
|
+
Management operations share a 30000 ms request deadline; `newPage` uses a supplied `timeout`. An expired queued change
|
|
1190
|
+
is rejected before dispatch. Unconditional `pageMetadata` reads, updates and clears use the explicit target
|
|
1191
|
+
independently of a long page action, including on the same page. Each request keeps its own URL/revision conditions.
|
|
1192
|
+
URL/revision-conditioned metadata keeps serialized condition checking.
|
|
1001
1193
|
|
|
1002
|
-
|
|
1194
|
+
Moving an existing page into a new window and group operations serialize with page release and recheck native membership
|
|
1195
|
+
and managed authority under the affected page locks. Page creation uses `active`; `activate` is accepted only by
|
|
1196
|
+
`movePage`.
|
|
1003
1197
|
|
|
1004
1198
|
### Browser events and original files
|
|
1005
1199
|
|
|
1006
1200
|
Prepare observation before clicking a download link, opening a dialog, or making a request. Use the returned `ref` to
|
|
1007
|
-
read or handle that exact event. These actions use the controlled page selected by `targetId` or the current default.
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
| `
|
|
1013
|
-
|
|
|
1014
|
-
| `
|
|
1015
|
-
| `
|
|
1016
|
-
| `
|
|
1201
|
+
read or handle that exact event. These actions use the controlled page selected by `targetId` or the current default. A
|
|
1202
|
+
reference retains its original page even after the default target changes. Default-target event configuration waits for
|
|
1203
|
+
temporary page actions to restore the selected page; ref-directed dialog and Fetch handling remain independent.
|
|
1204
|
+
Reconnecting the same server instance waits for its previous event resources to finish cleanup.
|
|
1205
|
+
|
|
1206
|
+
| `manage` action | Nested command |
|
|
1207
|
+
| ---------------- | --------------------------------------------------------------- |
|
|
1208
|
+
| `dialog` | `dialog:{op:"watch"\|"stop"\|"accept"\|"dismiss",ref?,text?}` |
|
|
1209
|
+
| `networkCapture` | `capture:{op:"start"\|"stop",include?:["body","stream"]}` |
|
|
1210
|
+
| `route` | `route:{op:"add"\|"remove"\|"continue"\|"fulfill"\|"fail",...}` |
|
|
1211
|
+
| `httpAuth` | `auth:{op:"set"\|"clear",...}` |
|
|
1212
|
+
| `download` | `download:{op:"watch"\|"stop"\|"wait"\|"save",...}` |
|
|
1213
|
+
|
|
1214
|
+
- `dialog`: Observe dialogs or handle one observed dialog; `text` supplies a prompt answer
|
|
1215
|
+
- `networkCapture`: Record original requests, optional bodies, and WebSocket/SSE messages
|
|
1216
|
+
- `route`: Match page requests or handle an observed paused request
|
|
1217
|
+
- `httpAuth`: Configure credentials for an explicit Server/Proxy challenge scope
|
|
1218
|
+
- `download`: Identify a download, wait for its native state, and save available original bytes
|
|
1017
1219
|
|
|
1018
1220
|
#### Handle a dialog
|
|
1019
1221
|
|
|
@@ -1036,24 +1238,28 @@ logs(type="network", targetId="PAGE_ID", view="details")
|
|
|
1036
1238
|
logs(type="network", view="responseBody", ref="REQUEST_REF", output="tmp:response.bin")
|
|
1037
1239
|
```
|
|
1038
1240
|
|
|
1039
|
-
`details` retains request identity, redirect hop, base headers, ExtraInfo headers, and their completeness.
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1241
|
+
`details` retains request identity, redirect hop, base headers, ExtraInfo headers, and their completeness. `requestBody`
|
|
1242
|
+
reads original POST data; `responseBody` reads the protocol-provided entity body. An explicit `output` saves decoded
|
|
1243
|
+
bytes. Inline bodies use `{encoding:"utf8"|"base64",data}`. Unavailable or evicted bodies return an error; multipart
|
|
1244
|
+
file parts and redirect bodies depend on native protocol availability. A body must be below 16 MiB. Headers, Cookie
|
|
1245
|
+
metadata copies such as `cookieLine`, and credential URL fields are redacted. URL-bearing headers such as `Location`,
|
|
1246
|
+
`Content-Location` and `Referer` also redact user information and sensitive query values in structured metadata and raw
|
|
1247
|
+
handshake header text; explicitly requested body content retains its bytes.
|
|
1044
1248
|
|
|
1045
1249
|
`view="stream"` returns WebSocket directions/opcodes and SSE messages in observed order. Inspect truncation, `dropped`
|
|
1046
1250
|
and `evicted` fields when consuming bounded buffers. Use `capture:{op:"stop"}` to end collection.
|
|
1047
1251
|
|
|
1048
1252
|
#### Continue or mock a matched request
|
|
1049
1253
|
|
|
1050
|
-
Add a route with `urlPattern` and optional `stage:"Request"|"Response"`. Read `logs(type="network",view="paused")`,
|
|
1051
|
-
|
|
1254
|
+
Add a route with `urlPattern` and optional `stage:"Request"|"Response"`. Read `logs(type="network",view="paused")`, then
|
|
1255
|
+
handle the returned paused-request reference:
|
|
1052
1256
|
|
|
1053
1257
|
```text
|
|
1054
1258
|
manage(action="route", targetId="PAGE_ID", route={op:"add", urlPattern:"https://example.com/api/*"})
|
|
1055
1259
|
logs(type="network", targetId="PAGE_ID", view="paused")
|
|
1056
|
-
manage(action="route", route={
|
|
1260
|
+
manage(action="route", route={
|
|
1261
|
+
op:"fulfill", ref:"PAUSED_REF", response:{status:200, body:{encoding:"utf8",data:"mock"}}
|
|
1262
|
+
})
|
|
1057
1263
|
```
|
|
1058
1264
|
|
|
1059
1265
|
`continue` accepts optional `request:{url?,method?,headers?,body?}`; headers are `{name,value}` arrays. `fulfill`
|
|
@@ -1061,7 +1267,8 @@ requires `response:{status,statusText?,headers?,body?}`. `fail` accepts a native
|
|
|
1061
1267
|
Remove a rule with `op:"remove"` and its rule reference. Unmatched requests continue immediately. Matched pauses expire
|
|
1062
1268
|
after 30 seconds; cancellation, navigation, release or owner disconnection aborts unresolved requests. A native
|
|
1063
1269
|
acknowledgement loss retains an unknown result and is not automatically resent. `clear` clears readable records while
|
|
1064
|
-
active pauses and dialogs keep their handling references. Raw `manage cdp` Fetch commands share this ownership and
|
|
1270
|
+
active pauses and dialogs keep their handling references. Raw `manage cdp` Fetch commands share this ownership and
|
|
1271
|
+
cleanup.
|
|
1065
1272
|
|
|
1066
1273
|
For HTTP authentication, set `auth:{op:"set",scope:{source:"Server"|"Proxy",origin,realm?},username,password}`.
|
|
1067
1274
|
Credentials stay in memory for that page and exact challenge scope. Failed repeat challenges are canceled. Read
|
|
@@ -1083,13 +1290,27 @@ As, blob downloads or browser security restrictions can leave the file unavailab
|
|
|
1083
1290
|
Shared-browser download policy remains unchanged. This capture path uses the same below-16-MiB body budget.
|
|
1084
1291
|
`download:{op:"stop"}` ends observation and releases its interception.
|
|
1085
1292
|
|
|
1293
|
+
After stopping, suspension or a document change, late body replies retain their original observation identity; a later
|
|
1294
|
+
same-URL download GUID cannot inherit those bytes. A body binds to a GUID only for one matching candidate with the same
|
|
1295
|
+
frame, URL, native session, observation generation and document revision. Reliably bound historical downloads remain
|
|
1296
|
+
readable through their original refs until eviction or controller disposal.
|
|
1297
|
+
|
|
1086
1298
|
References are bound to the server instance, page and connection generation. Stale or foreign references are rejected.
|
|
1087
1299
|
Cloudflare handling ends current Fetch control and suspends these observations before detaching the debugger; inspect
|
|
1088
1300
|
the returned `browserEvents` status and explicitly start observation again after verification. New event actions require
|
|
1089
|
-
matching Server and Extension builds; missing native capabilities are reported before enabling interception.
|
|
1090
|
-
|
|
1301
|
+
matching Server and Extension builds; missing native capabilities are reported before enabling interception. CDP
|
|
1302
|
+
authentication and response capture remain active after the connection request finishes. Each later tool call uses its
|
|
1303
|
+
own timeout and cancellation signal.
|
|
1091
1304
|
|
|
1092
|
-
|
|
1305
|
+
Cleanup failure retains the original controller, owner and unresolved resources. A later event action from the same
|
|
1306
|
+
Server first retries cleanup under that owner's control; new observation starts after cleanup succeeds. Unknown paused
|
|
1307
|
+
requests continue to block new configuration and debugger detach, returning the cleanup error and actual state while
|
|
1308
|
+
their handling refs remain valid. Confirmed native session or page termination releases the corresponding barrier.
|
|
1309
|
+
|
|
1310
|
+
`cleanupFailures` retains the existing string array. The parallel `cleanupFailureDetails` records timestamp, phase,
|
|
1311
|
+
observed ref or request ID, target, owner and session generation. Each controller retains at most 20 failures and clears
|
|
1312
|
+
them when disposed. A new controller starts empty; details already returned retain their original ownership. Console
|
|
1313
|
+
metadata and error messages redact sensitive URL query values; requested page text and body files retain their content.
|
|
1093
1314
|
|
|
1094
1315
|
### logs - Browser Logs
|
|
1095
1316
|
|
|
@@ -1105,16 +1326,18 @@ Parameters: `output` saves result to file. Console entries use the public levels
|
|
|
1105
1326
|
console logs keeps the hook active. When debugger collection becomes available, fallback capture is disabled. Console
|
|
1106
1327
|
methods still pointing to the MCP wrapper are restored, while wrappers installed later by the page are preserved.
|
|
1107
1328
|
Independent fallback console calls retain their levels and frequency even when their timestamp and text are identical;
|
|
1108
|
-
reading the same drained batch again does not append it again. Switching to debugger collection preserves pending calls
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1329
|
+
reading the same drained batch again does not append it again. Switching to debugger collection preserves pending calls
|
|
1330
|
+
once, without adding their Runtime history replay a second time or restoring cleared fallback calls. The buffer retains
|
|
1331
|
+
the latest 1000 entries. Network logs are finalized on `loadingFinished` or `loadingFailed`, not when headers arrive, so
|
|
1332
|
+
body failures retain both the HTTP status and `errorText`, and in-flight bodies continue to count against `networkidle`.
|
|
1333
|
+
Entries include `method`, `url`, `status`, `timestamp`, and `duration` when available. URL query parameters commonly
|
|
1334
|
+
used for credentials, signatures, passwords, and tokens are replaced with `[REDACTED]` in inline responses, diagnostics,
|
|
1335
|
+
and explicit `output` files. Redacted entries include `urlRedacted`, `urlOriginalLength`, and `redactedQueryParameters`.
|
|
1114
1336
|
Inline network results limit each sanitized URL to 2048 characters and add `urlLength` plus `urlTruncated: true` when
|
|
1115
1337
|
shortened. `urlPattern` supports `*` for any number of characters and `?` for one character. `tabId` targets a specific
|
|
1116
|
-
tab (Extension mode). `frame` is not applicable for logs.
|
|
1117
|
-
|
|
1338
|
+
tab (Extension mode). `frame` is not applicable for logs. In network views, `urlPattern` filters each request's URL,
|
|
1339
|
+
including paused requests and authentication events, before applying `limit`. `clear` preserves requests that still need
|
|
1340
|
+
handling.
|
|
1118
1341
|
|
|
1119
1342
|
When the Extension debugger is unavailable, network reads refresh performance entries and mark them with
|
|
1120
1343
|
`source="performance"`. Status uses the browser's `responseStatus` when available, or `0` otherwise; unknown request
|
|
@@ -1122,7 +1345,9 @@ methods remain empty. Repeated reads preserve record sequences. `clear` clears M
|
|
|
1122
1345
|
document's read boundary without clearing the page's shared performance timeline. A new document starts a new boundary.
|
|
1123
1346
|
Read failures return an error rather than an empty log.
|
|
1124
1347
|
|
|
1125
|
-
CDP network logs keep the HTTP status when a response body fails and record one terminal entry per request. Temporary
|
|
1348
|
+
CDP network logs keep the HTTP status when a response body fails and record one terminal entry per request. Temporary
|
|
1349
|
+
page selection preserves each target's log buffer. Clearing logs removes buffered entries while keeping in-flight
|
|
1350
|
+
requests until their final event, so a request completed after clearing appears in the new log.
|
|
1126
1351
|
|
|
1127
1352
|
### cookies - Cookie Management
|
|
1128
1353
|
|
|
@@ -1136,19 +1361,38 @@ CDP network logs keep the HTTP status when a response body fails and record one
|
|
|
1136
1361
|
All actions accept `targetId`, `partitionKey:{topLevelSite?,hasCrossSiteAncestor?}`, and a backend-specific store scope:
|
|
1137
1362
|
`storeId` for Extension or `browserContextId` for CDP. Extension resolves a supplied target to its native CookieStore
|
|
1138
1363
|
and rejects a conflicting store. Unsupported backend scope fields return an error. Without these fields, existing
|
|
1139
|
-
URL/domain behavior remains unchanged. `get` requires at least one nonblank `name`, `domain`, or `url`; storage scopes
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
`
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1364
|
+
URL/domain behavior remains unchanged. `get` requires at least one nonblank `name`, `domain`, or `url`; storage scopes
|
|
1365
|
+
and flags only narrow that explicit filter, including when exporting to a file.
|
|
1366
|
+
|
|
1367
|
+
URL path matching uses Cookie path boundaries in target and browser-context scopes too: a Cookie at `/app` matches
|
|
1368
|
+
`/app/info` and is excluded for `/apple/info`.
|
|
1369
|
+
|
|
1370
|
+
`clear` requires `url` or `domain`, with optional `name` to narrow the range. CDP preserves each selected Cookie's exact
|
|
1371
|
+
name, raw domain, path, partition and browser context for deletion. An omitted target is fixed to the current page's
|
|
1372
|
+
storage context when clear starts. An unserializable partition identity is rejected before deletion.
|
|
1373
|
+
|
|
1374
|
+
For CDP clear, `count` records identities present at the immediate precheck and absent after an acknowledged deletion
|
|
1375
|
+
request; `countSemantics="observed_present_then_absent"` identifies this state comparison. `acknowledged` counts native
|
|
1376
|
+
ACKs, `alreadyAbsent` counts identities missing at the initial check, and `matched` and `attempted` describe the
|
|
1377
|
+
selected candidates and started deletion steps. Concurrent page changes can occur between observations. Extension
|
|
1378
|
+
retains its native removal-confirmation count.
|
|
1379
|
+
|
|
1380
|
+
CDP stops at the first deletion, verification or cleanup failure and returns `COOKIE_CLEAR_PARTIAL` with the known
|
|
1381
|
+
count, ACKs, failed or unknown steps, unprocessed candidates, phase and original cause. Its action state preserves
|
|
1382
|
+
earlier changes and `retryable=false`; a session-detach failure retains the preceding ACK and any verified
|
|
1383
|
+
disappearance.
|
|
1384
|
+
|
|
1385
|
+
A deletion request sent without an ACK counts as `unknown` when the connection closes, is explicitly closed, times out
|
|
1386
|
+
or is canceled. The first unknown step reports `actionStatus="unknown"`; earlier ACKs keep the action `partial`.
|
|
1387
|
+
`failed` counts explicitly rejected or undispatched deletion steps and identities still present after an ACK.
|
|
1388
|
+
Unclassified errors after attempting deletion remain unknown, and later deletions stop.
|
|
1389
|
+
|
|
1390
|
+
MCP cancellation stops queued Cookie actions, connection waits and later deletions in both backends. CDP retains prior
|
|
1391
|
+
confirmed progress and an unacknowledged deletion's unknown result. A canceled or timed-out temporary attach retains
|
|
1392
|
+
responsibility for its native response: a late successful session is detached with an independent 1000 ms budget.
|
|
1393
|
+
Cleanup failure is logged with the command and session identity and remains tracked until the connection closes; no
|
|
1394
|
+
deletion is replayed. An Extension RPC canceled before its reply reports an unknown RPC result; the Extension stops its
|
|
1395
|
+
remaining native removals once the in-flight call settles.
|
|
1152
1396
|
|
|
1153
1397
|
## Usage Examples
|
|
1154
1398
|
|
|
@@ -1222,7 +1466,8 @@ startup, marked sessions older than 24 hours are removed only after their proces
|
|
|
1222
1466
|
remain accessible after restarting the server. Successful responses that save a `tmp:` file or directory include a
|
|
1223
1467
|
`retention` field describing the cleanup condition; `cwd:` responses omit it. Output paths reject Windows reserved
|
|
1224
1468
|
device names, alternate data streams, invalid characters, and trailing spaces or dots. On Windows, private file
|
|
1225
|
-
permissions must be verified before writing sensitive content.
|
|
1469
|
+
permissions must be verified before writing sensitive content. Windows permission checks and native pointer commands
|
|
1470
|
+
ignore inherited `PSModulePath`, allowing MCP to start under PowerShell 7 while using Windows PowerShell 5.1.
|
|
1226
1471
|
|
|
1227
1472
|
Invalid path syntax returns `INVALID_ARGUMENT`; `.` components are accepted and `..` components remain rejected. Paths
|
|
1228
1473
|
outside an allowed root, including symlink escapes, return `PATH_NOT_ALLOWED`. Both errors include the server's actual
|
|
@@ -1244,7 +1489,9 @@ extract(type="metadata")
|
|
|
1244
1489
|
|
|
1245
1490
|
### Nested frame operations
|
|
1246
1491
|
|
|
1247
|
-
Both backends resolve iframe selectors and indices through open ShadowRoots. Cross-origin and OOPIF frame preparation
|
|
1492
|
+
Both backends resolve iframe selectors and indices through open ShadowRoots. Cross-origin and OOPIF frame preparation
|
|
1493
|
+
uses the original request deadline; a timeout before script dispatch reports `actionExecuted=false` and
|
|
1494
|
+
`actionStatus="not_started"` and attempts to restore the previous target.
|
|
1248
1495
|
|
|
1249
1496
|
```
|
|
1250
1497
|
// Target iframe by CSS selector
|
|
@@ -1280,6 +1527,12 @@ calls keep their existing meaning; errors do not replay the script. When a read
|
|
|
1280
1527
|
diagnostics remove credentials, query strings, and fragments and are limited to 500 characters. `data:` and
|
|
1281
1528
|
`javascript:` URLs expose only the protocol; an unparseable URL reports `url=null` and `urlStatus="unavailable"`.
|
|
1282
1529
|
|
|
1530
|
+
Extension text, attribute and accessibility-state queries use frame-local element identity and rectangles. Read-only
|
|
1531
|
+
queries in scaled, rotated and nested transformed frames need no debugger attachment for root-coordinate calibration.
|
|
1532
|
+
Input target lookup uses the same frame-local references, including touch, selection, editing commands, upload and drag.
|
|
1533
|
+
Native pointer calibration still accepts translation-only frame offsets; scaled or rotated owners return
|
|
1534
|
+
`FRAME_GEOMETRY_UNAVAILABLE` before an inferred origin is used.
|
|
1535
|
+
|
|
1283
1536
|
### Wait for Element
|
|
1284
1537
|
|
|
1285
1538
|
```
|
|
@@ -1317,6 +1570,25 @@ wait(for="element", target={ text: "Loading complete" }, state="visible")
|
|
|
1317
1570
|
└──────────┘
|
|
1318
1571
|
```
|
|
1319
1572
|
|
|
1573
|
+
### Connection status and recovery
|
|
1574
|
+
|
|
1575
|
+
`browse(action="connect")` and the local `/api/info` endpoint report the active Extension background bundle hash and
|
|
1576
|
+
compare it with the bundle shipped beside the Server. `bundleStatus="stale"` means Chrome still runs an older bundle;
|
|
1577
|
+
reload that Extension in `chrome://extensions/`. A legacy Extension lacking `network_challenge_state` uses tab-title and
|
|
1578
|
+
DOM detection. Bundle identity does not block auto-connect.
|
|
1579
|
+
|
|
1580
|
+
Popup Disconnect immediately pauses local connections for the current Extension session, including Service Worker
|
|
1581
|
+
recovery. Connect resumes discovery; an Extension reload or Chrome restart restores auto-connect. When one Server
|
|
1582
|
+
restarts, the Extension retries it with the existing backoff while keeping other connections active; explicit Disconnect
|
|
1583
|
+
cancels those retries. Popup storage failures stay visible, and delayed old values cannot overwrite a newer choice. A
|
|
1584
|
+
temporary saved-pause read failure can recover on a later connection attempt in the same Worker; a pause-write failure
|
|
1585
|
+
remains visible.
|
|
1586
|
+
|
|
1587
|
+
Discovery reports the initial server-port set and changes, including an empty set. Every scan checks the full port
|
|
1588
|
+
range; unchanged scans and automatic reconnects do not repeat the summary. Explicit disconnect starts a new reporting
|
|
1589
|
+
cycle. Ordinary pre-open failures stay debug-level; authentication or protocol rejections from identified MCP servers
|
|
1590
|
+
produce one bounded warning when their summary changes.
|
|
1591
|
+
|
|
1320
1592
|
## Project Structure
|
|
1321
1593
|
|
|
1322
1594
|
```
|
|
@@ -1380,7 +1652,27 @@ mcp-chrome/
|
|
|
1380
1652
|
- Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still
|
|
1381
1653
|
contain sensitive information
|
|
1382
1654
|
|
|
1383
|
-
###
|
|
1655
|
+
### Pairing and local access
|
|
1656
|
+
|
|
1657
|
+
Ordinary local use auto-discovers servers by default. On shared machines, CI runners or containers where untrusted
|
|
1658
|
+
processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the Server and enter the same token in
|
|
1659
|
+
the Extension popup:
|
|
1660
|
+
|
|
1661
|
+
```bash
|
|
1662
|
+
MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
|
|
1663
|
+
```
|
|
1664
|
+
|
|
1665
|
+
To enforce token use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` and disable "Allow no-token local connection" in the
|
|
1666
|
+
popup. This immediately cancels pending health checks, WebSocket handshakes and reconnects, ending older no-token
|
|
1667
|
+
attempts.
|
|
1668
|
+
|
|
1669
|
+
Token peers require authentication protocol v2. Commands, responses, cancellations and heartbeats use
|
|
1670
|
+
direction-separated session keys and increasing sequence numbers; health proofs bind both nonces, the Server instance
|
|
1671
|
+
and port. Extension becomes available after authenticated ready, and Server accepts requests after authenticated hello.
|
|
1672
|
+
Older strict-token peers return a protocol diagnostic; default no-token discovery and automatic reconnection stay
|
|
1673
|
+
available.
|
|
1674
|
+
|
|
1675
|
+
### Anti-detection (stealth) capabilities
|
|
1384
1676
|
|
|
1385
1677
|
The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerprinting surfaces:
|
|
1386
1678
|
|