@pyrokine/mcp-chrome 2.4.4 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +401 -102
- package/README_zh.md +319 -79
- package/dist/anti-detection/injection.js +3 -3
- package/dist/cdp/client.d.ts +1 -1
- package/dist/cdp/client.d.ts.map +1 -1
- package/dist/cdp/client.js +18 -7
- package/dist/cdp/client.js.map +1 -1
- package/dist/cdp/launcher.d.ts +2 -3
- package/dist/cdp/launcher.d.ts.map +1 -1
- package/dist/cdp/launcher.js +84 -24
- package/dist/cdp/launcher.js.map +1 -1
- package/dist/core/auto-wait.d.ts +3 -3
- package/dist/core/auto-wait.d.ts.map +1 -1
- package/dist/core/auto-wait.js +45 -20
- package/dist/core/auto-wait.js.map +1 -1
- package/dist/core/browser-driver.d.ts +101 -12
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/errors.d.ts +16 -0
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +77 -0
- package/dist/core/errors.js.map +1 -1
- package/dist/core/locator.d.ts.map +1 -1
- package/dist/core/locator.js +6 -4
- package/dist/core/locator.js.map +1 -1
- package/dist/core/os-mouse.d.ts +15 -2
- package/dist/core/os-mouse.d.ts.map +1 -1
- package/dist/core/os-mouse.js +52 -8
- package/dist/core/os-mouse.js.map +1 -1
- package/dist/core/session.d.ts +34 -19
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +574 -130
- package/dist/core/session.js.map +1 -1
- package/dist/core/types.d.ts +2 -0
- package/dist/core/types.d.ts.map +1 -1
- package/dist/core/types.js.map +1 -1
- package/dist/core/unified-session.d.ts +95 -20
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +489 -117
- package/dist/core/unified-session.js.map +1 -1
- package/dist/core/utils.d.ts +5 -0
- package/dist/core/utils.d.ts.map +1 -1
- package/dist/core/utils.js +475 -54
- package/dist/core/utils.js.map +1 -1
- package/dist/extension/bridge.d.ts +46 -36
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +269 -112
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts +3 -0
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +19 -2
- package/dist/extension/http-server.js.map +1 -1
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -1
- package/dist/tools/browse.d.ts.map +1 -1
- package/dist/tools/browse.js +241 -171
- package/dist/tools/browse.js.map +1 -1
- package/dist/tools/challenge.d.ts +1 -1
- package/dist/tools/challenge.d.ts.map +1 -1
- package/dist/tools/challenge.js +75 -37
- package/dist/tools/challenge.js.map +1 -1
- package/dist/tools/cookies.d.ts.map +1 -1
- package/dist/tools/cookies.js +5 -3
- package/dist/tools/cookies.js.map +1 -1
- package/dist/tools/diagnostics.d.ts +3 -3
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +13 -12
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +57 -26
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +107 -175
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts +1 -1
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +380 -158
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/logs.d.ts.map +1 -1
- package/dist/tools/logs.js +5 -5
- package/dist/tools/logs.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +380 -57
- package/dist/tools/manage.js.map +1 -1
- package/dist/tools/page-context.d.ts +17 -0
- package/dist/tools/page-context.d.ts.map +1 -0
- package/dist/tools/page-context.js +103 -0
- package/dist/tools/page-context.js.map +1 -0
- package/dist/tools/png.d.ts +5 -0
- package/dist/tools/png.d.ts.map +1 -1
- package/dist/tools/png.js +84 -19
- package/dist/tools/png.js.map +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +5 -2
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/schema.d.ts +9 -0
- package/dist/tools/schema.d.ts.map +1 -1
- package/dist/tools/schema.js +15 -0
- package/dist/tools/schema.js.map +1 -1
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +32 -19
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +19 -25
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/content.ts-C4imZ6A9.js +13 -0
- package/extension/dist/assets/content.ts-loader-CnJuCGhl.js +13 -0
- package/extension/dist/assets/{index.ts-Bqcu2qiN.js → index.ts-GeHNZBml.js} +2040 -2111
- package/extension/dist/assets/page-scripts-CMIY1zhd.js +1379 -0
- package/extension/dist/assets/{popup.html-B81xccfq.js → popup.html-CgtWL6Py.js} +48 -1
- package/extension/dist/manifest.json +4 -3
- package/extension/dist/service-worker-loader.js +1 -1
- package/extension/dist/src/popup/popup.html +11 -1
- package/package.json +9 -7
- package/scripts/start-chrome.ps1 +58 -0
- package/extension/dist/assets/content.ts-Cj_iiU2s.js +0 -25
package/README.md
CHANGED
|
@@ -13,7 +13,8 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
|
|
|
13
13
|
|
|
14
14
|
- **Dual Mode**: Extension mode shares your login sessions; CDP mode for headless/isolated scenarios
|
|
15
15
|
- **8 Unified Tools**: Action-based design covering browse, input, extract, wait, evaluate, manage, cookies, logs
|
|
16
|
-
- **Multi-
|
|
16
|
+
- **Multi-Page Targeting**: `targetId` selects a page in either backend without changing browser focus; `tabId` remains
|
|
17
|
+
an alias
|
|
17
18
|
- **iframe Penetration**: `frame` parameter targets elements inside iframes (CSS selector or index, Extension mode)
|
|
18
19
|
- **Semantic Targeting**: 11 ways to locate elements (role, text, label, CSS, CSS+text combo, XPath, coordinates, etc.)
|
|
19
20
|
- **Auto-Wait**: Built-in clickability and input-ready detection with deadline-based timeout budget
|
|
@@ -24,6 +25,19 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
|
|
|
24
25
|
- **Anti-Detection**: Optional fingerprint masking and behavior simulation
|
|
25
26
|
- **Structured Errors**: Every error includes code, message, suggestion, and context
|
|
26
27
|
|
|
28
|
+
## Migrating to 3.0
|
|
29
|
+
|
|
30
|
+
- `manage(action="closePage")` now requires an explicit `targetId`; it no longer closes an implicit default page.
|
|
31
|
+
- In Extension mode, explicit `adoptPage` grants an existing tab the same managed reading, input, script, screenshot,
|
|
32
|
+
debugger, and log capabilities as a newly created page. No popup read grant is required for managed pages.
|
|
33
|
+
- A single-page ordinary-read grant covers text, HTML, attributes, computed styles and state. It does not enable
|
|
34
|
+
arbitrary JavaScript, CDP/debugger commands, input or screenshots.
|
|
35
|
+
- `tmp:` files belong to the current MCP server session. After a restart, regenerate them or retain needed files under
|
|
36
|
+
`cwd:` before stopping the server.
|
|
37
|
+
|
|
38
|
+
Local zero-config auto-connect is unchanged. Reloading the Extension or restarting the MCP client does not require a
|
|
39
|
+
manual Connect click.
|
|
40
|
+
|
|
27
41
|
## Compatible Clients
|
|
28
42
|
|
|
29
43
|
| Client | Status |
|
|
@@ -63,6 +77,21 @@ claude mcp add chrome -- node "$PWD/dist/index.js"
|
|
|
63
77
|
|
|
64
78
|
For Extension mode, load `extension/dist` in Chrome.
|
|
65
79
|
|
|
80
|
+
### Windows CDP launch
|
|
81
|
+
|
|
82
|
+
Chrome discovery checks Windows App Paths, `PATH`, installed Chrome channels, Chromium, Chrome for Testing, and
|
|
83
|
+
`MCP_CHROME_PORTABLE_DIR` (or `%USERPROFILE%\\.mcp-chrome\\portable`). To start a separate CDP browser from PowerShell:
|
|
84
|
+
|
|
85
|
+
```powershell
|
|
86
|
+
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222
|
|
87
|
+
# Or specify a portable executable and profile explicitly:
|
|
88
|
+
& '<npm-root>\@pyrokine\mcp-chrome\scripts\start-chrome.ps1' -Port 9222 -ExecutablePath 'C:\Browsers\chrome.exe' -ProfileDir 'C:\Temp\mcp-chrome-profile'
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Then call `browse(action="connect", port=9222)`. The script keeps its Chrome process in the foreground; Chrome exit
|
|
92
|
+
codes are reported by the script. Use a separate profile so an existing Chrome process cannot silently absorb the
|
|
93
|
+
launch.
|
|
94
|
+
|
|
66
95
|
## Quick Start
|
|
67
96
|
|
|
68
97
|
### Mode 1: Extension Mode (Recommended)
|
|
@@ -125,7 +154,8 @@ MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
|
|
|
125
154
|
```
|
|
126
155
|
|
|
127
156
|
To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server
|
|
128
|
-
and disable "Allow no-token local connection" in the Extension popup.
|
|
157
|
+
and disable "Allow no-token local connection" in the Extension popup. Disabling that policy immediately cancels pending
|
|
158
|
+
health checks, WebSocket handshakes, and scheduled reconnects, so an older no-token attempt cannot connect afterward.
|
|
129
159
|
|
|
130
160
|
### Mode 2: CDP Mode (Fallback)
|
|
131
161
|
|
|
@@ -164,13 +194,116 @@ browse(action="open", url="https://example.com")
|
|
|
164
194
|
| `close` | Close the page specified by `targetId` |
|
|
165
195
|
|
|
166
196
|
Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
|
|
167
|
-
(whether tab is controlled by MCP Chrome), `isActive` (
|
|
197
|
+
(whether the tab is controlled by MCP Chrome), `isActive` (Chrome's active tab within its window), `windowId`, `index`,
|
|
168
198
|
`pinned`, `incognito`, and `status` (`loading`/`complete`). The tree includes `windowCount`, `focusedWindowId`,
|
|
169
|
-
`activeTargetId`, and each window's ordered `tabs` list
|
|
170
|
-
|
|
199
|
+
`activeTargetId`, and each window's ordered `tabs` list. `defaultTargetId` identifies the selected operation target; CDP
|
|
200
|
+
does not infer Chrome's foreground tab from this selection. `open` auto-creates tab group (cyan color). `open`, `back`,
|
|
171
201
|
`forward`, and `refresh` accept `diagnostics=true` to return new console warnings/errors and failed network requests
|
|
172
|
-
observed during the action, including the first `open` that creates a page automatically. `
|
|
173
|
-
and
|
|
202
|
+
observed during the action, including the first `open` that creates a page automatically. `open` and `refresh` honor
|
|
203
|
+
`wait="load"`, `wait="domcontentloaded"`, and `wait="networkidle"` in both drivers. The wait is registered before the
|
|
204
|
+
command and bound to the new main document, so late lifecycle events from an earlier navigation are ignored. CDP
|
|
205
|
+
`networkidle` waits for the current main-frame loader's `networkIdle` event. Extension `networkidle` waits for the
|
|
206
|
+
current document to complete, all tracked response bodies to finish, and a 500 ms quiet period. Lost request tracking
|
|
207
|
+
causes a timeout instead of a false idle result. `close` requires `targetId` and closes only that page. It never closes
|
|
208
|
+
the entire CDP connection.
|
|
209
|
+
|
|
210
|
+
In Extension mode, `back` and `forward` use native browser history first. Only a native no-history error permits a
|
|
211
|
+
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`. Other native failures are preserved. A destroyed execution context or a
|
|
213
|
+
browser refusing injection into an error page still returns an operation failure, recorded as a warning in the Extension
|
|
214
|
+
rather than a program error. Arbitrary debugger commands are never automatically replayed.
|
|
215
|
+
|
|
216
|
+
For `open`, `back`, `forward`, and `refresh`, `timeout` starts at request entry. Target preparation, queueing, protocol
|
|
217
|
+
calls, page loading, Challenge inspection and clicks, diagnostics, and target restoration share the remaining budget;
|
|
218
|
+
navigation RPCs do not add transport time. An expired queued action is not dispatched, and later requests still wait for
|
|
219
|
+
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.
|
|
221
|
+
|
|
222
|
+
A timeout does not undo a Chrome operation already dispatched. When its result is unknown, the response reports
|
|
223
|
+
`TIMEOUT`, `actionExecuted="unknown"`, `actionStatus="unknown"`, and `retryable=false`; read the actual page state
|
|
224
|
+
instead of replaying navigation. `pageContext.after` uses a fresh snapshot when available; otherwise it is null with
|
|
225
|
+
`contextError`. Exhausted restoration is reported separately without replacing the primary action result. CDP history
|
|
226
|
+
waits accept a main-frame BFCache restore or same-document event from the current session, not an ordinary frame commit,
|
|
227
|
+
a child-frame event, or an event from another session.
|
|
228
|
+
|
|
229
|
+
Challenge click, detach, and inspection RPCs carry the remaining deadline and reject dispatch after queueing or page
|
|
230
|
+
validation exhausts it. OS mouse movement and fallback processes use the same deadline. A CDP press that has started
|
|
231
|
+
always attempts release on the original connection and session; release cleanup waits at most one second and never uses
|
|
232
|
+
a newly selected target. Read-only Challenge checks that expire return `CHALLENGE_TIMEOUT` with the known primary action
|
|
233
|
+
status. An uncertain click returns `TIMEOUT` with that primary status, `verificationStatus="unknown"`,
|
|
234
|
+
`verificationActionExecuted`, and `retryable=false`; neither navigation nor the click is automatically replayed.
|
|
235
|
+
|
|
236
|
+
Evaluate retains Challenge result fields on success, action failure, verification mismatch, and output failure.
|
|
237
|
+
`originResponsePending=true` means verification succeeded but the origin server has not responded; it does not mean the
|
|
238
|
+
destination content has loaded.
|
|
239
|
+
|
|
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
|
+
For `browse`, only `open`, `back`, `forward`, `refresh`, and `close` accept these conditions. Other actions, including
|
|
283
|
+
`attach`, reject them with `INVALID_ARGUMENT` before changing any target.
|
|
284
|
+
|
|
285
|
+
Explicit `manage(action="adoptPage", targetId=...)` makes an existing page fully managed without focusing or navigating
|
|
286
|
+
it. `browse attach` only selects a target. Creation provenance, group membership, and group color do not authorize a
|
|
287
|
+
page. `releasePage` revokes full managed access without closing the tab or changing its window or group; it clears MCP
|
|
288
|
+
log state and removes debugging and console capture resources. If Chrome prevents resource cleanup, the response
|
|
289
|
+
includes `warnings` while managed access is still revoked.
|
|
290
|
+
|
|
291
|
+
A managed tab can keep using this Extension's existing debugger session after a Service Worker restart. Sessions owned
|
|
292
|
+
by other debuggers still return `DEBUGGER_BLOCKED`.
|
|
293
|
+
|
|
294
|
+
Use `manage(action="grantReadAccess", targetId=...)` to grant ordinary reads and `revokeReadAccess` to revoke them; no
|
|
295
|
+
popup click is required. Both require an explicit target and accept `expectedUrl`/`expectedRevision`. Grants belong to
|
|
296
|
+
the calling server instance and the current document identity, URL and revision. Storage failure is an error, not
|
|
297
|
+
successful authorization. The popup remains an optional control. A grant survives a Service Worker restart only while
|
|
298
|
+
that connection and the approved document remain unchanged. Navigation, tab closure, or connection closure revokes it. A
|
|
299
|
+
target ID alone does not authorize reading. The grant covers ordinary content reads, including targeted text, HTML,
|
|
300
|
+
attributes, computed styles, and page state. Scripts, debugger operations, screenshots, input, and cookie access do not
|
|
301
|
+
inherit it; existing cookie operations have separate URL/name filter rules. When page management or navigation is
|
|
302
|
+
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`, and list results show creation and
|
|
304
|
+
last-use timestamps. Reads and updates accept `expectedUrl`/`expectedRevision`; a mismatch returns
|
|
305
|
+
`ACTION_PRECONDITION_FAILED` without reading or updating notes. This metadata is process-local and is removed when a
|
|
306
|
+
page is closed; it never authorizes content access.
|
|
174
307
|
|
|
175
308
|
### Access challenges
|
|
176
309
|
|
|
@@ -180,25 +313,27 @@ title passively for eight seconds. If the interstitial persists, MCP Chrome chec
|
|
|
180
313
|
clicks it only when it finds one. Extension inspect uses an isolated world and detaches the debugger first. Same-page
|
|
181
314
|
fixture buttons use the existing page click. If a Cloudflare Turnstile iframe is present, inspect CSS coordinates are
|
|
182
315
|
converted to screen coordinates and the OS mouse moves along a path, hovers, then presses and releases: `xdotool` on
|
|
183
|
-
Linux uses the focused Chrome window
|
|
184
|
-
|
|
316
|
+
Linux uses the focused Chrome client-window geometry and `xprop` GTK frame extents only when that window title matches
|
|
317
|
+
the test page. Missing tools, invalid geometry, or a viewport mismatch stop the click instead of guessing the content
|
|
318
|
+
origin from Chrome `screenX` or `outerHeight - innerHeight`; `cliclick` or System Events on macOS; and PowerShell
|
|
185
319
|
`mouse_event` on Windows. Widget clicks target the checkbox on the left of the compact Turnstile card, including when
|
|
186
320
|
the host wrapper is wider than the card, not the label. If a Cloudflare iframe is already in the DOM, the OS mouse is
|
|
187
321
|
used even when that iframe reports a zero-size rect, including the later host `Verify you are human` / `请验证您是真人`
|
|
188
322
|
button. The OS click runs only when the managed test tab is already the active tab in an already-focused window; mixed
|
|
189
323
|
windows are not focused. Debugger is detached and the viewport is read again before the OS click. Missing OS mouse tools
|
|
190
324
|
or an unfocused window return a visible error instead of a silent CDP click. A Turnstile widget is clicked only after
|
|
191
|
-
two inspections report the same click point
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
same wait. Use the default `diagnostics=false` for
|
|
195
|
-
and network collection.
|
|
325
|
+
two inspections report the same click point; unrelated elements do not become widgets just because their sizes match.
|
|
326
|
+
Distant OS-mouse paths start near the control instead of flying across the screen. The same checkbox or compact widget
|
|
327
|
+
is clicked at most once; if Cloudflare then shows a visible `Verify you are human` or `请验证您是真人` button, that
|
|
328
|
+
button is inspected as `verify` and clicked at most once in the same wait. Use the default `diagnostics=false` for
|
|
329
|
+
challenge-protected pages because diagnostics starts debugger console and network collection.
|
|
196
330
|
|
|
197
331
|
Detection covers titles such as `Just a moment...` and `请稍候…`, challenge DOM or body-text markers, and
|
|
198
|
-
`Verify you are human` / `请验证您是真人` controls
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
332
|
+
`Verify you are human` / `请验证您是真人` controls, including visible `button` elements with that exact text. Same-page
|
|
333
|
+
buttons use page input when no Cloudflare iframe is present. CDP reads live titles with `Target.getTargetInfo`. A
|
|
334
|
+
leftover Cloudflare iframe on a recovered page is not pending. Cached titles do not decide the result. MCP Chrome does
|
|
335
|
+
not call a CAPTCHA solver, retry navigation, or export `cf_clearance` values. A CDP timeout does not prove that the site
|
|
336
|
+
fails in a user Chrome session; check the returned `mode` before diagnosing the site.
|
|
202
337
|
|
|
203
338
|
A resolved challenge returns `challengeResolved=true`, `challengeKind`, `waitedMs`, `clickedTurnstile`, and
|
|
204
339
|
`clearanceCookiePresent` (name presence only). If the visible page text says verification succeeded and Cloudflare is
|
|
@@ -208,7 +343,7 @@ checkbox still counts as pending. Challenge results and errors include `mode`. T
|
|
|
208
343
|
`retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is not reported as `js`).
|
|
209
344
|
Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP reputation checks
|
|
210
345
|
cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears the header flag;
|
|
211
|
-
clearing network logs
|
|
346
|
+
ordinary iframe document responses and clearing network logs do not.
|
|
212
347
|
|
|
213
348
|
### input - Keyboard & Mouse Input
|
|
214
349
|
|
|
@@ -243,20 +378,53 @@ Special-case parameters:
|
|
|
243
378
|
`diagnostics=true` returns new console warnings/errors and failed network requests after the action. `postCondition`
|
|
244
379
|
waits for a page state after the events so callers can distinguish dispatched input from completed page behavior.
|
|
245
380
|
`postCondition.timeout` defaults to 3000 ms and is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
|
|
246
|
-
accepts 50-5000 ms. `
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
381
|
+
accepts 50-5000 ms. A `postCondition.script` may be an expression, function, async function, or Promise expression;
|
|
382
|
+
functions are invoked and the final Promise value is awaited before matching, while thrown or rejected errors fail the
|
|
383
|
+
check. `targetId` (or legacy `tabId`) selects a page in either backend; `frame` selects an iframe (CSS selector or
|
|
384
|
+
index) in Extension mode. When either scope is provided, the action, diagnostics, and post-condition use the backend
|
|
385
|
+
selected for that target scope.
|
|
386
|
+
|
|
387
|
+
For keyboard `type`, `timeout` includes Challenge waiting, focus preparation, character input, and `delay`/`humanize`
|
|
388
|
+
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 30000 ms. When the budget expires, subsequent characters and events stop.
|
|
390
|
+
Already dispatched input cannot be undone, so a timeout may leave partial input. A response with `actionExecuted=true`,
|
|
391
|
+
`actionStatus="unknown"`, and `retryable=false` requires an independent page read to check the actual value; do not
|
|
392
|
+
replay the whole event sequence.
|
|
393
|
+
|
|
394
|
+
Mouse target lookup, stepped movement, and `humanize` delays also share the remaining input budget. Each movement and
|
|
395
|
+
the subsequent click check the deadline; expiry stops further movement and clicking. Already dispatched native events
|
|
396
|
+
cannot be undone. Read the page independently after an unknown result instead of replaying the action.
|
|
397
|
+
|
|
398
|
+
Command focus, text selection, and replacement share the remaining event budget. Expiry stops subsequent actions; Shift
|
|
399
|
+
release is still attempted without hiding an earlier action error. Stepped CDP touch movement also stops at the
|
|
400
|
+
deadline.
|
|
401
|
+
|
|
402
|
+
In stealth mode, `delay` separates characters; the first character has no initial wait. Background page timer throttling
|
|
403
|
+
can lengthen subsequent intervals, but the same deadline still stops further input.
|
|
404
|
+
|
|
405
|
+
Precise Extension and CDP keyboard input use the current caret and selection. A `target` is clicked before typing and
|
|
406
|
+
can change the insertion point. To append to a contenteditable element, focus it, place the caret at its end, then send
|
|
407
|
+
`type` without a `target` so that it does not click again.
|
|
408
|
+
|
|
409
|
+
CDP clicks and keyboard input also wait for stable element position and size in background pages without activating
|
|
410
|
+
them. Visibility, enabled-state, viewport, and click coverage checks still apply. Target lookup, actionability checks,
|
|
411
|
+
and the final coordinate read share the remaining event budget. If any of these stages exhausts it, no mouse or keyboard
|
|
412
|
+
event is dispatched.
|
|
413
|
+
|
|
414
|
+
**`click`-specific**: `force: true` requires `forceReason` and a non-coordinate element `target`, and skips
|
|
415
|
+
actionability checks (useful for testing or hidden elements), but still dispatches the standard DOM mouse-event sequence
|
|
416
|
+
and does not call framework-private handlers. The same checks apply to middle/right clicks and multiple clicks. Missing
|
|
417
|
+
targets and coordinate targets cannot use `force`. Actionability failures return `ACTIONABILITY_FAILED` with `rect`,
|
|
418
|
+
`clickPoint`, covering element details, candidate blockers, and suggestions. **`type`-specific**: `mode="controlled"` or
|
|
419
|
+
`dispatch: true` sets `.value` directly and fires `input`/ `change` events — use for React/Vue controlled inputs where
|
|
420
|
+
keyboard events don't update state. Requires a non-coordinate `target`. Extension mode only. Controlled input and target
|
|
421
|
+
lookup failures return structured context with `locator`, `matchCount`, `nth`, bounded `candidates`, and an
|
|
422
|
+
`activeElement` summary without input values. The focus summary is `null` when unavailable; a failed DOM query also
|
|
423
|
+
returns `diagnosticError`. Selection-specific errors also report editor and selection state. Password input values are
|
|
424
|
+
omitted from failure diagnostics, and input `find` or replacement `text` values are redacted from failed responses. For
|
|
425
|
+
`select` and `replace`, event-level `nth` selects the Nth text occurrence while nested `target.nth` selects the Nth
|
|
426
|
+
matching element; both are zero-based and may be used together. Locator targets for `select` and `replace` work in CDP
|
|
427
|
+
mode without Extension ref IDs.
|
|
260
428
|
|
|
261
429
|
### extract - Content Extraction
|
|
262
430
|
|
|
@@ -270,18 +438,33 @@ without Extension ref IDs.
|
|
|
270
438
|
| `state` | Get page state (URL, title, interactive elements) |
|
|
271
439
|
| `metadata` | Extract page metadata (title, OG, JSON-LD, etc.) |
|
|
272
440
|
|
|
441
|
+
Text extraction uses the browser's `innerText` for HTML pages and selected elements. Rendered regions omit nested
|
|
442
|
+
`style`/`script` source and hidden descendants. Explicitly selected non-rendered HTML follows the browser's `innerText`
|
|
443
|
+
rules; SVG/XML nodes use `textContent`. Use `html` for source markup.
|
|
444
|
+
|
|
273
445
|
Parameters: `output` saves result to file (or directory for `images=data`). `images` (`info`/`data`) extracts image
|
|
274
446
|
metadata or data alongside HTML. `frameHtml` extracts the current iframe document after `frame` routing. Screenshot
|
|
275
447
|
accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline comparison, and `diffOutput` for a PNG diff
|
|
276
448
|
image. `diffOutput` requires `compareWith`. A `target` screenshot that has no match, whose `nth` is out of range, or
|
|
277
449
|
whose box has zero size returns a target error rather than silently returning a viewport screenshot. Screenshot
|
|
278
450
|
responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip`, and
|
|
279
|
-
`capabilities`.
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
`
|
|
451
|
+
`capabilities`. Capture is limited to 16,384 pixels per side, 12,000,000 pixels total, 48 MiB estimated RGBA memory and
|
|
452
|
+
25 MiB encoded data. PNG baselines are checked before reading; comparison is capped at 25 MiB per PNG and 12,000,000
|
|
453
|
+
pixels, and decompressed scanlines must exactly match the validated dimensions and are bounded during inflate. Malformed
|
|
454
|
+
or expansion-heavy PNGs are rejected. Use `clip` or `scale` for larger captures. Screenshot and diagnostic bundle
|
|
455
|
+
capabilities report `hiddenTabScreenshot: false` in both Extension and CDP modes. Hidden Extension tabs return
|
|
456
|
+
`HIDDEN_TAB_SCREENSHOT` without automatic activation. If another debugger blocks the precise screenshot path, viewport
|
|
457
|
+
fallback reports `degraded`, `fallback`, and `limitations`; unsupported fallback options return structured
|
|
458
|
+
`SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns `interactiveElements`; `metadata` returns `frames` in both
|
|
459
|
+
Extension and CDP modes. The document `url` is returned in both backends; Extension `frame` routing returns that iframe
|
|
460
|
+
document's URL. CDP frame entries retain declared fields as `null` when unavailable, including DOM selectors and owner
|
|
461
|
+
rectangles; frame-tree order and IDs are preserved. Metadata also returns the page's current `managed` state and a
|
|
462
|
+
`metadata` object with `createdBy`, `createdAt`, `lastUsedAt`, `taskHint`, and `note`, matching `browse list` and
|
|
463
|
+
`manage pageMetadata`. These notes describe the page even when `frame` selects an iframe document. They are local to the
|
|
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.
|
|
285
468
|
|
|
286
469
|
**`attribute` special prefix**: `computed:<property>` returns the computed CSS style value (e.g. `computed:color`,
|
|
287
470
|
`computed:font-size`). Use `computed:*` to return all computed style properties as JSON (returns 300+ properties — use
|
|
@@ -300,7 +483,11 @@ If another debugger blocks the precise screenshot path, viewport fallback report
|
|
|
300
483
|
| `time` | Fixed delay |
|
|
301
484
|
| `idle` | Wait for DOM or network quiet period |
|
|
302
485
|
|
|
303
|
-
Parameters: `tabId`
|
|
486
|
+
Parameters: `targetId` (or `tabId`) selects a page in either backend; `frame` selects an iframe in Extension mode.
|
|
487
|
+
|
|
488
|
+
In CDP mode, `visible` requires a nonzero DOM rectangle and CSS that does not hide the element (`display:none` or
|
|
489
|
+
`visibility:hidden/collapse`). `hidden` accepts these hidden states or a missing element; `attached` and `detached` only
|
|
490
|
+
check whether the element exists.
|
|
304
491
|
|
|
305
492
|
**`idle`-specific**: In Extension mode, after `readyState === 'complete'`, it injects a `MutationObserver` and waits for
|
|
306
493
|
a quiet period with no DOM changes. In CDP mode, it waits for network quiet instead. `ms` controls the relevant quiet
|
|
@@ -310,19 +497,19 @@ period (default 500ms). The response returns `idleKind` and `idlePeriodMs`; Exte
|
|
|
310
497
|
|
|
311
498
|
Execute JavaScript in page context.
|
|
312
499
|
|
|
313
|
-
| Parameter
|
|
314
|
-
|
|
|
315
|
-
| `script`
|
|
316
|
-
| `scriptFile`
|
|
317
|
-
| `args`
|
|
318
|
-
| `mode`
|
|
319
|
-
| `staleContextRetry`
|
|
320
|
-
| `output`
|
|
321
|
-
| `tabId`
|
|
322
|
-
| `frame`
|
|
323
|
-
| `timeout`
|
|
324
|
-
| `diagnostics`
|
|
325
|
-
| `postCondition`
|
|
500
|
+
| Parameter | Description |
|
|
501
|
+
| -------------------- | --------------------------------------------------------------------------------------------------- |
|
|
502
|
+
| `script` | JavaScript code. Bare `return` statements are wrapped in IIFE |
|
|
503
|
+
| `scriptFile` | Read code from a local file instead of `script` |
|
|
504
|
+
| `args` | Function arguments; `[]` invokes a zero-argument function, omission evaluates the script as written |
|
|
505
|
+
| `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
|
|
506
|
+
| `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly` |
|
|
507
|
+
| `output` | Save the result to a file |
|
|
508
|
+
| `targetId` / `tabId` | Select a page in either backend (`tabId` is an alias) |
|
|
509
|
+
| `frame` | Target an iframe by CSS selector or index (Extension mode) |
|
|
510
|
+
| `timeout` | End-to-end budget (ms) |
|
|
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 |
|
|
326
513
|
|
|
327
514
|
`script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
|
|
328
515
|
paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
|
|
@@ -342,37 +529,94 @@ and replay it once within the remaining timeout budget. A stale-context error af
|
|
|
342
529
|
`actionExecuted=true` and `actionStatus="unknown"`, because earlier side effects may already have happened even though
|
|
343
530
|
the final result is unavailable.
|
|
344
531
|
|
|
532
|
+
For object results in the main frame with Extension precise mode, an explicit `output` uses a 16 Mi (16777216) character
|
|
533
|
+
budget. Without `output`, the 1000000-character budget still applies, including automatic saving. Both paths retain the
|
|
534
|
+
depth limit of 8, the 2000-node budget, and non-serializable result rejection. The character budget counts UTF-16 code
|
|
535
|
+
units, not the output file's UTF-8 bytes; `tmp:` files also remain subject to the temporary output quota. Exceeding a
|
|
536
|
+
result limit reports the current limit and the completed script's output failure without replaying it.
|
|
537
|
+
|
|
345
538
|
### manage - Page & Environment Management
|
|
346
539
|
|
|
347
|
-
| Action
|
|
348
|
-
|
|
|
349
|
-
| `newPage`
|
|
350
|
-
| `
|
|
351
|
-
| `
|
|
352
|
-
| `
|
|
353
|
-
| `
|
|
354
|
-
| `
|
|
355
|
-
| `
|
|
356
|
-
| `
|
|
357
|
-
| `
|
|
358
|
-
| `
|
|
359
|
-
| `
|
|
360
|
-
| `
|
|
361
|
-
| `
|
|
362
|
-
| `
|
|
363
|
-
| `
|
|
364
|
-
| `
|
|
365
|
-
| `
|
|
366
|
-
| `
|
|
367
|
-
| `
|
|
368
|
-
| `
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
`
|
|
540
|
+
| Action | Description |
|
|
541
|
+
| ------------------ | ----------------------------------------------------------------- |
|
|
542
|
+
| `newPage` | Create new controlled page/tab |
|
|
543
|
+
| `pageMetadata` | Read or update per-page `taskHint` and `note` |
|
|
544
|
+
| `closePage` | Close controlled page and return `affected.before/after` |
|
|
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 a controlled tab and focus its window |
|
|
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
|
+
Native tab/window/group configuration is Extension-mode only. Mutations identify their existing targets with `targetId`,
|
|
573
|
+
`targetIds`, `windowId`, or `groupId` and return `affected.before/after`. Group results also include
|
|
574
|
+
`tabsBefore/tabsAfter`; `ungroupPages` removes an empty group through Chrome without revoking the tabs' managed state.
|
|
575
|
+
Group title/color/collapse updates and group moves require all group members to be managed. Window updates, resizing,
|
|
576
|
+
and focusing require all window tabs to be managed; a cached MCP window ID does not override that check. `clearCache` is
|
|
577
|
+
unavailable in Extension mode and returns `UNSUPPORTED_MODE` without clearing anything. Use scoped
|
|
578
|
+
`cookies(action="clear")` for cookies or CDP mode for storage and cache. `focusWindow` only returns success after the
|
|
579
|
+
target window is observed as focused; otherwise it returns `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed
|
|
580
|
+
windows with unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`. Persistent `adoptPage` and `releasePage` target
|
|
581
|
+
changes are serialized with scoped tab operations, so a concurrent multi-event input remains on its requested tab and
|
|
582
|
+
the persistent target is applied afterward.
|
|
583
|
+
|
|
584
|
+
| Action | Native parameters | Behavior |
|
|
585
|
+
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
586
|
+
| `newPage` | `url`, `windowId`, `index`, `active`, `pinned`, `openerTabId`, `groupId`, `timeout` | `active` defaults to false; `groupId=-1` disables grouping; explicit placement is not changed by the default visual group |
|
|
587
|
+
| `updatePage` | `url`, `active`, `pinned`, `highlighted`, `muted`, `autoDiscardable`, `openerTabId` | Requires `targetId`; only `active=true` is supported and does not focus the window; `active=false` is rejected before any update |
|
|
588
|
+
| `groupPages` | `targetIds`, `groupId`, `windowId`, `title`, `color`, `collapsed` | Omit `groupId` to create a group in the members' window; mixed-window members require `windowId`; joining an existing group accepts only `targetIds/groupId` |
|
|
589
|
+
| `ungroupPages` | `targetIds` | Removes group membership and retains controlled-page access |
|
|
590
|
+
| `updateGroup` | `groupId`, `title`, `color`, `collapsed` | An empty title and false collapsed value are applied as supplied |
|
|
591
|
+
| `moveGroup` | `groupId`, `windowId`, `index` | Moves all members; `index=-1` means the end of the window |
|
|
592
|
+
| `newWindow` | `url` or `urls`, `targetId`, `windowType`, `focused`, `incognito`, `left`, `top`, `width`, `height`, `windowState`, `setSelfAsOpener` | `normal` supports multiple URL tabs and an existing controlled tab; `popup` accepts only one page; created tabs are managed with distinct provenance |
|
|
593
|
+
| `updateWindow` / `resizeWindow` | `windowId`, `left`, `top`, `width`, `height`, `windowState`, `focused`, `drawAttention` | Applies supported Chrome window properties and returns observed state |
|
|
594
|
+
|
|
595
|
+
`updateWindow` and `resizeWindow` wait for a stable browser observation when changing state or geometry. Restoring a
|
|
596
|
+
non-normal window with `windowState="normal"` and bounds completes the state transition before applying bounds once.
|
|
597
|
+
OS-adjusted geometry is returned as observed. If observation does not stabilize within the bounded wait,
|
|
598
|
+
`WINDOW_UPDATE_NOT_OBSERVED` reports partial execution and the last observed window state; inspect `browse list` before
|
|
599
|
+
another update.
|
|
600
|
+
|
|
601
|
+
`browse list` defaults to `details="summary"`, returning target identity, URL/title, placement, managed/revision and
|
|
602
|
+
metadata. Set `details="full"` for highlighted/muted/discardable state, opener IDs and available native readonly
|
|
603
|
+
properties. False values are preserved. `targetIds` and `managedOnly=true` filter pages and their window/group
|
|
604
|
+
relations; `totalTargetCount`, `totalWindowCount` and `totalTabCount` distinguish inventory totals from selected counts.
|
|
605
|
+
Window objects reference pages through `targetIds` rather than repeating full targets. Inline favicon data URLs are
|
|
606
|
+
omitted; full details use `favIconInline=true` to indicate one exists. Groups retain title, color, collapsed/shared
|
|
607
|
+
state, window, first-member index and member IDs. Color belongs to a group, not a tab. Readonly properties are returned
|
|
608
|
+
when Chrome supplies them, not accepted as configuration writes. Listing does not read page content, navigate or focus.
|
|
609
|
+
|
|
610
|
+
Moving tabs/groups accepts `index=-1`; page creation requires a nonnegative index. Opener and explicit group/window
|
|
611
|
+
options must identify the same window. Pinned tabs cannot be created inside a group. Window state/bounds conflicts and
|
|
612
|
+
action-inappropriate fields are rejected before mutation. CDP rejects unsupported Chrome UI options rather than ignoring
|
|
613
|
+
them. `url` and `urls` are alternative inputs for `newWindow`; either can accompany `targetId` in a `normal` window. A
|
|
614
|
+
`popup` accepts a single URL or one existing tab, without additional URLs. Known preflight rejections retain
|
|
615
|
+
`actionExecuted=false`, `actionStatus="not_started"`, and `failureStage="preflight"`; rejected updates preserve the page
|
|
616
|
+
revision. Once a native update has been dispatched, a failure still invalidates that revision.
|
|
617
|
+
|
|
618
|
+
`emulate` applies the device viewport, pixel density, touch support, and User-Agent in both backends. `viewport`
|
|
619
|
+
restores desktop metrics, page scale, and disabled touch emulation; restore the User-Agent separately with `userAgent`.
|
|
376
620
|
|
|
377
621
|
**Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
|
|
378
622
|
|
|
@@ -388,14 +632,23 @@ and cache. `focusWindow` only returns success after the target window is observe
|
|
|
388
632
|
| `network` | Network request logs (with URL filter) |
|
|
389
633
|
|
|
390
634
|
Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and
|
|
391
|
-
`debug`; raw browser levels such as `warn` and `log` are normalized before filtering and return.
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
635
|
+
`debug`; raw browser levels such as `warn` and `log` are normalized before filtering and return. Clearing fallback
|
|
636
|
+
console logs keeps the hook active. When debugger collection becomes available, fallback capture is disabled. Console
|
|
637
|
+
methods still pointing to the MCP wrapper are restored, while wrappers installed later by the page are preserved.
|
|
638
|
+
Network logs are finalized on `loadingFinished` or `loadingFailed`, not when headers arrive, so body failures retain
|
|
639
|
+
both the HTTP status and `errorText`, and in-flight bodies continue to count against `networkidle`. Entries include
|
|
640
|
+
`method`, `url`, `status`, `timestamp`, and `duration` when available. URL query parameters commonly used for
|
|
641
|
+
credentials, signatures, passwords, and tokens are replaced with `[REDACTED]` in inline responses, diagnostics, and
|
|
642
|
+
explicit `output` files. Redacted entries include `urlRedacted`, `urlOriginalLength`, and `redactedQueryParameters`.
|
|
643
|
+
Inline network results limit each sanitized URL to 2048 characters and add `urlLength` plus `urlTruncated: true` when
|
|
644
|
+
shortened. `urlPattern` supports `*` for any number of characters and `?` for one character. `tabId` targets a specific
|
|
645
|
+
tab (Extension mode). `frame` is not applicable for logs.
|
|
646
|
+
|
|
647
|
+
When the Extension debugger is unavailable, network reads refresh performance entries and mark them with
|
|
648
|
+
`source="performance"`. Status uses the browser's `responseStatus` when available, or `0` otherwise; unknown request
|
|
649
|
+
methods remain empty. Repeated reads preserve record sequences. `clear` clears MCP records and advances the current
|
|
650
|
+
document's read boundary without clearing the page's shared performance timeline. A new document starts a new boundary.
|
|
651
|
+
Read failures return an error rather than an empty log.
|
|
399
652
|
|
|
400
653
|
### cookies - Cookie Management
|
|
401
654
|
|
|
@@ -407,7 +660,8 @@ logs.
|
|
|
407
660
|
| `clear` | Delete cookies in a URL or domain scope, optionally narrowed by `name` |
|
|
408
661
|
|
|
409
662
|
**Note**: `clear` requires `url` or `domain`. `name` can only further narrow that scope, so a same-named cookie on
|
|
410
|
-
another site cannot be removed accidentally.
|
|
663
|
+
another site cannot be removed accidentally. The returned `count` includes only cookies for which Chrome confirms a
|
|
664
|
+
removal; cookies that disappear between listing and removal are not counted.
|
|
411
665
|
|
|
412
666
|
## Target: Unified Element Locator
|
|
413
667
|
|
|
@@ -515,12 +769,30 @@ extract(type="html", target={ css: ".article" }, images="info")
|
|
|
515
769
|
|
|
516
770
|
// Get HTML + image data, save to directory
|
|
517
771
|
extract(type="html", images="data", output="tmp:page")
|
|
518
|
-
// Creates: <system-temp>/claude-tools/mcp-chrome/page/content.html, images/*, index.json
|
|
772
|
+
// Creates: <system-temp>/claude-tools/mcp-chrome/session-<id>/page/content.html, images/*, index.json
|
|
519
773
|
|
|
520
774
|
// Get HTML + image data inline (max 20 images)
|
|
521
775
|
extract(type="html", target={ css: ".card" }, images="data")
|
|
522
776
|
```
|
|
523
777
|
|
|
778
|
+
`tmp:` paths belong to the current server session. Temporary output has a 256-entry and 128 MiB session limit; on
|
|
779
|
+
startup, marked sessions older than 24 hours are removed only after their process exits. Use `cwd:` for files that must
|
|
780
|
+
remain accessible after restarting the server. Successful responses that save a `tmp:` file or directory include a
|
|
781
|
+
`retention` field describing the cleanup condition; `cwd:` responses omit it. Output paths reject Windows reserved
|
|
782
|
+
device names, alternate data streams, invalid characters, and trailing spaces or dots. On Windows, private file
|
|
783
|
+
permissions must be verified before writing sensitive content.
|
|
784
|
+
|
|
785
|
+
Invalid path syntax returns `INVALID_ARGUMENT`; `.` components are accepted and `..` components remain rejected. Paths
|
|
786
|
+
outside an allowed root, including symlink escapes, return `PATH_NOT_ALLOWED`. Both errors include the server's actual
|
|
787
|
+
working directory as `error.context.cwd`; scope rejections also include `allowedRoots`. Use `cwd:` with a path relative
|
|
788
|
+
to that directory, or `tmp:` for session output. These checks also apply to `scriptFile` and `compareWith`.
|
|
789
|
+
|
|
790
|
+
Quota rejection returns `TEMP_OUTPUT_QUOTA_EXCEEDED` with `limits`, `usage`, `remaining`, `requested`, and `projected`
|
|
791
|
+
in `error.context`. If `usage.complete` is false, usage is an observed lower bound and `remaining`/`projected` are null.
|
|
792
|
+
Existing output is preserved. An evaluate output failure retains `actionExecuted=true`, `actionStatus=completed`,
|
|
793
|
+
`failureStage=output`, and `retryable=false`; the script is not replayed. Use a repository-relative `cwd:` path for
|
|
794
|
+
subsequent output.
|
|
795
|
+
|
|
524
796
|
### Page Metadata
|
|
525
797
|
|
|
526
798
|
```
|
|
@@ -548,6 +820,18 @@ input(events=[
|
|
|
548
820
|
Selectors and numeric indices follow the parent document's DOM iframe order. Subframes absent from that DOM, including
|
|
549
821
|
frames added by other extensions, cannot shift the index or become fallback targets. If the selected element cannot be
|
|
550
822
|
tied to exactly one Chrome frame, the operation returns `FRAME_IDENTITY_UNAVAILABLE` instead of choosing another frame.
|
|
823
|
+
Precise evaluation matches the complete iframe URL, including query strings and fragments, and uses the selected DOM
|
|
824
|
+
iframe to distinguish frames with the same URL, including `about:srcdoc`. It rejects the operation when that identity
|
|
825
|
+
cannot be confirmed.
|
|
826
|
+
|
|
827
|
+
Frame selection failures return `INVALID_FRAME_SELECTOR`, `FRAME_NOT_IFRAME`, or `FRAME_NOT_FOUND`. Read injections
|
|
828
|
+
report `INVALID_SELECTOR`, `FRAME_STALE_CONTEXT`, `FRAME_INJECTION_DENIED`, `FRAME_SCRIPT_FAILED`,
|
|
829
|
+
`FRAME_INJECTION_FAILED`, or `FRAME_SCRIPT_NO_RESULT`, with the injection or script-result phase. A missing result does
|
|
830
|
+
not establish that the selector is invalid. Empty text, empty element arrays, null attribute values, and void script
|
|
831
|
+
calls keep their existing meaning; errors do not replay the script. When a read fails after resolving a frame,
|
|
832
|
+
`pageContext.frameContext` retains its selected DOM index, Chrome frame ID, and available document identity. Frame URL
|
|
833
|
+
diagnostics remove credentials, query strings, and fragments and are limited to 500 characters. `data:` and
|
|
834
|
+
`javascript:` URLs expose only the protocol; an unparseable URL reports `url=null` and `urlStatus="unavailable"`.
|
|
551
835
|
|
|
552
836
|
### Wait for Element
|
|
553
837
|
|
|
@@ -684,19 +968,34 @@ Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificat
|
|
|
684
968
|
as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with
|
|
685
969
|
`actionStatus="failed"`; result materialization or serialization errors report `actionStatus="completed"` and
|
|
686
970
|
`failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action
|
|
687
|
-
result.
|
|
688
|
-
|
|
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.
|
|
689
983
|
|
|
690
984
|
`replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other
|
|
691
985
|
input types use a native full-value update and return the requested and actual browser-normalized values. A standalone
|
|
692
986
|
`select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are
|
|
693
987
|
focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure
|
|
694
988
|
context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text`
|
|
695
|
-
values.
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
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.
|