@pyrokine/mcp-chrome 3.0.0 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +721 -303
- package/README_zh.md +750 -292
- package/dist/cdp/client.d.ts +7 -3
- package/dist/cdp/client.d.ts.map +1 -1
- package/dist/cdp/client.js +252 -63
- package/dist/cdp/client.js.map +1 -1
- package/dist/cdp/launcher.d.ts +1 -1
- package/dist/cdp/launcher.d.ts.map +1 -1
- package/dist/cdp/launcher.js +33 -12
- package/dist/cdp/launcher.js.map +1 -1
- package/dist/core/auto-wait.d.ts.map +1 -1
- package/dist/core/auto-wait.js +88 -52
- package/dist/core/auto-wait.js.map +1 -1
- package/dist/core/browser-driver.d.ts +76 -18
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/browser-event-schema.d.ts +287 -0
- package/dist/core/browser-event-schema.d.ts.map +1 -0
- package/dist/core/browser-event-schema.js +104 -0
- package/dist/core/browser-event-schema.js.map +1 -0
- package/dist/core/browser-events.d.ts +99 -0
- package/dist/core/browser-events.d.ts.map +1 -0
- package/dist/core/browser-events.js +1312 -0
- package/dist/core/browser-events.js.map +1 -0
- package/dist/core/challenge-page.d.ts +39 -0
- package/dist/core/challenge-page.d.ts.map +1 -0
- package/dist/core/challenge-page.js +226 -0
- package/dist/core/challenge-page.js.map +1 -0
- package/dist/core/dom-helpers.d.ts +28 -0
- package/dist/core/dom-helpers.d.ts.map +1 -0
- package/dist/core/dom-helpers.js +311 -0
- package/dist/core/dom-helpers.js.map +1 -0
- package/dist/core/errors.d.ts +10 -4
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +63 -13
- package/dist/core/errors.js.map +1 -1
- package/dist/core/file-upload.d.ts +22 -0
- package/dist/core/file-upload.d.ts.map +1 -0
- package/dist/core/file-upload.js +194 -0
- package/dist/core/file-upload.js.map +1 -0
- package/dist/core/locator.d.ts +17 -2
- package/dist/core/locator.d.ts.map +1 -1
- package/dist/core/locator.js +156 -212
- package/dist/core/locator.js.map +1 -1
- package/dist/core/os-mouse.d.ts +11 -0
- package/dist/core/os-mouse.d.ts.map +1 -1
- package/dist/core/os-mouse.js +102 -29
- package/dist/core/os-mouse.js.map +1 -1
- package/dist/core/retry.d.ts.map +1 -1
- package/dist/core/retry.js +4 -1
- package/dist/core/retry.js.map +1 -1
- package/dist/core/session.d.ts +65 -14
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +1089 -273
- package/dist/core/session.js.map +1 -1
- package/dist/core/types.d.ts +5 -1
- package/dist/core/types.d.ts.map +1 -1
- package/dist/core/types.js +16 -1
- package/dist/core/types.js.map +1 -1
- package/dist/core/unified-session.d.ts +50 -41
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +938 -285
- package/dist/core/unified-session.js.map +1 -1
- package/dist/core/utils.d.ts +5 -4
- package/dist/core/utils.d.ts.map +1 -1
- package/dist/core/utils.js +73 -18
- package/dist/core/utils.js.map +1 -1
- package/dist/extension/bridge.d.ts +50 -19
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +289 -57
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts +7 -2
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +219 -48
- package/dist/extension/http-server.js.map +1 -1
- package/dist/index.js +14 -1
- package/dist/index.js.map +1 -1
- package/dist/tools/browse.d.ts.map +1 -1
- package/dist/tools/browse.js +66 -32
- package/dist/tools/browse.js.map +1 -1
- package/dist/tools/browser-event-output.d.ts +7 -0
- package/dist/tools/browser-event-output.d.ts.map +1 -0
- package/dist/tools/browser-event-output.js +19 -0
- package/dist/tools/browser-event-output.js.map +1 -0
- package/dist/tools/challenge.d.ts +17 -5
- package/dist/tools/challenge.d.ts.map +1 -1
- package/dist/tools/challenge.js +113 -195
- package/dist/tools/challenge.js.map +1 -1
- package/dist/tools/cookies.d.ts.map +1 -1
- package/dist/tools/cookies.js +33 -8
- package/dist/tools/cookies.js.map +1 -1
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +14 -0
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/evaluate.d.ts +6 -5
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +102 -52
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +178 -124
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +623 -271
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/logs.d.ts.map +1 -1
- package/dist/tools/logs.js +50 -11
- package/dist/tools/logs.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +127 -46
- 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 +30 -1
- package/dist/tools/network-sanitizer.js.map +1 -1
- package/dist/tools/page-context.d.ts +4 -3
- package/dist/tools/page-context.d.ts.map +1 -1
- package/dist/tools/page-context.js +56 -14
- package/dist/tools/page-context.js.map +1 -1
- package/dist/tools/post-condition.d.ts +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +153 -47
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/schema.d.ts +7 -4
- package/dist/tools/schema.d.ts.map +1 -1
- package/dist/tools/schema.js +32 -122
- package/dist/tools/schema.js.map +1 -1
- package/dist/tools/target-diagnostics.d.ts +10 -2
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +74 -21
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +108 -42
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/{content.ts-C4imZ6A9.js → content.ts-BAMOcF3R.js} +1 -1
- package/extension/dist/assets/{content.ts-loader-CnJuCGhl.js → content.ts-loader-4F9a1EWZ.js} +1 -1
- package/extension/dist/assets/index.ts-B79g2ikq.js +19820 -0
- package/extension/dist/assets/{page-scripts-CMIY1zhd.js → page-scripts-CSxn58h1.js} +300 -410
- package/extension/dist/assets/{popup.html-CgtWL6Py.js → popup.html-DwwHo00N.js} +8 -6
- package/extension/dist/manifest.json +4 -4
- package/extension/dist/service-worker-loader.js +1 -1
- package/extension/dist/src/popup/popup.html +3 -3
- package/package.json +15 -7
- package/scripts/start-chrome.ps1 +9 -1
- package/extension/dist/assets/index.ts-GeHNZBml.js +0 -8972
package/README.md
CHANGED
|
@@ -15,7 +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
|
-
- **
|
|
18
|
+
- **Frames and Shadow DOM**: `frame` selects a child frame or a nested selector/index path in either backend;
|
|
19
|
+
CSS, text and semantic queries enter open shadow roots
|
|
19
20
|
- **Semantic Targeting**: 11 ways to locate elements (role, text, label, CSS, CSS+text combo, XPath, coordinates, etc.)
|
|
20
21
|
- **Auto-Wait**: Built-in clickability and input-ready detection with deadline-based timeout budget
|
|
21
22
|
- **Dual Input Mode**: `precise` (debugger API, bypasses CSP) or `stealth` (JS injection, no debug banner)
|
|
@@ -38,16 +39,6 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
|
|
|
38
39
|
Local zero-config auto-connect is unchanged. Reloading the Extension or restarting the MCP client does not require a
|
|
39
40
|
manual Connect click.
|
|
40
41
|
|
|
41
|
-
## Compatible Clients
|
|
42
|
-
|
|
43
|
-
| Client | Status |
|
|
44
|
-
| ------------------------- | ------ |
|
|
45
|
-
| Claude Code | ✅ |
|
|
46
|
-
| Claude Desktop | ✅ |
|
|
47
|
-
| Cursor | ✅ |
|
|
48
|
-
| Windsurf | ✅ |
|
|
49
|
-
| Any MCP-compatible client | ✅ |
|
|
50
|
-
|
|
51
42
|
## Installation
|
|
52
43
|
|
|
53
44
|
Requires Node.js 20.19 or newer.
|
|
@@ -85,7 +76,8 @@ Chrome discovery checks Windows App Paths, `PATH`, installed Chrome channels, Ch
|
|
|
85
76
|
```powershell
|
|
86
77
|
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
|
|
87
78
|
# Or specify a portable executable and profile explicitly:
|
|
88
|
-
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
|
|
79
|
+
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 `
|
|
80
|
+
-ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
|
|
89
81
|
```
|
|
90
82
|
|
|
91
83
|
Then call `browse(action="connect", port=9222)`. The script keeps its Chrome process in the foreground; Chrome exit
|
|
@@ -157,6 +149,20 @@ To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALL
|
|
|
157
149
|
and disable "Allow no-token local connection" in the Extension popup. Disabling that policy immediately cancels pending
|
|
158
150
|
health checks, WebSocket handshakes, and scheduled reconnects, so an older no-token attempt cannot connect afterward.
|
|
159
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.
|
|
165
|
+
|
|
160
166
|
### Mode 2: CDP Mode (Fallback)
|
|
161
167
|
|
|
162
168
|
CDP mode launches or connects to a dedicated Chrome instance. Used when the Extension is not installed, or for
|
|
@@ -177,6 +183,168 @@ browse(action="open", url="https://example.com")
|
|
|
177
183
|
> return to Extension mode. A CDP connection created only as fallback yields to Extension after the Extension
|
|
178
184
|
> reconnects.
|
|
179
185
|
|
|
186
|
+
## Target: Unified Element Locator
|
|
187
|
+
|
|
188
|
+
All tools use a unified `Target` type for element location. CSS, text, role and label queries traverse open shadow
|
|
189
|
+
roots in stable order; XPath retains native document-tree semantics. `aria-labelledby` uses IDs from the element's own
|
|
190
|
+
tree, preserves multiple-reference order and takes precedence over `aria-label`. Content-named roles such as `tab`,
|
|
191
|
+
`checkbox` and `menuitem` include visible descendant text, including nested spans. State names use the same rules;
|
|
192
|
+
ordinary inputs retain their current values in `value` and `pageContent`, separately from their names. Password,
|
|
193
|
+
hidden and file input values are not read by state extraction. Closed shadow roots remain outside Extension DOM queries.
|
|
194
|
+
|
|
195
|
+
Examples:
|
|
196
|
+
|
|
197
|
+
```typescript
|
|
198
|
+
// By accessibility (recommended - most stable)
|
|
199
|
+
const byRole = { role: 'button', name: 'Submit' }
|
|
200
|
+
|
|
201
|
+
// By accessibility with exact accessible name
|
|
202
|
+
const byExactRole = { role: 'button', name: 'Submit', exact: true }
|
|
203
|
+
|
|
204
|
+
// By text content
|
|
205
|
+
const byText = { text: 'Click here', exact: true }
|
|
206
|
+
|
|
207
|
+
// By form label
|
|
208
|
+
const byLabel = { label: 'Email' }
|
|
209
|
+
|
|
210
|
+
// By placeholder
|
|
211
|
+
const byPlaceholder = { placeholder: 'Enter your name' }
|
|
212
|
+
|
|
213
|
+
// By title attribute
|
|
214
|
+
const byTitle = { title: 'Close dialog' }
|
|
215
|
+
|
|
216
|
+
// By alt text (images)
|
|
217
|
+
const byAlt = { alt: 'Profile picture' }
|
|
218
|
+
|
|
219
|
+
// By test ID
|
|
220
|
+
const byTestId = { testId: 'submit-button' }
|
|
221
|
+
|
|
222
|
+
// By CSS selector
|
|
223
|
+
const byCss = { css: '#login-form .submit-btn' }
|
|
224
|
+
|
|
225
|
+
// Disambiguate multiple matches (0-based)
|
|
226
|
+
const secondMatch = { css: '.ant-select-input', nth: 1 }
|
|
227
|
+
|
|
228
|
+
// By CSS + text (filter by text content)
|
|
229
|
+
const byCssText = { css: 'button', text: 'Submit', exact: true }
|
|
230
|
+
|
|
231
|
+
// By XPath
|
|
232
|
+
const byXPath = { xpath: "//button[@type='submit']" }
|
|
233
|
+
|
|
234
|
+
// By coordinates
|
|
235
|
+
const byCoordinates = { x: 100, y: 200 }
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Text-only targets choose the innermost complete-text match, including nested text nodes. Explicit XPath preserves document order. Both backends use display, visibility and nonzero dimensions for visibility; an initially absent hidden/detached target succeeds on its first query.
|
|
239
|
+
|
|
240
|
+
In both backends, target lookup failures from `input`, `extract`, and `wait` report the failed locator, zero-based
|
|
241
|
+
`nth`, URL, tab/frame scope, managed state, last locator state, and at most 10 candidate summaries within the request
|
|
242
|
+
budget. `matchCount` is the observed total, not the candidate limit; an out-of-range `nth` does not turn 15 matches into
|
|
243
|
+
zero. Unknown counts or managed state are `null`, and unavailable diagnostics include `diagnosticError`. CDP retains
|
|
244
|
+
`ELEMENT_NOT_FOUND` for lookup failures and `TIMEOUT` for element waits, together with existing URL and log fields.
|
|
245
|
+
Diagnostics read the failed target before its scope is restored and never replay input.
|
|
246
|
+
|
|
247
|
+
Targeted operations resolve `target.nth` directly in both backends, including indices beyond the default 50-result
|
|
248
|
+
candidate list and pure-text indices beyond 200. A single-target result does not report a total; its diagnostic
|
|
249
|
+
`matchCount` is `null` unless a separate lookup measured the total. Element waits check that selected target, so an
|
|
250
|
+
existing high-index element cannot satisfy `hidden` or `detached` merely because candidate output is bounded.
|
|
251
|
+
|
|
252
|
+
Page tools accept `targetId` in either backend; the older `tabId` alias is still accepted. If both are supplied, they
|
|
253
|
+
must match. An explicit target changes only the operation scope and restores the previous default afterward.
|
|
254
|
+
`browse.close` and `manage.closePage` require an explicit ID. Page responses, including action failures, include
|
|
255
|
+
`pageContext` with the effective target and its source (`explicit`, `default`, `created`, `reused`, or `unconfirmed`),
|
|
256
|
+
before/after URL and revision, default target before/after, and Chrome's active target when Extension reports it.
|
|
257
|
+
`unconfirmed` means a page-creation action failed without returning a created target ID. CDP reports browser activity as
|
|
258
|
+
unavailable rather than treating the selected operation target as foreground.
|
|
259
|
+
|
|
260
|
+
Page URL fields in these snapshots, browse results, page/window management, state, metadata, and diagnostic bundles
|
|
261
|
+
redact credential query parameters, including `ticket`, and report `urlRedacted`, `urlOriginalLength`, and
|
|
262
|
+
`redactedQueryParameters`. Native `pendingUrl` and `favIconUrl` fields use equivalent field-prefixed markers.
|
|
263
|
+
Navigation waits and navigation error messages use the same display redaction. Navigation
|
|
264
|
+
and `expectedUrl` comparisons use the original URL; page content and user-script results retain their requested content.
|
|
265
|
+
Use `expectedRevision` or an original URL you hold for conditions; a redacted display URL cannot serve as `expectedUrl`.
|
|
266
|
+
|
|
267
|
+
When an older Extension lacks `page_snapshot`, unconditional page actions can still use a fresh page-list URL. Their
|
|
268
|
+
`pageContext.before` and `after` snapshots report `revision=null` with a `warning` about the unavailable revision and
|
|
269
|
+
atomic conditions. Requests with `expectedUrl` or `expectedRevision` return `DRIVER_CAPABILITY_ERROR`,
|
|
270
|
+
`actionExecuted=false`, and `actionStatus="not_started"` before dispatch; update the Extension to use these conditions.
|
|
271
|
+
Evaluate and input retain `failureStage="precondition"`, with matching top-level and error-context status and no script
|
|
272
|
+
or input events dispatched. Other snapshot errors still stop the action, and compatibility reads share the original
|
|
273
|
+
timeout budget.
|
|
274
|
+
|
|
275
|
+
In Extension mode, a page snapshot that reports the requested tab is missing returns `TARGET_NOT_FOUND` with
|
|
276
|
+
`context.targetId` and the original `context.nativeMessage`. Input rejected before dispatch retains `eventsExecuted=0`
|
|
277
|
+
and `actionExecuted=false`. The failed request is not redirected to another page or replayed. User-script exceptions
|
|
278
|
+
with the same text are not classified as missing pages.
|
|
279
|
+
|
|
280
|
+
Creation failures retain `error.context.createdTargetId`, window ID, actual `managed`, `actionExecuted`,
|
|
281
|
+
`actionStatus="partial"` and `failureStage` when Chrome has returned the identity. If an RPC response is unknown,
|
|
282
|
+
`actionStatus` and `actionExecuted` are `"unknown"`; `pageContext.targetId` is null unless the created identity is
|
|
283
|
+
known, never the previous default page. Failed creation is not automatically repeated or undone.
|
|
284
|
+
|
|
285
|
+
Temporary target restoration is reported separately in `pageContext.targetRestoration`: `restored` selects the previous
|
|
286
|
+
default, `cleared` leaves no default when none existed, `previous_target_closed` clears a closed default, and `failed`
|
|
287
|
+
reports restoration or cleanup errors while clearing the temporary selection. `error` and `cleanupError` retain the
|
|
288
|
+
respective failure messages. The primary action result or original error is preserved; completed input is not replayed
|
|
289
|
+
or reported as unexecuted. `browse attach` and `manage adoptPage` keep their persistent-default behavior. Concurrent
|
|
290
|
+
page responses describe the page actually used by each action.
|
|
291
|
+
|
|
292
|
+
`browse.list` returns each page's revision and metadata. Revisions combine a backend epoch with a per-page counter.
|
|
293
|
+
Extension counts main-frame navigations and MCP actions; CDP counts observed navigation for the attached page and
|
|
294
|
+
conservatively counts sent mutating commands, including evaluations. Neither driver tracks arbitrary DOM changes made by
|
|
295
|
+
the page itself; re-read URL and revision before a conditional action. `browse` navigation/close, `input`, `evaluate`,
|
|
296
|
+
and eligible `manage` page actions accept `expectedUrl` and `expectedRevision`. A mismatch at the backend returns
|
|
297
|
+
`ACTION_PRECONDITION_FAILED` before that page action is sent. A multi-event action checks conditions before its first
|
|
298
|
+
modifying command, not before every event. A failed or timed-out action can still change the revision when it may have
|
|
299
|
+
had partial effects.
|
|
300
|
+
|
|
301
|
+
## Request scope and failure handling
|
|
302
|
+
|
|
303
|
+
An input sequence keeps its backend and page through execution and target restoration. CDP binds frame execution to its context and OOPIF session; Extension checks the document and native iframe owner, so same-URL iframe reordering preserves the selected identity. Concurrent `browse(action="connect")` waits for that request scope.
|
|
304
|
+
|
|
305
|
+
Input and evaluate share one budget across queueing, page selection, preparation, dispatch and verification. Cancellation or budget settlement stops queued scripts, remaining events and later context or diagnostic reads. Keys newly held by that request are released with a separate bounded cleanup budget. Confirmed final events retain `actionStatus="completed"` if later response handling exceeds the deadline; dispatched actions without confirmation retain `unknown` and `retryable=false`. Read the current page before deciding on another action.
|
|
306
|
+
|
|
307
|
+
Coordinate input waits for synchronous scroll cascades, including open Shadow roots created during preparation, then reads the current frame-local rectangle. Unrelated requestAnimationFrame scrolling does not keep a stable target waiting. Continuous synchronous self-scrolling is bounded by the request deadline, even when the target stays still.
|
|
308
|
+
|
|
309
|
+
MCP cancellation also stops queued window and group changes. The Extension checks the request after asynchronous preflight and before native changes or uncommitted ownership, read-grant and metadata updates. A successful storage commit is synchronized to memory; required registration after creation and cleanup after closing still finish. Event-ref controls remain available while another page action is waiting.
|
|
310
|
+
|
|
311
|
+
Extract uses the same signal for queueing, page reads and exports. Cookie, log, event, evaluate and extract outputs check the signal and deadline during preparation and before publication. Cancellation stops later reads, unpublished files and later log manifests; published files remain available and temporary-file cleanup finishes. A completed script retains its execution state if its output is stopped.
|
|
312
|
+
|
|
313
|
+
## Operation status and diagnostics
|
|
314
|
+
|
|
315
|
+
Input and evaluate expose execution and verification separately:
|
|
316
|
+
|
|
317
|
+
| Field | Values | Meaning |
|
|
318
|
+
| -------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
|
|
319
|
+
| `actionExecuted` | `false`, `true`, `"unknown"` | Known principal-action execution fact |
|
|
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 |
|
|
325
|
+
|
|
326
|
+
Page-thrown exceptions retain their message text, including empty strings, JSON-shaped text and primitive values, with `actionExecuted=true` and `actionStatus="failed"`. Existing exception descriptions and stacks are preserved. Once the script's result has resolved, failures during type inspection, diagnostic summaries, or JSON encoding and decoding of results and error details report `actionExecuted=true`, `actionStatus="completed"`, `failureStage="output"` and `retryable=false`, including in stealth mode. Promise rejection while adopting the return value remains an action failure. If an encoded error summary cannot be decoded, `error.context.originalOutputError` retains the first output diagnostic.
|
|
327
|
+
|
|
328
|
+
An initial snapshot failure reports `false/not_started`, `failureStage="context"` and `pageContext.contextPhase="before"`. A snapshot checking `expectedUrl` or `expectedRevision` uses `precondition` for both stage fields. If a target, frame, Challenge, argument or per-event preparation RPC has an unknown receipt or an internal evaluate output failure before the principal action is dispatched, the top-level action remains `false/not_started/context`; the auxiliary operation keeps its own facts in the error context. Confirmed earlier input events remain counted. Late replies do not dispatch or replay the principal action.
|
|
329
|
+
|
|
330
|
+
A page precondition mismatch reports `false/not_started/precondition`. Target diagnostics read the current tab instead of cached attach metadata.
|
|
331
|
+
|
|
332
|
+
### Native failures and diagnostics
|
|
333
|
+
|
|
334
|
+
Native script termination, `Internal error`, `Object couldn't be returned by value`, and
|
|
335
|
+
`Object reference chain is too long` responses from CDP `Runtime` script commands preserve the original error code.
|
|
336
|
+
evaluate and `manage cdp` return `actionExecuted=true`, `actionStatus="unknown"`, and `retryable=false` without
|
|
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 the same text
|
|
339
|
+
remain non-retryable action failures.
|
|
340
|
+
|
|
341
|
+
Recognized Extension CDP rejections return `CDP_ERROR` with the method, target, native message and available protocol
|
|
342
|
+
code. The context distinguishes a disabled Debugger domain, stale script ID, browser-level command restriction, missing
|
|
343
|
+
method, command permission refusal (`Not allowed`), and native result serialization failure. A resource or method lookup
|
|
344
|
+
failure does not imply that the entire domain is unsupported. These remain failed calls with warning diagnostics;
|
|
345
|
+
unknown errors retain error-level reporting. A closed tab found during a native snapshot or permission check remains a
|
|
346
|
+
target failure, separate from page-thrown exceptions with matching text.
|
|
347
|
+
|
|
180
348
|
## Available Tools (8 Tools)
|
|
181
349
|
|
|
182
350
|
### browse - Browser Management & Navigation
|
|
@@ -193,10 +361,16 @@ browse(action="open", url="https://example.com")
|
|
|
193
361
|
| `refresh` | Reload page |
|
|
194
362
|
| `close` | Close the page specified by `targetId` |
|
|
195
363
|
|
|
364
|
+
A default `launch` uses a connected Extension. Explicit `headless`, `incognito`, `userDataDir`, `executablePath`, or
|
|
365
|
+
`port` selects a new CDP browser and returns `mode="cdp"`. An existing CDP connection is reported as a conflict before
|
|
366
|
+
creating or closing a browser; supplied launch settings are applied or rejected.
|
|
367
|
+
|
|
196
368
|
Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
|
|
197
369
|
(whether the tab is controlled by MCP Chrome), `isActive` (Chrome's active tab within its window), `windowId`, `index`,
|
|
198
|
-
`pinned`, `incognito`, and `status` (`loading`/`complete`).
|
|
199
|
-
`
|
|
370
|
+
`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, `focusedWindowId`
|
|
372
|
+
identifies it and `activeTargetId` identifies its active tab. With no focused Chrome window, both fields are omitted;
|
|
373
|
+
each window still reports its own `activeTabId`. `defaultTargetId` identifies the selected operation target; CDP
|
|
200
374
|
does not infer Chrome's foreground tab from this selection. `open` auto-creates tab group (cyan color). `open`, `back`,
|
|
201
375
|
`forward`, and `refresh` accept `diagnostics=true` to return new console warnings/errors and failed network requests
|
|
202
376
|
observed during the action, including the first `open` that creates a page automatically. `open` and `refresh` honor
|
|
@@ -209,15 +383,23 @@ the entire CDP connection.
|
|
|
209
383
|
|
|
210
384
|
In Extension mode, `back` and `forward` use native browser history first. Only a native no-history error permits a
|
|
211
385
|
script fallback, and only on a scriptable document; restricted URLs and browser error pages are not injected. With no
|
|
212
|
-
available history they return `navigated=false
|
|
386
|
+
available history they return `navigated=false` without consuming the navigation wait budget. The page fallback checks `history.length` and, when available, the Navigation API's direction flag before dispatch. Other native failures are preserved. A destroyed execution context or a
|
|
213
387
|
browser refusing injection into an error page still returns an operation failure, recorded as a warning in the Extension
|
|
214
388
|
rather than a program error. Arbitrary debugger commands are never automatically replayed.
|
|
215
389
|
|
|
390
|
+
If a CDP history-navigation command is rejected, the original error is returned and that navigation wait ends immediately, keeping later requests available.
|
|
391
|
+
|
|
216
392
|
For `open`, `back`, `forward`, and `refresh`, `timeout` starts at request entry. Target preparation, queueing, protocol
|
|
217
393
|
calls, page loading, Challenge inspection and clicks, diagnostics, and target restoration share the remaining budget;
|
|
218
394
|
navigation RPCs do not add transport time. An expired queued action is not dispatched, and later requests still wait for
|
|
219
395
|
an earlier in-flight action to settle. Explicit `timeout=0` rejects before navigation dispatch. Page creation retains
|
|
220
|
-
its separate load-wait and transport-time contract.
|
|
396
|
+
its separate load-wait and transport-time contract. When the navigation wait exhausts the request deadline, later metadata and diagnostic reads stop. A shorter wait timeout leaves the enclosing request's remaining budget available.
|
|
397
|
+
|
|
398
|
+
MCP cancellation stops queued browse actions before dispatch and ends active navigation or Challenge waits. The same signal stops later OS mouse commands and CDP launch steps after an interrupted wait; launch cleanup terminates only a process created by that request and not yet delivered.
|
|
399
|
+
|
|
400
|
+
If a mouse button was already pressed, the request retains the tab lock until its necessary release completes or the independent 5000 ms cleanup budget ends. Subsequent navigation and input remain queued during release. A failed or timed-out release reports `releaseStatus="unknown"` with an explicit error; check and release the mouse button before continuing.
|
|
401
|
+
|
|
402
|
+
A confirmed navigation keeps `actionExecuted=true` and `actionStatus="completed"` when its later state read fails, with `failureStage="metadata"` and `retryable=false`; page verification retains its own result.
|
|
221
403
|
|
|
222
404
|
A timeout does not undo a Chrome operation already dispatched. When its result is unknown, the response reports
|
|
223
405
|
`TIMEOUT`, `actionExecuted="unknown"`, `actionStatus="unknown"`, and `retryable=false`; read the actual page state
|
|
@@ -237,48 +419,6 @@ Evaluate retains Challenge result fields on success, action failure, verificatio
|
|
|
237
419
|
`originResponsePending=true` means verification succeeded but the origin server has not responded; it does not mean the
|
|
238
420
|
destination content has loaded.
|
|
239
421
|
|
|
240
|
-
Page tools accept `targetId` in either backend; the older `tabId` alias is still accepted. If both are supplied, they
|
|
241
|
-
must match. An explicit target changes only the operation scope and restores the previous default afterward.
|
|
242
|
-
`browse.close` and `manage.closePage` require an explicit ID. Page responses, including action failures, include
|
|
243
|
-
`pageContext` with the effective target and its source (`explicit`, `default`, `created`, `reused`, or `unconfirmed`),
|
|
244
|
-
before/after URL and revision, default target before/after, and Chrome's active target when Extension reports it.
|
|
245
|
-
`unconfirmed` means a page-creation action failed without returning a created target ID. CDP reports browser activity as
|
|
246
|
-
unavailable rather than treating the selected operation target as foreground.
|
|
247
|
-
|
|
248
|
-
When an older Extension lacks `page_snapshot`, unconditional page actions can still use a fresh page-list URL. Their
|
|
249
|
-
`pageContext.before` and `after` snapshots report `revision=null` with a `warning` about the unavailable revision and
|
|
250
|
-
atomic conditions. Requests with `expectedUrl` or `expectedRevision` return `DRIVER_CAPABILITY_ERROR`,
|
|
251
|
-
`actionExecuted=false`, and `actionStatus="not_started"` before dispatch; update the Extension to use these conditions.
|
|
252
|
-
Evaluate and input retain `failureStage="precondition"`, with matching top-level and error-context status and no script
|
|
253
|
-
or input events dispatched. Other snapshot errors still stop the action, and compatibility reads share the original
|
|
254
|
-
timeout budget.
|
|
255
|
-
|
|
256
|
-
In Extension mode, a page snapshot that reports the requested tab is missing returns `TARGET_NOT_FOUND` with
|
|
257
|
-
`context.targetId` and the original `context.nativeMessage`. Input rejected before dispatch retains `eventsExecuted=0`
|
|
258
|
-
and `actionExecuted=false`. The failed request is not redirected to another page or replayed. User-script exceptions
|
|
259
|
-
with the same text are not classified as missing pages.
|
|
260
|
-
|
|
261
|
-
Creation failures retain `error.context.createdTargetId`, window ID, actual `managed`, `actionExecuted`,
|
|
262
|
-
`actionStatus="partial"` and `failureStage` when Chrome has returned the identity. If an RPC response is unknown,
|
|
263
|
-
`actionStatus` and `actionExecuted` are `"unknown"`; `pageContext.targetId` is null unless the created identity is
|
|
264
|
-
known, never the previous default page. Failed creation is not automatically repeated or undone.
|
|
265
|
-
|
|
266
|
-
Temporary target restoration is reported separately in `pageContext.targetRestoration`: `restored` selects the previous
|
|
267
|
-
default, `cleared` leaves no default when none existed, `previous_target_closed` clears a closed default, and `failed`
|
|
268
|
-
reports restoration or cleanup errors while clearing the temporary selection. `error` and `cleanupError` retain the
|
|
269
|
-
respective failure messages. The primary action result or original error is preserved; completed input is not replayed
|
|
270
|
-
or reported as unexecuted. `browse attach` and `manage adoptPage` keep their persistent-default behavior. Concurrent
|
|
271
|
-
page responses describe the page actually used by each action.
|
|
272
|
-
|
|
273
|
-
`browse.list` returns each page's revision and metadata. Revisions combine a backend epoch with a per-page counter.
|
|
274
|
-
Extension counts main-frame navigations and MCP actions; CDP counts observed navigation for the attached page and
|
|
275
|
-
conservatively counts sent mutating commands, including evaluations. Neither driver tracks arbitrary DOM changes made by
|
|
276
|
-
the page itself; re-read URL and revision before a conditional action. `browse` navigation/close, `input`, `evaluate`,
|
|
277
|
-
and eligible `manage` page actions accept `expectedUrl` and `expectedRevision`. A mismatch at the backend returns
|
|
278
|
-
`ACTION_PRECONDITION_FAILED` before that page action is sent. A multi-event action checks conditions before its first
|
|
279
|
-
modifying command, not before every event. A failed or timed-out action can still change the revision when it may have
|
|
280
|
-
had partial effects.
|
|
281
|
-
|
|
282
422
|
For `browse`, only `open`, `back`, `forward`, `refresh`, and `close` accept these conditions. Other actions, including
|
|
283
423
|
`attach`, reject them with `INVALID_ARGUMENT` before changing any target.
|
|
284
424
|
|
|
@@ -288,8 +428,12 @@ page. `releasePage` revokes full managed access without closing the tab or chang
|
|
|
288
428
|
log state and removes debugging and console capture resources. If Chrome prevents resource cleanup, the response
|
|
289
429
|
includes `warnings` while managed access is still revoked.
|
|
290
430
|
|
|
291
|
-
|
|
292
|
-
|
|
431
|
+
Managed access survives a Service Worker restart. Reloading the Extension also restores access to surviving managed tabs
|
|
432
|
+
whose original document identity still matches, without refreshing or adopting them again. Tabs with unavailable
|
|
433
|
+
document identity require explicit `adoptPage` after an Extension reload; ordinary navigation keeps managed access, and
|
|
434
|
+
`releasePage` remains revoked after a restart or reload. A reused tab ID does not authorize a different document. A
|
|
435
|
+
managed tab can keep using this Extension's existing debugger session after a Service Worker restart. Sessions owned by
|
|
436
|
+
other debuggers still return `DEBUGGER_BLOCKED`.
|
|
293
437
|
|
|
294
438
|
Use `manage(action="grantReadAccess", targetId=...)` to grant ordinary reads and `revokeReadAccess` to revoke them; no
|
|
295
439
|
popup click is required. Both require an explicit target and accept `expectedUrl`/`expectedRevision`. Grants belong to
|
|
@@ -300,52 +444,90 @@ target ID alone does not authorize reading. The grant covers ordinary content re
|
|
|
300
444
|
attributes, computed styles, and page state. Scripts, debugger operations, screenshots, input, and cookie access do not
|
|
301
445
|
inherit it; existing cookie operations have separate URL/name filter rules. When page management or navigation is
|
|
302
446
|
refused for lack of managed access, the revision and any valid ordinary-read grant remain unchanged.
|
|
303
|
-
`manage(action="pageMetadata", targetId=...)` reads or updates `taskHint` and `note`,
|
|
304
|
-
|
|
305
|
-
`
|
|
306
|
-
|
|
447
|
+
`manage(action="pageMetadata", targetId=...)` reads or updates `taskHint` and `note`, with
|
|
448
|
+
`expectedUrl`/`expectedRevision` conditions. A mismatch returns `ACTION_PRECONDITION_FAILED` before reading or updating
|
|
449
|
+
notes. Extension persists `origin=created/adopted/unknown`, creation time and task notes. Existing v1 pages migrate to
|
|
450
|
+
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
|
+
are maintained
|
|
453
|
+
by Extension; notes never grant content access.
|
|
454
|
+
|
|
455
|
+
Start each task with `browse list`, select a suitable page by task name and notes, and attach in the
|
|
456
|
+
background to reuse it.
|
|
457
|
+
Call `newPage` only when no suitable page exists, supplying `taskHint` and a `note` that identifies temporary, output or
|
|
458
|
+
reusable use. `newPage` always creates a new page. By default, it uses an existing normal window containing a trusted
|
|
459
|
+
created page, then another existing normal window. With no normal window it returns an error; lost caches never create a
|
|
460
|
+
window. Task groups are reused only through trusted creation records and current native membership, never their name.
|
|
461
|
+
Mixed user groups and same-name user groups remain untouched. Renaming a task updates the native group title when all
|
|
462
|
+
trusted members share that task. Native moves, closure and membership changes clear invalid relationships.
|
|
463
|
+
|
|
464
|
+
At task completion, use the existing close/release actions on an explicit page set. Default cleanup closes only pages
|
|
465
|
+
created for this task whose notes explicitly identify temporary use. Preserve adopted/unknown pages, outputs, reusable
|
|
466
|
+
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
|
+
groups require
|
|
469
|
+
Extension; CDP accepts metadata-only `taskHint/note` options.
|
|
470
|
+
|
|
471
|
+
Explicit `networkidle` starts Network observation before navigation and requires 500 ms of quiet after tracked requests finish. Missing or interrupted observation returns an error. The default `load` path does not attach a debugger for network-idle tracking.
|
|
307
472
|
|
|
308
473
|
### Access challenges
|
|
309
474
|
|
|
310
475
|
After `open`, `back`, `forward`, `refresh`, `input`, and `evaluate`, MCP Chrome waits for a Cloudflare JS Challenge or
|
|
311
|
-
Turnstile checkbox. When Extension mode is active, navigation starts without debugger logging
|
|
312
|
-
title passively for eight seconds. If the interstitial persists,
|
|
313
|
-
clicks it only when it finds one. Extension inspect uses an isolated world
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
`Verify you are human`
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
476
|
+
Turnstile checkbox. When Extension mode is active, navigation starts without debugger logging. While a Challenge title
|
|
477
|
+
persists, MCP Chrome reads the live tab title passively for the first eight seconds. If the interstitial persists, it
|
|
478
|
+
checks for a visible Turnstile control and clicks it only when it finds one. Extension inspect uses an isolated world.
|
|
479
|
+
Challenge titles detach the debugger before inspection; ordinary-page checks retain an existing connection unless a
|
|
480
|
+
visible verification control or unresolved challenge content is found. Same-page fixture buttons use the existing page
|
|
481
|
+
click. If a Cloudflare Turnstile iframe is present, inspect CSS coordinates are converted to screen coordinates and the
|
|
482
|
+
OS mouse moves along a path, hovers, then presses and releases: `xdotool` on Linux uses the focused Chrome client-window
|
|
483
|
+
geometry and `xprop` GTK frame extents only when that window title matches the test page. Missing tools, invalid
|
|
484
|
+
geometry, or a viewport mismatch stop the click instead of guessing the content origin from Chrome `screenX` or
|
|
485
|
+
`outerHeight - innerHeight`; `cliclick` or System Events on macOS; and PowerShell `mouse_event` on Windows. Widget
|
|
486
|
+
clicks target the checkbox on the left of the compact Turnstile card, including when the host wrapper is wider than the
|
|
487
|
+
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
|
+
zero-size rect, including the later host `Verify you are human` / `请验证您是真人` button. The OS click runs only when
|
|
489
|
+
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 again
|
|
491
|
+
before pressing. On Linux, a 1 px native round trip calibrates the current content origin while the debugger banner
|
|
492
|
+
animates. If the control moves, the mouse repeats the path, hover and calibration within the original timeout. A changed
|
|
493
|
+
page, control stage or focus stops the click. Missing OS mouse tools or an unfocused window return a visible error instead
|
|
494
|
+
of a silent CDP click. A Turnstile widget is clicked only after two inspections report the same
|
|
495
|
+
click point; unrelated elements do not become widgets just because their sizes match. Distant OS-mouse paths start near
|
|
496
|
+
the control instead of flying across the screen. The same checkbox or compact widget is clicked at most once; if
|
|
497
|
+
Cloudflare then shows a visible `Verify you are human` or `请验证您是真人` button, that button is inspected as `verify`
|
|
498
|
+
and clicked at most once in the same wait. Use the default `diagnostics=false` for challenge-protected pages because
|
|
499
|
+
diagnostics starts debugger console and network collection.
|
|
500
|
+
|
|
501
|
+
Detection covers titles such as `Just a moment...` and `请稍候…`, visible challenge DOM or body-text markers, and
|
|
502
|
+
`Verify you are human` / `请验证您是真人` controls, including visible `button` elements with that exact text. A normal
|
|
503
|
+
title still requires a bounded check of visible content: visible `正在进行安全验证` blocks the action, while hidden
|
|
504
|
+
markers do not. Pages without challenge evidence continue without a fixed eight-second wait. Same-page buttons use page
|
|
505
|
+
input when no Cloudflare iframe is present. CDP reads live titles with `Target.getTargetInfo`. A leftover Cloudflare
|
|
506
|
+
iframe or an old pending header alone does not keep a recovered page pending or trigger scrolling or a click. Cached
|
|
507
|
+
titles do not decide the result. MCP Chrome does not call a CAPTCHA solver, retry navigation, or export `cf_clearance`
|
|
508
|
+
values. A CDP timeout does not prove that the site fails in a user Chrome session; check the returned `mode` before
|
|
509
|
+
diagnosing the site.
|
|
510
|
+
|
|
511
|
+
A completed embedded widget can retain its container. An associated nonempty response marks that widget complete;
|
|
512
|
+
reset or expiry returns it to pending. Each widget is checked separately, and a response in another form cannot complete
|
|
513
|
+
it. Detection returns completion state without returning the response value.
|
|
514
|
+
|
|
515
|
+
Input and evaluate check for a new challenge after the action returns, using the remaining budget. A verification
|
|
516
|
+
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 timeout
|
|
518
|
+
returns `retryable=false` and `nextAction="wait_and_verify"`; wait for verification and inspect the business result.
|
|
337
519
|
|
|
338
520
|
A resolved challenge returns `challengeResolved=true`, `challengeKind`, `waitedMs`, `clickedTurnstile`, and
|
|
339
521
|
`clearanceCookiePresent` (name presence only). If the visible page text says verification succeeded and Cloudflare is
|
|
340
522
|
waiting for the origin, the result also has `originResponsePending=true`; verification passed, but the destination page
|
|
341
523
|
is not loaded yet. Hidden template text such as a `display:none` success heading does not count, and a visible Turnstile
|
|
342
|
-
checkbox still counts as pending. Challenge results and errors include `mode`.
|
|
343
|
-
`retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is not reported as `js`).
|
|
524
|
+
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 not reported as `js`).
|
|
344
526
|
Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP reputation checks
|
|
345
527
|
cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears the header flag;
|
|
346
528
|
ordinary iframe document responses and clearing network logs do not.
|
|
347
529
|
|
|
348
|
-
### input - Keyboard &
|
|
530
|
+
### input - Keyboard, Mouse & File Input
|
|
349
531
|
|
|
350
532
|
Event sequence model supporting arbitrary combinations:
|
|
351
533
|
|
|
@@ -358,6 +540,7 @@ Event sequence model supporting arbitrary combinations:
|
|
|
358
540
|
| `wheel` | Mouse wheel scroll |
|
|
359
541
|
| `touchstart` / `touchmove` / `touchend` | Touch events |
|
|
360
542
|
| `type` | Type text (with optional `delay`, `dispatch` for React/Vue) |
|
|
543
|
+
| `upload` | Select local files in a file input; `files:[]` clears the selection |
|
|
361
544
|
| `wait` | Pause between events |
|
|
362
545
|
| `select` | Select text by content (mouse sim) |
|
|
363
546
|
| `replace` | Find and replace text |
|
|
@@ -366,12 +549,20 @@ Event sequence model supporting arbitrary combinations:
|
|
|
366
549
|
| `editorInsert` | Insert text at the current editor selection |
|
|
367
550
|
| `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
|
|
368
551
|
|
|
552
|
+
On background Extension tabs, a default unmodified left click on an element uses checked synthetic events and returns a
|
|
553
|
+
`warnings` entry with `isTrusted=false`, without selecting the tab. On a rendered active tab, precise mode uses native input.
|
|
554
|
+
Background coordinate clicks, movement, or modified/multiple clicks require explicit
|
|
555
|
+
`manage(action="inputMode",inputMode="stealth")`; mouse-button cleanup remains available.
|
|
556
|
+
|
|
369
557
|
Special-case parameters:
|
|
370
558
|
|
|
371
559
|
- `keydown` accepts `commands` (e.g. `["selectAll"]`, `["copy"]`, `["paste"]`, `["cut"]`, `["undo"]`, `["redo"]`) to
|
|
372
560
|
trigger native browser editing commands. A successful response means the browser accepted the command dispatch; use
|
|
373
561
|
`postCondition` or `extract` to verify the page result. `commands` is precise-mode only; stealth mode throws because
|
|
374
|
-
the CDP commands API has no JS-event equivalent.
|
|
562
|
+
the CDP commands API has no JS-event equivalent. An element or coordinate `target` is focused without mouse events
|
|
563
|
+
before command dispatch. Coordinate focus does not toggle checkboxes, follow links, or invoke click listeners. A
|
|
564
|
+
missing or unfocusable target returns an error before commands are sent. Extension `frame` coordinates are local to
|
|
565
|
+
that frame.
|
|
375
566
|
- `keydown` on a key already held emits `rawKeyDown` with `autoRepeat: true` (Puppeteer-compatible long-press).
|
|
376
567
|
|
|
377
568
|
`events` must contain at least one event. Parameters: `humanize` enables Bézier curve movement and random delays.
|
|
@@ -381,50 +572,147 @@ waits for a page state after the events so callers can distinguish dispatched in
|
|
|
381
572
|
accepts 50-5000 ms. A `postCondition.script` may be an expression, function, async function, or Promise expression;
|
|
382
573
|
functions are invoked and the final Promise value is awaited before matching, while thrown or rejected errors fail the
|
|
383
574
|
check. `targetId` (or legacy `tabId`) selects a page in either backend; `frame` selects an iframe (CSS selector or
|
|
384
|
-
index) in
|
|
575
|
+
index or a nested path) in either backend. When either scope is provided, the action, diagnostics, and post-condition use the backend
|
|
385
576
|
selected for that target scope.
|
|
386
577
|
|
|
578
|
+
Text, selector and URL checks recover a transient lost context within the remaining input and verification deadlines. A context that stays unavailable, a closed native connection, or an exhausted read budget returns `verificationStatus="unavailable"`. Script checks report native context failures immediately. Native execution termination and engine execution timeouts during verification return `unavailable` in both Extension and CDP. Selector syntax errors and page-thrown or rejected errors return `error`, including when an exception's string conversion also throws. Error text mentioning a frame or timeout does not change the source. A completed input keeps `actionStatus="completed"`, `failureStage="verification"` and top-level `retryable=false`. Use `postCondition.retryable` to retry the check on its own. Verification shares the action's total deadline; an exhausted total budget starts no new check.
|
|
579
|
+
|
|
580
|
+
Cancellation interrupts verification reads and polling waits. Input then attempts a bounded release of keys newly pressed by that request before the next queued action starts. Keys held before the request remain held; release failures retain a diagnostic.
|
|
581
|
+
|
|
582
|
+
Text checks match rendered page text and visible, non-password form values. The bounded `actual` excerpt includes the matched text. Clicks on a Shadow host accept its own shadow descendants; synthetic click, key and input events reach host and document listeners, while mouseenter and change retain their local event semantics.
|
|
583
|
+
|
|
584
|
+
Coordinate targets use the selected frame's viewport coordinates. Native precise input accounts for the frame's content boundary, scaling, rotation, skew and nested placement; input whose coordinates cannot be mapped reliably fails before the affected event. Earlier completed events retain their progress. Stealth events keep frame-local coordinates.
|
|
585
|
+
|
|
586
|
+
Target-based coordinate preparation follows assigned slots and Shadow hosts to the actual scroll container. On visible pages, it checks the target rectangle and ancestor scroll positions across consecutive renders, including cascades triggered by page listeners that stop event propagation. A stable target remains actionable beside a looping, unrelated scroller. A page hidden during this wait uses its current layout without waiting for paused animation frames; a page that becomes visible resumes render checks. Continuous target motion or ancestor scrolling can exhaust the shared request deadline, leaving that event undispatched.
|
|
587
|
+
|
|
588
|
+
An omitted wheel target keeps the current mouse position. Extension wheel helper setup and input target the same resolved documentId; replacement or removal before input returns not_started without selecting the new document.
|
|
589
|
+
|
|
590
|
+
Wheel and mouse events carry the currently held Ctrl, Shift, Alt and Meta fields, including combined modifiers and precise right-click events that use synthetic dispatch. Synthetic events retain `isTrusted=false`; application listeners can inspect the modifier fields and cancel their default scroll.
|
|
591
|
+
|
|
592
|
+
Extension coordinate wheel follows each axis's effective scroll range, including reverse Flex layouts and vertical writing modes. Fractional deltas accumulate across consecutive inputs to the same scroll container, including changes to the hit descendant and scrolling performed by that wheel listener. Position changes between inputs reset that container's pending fraction; another container or document starts its own sequence. Native scroll progress identifies fractional endpoints under CSS zoom. When native progress is unavailable, a console warning identifies the CSSOM-bounds compatibility path. Element scroll distances account for effective CSS zoom; ordinary transform scale keeps its existing wheel-distance semantics. Viewport scrolling uses its own units.
|
|
593
|
+
|
|
594
|
+
Scroll-container eligibility accounts for the namespace, principal box and text-editing controls. MathML math layouts, flow-root and inline flow-root list items, block ruby and Chrome-supported `-webkit-box`/`-webkit-inline-box` layouts retain their scrolling and boundary behavior. A text input can scroll its internal text even when Chrome reports computed overflow as clip. A block SVG viewport does not become a CSS scroll boundary from hidden/contain declarations; a foreignObject with a scrolling box retains its own auto scrolling and hidden contain/none boundary, and embedded HTML retains its own scrolling behavior. At a real container boundary, `overscroll-behavior-x/y: contain` or `none` stops that axis, including zero-range containers; `auto` lets an unconsumed axis continue along the original chain. A nested `overflow:hidden` container keeps its boundary policy without scrolling itself; ordinary clip/visible, non-atomic inline and display:contents nodes do not add that boundary.
|
|
595
|
+
|
|
596
|
+
The viewport follows root/body overflow propagation. A body with no principal box, including display:contents, does not supply its overflow. Effective containment on html/body, including content-visibility or container-type, keeps the body independent. A body supplying viewport overflow is not a separate boundary, and hidden/clip viewport axes do not scroll. A scrollable target consumes its own input first. Absolute/fixed targets then follow the nearest applicable positioning containing block through the composed tree, including slots and foreignObject content. Transform, filter, containment, 3D/motion conditions and applicable will-change names keep their own box-eligibility rules.
|
|
597
|
+
|
|
598
|
+
The composed, cancelable wheel event reaches Shadow host and document listeners. Effective `preventDefault()` suppresses the simulated default scroll; the event still reports `actionStatus="completed"` and counts as one executed input. Each axis selects its scroll route from the boundary at input start. A listener that resizes or repositions a scroll container retains its own changes; the default action uses the resulting position on the selected route. A container that loses its scroll range lets unconsumed input continue along the original chain under its overscroll policy. Removing or moving the hit element does not redirect that wheel to a newly inserted ancestor or an unrelated viewport.
|
|
599
|
+
|
|
600
|
+
Extension wheel uses programmatic scrolling for its default action. Scroll snapping follows that programmatic endpoint, which can differ from native wheel intent. Mandatory and proximity snap layouts retain their declared snapping; native wheel endpoint differences are an accepted compatibility behavior.
|
|
601
|
+
|
|
387
602
|
For keyboard `type`, `timeout` includes Challenge waiting, focus preparation, character input, and `delay`/`humanize`
|
|
388
603
|
delays. Extension precise/stealth and CDP use the remaining budget. An explicit budget such as `timeout=45000` allows
|
|
389
|
-
valid input to take longer than the default
|
|
390
|
-
Already dispatched input cannot be undone, so a timeout may leave partial input. A response with
|
|
391
|
-
`actionStatus="unknown"`, and `retryable=false` requires an independent page read to check the
|
|
392
|
-
replay the whole event sequence.
|
|
604
|
+
valid input to take longer than the default 30,000 milliseconds. When the budget expires, subsequent characters and
|
|
605
|
+
events stop. Already dispatched input cannot be undone, so a timeout may leave partial input. A response with
|
|
606
|
+
`actionExecuted=true`, `actionStatus="unknown"`, and `retryable=false` requires an independent page read to check the
|
|
607
|
+
actual value; do not replay the whole event sequence.
|
|
393
608
|
|
|
394
609
|
Mouse target lookup, stepped movement, and `humanize` delays also share the remaining input budget. Each movement and
|
|
395
610
|
the subsequent click check the deadline; expiry stops further movement and clicking. Already dispatched native events
|
|
396
611
|
cannot be undone. Read the page independently after an unknown result instead of replaying the action.
|
|
397
612
|
|
|
613
|
+
Explicit Extension precise `keydown`/`keyup` events use native keyboard input. Focus preparation shares the remaining request budget. When focus emulation is needed, response `warnings` explains that the document temporarily reports `visible`; the actual tab and window focus stay unchanged. The original setting is restored before `postCondition` runs.
|
|
614
|
+
|
|
615
|
+
A recovered debugger session with an unknown original focus setting on a background tab returns `KEYBOARD_FOCUS_STATE_UNKNOWN` and `not_started`, preserving that setting. Explicit stealth or an independent CDP session remain available. Restoration failures return `keyboardFocusCleanup`; completed events retain `completed`, and unconfirmed dispatch retains `unknown`. Failure, cancellation or expiry attempts to release keys newly pressed by this request. Successful requests preserve intentionally held keys.
|
|
616
|
+
|
|
398
617
|
Command focus, text selection, and replacement share the remaining event budget. Expiry stops subsequent actions; Shift
|
|
399
618
|
release is still attempted without hiding an earlier action error. Stepped CDP touch movement also stops at the
|
|
400
619
|
deadline.
|
|
401
620
|
|
|
621
|
+
Stealth left clicks emit `click`, middle clicks emit `auxclick`, and right clicks emit `contextmenu`. Each press/release
|
|
622
|
+
pair carries its click `detail`; only left multiple clicks emit `dblclick` at `detail=2`. Separate stealth `mouseup`
|
|
623
|
+
events follow the same button mapping.
|
|
624
|
+
|
|
402
625
|
In stealth mode, `delay` separates characters; the first character has no initial wait. Background page timer throttling
|
|
403
626
|
can lengthen subsequent intervals, but the same deadline still stops further input.
|
|
404
627
|
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
`
|
|
628
|
+
Default precise keyboard `type` in Extension and CDP mode dispatches Enter for each newline (CRLF is normalized).
|
|
629
|
+
An editor that submits on Enter can therefore submit part of a multiline input. For multiline replacement in Extension
|
|
630
|
+
mode, use `mode="controlled"` (or `dispatch=true`) with a `target`: it replaces the complete value or contenteditable
|
|
631
|
+
text and dispatches input/change without Enter. Form controls keep their native value setters.
|
|
632
|
+
|
|
633
|
+
Keyboard input and `editorInsert` use the current caret and selection. Keyboard `type` with a `target` clicks it first
|
|
634
|
+
and can change the insertion point; `editorInsert` focuses its target without clicking and inserts through the browser
|
|
635
|
+
editing API without Enter. To append multiline text, place the caret at the end and send `editorInsert` without a
|
|
636
|
+
`target`. A nonempty selection is replaced, not appended. Read the resulting value to verify the editor accepted it.
|
|
408
637
|
|
|
409
638
|
CDP clicks and keyboard input also wait for stable element position and size in background pages without activating
|
|
410
639
|
them. Visibility, enabled-state, viewport, and click coverage checks still apply. Target lookup, actionability checks,
|
|
411
640
|
and the final coordinate read share the remaining event budget. If any of these stages exhausts it, no mouse or keyboard
|
|
412
641
|
event is dispatched.
|
|
413
642
|
|
|
414
|
-
**`click`-specific**: `force: true` requires `forceReason` and a non-coordinate element `target`, and
|
|
415
|
-
|
|
416
|
-
and
|
|
417
|
-
|
|
418
|
-
`
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
643
|
+
**`click`-specific**: `force: true` requires `forceReason` and a non-coordinate element `target`. It skips actionability checks while dispatching standard DOM mouse events. Middle/right and multiple clicks use the same rules; a coordinate or omitted target cannot use force. Failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering elements, candidate blockers and suggestions.
|
|
644
|
+
|
|
645
|
+
**`type`-specific**: `mode="controlled"` or `dispatch:true` replaces the value or contenteditable text and sends `input`/`change` without Enter. It requires a non-coordinate `target` and Extension mode. Targets must be HTML `input`, `textarea`, `select` or contenteditable; effectively disabled controls, readonly controls, unsupported containers and file inputs are rejected before focus or input events. Disabled fieldsets follow HTML rules, including the first-legend exception. Use `upload` for a file input. Ordinary controls, customized built-ins and same-origin controls adopted from another document use the native value setter for their actual form interface; an unavailable setter returns an error before focus.
|
|
646
|
+
|
|
647
|
+
Controlled input and target-lookup failures return `locator`, `matchCount`, `nth`, bounded `candidates` and an `activeElement` summary without input values. Unavailable focus is `null`; a failed DOM query adds `diagnosticError`.
|
|
648
|
+
|
|
649
|
+
Cancellation or expiry after a confirmed Extension precise character or Enter event preserves executed progress and invalidates the old page revision. Cancellation before the first dispatch keeps the not-started state. Read the current value and revision before another action.
|
|
650
|
+
|
|
651
|
+
For a tag field that commits on Enter, send the text and explicit Enter events, then check the created tag. This `input` example uses `#tag-entry` for the field and `#tags` for its tag list; use the selectors from the page:
|
|
652
|
+
|
|
653
|
+
```json
|
|
654
|
+
{
|
|
655
|
+
"events": [
|
|
656
|
+
{ "type": "type", "target": { "css": "#tag-entry" }, "text": "12345" },
|
|
657
|
+
{ "type": "keydown", "key": "Enter" },
|
|
658
|
+
{ "type": "keyup", "key": "Enter" }
|
|
659
|
+
],
|
|
660
|
+
"postCondition": { "selector": "#tags [data-value=\"12345\"]" }
|
|
661
|
+
}
|
|
662
|
+
```
|
|
663
|
+
|
|
664
|
+
#### Text selection and sensitive input
|
|
665
|
+
|
|
666
|
+
`replace` uses text selection for `textarea` and input types `text`, `search`, `tel`, `url` and `password`. Other input types use a native full-value update and return requested and actual browser-normalized values. Standalone `select` on an unsupported type returns `UNSUPPORTED_SELECTION`. CDP locator targets are focused through CDP rather than Extension ref IDs.
|
|
667
|
+
|
|
668
|
+
Event-level `nth` selects a text occurrence; nested `target.nth` selects a matching element. Both are zero-based and can be combined. Selection errors include editor and selection state.
|
|
669
|
+
|
|
670
|
+
Password values are omitted from failure context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text`, including locator details in `error.logs`. Password `select`/`replace` hides console and network diagnostic bodies on success and failure, returning `diagnostics.redacted=true` and `reason="sensitive_input_or_unresolved_target"`. An unresolved selection target receives the same protection. Ordinary input keeps its diagnostics, and password protection ends with the current input request.
|
|
671
|
+
|
|
672
|
+
#### Upload local files
|
|
673
|
+
|
|
674
|
+
Prefer mcp-chrome for browsing, page interaction, and file uploads. Uploads reuse the current page and Extension/CDP
|
|
675
|
+
connection. Use Chrome DevTools for browser or extension diagnostics and specific tasks that mcp-chrome does not cover.
|
|
676
|
+
|
|
677
|
+
Select a file at its original path, including files in Downloads, through the `input` tool's `upload` event:
|
|
678
|
+
|
|
679
|
+
```json
|
|
680
|
+
{
|
|
681
|
+
"events": [
|
|
682
|
+
{
|
|
683
|
+
"type": "upload",
|
|
684
|
+
"target": { "css": "input[type=file]" },
|
|
685
|
+
"files": ["./review.zip"]
|
|
686
|
+
}
|
|
687
|
+
]
|
|
688
|
+
}
|
|
689
|
+
```
|
|
690
|
+
|
|
691
|
+
`files` is required. Paths refer to readable regular files on the MCP Server machine. Relative paths use the Server's
|
|
692
|
+
working directory; absolute paths and `~/` paths are supported. The Server transfers file bytes, so the browser may run
|
|
693
|
+
on another machine. The selected files' combined size must be below 50 MiB; a total at or above that limit fails before
|
|
694
|
+
changing the file input.
|
|
695
|
+
|
|
696
|
+
Use multiple paths for an input with the `multiple` attribute. Use `files:[]` to clear it:
|
|
697
|
+
|
|
698
|
+
```json
|
|
699
|
+
{"events":[{"type":"upload","target":{"css":"#attachments"},"files":[]}]}
|
|
700
|
+
```
|
|
701
|
+
|
|
702
|
+
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. Uploads use the current
|
|
704
|
+
Extension or CDP connection and the selected input mode. Default precise mode supports strict CSP pages; stealth keeps
|
|
705
|
+
the page's CSP restrictions. Extension upload requires managed-page access, checked before any local file read.
|
|
706
|
+
|
|
707
|
+
The result summarizes the selected file names, sizes, MIME types, and dispatched events. The input receives `input`
|
|
708
|
+
followed by `change`, using synthetic events. Sites requiring trusted events need site-specific verification. A page
|
|
709
|
+
that clears the input in its `change` handler still receives the file selection; the result describes the assignment
|
|
710
|
+
before those handlers run.
|
|
711
|
+
|
|
712
|
+
Use `postCondition` for the site's attachment-ready or upload-complete state, and submit separately when the site
|
|
713
|
+
requires it. A failed post-condition preserves the completed input action. File reads, transfer, and assignment share
|
|
714
|
+
the input timeout and cancellation. A failure before assignment leaves the selection unchanged. An unconfirmed
|
|
715
|
+
assignment returns `actionStatus="unknown"` and `retryable=false`; inspect the page before deciding what to do next.
|
|
428
716
|
|
|
429
717
|
### extract - Content Extraction
|
|
430
718
|
|
|
@@ -442,37 +730,44 @@ Text extraction uses the browser's `innerText` for HTML pages and selected eleme
|
|
|
442
730
|
`style`/`script` source and hidden descendants. Explicitly selected non-rendered HTML follows the browser's `innerText`
|
|
443
731
|
rules; SVG/XML nodes use `textContent`. Use `html` for source markup.
|
|
444
732
|
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
`
|
|
452
|
-
|
|
453
|
-
pixels, and
|
|
454
|
-
|
|
455
|
-
capabilities report `hiddenTabScreenshot
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
current Server process; unknown creation provenance stays `unknown`, and another Server does not inherit the notes. They
|
|
465
|
-
are not cross-session ownership or permission evidence. Inline and file outputs include the same fields. `managed`
|
|
466
|
-
describes Extension page management; CDP returns false without restricting normal operations through the CDP connection.
|
|
467
|
-
`targetId` (or `tabId`) selects a page in either backend; `frame` is Extension-only.
|
|
733
|
+
#### HTML and images
|
|
734
|
+
|
|
735
|
+
`output` saves to a file, or a directory for `images=data`. `images=info|data` includes image metadata or bytes with HTML. Image data is limited to 2 MiB per image and 8 MiB per request. Directory export reads and writes one image at a time; each index entry records an `omitted` reason for unavailable or over-budget data. Inline output keeps the first 20 images with the same reasons and byte budgets. `frameHtml` reads the current document after `frame` routing.
|
|
736
|
+
|
|
737
|
+
#### Screenshots
|
|
738
|
+
|
|
739
|
+
Use `clip` for a coordinate region, `compareWith` for a PNG baseline and `diffOutput` for a PNG difference image. `diffOutput` requires `compareWith`. An unmatched, out-of-range or zero-sized target returns a target error. Responses contain `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip` and `capabilities`.
|
|
740
|
+
|
|
741
|
+
Capture limits are 16,384 pixels per side, 12,000,000 pixels total, 48 MiB estimated RGBA memory and 25 MiB encoded data. PNG baselines are checked before reading. Comparison limits each PNG to 25 MiB and 12,000,000 pixels; inflate output and scanline lengths must match the validated dimensions. Malformed or expansion-heavy PNGs are rejected. Use `clip` or `scale` for larger captures.
|
|
742
|
+
|
|
743
|
+
Screenshot and diagnostic-bundle capabilities report `hiddenTabScreenshot=false` in both backends. A hidden Extension tab returns `HIDDEN_TAB_SCREENSHOT`. Full-page capture preserves viewport and device emulation. If another debugger blocks precise capture, viewport fallback reports `metadata.degraded`, `metadata.fallback` and `metadata.limitations` in inline and file output. A window-level capture is discarded when the active tab changes, including A-to-B-to-A. Unsupported fallback options return `SCREENSHOT_FALLBACK_UNSUPPORTED`.
|
|
744
|
+
|
|
745
|
+
#### State and metadata
|
|
746
|
+
|
|
747
|
+
`state` returns `interactiveElements`. Both backends return metadata `frames` and the actual document `url`; Extension `frame` routing returns the selected document's URL. Unavailable declared CDP frame fields remain `null`, including DOM selectors and owner rectangles. Frame-tree order and IDs are preserved.
|
|
748
|
+
|
|
749
|
+
Metadata includes current `managed` state and `createdBy`, `createdAt`, `lastUsedAt`, `taskHint` and `note`, matching `browse list` and `manage pageMetadata` in both inline and file output. Notes belong to the page even when `frame` selects an iframe document. Extension preserves creation records, notes and trusted group relationships across Server and Extension reloads, checking live identity during restoration. CDP notes belong to the current Server process. Unknown provenance stays `unknown`; notes grant no access or cross-session ownership. CDP returns `managed=false` while retaining normal operations through its connection.
|
|
750
|
+
|
|
751
|
+
Page selection uses `targetId` or legacy `tabId`; `frame` selects a child or nested document in either backend.
|
|
468
752
|
|
|
469
753
|
**`attribute` special prefix**: `computed:<property>` returns the computed CSS style value (e.g. `computed:color`,
|
|
470
754
|
`computed:font-size`). Use `computed:*` to return all computed style properties as JSON (returns 300+ properties — use
|
|
471
755
|
`output` to save to file).
|
|
472
756
|
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
`
|
|
757
|
+
`extract.timeout` is the overall browser-operation budget in milliseconds (default 30000), including queueing,
|
|
758
|
+
page/frame preparation, target waiting, content reads, and page-context metadata. Each RPC uses the remaining budget;
|
|
759
|
+
`state` does not start a separate 30-second wait. An unconfirmed dispatched request returns unknown and is not replayed.
|
|
760
|
+
|
|
761
|
+
**`state`-specific**: `depth` controls accessibility-tree traversal depth (default 15). Reduce it to limit response size
|
|
762
|
+
on large pages. `mode` selects `accessibility` (default, derived from the a11y tree) or `domsnapshot` (raw
|
|
763
|
+
`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 requires full managed access to use the debugger.
|
|
765
|
+
Unavailable sibling iframe probes are listed in metadata as `unavailableFrames` and per-frame
|
|
766
|
+
`unavailableReason`; a uniquely verified selected iframe remains usable.
|
|
767
|
+
|
|
768
|
+
`target` restricts accessibility state to the selected element and its descendants in both backends. `depth` is relative to that subtree.
|
|
769
|
+
|
|
770
|
+
Accessibility state does not read hidden/password/file input value getters for element names or state text, including default `all`, subtrees and file output. Hidden controls retain their labels and `visible=false`. Labels, placeholders and titles provide names; ordinary inputs retain current values separately in `value` and `pageContent`, including named inputs. Submit labels retain their full text. Explicit script, HTML and attribute reads keep their existing behavior.
|
|
476
771
|
|
|
477
772
|
### wait - Wait for Conditions
|
|
478
773
|
|
|
@@ -483,7 +778,7 @@ describes Extension page management; CDP returns false without restricting norma
|
|
|
483
778
|
| `time` | Fixed delay |
|
|
484
779
|
| `idle` | Wait for DOM or network quiet period |
|
|
485
780
|
|
|
486
|
-
Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects
|
|
781
|
+
Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects a child document or nested path in either backend.
|
|
487
782
|
|
|
488
783
|
In CDP mode, `visible` requires a nonzero DOM rectangle and CSS that does not hide the element (`display:none` or
|
|
489
784
|
`visibility:hidden/collapse`). `hidden` accepts these hidden states or a missing element; `attached` and `detached` only
|
|
@@ -493,23 +788,23 @@ check whether the element exists.
|
|
|
493
788
|
a quiet period with no DOM changes. In CDP mode, it waits for network quiet instead. `ms` controls the relevant quiet
|
|
494
789
|
period (default 500ms). The response returns `idleKind` and `idlePeriodMs`; Extension responses also return `domStable`.
|
|
495
790
|
|
|
791
|
+
CDP idle includes requests already in flight. Independent idle and same-document `networkidle` exclude Worker requests with an empty `loaderId`, whose terminal events can be absent from the page session; page Fetch and Script requests remain pending until completion.
|
|
792
|
+
|
|
496
793
|
### evaluate - JavaScript Execution
|
|
497
794
|
|
|
498
795
|
Execute JavaScript in page context.
|
|
499
796
|
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
| `diagnostics` | Return new console warnings/errors and failed requests after execution |
|
|
512
|
-
| `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
|
|
797
|
+
- `script`: JavaScript code. Bare `return` statements are wrapped in IIFE
|
|
798
|
+
- `scriptFile`: Read code from a local file instead of `script`
|
|
799
|
+
- `args`: Function arguments; `[]` invokes a zero-argument function, omission evaluates the script as written
|
|
800
|
+
- `mode`: `precise` (default, debugger API) or `stealth` (JS injection)
|
|
801
|
+
- `staleContextRetry`: iframe stale-context policy: `never` (default) or `readOnly`
|
|
802
|
+
- `output`: Save the result to a file
|
|
803
|
+
- `targetId` / `tabId`: Select a page in either backend (`tabId` is an alias)
|
|
804
|
+
- `frame`: Target a child iframe by CSS selector/index, or use a nested path such as `["#outer", 0]` in either backend
|
|
805
|
+
- `timeout`: End-to-end budget (ms)
|
|
806
|
+
- `diagnostics`: Return new console warnings/errors and failed requests after execution
|
|
807
|
+
- `postCondition`: Wait for text, selector, URL fragment, or script result after execution
|
|
513
808
|
|
|
514
809
|
`script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
|
|
515
810
|
paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
|
|
@@ -522,12 +817,17 @@ such as `textContent` or `outerHTML`. Result materialization and serialization f
|
|
|
522
817
|
`actionStatus="completed"`, and `failureStage="output"` because the page script has already finished. Evaluate defaults
|
|
523
818
|
to `precise` even when global `inputMode` is `stealth`, and its `postCondition` checks use the same evaluate mode as the
|
|
524
819
|
action. `postCondition` is optional; when it is not provided, `success=true` only means the script executed and
|
|
525
|
-
returned.
|
|
526
|
-
observed checks. Precise iframe evaluation does not replay a script after a stale execution context by default. Set
|
|
820
|
+
returned. With a post-condition, `verificationStatus` distinguishes `matched`, `not_matched`, `unavailable` and `error`, with the last observed checks. A completed script keeps `actionStatus="completed"` and top-level `retryable=false`; `postCondition.retryable` applies only to an independent verification read. Precise iframe evaluation does not replay a script after a stale execution context by default. Set
|
|
527
821
|
`staleContextRetry="readOnly"` only when the script has no side effects; the Extension may then resolve a new context
|
|
528
|
-
and replay it once within the remaining timeout budget.
|
|
529
|
-
|
|
530
|
-
|
|
822
|
+
and replay it once within the remaining timeout budget. If Chrome still reports the removed document while resolving
|
|
823
|
+
that retry, the Extension waits for the current document within the same budget; this does not add script executions.
|
|
824
|
+
Permission failures stop immediately. CDP iframe execution supports `never`; requesting `readOnly` returns
|
|
825
|
+
`DRIVER_CAPABILITY_ERROR` with `actionExecuted=false` and `actionStatus="not_started"` before script dispatch.
|
|
826
|
+
A stale-context error after `Runtime.evaluate` reports `actionExecuted=true`, `actionStatus="unknown"` and
|
|
827
|
+
`retryable=false` in both backends, because earlier side effects may already have happened even though the final
|
|
828
|
+
result is unavailable. CDP preserves its native `CDP_ERROR`.
|
|
829
|
+
|
|
830
|
+
The total evaluate timeout also limits post-condition checks. If it expires after the action completes, the action stays completed and verification returns unavailable. A queue timeout before script dispatch preserves `actionExecuted=false` and the queue stage; a dispatched script with an unknown acknowledgement stays unknown. Read the page independently to determine its effects.
|
|
531
831
|
|
|
532
832
|
For object results in the main frame with Extension precise mode, an explicit `output` uses a 16 Mi (16777216) character
|
|
533
833
|
budget. Without `output`, the 1000000-character budget still applies, including automatic saving. Both paths retain the
|
|
@@ -535,68 +835,136 @@ depth limit of 8, the 2000-node budget, and non-serializable result rejection. T
|
|
|
535
835
|
units, not the output file's UTF-8 bytes; `tmp:` files also remain subject to the temporary output quota. Exceeding a
|
|
536
836
|
result limit reports the current limit and the completed script's output failure without replaying it.
|
|
537
837
|
|
|
838
|
+
Absolute `scriptFile` and `output` paths must resolve inside the Server working directory or this Server session's controlled temporary directory. The operating system's whole temp directory and Downloads are not automatic allowed roots. `PATH_NOT_ALLOWED` reports the actual `error.context.allowedRoots`; use `cwd:` or `tmp:` paths within them.
|
|
839
|
+
|
|
840
|
+
Responses include the stale-context policy, `retryAttempted`, bounded `retryReason` and the final `frameContext`: Extension frame, parent frame, URL, CDP frame and execution-context IDs. Same-URL frames are rejected only when the selected DOM iframe cannot identify one target. Existing iframe targets remain usable after an Extension reload without refreshing or navigating the page. Invalidated probe contexts report a warning and stop listening.
|
|
841
|
+
|
|
842
|
+
Sibling frames still loading do not delay selection of an available iframe. Background-page timer throttling does not extend the frame-probe wait. Cancellation or timeout before script dispatch releases the probes and leaves that script unexecuted.
|
|
843
|
+
|
|
844
|
+
A trusted Function-compilation policy rejection reports `CSP_BLOCKED` with the script not executed. Page `throw` or Promise rejection keeps its original error and executed state even when the text contains `CSP`, `Content Security Policy` or `unsafe-eval`.
|
|
845
|
+
|
|
538
846
|
### manage - Page & Environment Management
|
|
539
847
|
|
|
540
|
-
| Action | Description
|
|
541
|
-
| ------------------ |
|
|
542
|
-
| `newPage` | Create new controlled page/tab
|
|
543
|
-
| `pageMetadata` | Read or update per-page `taskHint` and `note`
|
|
544
|
-
| `closePage` | Close
|
|
545
|
-
| `adoptPage` | Grant full controlled-page access without focusing it
|
|
546
|
-
| `releasePage` | Remove a controlled tab from management without closing it
|
|
547
|
-
| `grantReadAccess` | Grant ordinary reads for an explicit page to the calling instance
|
|
548
|
-
| `revokeReadAccess` | Revoke that instance's ordinary read grant
|
|
549
|
-
| `updatePage` | Update native tab properties and return actual state
|
|
550
|
-
| `movePage` | Move a controlled tab to another window or index
|
|
551
|
-
| `reorderPage` | Reorder a controlled tab inside its window
|
|
552
|
-
| `pinPage` | Pin a controlled tab
|
|
553
|
-
| `unpinPage` | Unpin a controlled tab
|
|
554
|
-
| `activatePage` | Activate
|
|
555
|
-
| `focusWindow` | Focus an explicit window
|
|
556
|
-
| `resizeWindow` | Resize or change state for an explicit window
|
|
557
|
-
| `newWindow` | Create a new controlled window
|
|
558
|
-
| `closeWindow` | Close a window only when all tabs are managed
|
|
559
|
-
| `updateWindow` | Update native window position, state, focus or attention
|
|
560
|
-
| `groupPages` | Create a group or add controlled tabs to an existing group
|
|
561
|
-
| `ungroupPages` | Remove controlled tabs from groups without releasing them
|
|
562
|
-
| `updateGroup` | Update group title, color and collapsed state
|
|
563
|
-
| `moveGroup` | Move a group and its tabs to a window or index
|
|
564
|
-
| `clearCache` | Clear cache/storage (use `cookies` tool to clear cookies)
|
|
565
|
-
| `viewport` | Set viewport size
|
|
566
|
-
| `userAgent` | Set User-Agent
|
|
567
|
-
| `emulate` | Device emulation (iPhone, iPad, etc.)
|
|
568
|
-
| `inputMode` | Query or set input mode (`precise` / `stealth`)
|
|
569
|
-
| `stealth` | Inject anti-detection scripts
|
|
570
|
-
| `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`)
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
848
|
+
| Action | Description |
|
|
849
|
+
| ------------------ | ------------------------------------------------------------------------ |
|
|
850
|
+
| `newPage` | Create new controlled page/tab |
|
|
851
|
+
| `pageMetadata` | Read or update per-page `taskHint` and `note` |
|
|
852
|
+
| `closePage` | Close page and return `affected.before/after` in Extension and CDP modes |
|
|
853
|
+
| `adoptPage` | Grant full controlled-page access without focusing it |
|
|
854
|
+
| `releasePage` | Remove a controlled tab from management without closing it |
|
|
855
|
+
| `grantReadAccess` | Grant ordinary reads for an explicit page to the calling instance |
|
|
856
|
+
| `revokeReadAccess` | Revoke that instance's ordinary read grant |
|
|
857
|
+
| `updatePage` | Update native tab properties and return actual state |
|
|
858
|
+
| `movePage` | Move a controlled tab to another window or index |
|
|
859
|
+
| `reorderPage` | Reorder a controlled tab inside its window |
|
|
860
|
+
| `pinPage` | Pin a controlled tab |
|
|
861
|
+
| `unpinPage` | Unpin a controlled tab |
|
|
862
|
+
| `activatePage` | Activate an explicit page; Extension requires a controlled tab |
|
|
863
|
+
| `focusWindow` | Focus an explicit window |
|
|
864
|
+
| `resizeWindow` | Resize or change state for an explicit window |
|
|
865
|
+
| `newWindow` | Create a new controlled window |
|
|
866
|
+
| `closeWindow` | Close a window only when all tabs are managed |
|
|
867
|
+
| `updateWindow` | Update native window position, state, focus or attention |
|
|
868
|
+
| `groupPages` | Create a group or add controlled tabs to an existing group |
|
|
869
|
+
| `ungroupPages` | Remove controlled tabs from groups without releasing them |
|
|
870
|
+
| `updateGroup` | Update group title, color and collapsed state |
|
|
871
|
+
| `moveGroup` | Move a group and its tabs to a window or index |
|
|
872
|
+
| `clearCache` | Clear cache/storage (use `cookies` tool to clear cookies) |
|
|
873
|
+
| `viewport` | Set viewport size |
|
|
874
|
+
| `userAgent` | Set User-Agent |
|
|
875
|
+
| `emulate` | Device emulation (iPhone, iPad, etc.) |
|
|
876
|
+
| `inputMode` | Query or set input mode (`precise` / `stealth`) |
|
|
877
|
+
| `stealth` | Inject anti-detection scripts |
|
|
878
|
+
| `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
|
|
879
|
+
| `dialog` | Observe or handle dialogs |
|
|
880
|
+
| `networkCapture` | Start or stop original request/body/stream collection |
|
|
881
|
+
| `route` | Match and resolve paused requests |
|
|
882
|
+
| `httpAuth` | Set or clear scoped HTTP challenge credentials |
|
|
883
|
+
| `download` | Observe, wait for, and save an original download |
|
|
884
|
+
|
|
885
|
+
Native tab/window/group configuration uses Extension mode; `activatePage` also supports CDP. Mutations identify their
|
|
886
|
+
existing targets with `targetId`, `targetIds`, `windowId`, or `groupId` and return `affected.before/after`. Group
|
|
887
|
+
results also include `tabsBefore/tabsAfter`; `ungroupPages` removes an empty group through Chrome without revoking the
|
|
888
|
+
tabs' managed state. Window display changes and group title/color/collapse updates use the explicit `windowId` or
|
|
889
|
+
`groupId`, including containers with unmanaged members. They do not grant page permissions. Group moves and window
|
|
890
|
+
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
|
+
window in the background, including windows with unmanaged tabs. `clearCache` is unavailable in Extension mode
|
|
893
|
+
and returns `UNSUPPORTED_MODE`
|
|
894
|
+
without clearing anything. Use scoped `cookies(action="clear")` for cookies or CDP mode for storage and cache.
|
|
895
|
+
`focusWindow` only returns success after the target window is observed as focused; otherwise it returns
|
|
896
|
+
`WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with unmanaged tabs and returns
|
|
897
|
+
`WINDOW_HAS_UNMANAGED_TABS`. Persistent `adoptPage` and `releasePage` target changes are serialized with scoped tab
|
|
898
|
+
operations, so a concurrent multi-event input remains on its requested tab and the persistent target is applied
|
|
899
|
+
afterward.
|
|
900
|
+
|
|
901
|
+
CDP `activatePage` retains the default operation target and reports the fields available from that backend, without
|
|
902
|
+
inventing an `active` value or system-window focus. In Extension mode, `viewport`, `userAgent`, `emulate`, raw `cdp`,
|
|
903
|
+
and precise `evaluate` support controlled `about:blank` pages. Chrome-internal and Extension pages retain their access
|
|
904
|
+
restrictions. Querying `manage(action="emulate")` without `device` returns the local device catalogue without a live
|
|
905
|
+
page; page conditions are rejected for this query. Setting a device continues to validate the selected page and
|
|
906
|
+
conditions.
|
|
907
|
+
|
|
908
|
+
#### `newPage`
|
|
909
|
+
|
|
910
|
+
Parameters: `url`, `windowId`, `index`, `active`, `pinned`, `openerTabId`, `groupId`, `timeout`, `taskHint`,
|
|
911
|
+
`note`
|
|
912
|
+
|
|
913
|
+
`active` defaults to false; `groupId=-1` disables grouping; explicit placement is not changed by the default
|
|
914
|
+
visual group
|
|
915
|
+
|
|
916
|
+
#### `updatePage`
|
|
917
|
+
|
|
918
|
+
Parameters: `url`, `active`, `pinned`, `highlighted`, `muted`, `autoDiscardable`, `openerTabId`
|
|
919
|
+
|
|
920
|
+
Requires `targetId`; only `active=true` is supported and does not focus the window; `active=false` is rejected
|
|
921
|
+
before any update
|
|
922
|
+
|
|
923
|
+
#### `groupPages`
|
|
924
|
+
|
|
925
|
+
Parameters: `targetIds`, `groupId`, `windowId`, `title`, `color`, `collapsed`
|
|
926
|
+
|
|
927
|
+
Omit `groupId` to create a group in the members' window; mixed-window members require `windowId`; joining an
|
|
928
|
+
existing group accepts only `targetIds/groupId`
|
|
929
|
+
|
|
930
|
+
#### `ungroupPages`
|
|
931
|
+
|
|
932
|
+
Parameters: `targetIds`
|
|
933
|
+
|
|
934
|
+
Removes group membership and retains controlled-page access
|
|
935
|
+
|
|
936
|
+
#### `updateGroup`
|
|
937
|
+
|
|
938
|
+
Parameters: `groupId`, `title`, `color`, `collapsed`
|
|
939
|
+
|
|
940
|
+
An empty title and false collapsed value are applied as supplied
|
|
941
|
+
|
|
942
|
+
#### `moveGroup`
|
|
943
|
+
|
|
944
|
+
Parameters: `groupId`, `windowId`, `index`
|
|
945
|
+
|
|
946
|
+
Moves all members; `index=-1` means the end of the window
|
|
947
|
+
|
|
948
|
+
#### `newWindow`
|
|
949
|
+
|
|
950
|
+
Parameters: `url` or `urls`, `targetId`, `windowType`, `focused`, `incognito`, `left`, `top`, `width`,
|
|
951
|
+
`height`, `windowState`, `setSelfAsOpener`
|
|
952
|
+
|
|
953
|
+
`normal` supports multiple URL tabs and an existing controlled tab; `popup` accepts only one page; created
|
|
954
|
+
tabs are managed with distinct provenance
|
|
955
|
+
|
|
956
|
+
#### `updateWindow` / `resizeWindow`
|
|
957
|
+
|
|
958
|
+
Parameters: `windowId`, `left`, `top`, `width`, `height`, `windowState`, `focused`, `drawAttention`
|
|
959
|
+
|
|
960
|
+
Applies supported Chrome window properties and returns observed state
|
|
594
961
|
|
|
595
962
|
`updateWindow` and `resizeWindow` wait for a stable browser observation when changing state or geometry. Restoring a
|
|
596
963
|
non-normal window with `windowState="normal"` and bounds completes the state transition before applying bounds once.
|
|
597
964
|
OS-adjusted geometry is returned as observed. If observation does not stabilize within the bounded wait,
|
|
598
965
|
`WINDOW_UPDATE_NOT_OBSERVED` reports partial execution and the last observed window state; inspect `browse list` before
|
|
599
|
-
another update.
|
|
966
|
+
another update. If Chrome rejects bounds outside visible screen space, use coordinates and dimensions within the
|
|
967
|
+
screen's available area; the response preserves the bounds error without page-activation guidance.
|
|
600
968
|
|
|
601
969
|
`browse list` defaults to `details="summary"`, returning target identity, URL/title, placement, managed/revision and
|
|
602
970
|
metadata. Set `details="full"` for highlighted/muted/discardable state, opener IDs and available native readonly
|
|
@@ -607,6 +975,11 @@ omitted; full details use `favIconInline=true` to indicate one exists. Groups re
|
|
|
607
975
|
state, window, first-member index and member IDs. Color belongs to a group, not a tab. Readonly properties are returned
|
|
608
976
|
when Chrome supplies them, not accepted as configuration writes. Listing does not read page content, navigate or focus.
|
|
609
977
|
|
|
978
|
+
Older Extensions that return group summaries without member arrays use the same response's window/tab membership to
|
|
979
|
+
populate group members and first-member index. Summary/full details and filters remain available without another RPC. If
|
|
980
|
+
group information is absent entirely, `groups` is omitted with a warning that it is unavailable. A supplied `groups: []`
|
|
981
|
+
means no groups. Malformed group data, including only one member array, returns an error.
|
|
982
|
+
|
|
610
983
|
Moving tabs/groups accepts `index=-1`; page creation requires a nonnegative index. Opener and explicit group/window
|
|
611
984
|
options must identify the same window. Pinned tabs cannot be created inside a group. Window state/bounds conflicts and
|
|
612
985
|
action-inappropriate fields are rejected before mutation. CDP rejects unsupported Chrome UI options rather than ignoring
|
|
@@ -624,17 +997,115 @@ restores desktop metrics, page scale, and disabled touch emulation; restore the
|
|
|
624
997
|
- `safe` (default) — minimal patches (remove `navigator.webdriver`, clean CDP traces)
|
|
625
998
|
- `aggressive` — adds a few WebGL/plugin/language fingerprint patches (does NOT equal full masking)
|
|
626
999
|
|
|
1000
|
+
Management operations share a 30000 ms request deadline; `newPage` uses a supplied `timeout`. An expired queued change is rejected before dispatch. Unconditional `pageMetadata` reads, updates and clears use the explicit target independently of a long page action, including on the same page. Each request keeps its own URL/revision conditions. URL/revision-conditioned metadata keeps serialized condition checking.
|
|
1001
|
+
|
|
1002
|
+
Group operations serialize with page release and recheck native membership and managed authority under the affected page locks. Page creation uses `active`; `activate` is accepted only by `movePage`.
|
|
1003
|
+
|
|
1004
|
+
### Browser events and original files
|
|
1005
|
+
|
|
1006
|
+
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
|
+
A reference retains its original page even after the default target changes.
|
|
1009
|
+
|
|
1010
|
+
| `manage` action | Nested command | Result |
|
|
1011
|
+
| ---------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
|
1012
|
+
| `dialog` | `dialog:{op:"watch"\|"stop"\|"accept"\|"dismiss",ref?,text?}` | Observe dialogs or handle one observed dialog; `text` supplies a prompt answer |
|
|
1013
|
+
| `networkCapture` | `capture:{op:"start"\|"stop",include?:["body","stream"]}` | Record original requests, optional bodies, and WebSocket/SSE messages |
|
|
1014
|
+
| `route` | `route:{op:"add"\|"remove"\|"continue"\|"fulfill"\|"fail",...}` | Match page requests or handle an observed paused request |
|
|
1015
|
+
| `httpAuth` | `auth:{op:"set"\|"clear",...}` | Configure credentials for an explicit Server/Proxy challenge scope |
|
|
1016
|
+
| `download` | `download:{op:"watch"\|"stop"\|"wait"\|"save",...}` | Identify a download, wait for its native state, and save available original bytes |
|
|
1017
|
+
|
|
1018
|
+
#### Handle a dialog
|
|
1019
|
+
|
|
1020
|
+
```text
|
|
1021
|
+
manage(action="dialog", targetId="PAGE_ID", dialog={op:"watch"})
|
|
1022
|
+
input(targetId="PAGE_ID", events=[{type:"click", target:{css:"#show-prompt"}}])
|
|
1023
|
+
logs(type="dialog", targetId="PAGE_ID")
|
|
1024
|
+
manage(action="dialog", dialog={op:"accept", ref:"DIALOG_REF", text:"Answer"})
|
|
1025
|
+
```
|
|
1026
|
+
|
|
1027
|
+
A blocking dialog returns `DIALOG_OPEN` and its reference. Handle it, then check the original action's result. Dialog
|
|
1028
|
+
reads and handling remain available while that original request is blocked. `dismiss` omits `text`; `stop` ends
|
|
1029
|
+
observation. Log reads leave the dialog unchanged.
|
|
1030
|
+
|
|
1031
|
+
#### Read the original response
|
|
1032
|
+
|
|
1033
|
+
```text
|
|
1034
|
+
manage(action="networkCapture", targetId="PAGE_ID", capture={op:"start", include:["body","stream"]})
|
|
1035
|
+
logs(type="network", targetId="PAGE_ID", view="details")
|
|
1036
|
+
logs(type="network", view="responseBody", ref="REQUEST_REF", output="tmp:response.bin")
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
`details` retains request identity, redirect hop, base headers, ExtraInfo headers, and their completeness.
|
|
1040
|
+
`requestBody` reads original POST data; `responseBody` reads the protocol-provided entity body. An explicit `output`
|
|
1041
|
+
saves decoded bytes. Inline bodies use `{encoding:"utf8"|"base64",data}`. Unavailable or evicted bodies return an
|
|
1042
|
+
error; multipart file parts and redirect bodies depend on native protocol availability. A body must be below 16 MiB.
|
|
1043
|
+
Headers, Cookie metadata copies such as `cookieLine`, and credential URL fields are redacted. URL-bearing headers such as `Location`, `Content-Location` and `Referer` also redact user information and sensitive query values in structured metadata and raw handshake header text; explicitly requested body content retains its bytes.
|
|
1044
|
+
|
|
1045
|
+
`view="stream"` returns WebSocket directions/opcodes and SSE messages in observed order. Inspect truncation, `dropped`
|
|
1046
|
+
and `evicted` fields when consuming bounded buffers. Use `capture:{op:"stop"}` to end collection.
|
|
1047
|
+
|
|
1048
|
+
#### Continue or mock a matched request
|
|
1049
|
+
|
|
1050
|
+
Add a route with `urlPattern` and optional `stage:"Request"|"Response"`. Read `logs(type="network",view="paused")`,
|
|
1051
|
+
then handle the returned paused-request reference:
|
|
1052
|
+
|
|
1053
|
+
```text
|
|
1054
|
+
manage(action="route", targetId="PAGE_ID", route={op:"add", urlPattern:"https://example.com/api/*"})
|
|
1055
|
+
logs(type="network", targetId="PAGE_ID", view="paused")
|
|
1056
|
+
manage(action="route", route={op:"fulfill", ref:"PAUSED_REF", response:{status:200, body:{encoding:"utf8",data:"mock"}}})
|
|
1057
|
+
```
|
|
1058
|
+
|
|
1059
|
+
`continue` accepts optional `request:{url?,method?,headers?,body?}`; headers are `{name,value}` arrays. `fulfill`
|
|
1060
|
+
requires `response:{status,statusText?,headers?,body?}`. `fail` accepts a native `errorReason`, defaulting to `Aborted`.
|
|
1061
|
+
Remove a rule with `op:"remove"` and its rule reference. Unmatched requests continue immediately. Matched pauses expire
|
|
1062
|
+
after 30 seconds; cancellation, navigation, release or owner disconnection aborts unresolved requests. A native
|
|
1063
|
+
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 cleanup.
|
|
1065
|
+
|
|
1066
|
+
For HTTP authentication, set `auth:{op:"set",scope:{source:"Server"|"Proxy",origin,realm?},username,password}`.
|
|
1067
|
+
Credentials stay in memory for that page and exact challenge scope. Failed repeat challenges are canceled. Read
|
|
1068
|
+
`logs(type="network",view="auth")` for redacted status, and use `auth:{op:"clear"}` to remove credentials.
|
|
1069
|
+
|
|
1070
|
+
#### Save a download
|
|
1071
|
+
|
|
1072
|
+
```text
|
|
1073
|
+
manage(action="download", targetId="PAGE_ID", download={op:"watch",urlPattern:"https://example.com/files/*"})
|
|
1074
|
+
input(targetId="PAGE_ID", events=[{type:"click",target:{css:"a.download"}}])
|
|
1075
|
+
logs(type="download", targetId="PAGE_ID")
|
|
1076
|
+
manage(action="download", download={op:"wait",ref:"DOWNLOAD_REF",timeout:30000})
|
|
1077
|
+
manage(action="download", download={op:"save",ref:"DOWNLOAD_REF",output:"tmp:attachment.bin"})
|
|
1078
|
+
```
|
|
1079
|
+
|
|
1080
|
+
The native download GUID and state distinguish completion from file availability. `save` requires a completed download
|
|
1081
|
+
with `artifact="available"`; it writes the captured original response without making another HTTP request. Native Save
|
|
1082
|
+
As, blob downloads or browser security restrictions can leave the file unavailable, with the reason reported.
|
|
1083
|
+
Shared-browser download policy remains unchanged. This capture path uses the same below-16-MiB body budget.
|
|
1084
|
+
`download:{op:"stop"}` ends observation and releases its interception.
|
|
1085
|
+
|
|
1086
|
+
References are bound to the server instance, page and connection generation. Stale or foreign references are rejected.
|
|
1087
|
+
Cloudflare handling ends current Fetch control and suspends these observations before detaching the debugger; inspect
|
|
1088
|
+
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
|
+
CDP authentication and response capture remain active after the connection request finishes. Each later tool call uses its own timeout and cancellation signal.
|
|
1091
|
+
|
|
1092
|
+
`cleanupFailures` retains the existing string array. The parallel `cleanupFailureDetails` records timestamp, phase, observed ref or request ID, target, owner and session generation. Each controller retains at most 20 failures and clears them when disposed. A new controller starts empty; details already returned retain their original ownership.
|
|
1093
|
+
|
|
627
1094
|
### logs - Browser Logs
|
|
628
1095
|
|
|
629
|
-
| Type
|
|
630
|
-
|
|
|
631
|
-
| `console`
|
|
632
|
-
| `network`
|
|
1096
|
+
| Type | Description |
|
|
1097
|
+
| ---------- | -------------------------------------------------------------------------- |
|
|
1098
|
+
| `console` | Console logs (with level filter) |
|
|
1099
|
+
| `network` | Request summary, details, bodies, paused requests, auth or stream messages |
|
|
1100
|
+
| `dialog` | Observed dialog references and pending/closed state |
|
|
1101
|
+
| `download` | Native download state and original-file availability |
|
|
633
1102
|
|
|
634
1103
|
Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and
|
|
635
1104
|
`debug`; raw browser levels such as `warn` and `log` are normalized before filtering and return. Clearing fallback
|
|
636
1105
|
console logs keeps the hook active. When debugger collection becomes available, fallback capture is disabled. Console
|
|
637
1106
|
methods still pointing to the MCP wrapper are restored, while wrappers installed later by the page are preserved.
|
|
1107
|
+
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 once, without adding their Runtime history replay a second time or restoring cleared fallback calls. The buffer retains the latest 1000 entries.
|
|
638
1109
|
Network logs are finalized on `loadingFinished` or `loadingFailed`, not when headers arrive, so body failures retain
|
|
639
1110
|
both the HTTP status and `errorText`, and in-flight bodies continue to count against `networkidle`. Entries include
|
|
640
1111
|
`method`, `url`, `status`, `timestamp`, and `duration` when available. URL query parameters commonly used for
|
|
@@ -643,6 +1114,7 @@ explicit `output` files. Redacted entries include `urlRedacted`, `urlOriginalLen
|
|
|
643
1114
|
Inline network results limit each sanitized URL to 2048 characters and add `urlLength` plus `urlTruncated: true` when
|
|
644
1115
|
shortened. `urlPattern` supports `*` for any number of characters and `?` for one character. `tabId` targets a specific
|
|
645
1116
|
tab (Extension mode). `frame` is not applicable for logs.
|
|
1117
|
+
In network views, `urlPattern` filters each request's URL, including paused requests and authentication events, before applying `limit`. `clear` preserves requests that still need handling.
|
|
646
1118
|
|
|
647
1119
|
When the Extension debugger is unavailable, network reads refresh performance entries and mark them with
|
|
648
1120
|
`source="performance"`. Status uses the browser's `responseStatus` when available, or `0` otherwise; unknown request
|
|
@@ -650,6 +1122,8 @@ methods remain empty. Repeated reads preserve record sequences. `clear` clears M
|
|
|
650
1122
|
document's read boundary without clearing the page's shared performance timeline. A new document starts a new boundary.
|
|
651
1123
|
Read failures return an error rather than an empty log.
|
|
652
1124
|
|
|
1125
|
+
CDP network logs keep the HTTP status when a response body fails and record one terminal entry per request. Temporary page selection preserves each target's log buffer. Clearing logs removes buffered entries while keeping in-flight requests until their final event, so a request completed after clearing appears in the new log.
|
|
1126
|
+
|
|
653
1127
|
### cookies - Cookie Management
|
|
654
1128
|
|
|
655
1129
|
| Action | Description |
|
|
@@ -659,54 +1133,22 @@ Read failures return an error rather than an empty log.
|
|
|
659
1133
|
| `delete` | Delete cookie |
|
|
660
1134
|
| `clear` | Delete cookies in a URL or domain scope, optionally narrowed by `name` |
|
|
661
1135
|
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
## Target: Unified Element Locator
|
|
667
|
-
|
|
668
|
-
All tools use a unified `Target` type for element location:
|
|
669
|
-
|
|
670
|
-
```typescript
|
|
671
|
-
// By accessibility (recommended - most stable)
|
|
672
|
-
const byRole = { role: 'button', name: 'Submit' }
|
|
673
|
-
|
|
674
|
-
// By accessibility with exact accessible name
|
|
675
|
-
const byExactRole = { role: 'button', name: 'Submit', exact: true }
|
|
676
|
-
|
|
677
|
-
// By text content
|
|
678
|
-
const byText = { text: 'Click here', exact: true }
|
|
679
|
-
|
|
680
|
-
// By form label
|
|
681
|
-
const byLabel = { label: 'Email' }
|
|
1136
|
+
All actions accept `targetId`, `partitionKey:{topLevelSite?,hasCrossSiteAncestor?}`, and a backend-specific store scope:
|
|
1137
|
+
`storeId` for Extension or `browserContextId` for CDP. Extension resolves a supplied target to its native CookieStore
|
|
1138
|
+
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 and flags only narrow that explicit filter, including when exporting to a file.
|
|
682
1140
|
|
|
683
|
-
|
|
684
|
-
const byPlaceholder = { placeholder: 'Enter your name' }
|
|
1141
|
+
URL path matching uses Cookie path boundaries in target and browser-context scopes too: a Cookie at `/app` matches `/app/info` and is excluded for `/apple/info`.
|
|
685
1142
|
|
|
686
|
-
|
|
687
|
-
const byTitle = { title: 'Close dialog' }
|
|
1143
|
+
`clear` requires `url` or `domain`, with optional `name` to narrow the range. CDP preserves each selected Cookie's exact name, raw domain, path, partition and browser context for deletion. An omitted target is fixed to the current page's storage context when clear starts. An unserializable partition identity is rejected before deletion.
|
|
688
1144
|
|
|
689
|
-
|
|
690
|
-
const byAlt = { alt: 'Profile picture' }
|
|
1145
|
+
For CDP clear, `count` records identities present at the immediate precheck and absent after an acknowledged deletion request; `countSemantics="observed_present_then_absent"` identifies this state comparison. `acknowledged` counts native ACKs, `alreadyAbsent` counts identities missing at the precheck, and `matched` and `attempted` describe the selected candidates and started deletion steps. Concurrent page changes can occur between observations. Extension retains its native removal-confirmation count.
|
|
691
1146
|
|
|
692
|
-
|
|
693
|
-
const byTestId = { testId: 'submit-button' }
|
|
694
|
-
|
|
695
|
-
// By CSS selector
|
|
696
|
-
const byCss = { css: '#login-form .submit-btn' }
|
|
697
|
-
|
|
698
|
-
// Disambiguate multiple matches (0-based)
|
|
699
|
-
const secondMatch = { css: '.ant-select-input', nth: 1 }
|
|
700
|
-
|
|
701
|
-
// By CSS + text (filter by text content)
|
|
702
|
-
const byCssText = { css: 'button', text: 'Submit', exact: true }
|
|
1147
|
+
CDP stops at the first deletion, verification or cleanup failure and returns `COOKIE_CLEAR_PARTIAL` with the known count, ACKs, failed or unknown steps, unprocessed candidates, phase and original cause. Its action state preserves earlier changes and `retryable=false`; a session-detach failure retains the preceding ACK and any verified disappearance.
|
|
703
1148
|
|
|
704
|
-
|
|
705
|
-
const byXPath = { xpath: "//button[@type='submit']" }
|
|
1149
|
+
A delete sent without an ACK counts as `unknown` when the connection closes, is explicitly closed, times out or is cancelled. The first unknown step reports `actionStatus="unknown"`; earlier ACKs keep the action `partial`. `failed` counts explicitly rejected or undispatched deletion steps and identities still present after an ACK. Unclassified errors after a deletion attempt remain unknown, and later deletions stop.
|
|
706
1150
|
|
|
707
|
-
|
|
708
|
-
const byCoordinates = { x: 100, y: 200 }
|
|
709
|
-
```
|
|
1151
|
+
MCP cancellation stops queued Cookie actions, connection waits and later deletions in both backends. CDP retains prior confirmed progress and an unacknowledged deletion's unknown result. A cancelled or timed-out temporary attach retains responsibility for its native response: a late successful session is detached with an independent 1000 ms budget. Cleanup failure is logged with the command and session identity and remains tracked until the connection closes; no deletion is replayed. An Extension RPC cancelled before its reply reports an unknown RPC result; the Extension stops its remaining native removals once the in-flight call settles.
|
|
710
1152
|
|
|
711
1153
|
## Usage Examples
|
|
712
1154
|
|
|
@@ -800,7 +1242,9 @@ subsequent output.
|
|
|
800
1242
|
extract(type="metadata")
|
|
801
1243
|
```
|
|
802
1244
|
|
|
803
|
-
###
|
|
1245
|
+
### Nested frame operations
|
|
1246
|
+
|
|
1247
|
+
Both backends resolve iframe selectors and indices through open ShadowRoots. Cross-origin and OOPIF frame preparation uses the original request deadline; a timeout before script dispatch reports `actionExecuted=false` and `actionStatus="not_started"` and attempts to restore the previous target.
|
|
804
1248
|
|
|
805
1249
|
```
|
|
806
1250
|
// Target iframe by CSS selector
|
|
@@ -809,6 +1253,9 @@ evaluate(script="document.title", frame="iframe#main")
|
|
|
809
1253
|
// Target iframe by index
|
|
810
1254
|
extract(type="text", frame=0)
|
|
811
1255
|
|
|
1256
|
+
// Resolve each step relative to the selected parent, including OOPIFs in CDP
|
|
1257
|
+
evaluate(script="document.title", frame=["iframe#outer", "iframe#inner"])
|
|
1258
|
+
|
|
812
1259
|
// Input inside iframe
|
|
813
1260
|
input(events=[
|
|
814
1261
|
{ type: "mousedown", target: { label: "Username" } },
|
|
@@ -950,7 +1397,17 @@ The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerpri
|
|
|
950
1397
|
- **Chrome only**: Only supports Chrome/Chromium browsers (no Firefox/Safari)
|
|
951
1398
|
- **Single CDP session**: CDP mode supports one browser session at a time
|
|
952
1399
|
- **Extension mode requires Chrome**: Extension is Manifest V3, Chrome-specific
|
|
953
|
-
- **iframe**:
|
|
1400
|
+
- **iframe**: Nested selection uses a selector/index array; XPath keeps its native document scope
|
|
1401
|
+
|
|
1402
|
+
## Compatible Clients
|
|
1403
|
+
|
|
1404
|
+
| Client | Status |
|
|
1405
|
+
| ------------------------- | ------ |
|
|
1406
|
+
| Claude Code | ✅ |
|
|
1407
|
+
| Claude Desktop | ✅ |
|
|
1408
|
+
| Cursor | ✅ |
|
|
1409
|
+
| Windsurf | ✅ |
|
|
1410
|
+
| Any MCP-compatible client | ✅ |
|
|
954
1411
|
|
|
955
1412
|
## License
|
|
956
1413
|
|
|
@@ -960,42 +1417,3 @@ MIT License - see [LICENSE](LICENSE) for details.
|
|
|
960
1417
|
|
|
961
1418
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
|
|
962
1419
|
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP documentation
|
|
963
|
-
|
|
964
|
-
## Operation status and diagnostics
|
|
965
|
-
|
|
966
|
-
Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and
|
|
967
|
-
`retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action
|
|
968
|
-
as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with
|
|
969
|
-
`actionStatus="failed"`; result materialization or serialization errors report `actionStatus="completed"` and
|
|
970
|
-
`failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action
|
|
971
|
-
result. On a page precondition mismatch, input and evaluate report `actionExecuted=false` and
|
|
972
|
-
`actionStatus="not_started"`. Browse and wait errors also retain any diagnostics collected before the action failed.
|
|
973
|
-
Target diagnostics query the current tab state instead of relying on cached attach metadata.
|
|
974
|
-
|
|
975
|
-
Native script termination and `Internal error` responses from CDP `Runtime` script commands preserve the original error
|
|
976
|
-
code. evaluate and `manage cdp` return `actionExecuted=true`, `actionStatus="unknown"`, and `retryable=false` without
|
|
977
|
-
replaying the command. evaluate also returns `retryable=false` when an in-flight RPC timeout or stale execution context
|
|
978
|
-
leaves the result unknown; timeouts before execution starts remain retryable. Page-thrown exceptions with the same text
|
|
979
|
-
remain action failures.
|
|
980
|
-
|
|
981
|
-
Extension accessibility state does not read password values to generate element names. Labels, placeholders, titles, and
|
|
982
|
-
ordinary input values remain available. Explicit script, HTML, and attribute reads retain their existing behavior.
|
|
983
|
-
|
|
984
|
-
`replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other
|
|
985
|
-
input types use a native full-value update and return the requested and actual browser-normalized values. A standalone
|
|
986
|
-
`select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are
|
|
987
|
-
focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure
|
|
988
|
-
context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text`
|
|
989
|
-
values. Password `select`/`replace` responses hide console and network diagnostic bodies on success and failure,
|
|
990
|
-
returning `diagnostics.redacted=true` with `reason="sensitive_input_or_unresolved_target"`. This also applies when a
|
|
991
|
-
selection target cannot be identified safely. Ordinary input retains its diagnostics; password protection lasts for the
|
|
992
|
-
current input request. Target timeouts include bounded locator, tab, frame, match, and candidate context. Explicit
|
|
993
|
-
`tabId` and `frame` scopes resolve the active backend before input, wait, logs, or extract work begins, so actions and
|
|
994
|
-
verification use the same target backend. Precise iframe evaluation defaults to `staleContextRetry="never"` and does not
|
|
995
|
-
replay stale scripts. `readOnly` permits one replay after the Extension verifies the frame identity and resolves a new
|
|
996
|
-
execution context. Responses include the policy, `retryAttempted`, bounded `retryReason`, and the final `frameContext`
|
|
997
|
-
with the Extension frame, parent frame, URL, CDP frame, and execution context IDs. Same-URL frames are rejected only
|
|
998
|
-
when the selected DOM iframe cannot identify one target. Existing iframe targets remain usable after an Extension reload
|
|
999
|
-
without refreshing or navigating the page. Port scanning aggregates ordinary pre-open failures at debug level;
|
|
1000
|
-
authentication and protocol rejections from identified MCP servers produce one bounded warning when the rejection
|
|
1001
|
-
summary changes.
|