@pyrokine/mcp-chrome 2.4.1 → 2.4.4

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.
Files changed (105) hide show
  1. package/README.md +213 -158
  2. package/README_zh.md +245 -187
  3. package/dist/anti-detection/behavior.js +1 -1
  4. package/dist/anti-detection/behavior.js.map +1 -1
  5. package/dist/anti-detection/injection.d.ts.map +1 -1
  6. package/dist/anti-detection/injection.js +2 -1
  7. package/dist/anti-detection/injection.js.map +1 -1
  8. package/dist/cdp/client.d.ts +2 -2
  9. package/dist/cdp/client.d.ts.map +1 -1
  10. package/dist/cdp/client.js +7 -4
  11. package/dist/cdp/client.js.map +1 -1
  12. package/dist/core/browser-driver.d.ts +3 -2
  13. package/dist/core/browser-driver.d.ts.map +1 -1
  14. package/dist/core/browser-driver.js +1 -0
  15. package/dist/core/browser-driver.js.map +1 -1
  16. package/dist/core/errors.d.ts +9 -0
  17. package/dist/core/errors.d.ts.map +1 -1
  18. package/dist/core/errors.js +16 -1
  19. package/dist/core/errors.js.map +1 -1
  20. package/dist/core/os-mouse.d.ts +65 -0
  21. package/dist/core/os-mouse.d.ts.map +1 -0
  22. package/dist/core/os-mouse.js +334 -0
  23. package/dist/core/os-mouse.js.map +1 -0
  24. package/dist/core/session.d.ts +14 -4
  25. package/dist/core/session.d.ts.map +1 -1
  26. package/dist/core/session.js +159 -54
  27. package/dist/core/session.js.map +1 -1
  28. package/dist/core/types.d.ts +10 -0
  29. package/dist/core/types.d.ts.map +1 -1
  30. package/dist/core/types.js +2 -0
  31. package/dist/core/types.js.map +1 -1
  32. package/dist/core/unified-session.d.ts +24 -3
  33. package/dist/core/unified-session.d.ts.map +1 -1
  34. package/dist/core/unified-session.js +143 -25
  35. package/dist/core/unified-session.js.map +1 -1
  36. package/dist/extension/bridge.d.ts +16 -0
  37. package/dist/extension/bridge.d.ts.map +1 -1
  38. package/dist/extension/bridge.js +27 -0
  39. package/dist/extension/bridge.js.map +1 -1
  40. package/dist/extension/http-server.d.ts.map +1 -1
  41. package/dist/extension/http-server.js +6 -1
  42. package/dist/extension/http-server.js.map +1 -1
  43. package/dist/tools/browse.d.ts +1 -1
  44. package/dist/tools/browse.d.ts.map +1 -1
  45. package/dist/tools/browse.js +72 -26
  46. package/dist/tools/browse.js.map +1 -1
  47. package/dist/tools/challenge.d.ts +153 -0
  48. package/dist/tools/challenge.d.ts.map +1 -0
  49. package/dist/tools/challenge.js +573 -0
  50. package/dist/tools/challenge.js.map +1 -0
  51. package/dist/tools/cookies.d.ts.map +1 -1
  52. package/dist/tools/cookies.js +8 -4
  53. package/dist/tools/cookies.js.map +1 -1
  54. package/dist/tools/diagnostics.d.ts +2 -2
  55. package/dist/tools/diagnostics.d.ts.map +1 -1
  56. package/dist/tools/diagnostics.js +26 -8
  57. package/dist/tools/diagnostics.js.map +1 -1
  58. package/dist/tools/evaluate.d.ts.map +1 -1
  59. package/dist/tools/evaluate.js +61 -9
  60. package/dist/tools/evaluate.js.map +1 -1
  61. package/dist/tools/extract.d.ts.map +1 -1
  62. package/dist/tools/extract.js +110 -51
  63. package/dist/tools/extract.js.map +1 -1
  64. package/dist/tools/input.d.ts.map +1 -1
  65. package/dist/tools/input.js +148 -22
  66. package/dist/tools/input.js.map +1 -1
  67. package/dist/tools/logs.js +2 -2
  68. package/dist/tools/logs.js.map +1 -1
  69. package/dist/tools/manage.d.ts.map +1 -1
  70. package/dist/tools/manage.js +20 -7
  71. package/dist/tools/manage.js.map +1 -1
  72. package/dist/tools/network-sanitizer.d.ts.map +1 -1
  73. package/dist/tools/network-sanitizer.js +1 -0
  74. package/dist/tools/network-sanitizer.js.map +1 -1
  75. package/dist/tools/png.js +5 -3
  76. package/dist/tools/png.js.map +1 -1
  77. package/dist/tools/post-condition.d.ts.map +1 -1
  78. package/dist/tools/post-condition.js +12 -3
  79. package/dist/tools/post-condition.js.map +1 -1
  80. package/dist/tools/target-diagnostics.d.ts +7 -0
  81. package/dist/tools/target-diagnostics.d.ts.map +1 -1
  82. package/dist/tools/target-diagnostics.js +18 -1
  83. package/dist/tools/target-diagnostics.js.map +1 -1
  84. package/dist/tools/wait.d.ts.map +1 -1
  85. package/dist/tools/wait.js +41 -39
  86. package/dist/tools/wait.js.map +1 -1
  87. package/extension/dist/assets/{index.ts-GG6dPUPX.js → index.ts-Bqcu2qiN.js} +286 -9
  88. package/extension/dist/manifest.json +1 -1
  89. package/extension/dist/service-worker-loader.js +1 -1
  90. package/extension/dist/src/popup/popup.html +44 -44
  91. package/package.json +8 -7
  92. package/dist/extension/native-host-installer.d.ts +0 -21
  93. package/dist/extension/native-host-installer.d.ts.map +0 -1
  94. package/dist/extension/native-host-installer.js +0 -147
  95. package/dist/extension/native-host-installer.js.map +0 -1
  96. package/dist/extension/socket-server.d.ts +0 -32
  97. package/dist/extension/socket-server.d.ts.map +0 -1
  98. package/dist/extension/socket-server.js +0 -177
  99. package/dist/extension/socket-server.js.map +0 -1
  100. package/dist/extension/ws-server.d.ts +0 -40
  101. package/dist/extension/ws-server.d.ts.map +0 -1
  102. package/dist/extension/ws-server.js +0 -246
  103. package/dist/extension/ws-server.js.map +0 -1
  104. package/dist/native-host/index.js +0 -280
  105. package/dist/native-host/mcp-chrome-host +0 -2
package/README.md CHANGED
@@ -15,7 +15,7 @@ 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-Tab Parallel**: `tabId` parameter enables operations on any tab without switching focus
17
17
  - **iframe Penetration**: `frame` parameter targets elements inside iframes (CSS selector or index, Extension mode)
18
- - **Semantic Targeting**: 11 ways to locate elements (role, text, label, css, css+text combo, xpath, coordinates, etc.)
18
+ - **Semantic Targeting**: 11 ways to locate elements (role, text, label, CSS, CSS+text combo, XPath, coordinates, etc.)
19
19
  - **Auto-Wait**: Built-in clickability and input-ready detection with deadline-based timeout budget
20
20
  - **Dual Input Mode**: `precise` (debugger API, bypasses CSP) or `stealth` (JS injection, no debug banner)
21
21
  - **Smart Output**: Bare `return` auto-wrapped in IIFE; large results (>100KB) auto-saved to file; `output` writes raw
@@ -27,12 +27,12 @@ existing browser, **CDP mode** (fallback) launches a dedicated instance.
27
27
  ## Compatible Clients
28
28
 
29
29
  | Client | Status |
30
- |---------------------------|--------|
31
- | Claude Code | ✅ |
32
- | Claude Desktop | ✅ |
33
- | Cursor | ✅ |
34
- | Windsurf | ✅ |
35
- | Any MCP-compatible client | ✅ |
30
+ | ------------------------- | ------ |
31
+ | Claude Code | ✅ |
32
+ | Claude Desktop | ✅ |
33
+ | Cursor | ✅ |
34
+ | Windsurf | ✅ |
35
+ | Any MCP-compatible client | ✅ |
36
36
 
37
37
  ## Installation
38
38
 
@@ -46,7 +46,8 @@ claude mcp add chrome -- mcp-chrome
46
46
  npm root -g
47
47
  ```
48
48
 
49
- For Extension mode, open `chrome://extensions/`, enable Developer mode, click "Load unpacked", and select `<npm-root>/@pyrokine/mcp-chrome/extension/dist`.
49
+ For Extension mode, open `chrome://extensions/`, enable Developer mode, click "Load unpacked", and select
50
+ `<npm-root>/@pyrokine/mcp-chrome/extension/dist`.
50
51
 
51
52
  ### From source
52
53
 
@@ -89,14 +90,12 @@ Claude Desktop / Other Clients:
89
90
 
90
91
  ```json
91
92
  {
92
- "mcpServers": {
93
- "chrome": {
94
- "command": "node",
95
- "args": [
96
- "/path/to/mcp-chrome/dist/index.js"
97
- ]
93
+ "mcpServers": {
94
+ "chrome": {
95
+ "command": "node",
96
+ "args": ["/path/to/mcp-chrome/dist/index.js"]
97
+ }
98
98
  }
99
- }
100
99
  }
101
100
  ```
102
101
 
@@ -104,9 +103,10 @@ Claude Desktop / Other Clients:
104
103
 
105
104
  The Extension auto-connects to the MCP Server via HTTP/WebSocket (port 19222-19299). Click the toolbar icon to verify
106
105
  connection status. `browse(action="connect")` and the local `/api/info` endpoint report the active Extension background
107
- bundle hash and compare it with the bundle shipped beside the server. `bundleStatus="stale"` means Chrome is still running
108
- an older unpacked Extension bundle; reload the Extension in `chrome://extensions/`. Legacy Extensions without a bundle hash
109
- remain compatible, and bundle identity never disables zero-config auto-connect.
106
+ bundle hash and compare it with the bundle shipped beside the server. `bundleStatus="stale"` means Chrome is still
107
+ running an older unpacked Extension bundle; reload the Extension in `chrome://extensions/`. A legacy Extension that
108
+ lacks `network_challenge_state` falls back to tab-title and DOM challenge detection. Bundle identity never disables
109
+ zero-config auto-connect.
110
110
 
111
111
  ```
112
112
  browse(action="list") // List all tabs
@@ -117,15 +117,15 @@ extract(type="screenshot")
117
117
  **Pairing token**
118
118
 
119
119
  Extension mode keeps zero-config local auto-connect by default. On shared machines, CI runners, or containers where
120
- untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter the
121
- same token in the Extension popup:
120
+ untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter
121
+ the same token in the Extension popup:
122
122
 
123
123
  ```bash
124
124
  MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
125
125
  ```
126
126
 
127
- To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server and
128
- disable "Allow no-token local connection" in the Extension popup.
127
+ 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.
129
129
 
130
130
  ### Mode 2: CDP Mode (Fallback)
131
131
 
@@ -142,54 +142,94 @@ browse(action="connect", port=9222)
142
142
  browse(action="open", url="https://example.com")
143
143
  ```
144
144
 
145
- > When the Extension is connected, all tools use Extension mode automatically. CDP mode activates only when the
146
- > Extension is unavailable.
145
+ > A connected Extension is the default for every tool. CDP is used only while the Extension is unavailable. A
146
+ > `browse(action="connect", port=9222)` call explicitly selects CDP for later tools; use `browse(action="connect")` to
147
+ > return to Extension mode. A CDP connection created only as fallback yields to Extension after the Extension
148
+ > reconnects.
147
149
 
148
150
  ## Available Tools (8 Tools)
149
151
 
150
152
  ### browse - Browser Management & Navigation
151
153
 
152
- | Action | Description |
153
- |-----------|---------------------------------------|
154
- | `launch` | Launch new Chrome instance (CDP mode) |
155
- | `connect` | Connect to running Chrome (CDP mode) |
156
- | `list` | List all pages/tabs |
157
- | `attach` | Attach to a specific page/tab |
158
- | `open` | Navigate to URL |
159
- | `back` | Go back in history |
160
- | `forward` | Go forward in history |
161
- | `refresh` | Reload page |
162
- | `close` | Close browser connection |
154
+ | Action | Description |
155
+ | --------- | --------------------------------------------------------------------------- |
156
+ | `launch` | Create a managed Extension tab, or launch CDP when Extension is unavailable |
157
+ | `connect` | Confirm Extension by default; `port` explicitly selects CDP |
158
+ | `list` | List all pages/tabs |
159
+ | `attach` | Attach to a specific page/tab |
160
+ | `open` | Navigate to URL |
161
+ | `back` | Go back in history |
162
+ | `forward` | Go forward in history |
163
+ | `refresh` | Reload page |
164
+ | `close` | Close the page specified by `targetId` |
163
165
 
164
166
  Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
165
167
  (whether tab is controlled by MCP Chrome), `isActive` (whether it's the current operation target), `windowId`, `index`,
166
168
  `pinned`, `incognito`, and `status` (`loading`/`complete`). The tree includes `windowCount`, `focusedWindowId`,
167
169
  `activeTargetId`, and each window's ordered `tabs` list, so callers can distinguish the active tab inside each window
168
- from the page currently visible in the focused window.
169
- `open` auto-creates tab group (cyan color). `open`, `back`, `forward`, and `refresh` accept `diagnostics=true` to return
170
- new console warnings/errors and failed network requests observed during the action, including the first `open` that
171
- creates a page automatically.
170
+ from the page currently visible in the focused window. `open` auto-creates tab group (cyan color). `open`, `back`,
171
+ `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. `close` requires `targetId`
173
+ and closes only that page. It never closes the entire CDP connection.
174
+
175
+ ### Access challenges
176
+
177
+ After `open`, `back`, `forward`, `refresh`, `input`, and `evaluate`, MCP Chrome waits for a Cloudflare JS Challenge or
178
+ Turnstile checkbox. When Extension mode is active, navigation starts without debugger logging and reads the live tab
179
+ title passively for eight seconds. If the interstitial persists, MCP Chrome checks for a visible Turnstile control and
180
+ clicks it only when it finds one. Extension inspect uses an isolated world and detaches the debugger first. Same-page
181
+ fixture buttons use the existing page click. If a Cloudflare Turnstile iframe is present, inspect CSS coordinates are
182
+ 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 origin plus window chrome insets only when that window title matches the test page,
184
+ rather than Chrome `screenX` or `outerHeight - innerHeight`; `cliclick` or System Events on macOS; and PowerShell
185
+ `mouse_event` on Windows. Widget clicks target the checkbox on the left of the compact Turnstile card, including when
186
+ 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
+ used even when that iframe reports a zero-size rect, including the later host `Verify you are human` / `请验证您是真人`
188
+ button. The OS click runs only when the managed test tab is already the active tab in an already-focused window; mixed
189
+ windows are not focused. Debugger is detached and the viewport is read again before the OS click. Missing OS mouse tools
190
+ 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. Distant OS-mouse paths start near the control instead of flying across the
192
+ screen. The same checkbox or compact widget is clicked at most once; if Cloudflare then shows a visible
193
+ `Verify you are human` or `请验证您是真人` button, that button is inspected as `verify` and clicked at most once in the
194
+ same wait. Use the default `diagnostics=false` for challenge-protected pages because diagnostics starts debugger console
195
+ and network collection.
196
+
197
+ Detection covers titles such as `Just a moment...` and `请稍候…`, challenge DOM or body-text markers, and
198
+ `Verify you are human` / `请验证您是真人` controls. CDP reads live titles with `Target.getTargetInfo`. A leftover
199
+ Cloudflare iframe on a recovered page is not pending. Cached titles do not decide the result. MCP Chrome does not call a
200
+ CAPTCHA solver, retry navigation, or export `cf_clearance` values. A CDP timeout does not prove that the site fails in a
201
+ user Chrome session; check the returned `mode` before diagnosing the site.
202
+
203
+ A resolved challenge returns `challengeResolved=true`, `challengeKind`, `waitedMs`, `clickedTurnstile`, and
204
+ `clearanceCookiePresent` (name presence only). If the visible page text says verification succeeded and Cloudflare is
205
+ waiting for the origin, the result also has `originResponsePending=true`; verification passed, but the destination page
206
+ is not loaded yet. Hidden template text such as a `display:none` success heading does not count, and a visible Turnstile
207
+ checkbox still counts as pending. Challenge results and errors include `mode`. Timeout returns `CHALLENGE_TIMEOUT` with
208
+ `retryable=true`, `clickedTurnstile`, and the observed `challengeKind` (a Turnstile click is not reported as `js`).
209
+ Cloudflare Access denied returns `CHALLENGE_DENIED`. Interactive CAPTCHAs, Bot Fight Mode, and IP reputation checks
210
+ cannot be completed by waiting or clicking a checkbox. A later normal main-document response clears the header flag;
211
+ clearing network logs does not.
172
212
 
173
213
  ### input - Keyboard & Mouse Input
174
214
 
175
215
  Event sequence model supporting arbitrary combinations:
176
216
 
177
- | Event Type | Description |
178
- |-----------------------------------------|-----------------------------------------------------------------------------------|
179
- | `keydown` / `keyup` | Key press/release |
180
- | `click` | Click with actionability checks (visible, enabled, not-covered, auto-scroll) |
181
- | `mousedown` / `mouseup` | Mouse button press/release |
182
- | `mousemove` | Mouse movement |
183
- | `wheel` | Mouse wheel scroll |
184
- | `touchstart` / `touchmove` / `touchend` | Touch events |
185
- | `type` | Type text (with optional `delay`, `dispatch` for React/Vue) |
186
- | `wait` | Pause between events |
187
- | `select` | Select text by content (mouse sim) |
188
- | `replace` | Find and replace text |
189
- | `drag` | HTML5 drag-and-drop (DragEvent in MAIN world, with `target` source + `to` target) |
190
- | `editorContext` | Read focused editor and selection context |
191
- | `editorInsert` | Insert text at the current editor selection |
192
- | `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
217
+ | Event Type | Description |
218
+ | --------------------------------------- | ---------------------------------------------------------------------- |
219
+ | `keydown` / `keyup` | Key press/release |
220
+ | `click` | Click after visibility, enabled, coverage, and scroll checks |
221
+ | `mousedown` / `mouseup` | Mouse button press/release |
222
+ | `mousemove` | Mouse movement |
223
+ | `wheel` | Mouse wheel scroll |
224
+ | `touchstart` / `touchmove` / `touchend` | Touch events |
225
+ | `type` | Type text (with optional `delay`, `dispatch` for React/Vue) |
226
+ | `wait` | Pause between events |
227
+ | `select` | Select text by content (mouse sim) |
228
+ | `replace` | Find and replace text |
229
+ | `drag` | HTML5 drag-and-drop (`target` source and `to` destination) |
230
+ | `editorContext` | Read focused editor and selection context |
231
+ | `editorInsert` | Insert text at the current editor selection |
232
+ | `editorCommand` | Execute browser editing commands such as `bold` or `insertOrderedList` |
193
233
 
194
234
  Special-case parameters:
195
235
 
@@ -199,28 +239,29 @@ Special-case parameters:
199
239
  the CDP commands API has no JS-event equivalent.
200
240
  - `keydown` on a key already held emits `rawKeyDown` with `autoRepeat: true` (Puppeteer-compatible long-press).
201
241
 
202
- Parameters: `humanize` enables Bézier curve movement and random delays. `diagnostics=true` returns new console
203
- warnings/errors and failed network requests after the action. `postCondition` waits for a page state after the events so
204
- callers can distinguish dispatched input from completed page behavior. `postCondition.timeout` defaults to 3000 ms and
205
- is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and accepts 50-5000 ms. `tabId` targets a specific
206
- tab. `frame` targets an iframe (CSS selector or index). Both are Extension-mode only. When either scope is provided, the
207
- action, diagnostics, and post-condition use the backend selected for that target scope.
242
+ `events` must contain at least one event. Parameters: `humanize` enables Bézier curve movement and random delays.
243
+ `diagnostics=true` returns new console warnings/errors and failed network requests after the action. `postCondition`
244
+ waits for a page state after the events so callers can distinguish dispatched input from completed page behavior.
245
+ `postCondition.timeout` defaults to 3000 ms and is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
246
+ accepts 50-5000 ms. `tabId` targets a specific tab. `frame` targets an iframe (CSS selector or index). Both are
247
+ Extension-mode only. When either scope is provided, the action, diagnostics, and post-condition use the backend selected
248
+ for that target scope.
208
249
 
209
250
  **`click`-specific**: `force: true` skips actionability checks (useful for testing or hidden elements). Actionability
210
251
  failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering element details, candidate blockers, and
211
- suggestions.
212
- **`type`-specific**: `mode="controlled"` or `dispatch: true` sets `.value` directly and fires `input`/`change` events —
213
- use for React/Vue controlled inputs where keyboard events don't update state. Requires a non-coordinate `target`.
214
- Extension mode only. Controlled input and target lookup failures return structured context with `target`, `matchCount`,
215
- `nth`, `activeElement`, `selection`, and candidate controls. Password input values are omitted from failure diagnostics,
216
- and input `find` or replacement `text` values are redacted from failed responses. For `select` and `replace`, event-level
217
- `nth` selects the Nth text occurrence while nested `target.nth` selects the Nth matching element; both are zero-based and
218
- may be used together. Locator targets for `select` and `replace` work in CDP mode without Extension ref IDs.
252
+ suggestions. **`type`-specific**: `mode="controlled"` or `dispatch: true` sets `.value` directly and fires `input`/
253
+ `change` events — use for React/Vue controlled inputs where keyboard events don't update state. Requires a
254
+ non-coordinate `target`. Extension mode only. Controlled input and target lookup failures return structured context with
255
+ `target`, `matchCount`, `nth`, `activeElement`, `selection`, and candidate controls. Password input values are omitted
256
+ from failure diagnostics, and input `find` or replacement `text` values are redacted from failed responses. For `select`
257
+ and `replace`, event-level `nth` selects the Nth text occurrence while nested `target.nth` selects the Nth matching
258
+ element; both are zero-based and may be used together. Locator targets for `select` and `replace` work in CDP mode
259
+ without Extension ref IDs.
219
260
 
220
261
  ### extract - Content Extraction
221
262
 
222
263
  | Type | Description |
223
- |--------------|---------------------------------------------------|
264
+ | ------------ | ------------------------------------------------- |
224
265
  | `text` | Extract text content |
225
266
  | `html` | Extract HTML source |
226
267
  | `frameHtml` | Extract HTML from the selected iframe |
@@ -232,10 +273,12 @@ may be used together. Locator targets for `select` and `replace` work in CDP mod
232
273
  Parameters: `output` saves result to file (or directory for `images=data`). `images` (`info`/`data`) extracts image
233
274
  metadata or data alongside HTML. `frameHtml` extracts the current iframe document after `frame` routing. Screenshot
234
275
  accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline comparison, and `diffOutput` for a PNG diff
235
- image. Screenshot responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`,
236
- `scale`, `clip`, and `capabilities`. PNG comparison is capped before decode at 25 MiB per PNG and 12,000,000 pixels; use
237
- `clip` or `scale` for larger captures. Hidden Extension tabs return `HIDDEN_TAB_SCREENSHOT` instead of auto-focusing the
238
- browser. If another debugger blocks the precise screenshot path, viewport fallback reports `degraded`, `fallback`, and
276
+ image. `diffOutput` requires `compareWith`. A `target` screenshot that has no match, whose `nth` is out of range, or
277
+ whose box has zero size returns a target error rather than silently returning a viewport screenshot. Screenshot
278
+ responses include `metadata.format`, `width`, `height`, `dimensionSource`, `byteSize`, `fullPage`, `scale`, `clip`, and
279
+ `capabilities`. PNG comparison is capped before decode at 25 MiB per PNG and 12,000,000 pixels; use `clip` or `scale`
280
+ for larger captures. Hidden Extension tabs return `HIDDEN_TAB_SCREENSHOT` instead of automatically focusing the browser.
281
+ If another debugger blocks the precise screenshot path, viewport fallback reports `degraded`, `fallback`, and
239
282
  `limitations`; unsupported fallback options return structured `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns
240
283
  `interactiveElements`; `metadata` returns `frames` in both Extension and CDP modes. `tabId` targets a specific tab.
241
284
  `frame` targets an iframe. Both Extension mode only.
@@ -251,35 +294,35 @@ browser. If another debugger blocks the precise screenshot path, viewport fallba
251
294
  ### wait - Wait for Conditions
252
295
 
253
296
  | For | Description |
254
- |--------------|-----------------------------------------------------|
297
+ | ------------ | --------------------------------------------------- |
255
298
  | `element` | Wait for element (visible/hidden/attached/detached) |
256
299
  | `navigation` | Wait for navigation complete |
257
300
  | `time` | Fixed delay |
258
- | `idle` | Wait for page load + DOM mutation quiet period |
301
+ | `idle` | Wait for DOM or network quiet period |
259
302
 
260
303
  Parameters: `tabId` targets a specific tab. `frame` targets an iframe. Both Extension mode only.
261
304
 
262
- **`idle`-specific**: After `readyState === 'complete'`, injects a `MutationObserver` and waits for a quiet period with
263
- no DOM changes. The `ms` parameter controls the quiet period duration (default 500ms). Returns `domStable: true` when
264
- the DOM settled, `domStable: false` if still mutating when the budget ran out.
305
+ **`idle`-specific**: In Extension mode, after `readyState === 'complete'`, it injects a `MutationObserver` and waits for
306
+ a quiet period with no DOM changes. In CDP mode, it waits for network quiet instead. `ms` controls the relevant quiet
307
+ period (default 500ms). The response returns `idleKind` and `idlePeriodMs`; Extension responses also return `domStable`.
265
308
 
266
309
  ### evaluate - JavaScript Execution
267
310
 
268
311
  Execute JavaScript in page context.
269
312
 
270
- | Parameter | Description |
271
- |-----------------|-----------------------------------------------------------------------------------------------------------------------------------|
272
- | `script` | JavaScript code. Bare `return` statements auto-wrapped in IIFE |
273
- | `scriptFile` | Read script from a local file (alternative to `script`, relative paths default to controlled temp dir, use `cwd:` for repo files) |
274
- | `args` | Arguments passed to script (script must be a function expression) |
275
- | `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
276
- | `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly` |
277
- | `output` | Save result to file (relative paths default to controlled temp dir, use `cwd:` to persist in repo) |
278
- | `tabId` | Target a specific tab (Extension mode) |
279
- | `frame` | Target an iframe by CSS selector or index (Extension mode) |
280
- | `timeout` | End-to-end budget (ms) |
281
- | `diagnostics` | Return new console warnings/errors and failed network requests after execution |
282
- | `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
313
+ | Parameter | Description |
314
+ | ------------------- | ----------------------------------------------------------------------- |
315
+ | `script` | JavaScript code. Bare `return` statements are wrapped in IIFE |
316
+ | `scriptFile` | Read code from a local file instead of `script` |
317
+ | `args` | Arguments passed to a script written as a function expression |
318
+ | `mode` | `precise` (default, debugger API) or `stealth` (JS injection) |
319
+ | `staleContextRetry` | iframe stale-context policy: `never` (default) or `readOnly` |
320
+ | `output` | Save the result to a file |
321
+ | `tabId` | Target a specific tab (Extension mode) |
322
+ | `frame` | Target an iframe by CSS selector or index (Extension mode) |
323
+ | `timeout` | End-to-end budget (ms) |
324
+ | `diagnostics` | Return new console warnings/errors and failed requests after execution |
325
+ | `postCondition` | Wait for text, selector, URL fragment, or script result after execution |
283
326
 
284
327
  `script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
285
328
  paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
@@ -290,17 +333,19 @@ Results >100KB are auto-saved to the controlled OS temp directory with a structu
290
333
  `NodeList`, and `HTMLCollection` results return `NON_SERIALIZABLE_EVALUATE_RESULT` with a hint to return simple fields
291
334
  such as `textContent` or `outerHTML`. Result materialization and serialization failures report `actionExecuted=true`,
292
335
  `actionStatus="completed"`, and `failureStage="output"` because the page script has already finished. Evaluate defaults
293
- to `precise` even when global `inputMode` is `stealth`, and its
294
- `postCondition` checks use the same evaluate mode as the action. `postCondition` is optional; when it is not provided,
295
- `success=true` only means the script executed and returned. When it is provided and does not match before timeout, the
296
- tool returns `POST_CONDITION_FAILED` with the last observed checks. Precise iframe evaluation does not replay a script
297
- after a stale execution context by default. Set `staleContextRetry="readOnly"` only when the script has no side effects;
298
- the Extension may then resolve a new context and replay it once within the remaining timeout budget. A stale-context error after `Runtime.evaluate` reports `actionExecuted=true` and `actionStatus="unknown"`, because earlier side effects may already have happened even though the final result is unavailable.
336
+ to `precise` even when global `inputMode` is `stealth`, and its `postCondition` checks use the same evaluate mode as the
337
+ action. `postCondition` is optional; when it is not provided, `success=true` only means the script executed and
338
+ returned. When it is provided and does not match before timeout, the tool returns `POST_CONDITION_FAILED` with the last
339
+ observed checks. Precise iframe evaluation does not replay a script after a stale execution context by default. Set
340
+ `staleContextRetry="readOnly"` only when the script has no side effects; the Extension may then resolve a new context
341
+ and replay it once within the remaining timeout budget. A stale-context error after `Runtime.evaluate` reports
342
+ `actionExecuted=true` and `actionStatus="unknown"`, because earlier side effects may already have happened even though
343
+ the final result is unavailable.
299
344
 
300
345
  ### manage - Page & Environment Management
301
346
 
302
347
  | Action | Description |
303
- |----------------|------------------------------------------------------------|
348
+ | -------------- | ---------------------------------------------------------- |
304
349
  | `newPage` | Create new controlled page/tab |
305
350
  | `closePage` | Close controlled page and return `affected.before/after` |
306
351
  | `adoptPage` | Mark an existing tab as controlled without focusing it |
@@ -323,9 +368,11 @@ the Extension may then resolve a new context and replay it once within the remai
323
368
  | `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
324
369
 
325
370
  Tab/window management actions are Extension-mode only. Actions that change visible browser state require explicit
326
- `targetId` or `windowId` and return `affected.before/after`. `focusWindow` only returns success after the target window
327
- is observed as focused; otherwise it returns `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with
328
- unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
371
+ `targetId` or `windowId` and return `affected.before/after`. `clearCache` is unavailable in Extension mode and returns
372
+ `UNSUPPORTED_MODE` without clearing anything. Use scoped `cookies(action="clear")` for cookies or CDP mode for storage
373
+ and cache. `focusWindow` only returns success after the target window is observed as focused; otherwise it returns
374
+ `WINDOW_FOCUS_NOT_OBSERVED`. `closeWindow` refuses mixed windows with unmanaged tabs and returns
375
+ `WINDOW_HAS_UNMANAGED_TABS`.
329
376
 
330
377
  **Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
331
378
 
@@ -336,30 +383,31 @@ unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
336
383
  ### logs - Browser Logs
337
384
 
338
385
  | Type | Description |
339
- |-----------|----------------------------------------|
386
+ | --------- | -------------------------------------- |
340
387
  | `console` | Console logs (with level filter) |
341
388
  | `network` | Network request logs (with URL filter) |
342
389
 
343
- Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and `debug`;
344
- raw browser levels such as `warn` and `log` are normalized before filtering and return. Network logs include completed
345
- requests, HTTP 4xx/5xx responses, and failed loads with `errorText`, `method`, `url`, `status`, `timestamp`, and `duration`
346
- when available. URL query parameters commonly used for credentials, signatures, passwords, and tokens are replaced with
347
- `[REDACTED]` in inline responses, diagnostics, and explicit `output` files. Redacted entries include `urlRedacted`,
348
- `urlOriginalLength`, and `redactedQueryParameters`. Inline network results limit each sanitized URL to 2048 characters and
349
- add `urlLength` plus `urlTruncated: true` when shortened. `urlPattern` supports `*` for any number of characters and `?`
350
- for one character. `tabId` targets a specific tab (Extension mode). `frame` is not applicable for logs.
390
+ 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. Network logs include
392
+ completed requests, HTTP 4xx/5xx responses, and failed loads with `errorText`, `method`, `url`, `status`, `timestamp`,
393
+ and `duration` when available. URL query parameters commonly used for credentials, signatures, passwords, and tokens are
394
+ replaced with `[REDACTED]` in inline responses, diagnostics, and explicit `output` files. Redacted entries include
395
+ `urlRedacted`, `urlOriginalLength`, and `redactedQueryParameters`. Inline network results limit each sanitized URL to
396
+ 2048 characters and add `urlLength` plus `urlTruncated: true` when shortened. `urlPattern` supports `*` for any number
397
+ of characters and `?` for one character. `tabId` targets a specific tab (Extension mode). `frame` is not applicable for
398
+ logs.
351
399
 
352
400
  ### cookies - Cookie Management
353
401
 
354
- | Action | Description |
355
- |----------|---------------------------------------------------------------|
356
- | `get` | Get cookies |
357
- | `set` | Set cookie |
358
- | `delete` | Delete cookie |
359
- | `clear` | Delete cookies by filter (`name`/`domain`/`url`, ≥1 required) |
402
+ | Action | Description |
403
+ | -------- | ---------------------------------------------------------------------- |
404
+ | `get` | Get cookies |
405
+ | `set` | Set cookie |
406
+ | `delete` | Delete cookie |
407
+ | `clear` | Delete cookies in a URL or domain scope, optionally narrowed by `name` |
360
408
 
361
- **Note**: `clear` requires at least one of `name`, `domain`, or `url` to filter — calling without any filter is rejected
362
- to avoid wiping the user's login cookies.
409
+ **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.
363
411
 
364
412
  ## Target: Unified Element Locator
365
413
 
@@ -367,57 +415,43 @@ All tools use a unified `Target` type for element location:
367
415
 
368
416
  ```typescript
369
417
  // By accessibility (recommended - most stable)
370
- { role: "button", name: "Submit" }
418
+ const byRole = { role: 'button', name: 'Submit' }
371
419
 
372
420
  // By accessibility with exact accessible name
373
- { role: "button", name: "Submit", exact: true }
421
+ const byExactRole = { role: 'button', name: 'Submit', exact: true }
374
422
 
375
423
  // By text content
376
- { text: "Click here", exact: true }
424
+ const byText = { text: 'Click here', exact: true }
377
425
 
378
426
  // By form label
379
- {
380
- label: "Email"
381
- }
427
+ const byLabel = { label: 'Email' }
382
428
 
383
429
  // By placeholder
384
- {
385
- placeholder: "Enter your name"
386
- }
430
+ const byPlaceholder = { placeholder: 'Enter your name' }
387
431
 
388
432
  // By title attribute
389
- {
390
- title: "Close dialog"
391
- }
433
+ const byTitle = { title: 'Close dialog' }
392
434
 
393
435
  // By alt text (images)
394
- {
395
- alt: "Profile picture"
396
- }
436
+ const byAlt = { alt: 'Profile picture' }
397
437
 
398
438
  // By test ID
399
- {
400
- testId: "submit-button"
401
- }
439
+ const byTestId = { testId: 'submit-button' }
402
440
 
403
441
  // By CSS selector
404
- {
405
- css: "#login-form .submit-btn"
406
- }
442
+ const byCss = { css: '#login-form .submit-btn' }
407
443
 
408
444
  // Disambiguate multiple matches (0-based)
409
- { css: ".ant-select-input", nth: 1 }
445
+ const secondMatch = { css: '.ant-select-input', nth: 1 }
410
446
 
411
447
  // By CSS + text (filter by text content)
412
- { css: "button", text: "Submit", exact: true }
448
+ const byCssText = { css: 'button', text: 'Submit', exact: true }
413
449
 
414
450
  // By XPath
415
- {
416
- xpath: "//button[@type='submit']"
417
- }
451
+ const byXPath = { xpath: "//button[@type='submit']" }
418
452
 
419
453
  // By coordinates
420
- { x: 100, y: 200 }
454
+ const byCoordinates = { x: 100, y: 200 }
421
455
  ```
422
456
 
423
457
  ## Usage Examples
@@ -511,7 +545,9 @@ input(events=[
511
545
  ], frame="iframe.login-frame")
512
546
  ```
513
547
 
514
- Selectors and numeric indices follow the parent document's DOM iframe order. Subframes absent from that DOM, including frames added by other extensions, cannot shift the index or become fallback targets. If the selected element cannot be tied to exactly one Chrome frame, the operation returns `FRAME_IDENTITY_UNAVAILABLE` instead of choosing another frame.
548
+ Selectors and numeric indices follow the parent document's DOM iframe order. Subframes absent from that DOM, including
549
+ frames added by other extensions, cannot shift the index or become fallback targets. If the selected element cannot be
550
+ tied to exactly one Chrome frame, the operation returns `FRAME_IDENTITY_UNAVAILABLE` instead of choosing another frame.
515
551
 
516
552
  ### Wait for Element
517
553
 
@@ -601,8 +637,8 @@ mcp-chrome/
601
637
 
602
638
  ## Security Notes
603
639
 
604
- - **Trust boundary**: Extension mode auto-connects to local MCP servers by default. Use `MCP_CHROME_PAIRING_TOKEN`, or set
605
- `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`, on multi-user systems, CI runners, or containers with `--net=host` where
640
+ - **Trust boundary**: Extension mode auto-connects to local MCP servers by default. Use `MCP_CHROME_PAIRING_TOKEN`, or
641
+ set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0`, on multi-user systems, CI runners, or containers with `--net=host` where
606
642
  untrusted code can reach `127.0.0.1:19222-19299`. WebSocket upgrades require a `chrome-extension://` Origin header,
607
643
  which blocks browser pages and curl, but does not stop a malicious local process running as the same user.
608
644
  - Extension mode: shares your browser sessions — only use on trusted machines
@@ -610,7 +646,8 @@ mcp-chrome/
610
646
  - Default ports bind to 127.0.0.1 only (localhost)
611
647
  - The `evaluate` tool can execute arbitrary JavaScript
612
648
  - The `manage cdp` action can send arbitrary CDP commands
613
- - Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still contain sensitive information
649
+ - Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still
650
+ contain sensitive information
614
651
 
615
652
  ### Anti-detection (stealth) — what it actually does
616
653
 
@@ -618,10 +655,11 @@ The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerpri
618
655
 
619
656
  - **Covers**: `navigator.webdriver`, `cdc_*` properties, User-Agent string, a few WebGL vendor/renderer values, Chrome
620
657
  runtime properties
621
- - **Does NOT cover**: Canvas fingerprinting, AudioContext fingerprinting, Font enumeration, TLS-level fingerprints (
622
- JA3/JA4), CDP attach banner ("Chrome is being controlled by automated software"), Extension presence detection
623
- - **Warning**: Do NOT rely on this to bypass commercial anti-bot services (Cloudflare Turnstile, Akamai, DataDome,
624
- PerimeterX). Real bot detection happens at multiple layers we cannot patch from inside the page
658
+ - **Does NOT cover**: Canvas fingerprinting, AudioContext fingerprinting, Font enumeration, TLS-level fingerprints
659
+ (JA3/JA4), CDP attach banner ("Chrome is being controlled by automated software"), Extension presence detection
660
+ - **Warning**: These patches do not pass Cloudflare. JS Challenge and Turnstile checkbox handling is a separate wait in
661
+ the real browser after navigation, input, or evaluate. It does not cover Akamai, DataDome, PerimeterX, interactive
662
+ CAPTCHAs, or IP reputation
625
663
 
626
664
  ## Known Limitations
627
665
 
@@ -639,9 +677,26 @@ MIT License - see [LICENSE](LICENSE) for details.
639
677
  - [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
640
678
  - [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP documentation
641
679
 
642
-
643
680
  ## Operation status and diagnostics
644
681
 
645
- Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and `retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with `actionStatus="failed"`; result materialization or serialization errors report `actionStatus="completed"` and `failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action result. Browse and wait errors also retain any diagnostics collected before the action failed. Target diagnostics query the current tab state instead of relying on cached attach metadata.
646
-
647
- `replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other input types use a native full-value update and return the requested and actual browser-normalized values. A standalone `select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text` values. Target timeouts include bounded locator, tab, frame, match, and candidate context. Explicit `tabId` and `frame` scopes resolve the active backend before input, wait, logs, or extract work begins, so actions and verification use the same target backend. Precise iframe evaluation defaults to `staleContextRetry="never"` and does not replay stale scripts. `readOnly` permits one replay after the Extension verifies the frame identity and resolves a new execution context. Responses include the policy, `retryAttempted`, bounded `retryReason`, and the final `frameContext` with the Extension frame, parent frame, URL, CDP frame, and execution context IDs. Ambiguous same-URL frames are rejected. Port scanning aggregates ordinary pre-open failures at debug level; authentication and protocol rejections from identified MCP servers produce one bounded warning when the rejection summary changes.
682
+ Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and
683
+ `retryable`. Verification uses `matched`, `not_matched`, `unavailable`, or `error`; debugger timeouts report the action
684
+ as `unknown` when completion cannot be proven. Page-thrown exceptions report `actionExecuted=true` with
685
+ `actionStatus="failed"`; result materialization or serialization errors report `actionStatus="completed"` and
686
+ `failureStage="output"`. Diagnostics are best-effort and return `diagnosticsStatus` without replacing the main action
687
+ result. Browse and wait errors also retain any diagnostics collected before the action failed. Target diagnostics query
688
+ the current tab state instead of relying on cached attach metadata.
689
+
690
+ `replace` uses text selection only for `textarea` and input types `text`, `search`, `tel`, `url`, and `password`. Other
691
+ input types use a native full-value update and return the requested and actual browser-normalized values. A standalone
692
+ `select` on unsupported types returns `UNSUPPORTED_SELECTION`. CDP locator targets for `select` and `replace` are
693
+ focused through the CDP locator instead of Extension-only ref IDs. Password values are omitted from input failure
694
+ context and text post-condition observations; failed input responses also redact supplied `find` and replacement `text`
695
+ values. Target timeouts include bounded locator, tab, frame, match, and candidate context. Explicit `tabId` and `frame`
696
+ scopes resolve the active backend before input, wait, logs, or extract work begins, so actions and verification use the
697
+ same target backend. Precise iframe evaluation defaults to `staleContextRetry="never"` and does not replay stale
698
+ scripts. `readOnly` permits one replay after the Extension verifies the frame identity and resolves a new execution
699
+ context. Responses include the policy, `retryAttempted`, bounded `retryReason`, and the final `frameContext` with the
700
+ Extension frame, parent frame, URL, CDP frame, and execution context IDs. Ambiguous same-URL frames are rejected. Port
701
+ scanning aggregates ordinary pre-open failures at debug level; authentication and protocol rejections from identified
702
+ MCP servers produce one bounded warning when the rejection summary changes.