@pyrokine/mcp-chrome 2.4.0 → 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.
- package/README.md +220 -149
- package/README_zh.md +245 -179
- package/dist/anti-detection/behavior.js +1 -1
- package/dist/anti-detection/behavior.js.map +1 -1
- package/dist/anti-detection/injection.d.ts.map +1 -1
- package/dist/anti-detection/injection.js +2 -1
- package/dist/anti-detection/injection.js.map +1 -1
- package/dist/cdp/client.d.ts +2 -2
- package/dist/cdp/client.d.ts.map +1 -1
- package/dist/cdp/client.js +7 -4
- package/dist/cdp/client.js.map +1 -1
- package/dist/core/browser-driver.d.ts +9 -3
- package/dist/core/browser-driver.d.ts.map +1 -1
- package/dist/core/browser-driver.js +1 -0
- package/dist/core/browser-driver.js.map +1 -1
- package/dist/core/errors.d.ts +9 -0
- package/dist/core/errors.d.ts.map +1 -1
- package/dist/core/errors.js +16 -1
- package/dist/core/errors.js.map +1 -1
- package/dist/core/os-mouse.d.ts +65 -0
- package/dist/core/os-mouse.d.ts.map +1 -0
- package/dist/core/os-mouse.js +334 -0
- package/dist/core/os-mouse.js.map +1 -0
- package/dist/core/session.d.ts +16 -6
- package/dist/core/session.d.ts.map +1 -1
- package/dist/core/session.js +160 -55
- package/dist/core/session.js.map +1 -1
- package/dist/core/types.d.ts +10 -0
- package/dist/core/types.d.ts.map +1 -1
- package/dist/core/types.js +2 -0
- package/dist/core/types.js.map +1 -1
- package/dist/core/unified-session.d.ts +34 -5
- package/dist/core/unified-session.d.ts.map +1 -1
- package/dist/core/unified-session.js +172 -30
- package/dist/core/unified-session.js.map +1 -1
- package/dist/extension/bridge.d.ts +24 -2
- package/dist/extension/bridge.d.ts.map +1 -1
- package/dist/extension/bridge.js +32 -1
- package/dist/extension/bridge.js.map +1 -1
- package/dist/extension/http-server.d.ts +17 -0
- package/dist/extension/http-server.d.ts.map +1 -1
- package/dist/extension/http-server.js +69 -9
- package/dist/extension/http-server.js.map +1 -1
- package/dist/extension/index.d.ts +1 -0
- package/dist/extension/index.d.ts.map +1 -1
- package/dist/extension/index.js.map +1 -1
- package/dist/tools/browse.d.ts +1 -1
- package/dist/tools/browse.d.ts.map +1 -1
- package/dist/tools/browse.js +73 -26
- package/dist/tools/browse.js.map +1 -1
- package/dist/tools/challenge.d.ts +153 -0
- package/dist/tools/challenge.d.ts.map +1 -0
- package/dist/tools/challenge.js +573 -0
- package/dist/tools/challenge.js.map +1 -0
- package/dist/tools/cookies.d.ts.map +1 -1
- package/dist/tools/cookies.js +8 -4
- package/dist/tools/cookies.js.map +1 -1
- package/dist/tools/diagnostics.d.ts +2 -2
- package/dist/tools/diagnostics.d.ts.map +1 -1
- package/dist/tools/diagnostics.js +28 -9
- package/dist/tools/diagnostics.js.map +1 -1
- package/dist/tools/evaluate.d.ts +8 -0
- package/dist/tools/evaluate.d.ts.map +1 -1
- package/dist/tools/evaluate.js +92 -14
- package/dist/tools/evaluate.js.map +1 -1
- package/dist/tools/extract.d.ts.map +1 -1
- package/dist/tools/extract.js +119 -59
- package/dist/tools/extract.js.map +1 -1
- package/dist/tools/input.d.ts +4 -0
- package/dist/tools/input.d.ts.map +1 -1
- package/dist/tools/input.js +248 -94
- package/dist/tools/input.js.map +1 -1
- package/dist/tools/logs.d.ts +7 -4
- package/dist/tools/logs.d.ts.map +1 -1
- package/dist/tools/logs.js +11 -8
- package/dist/tools/logs.js.map +1 -1
- package/dist/tools/manage.d.ts.map +1 -1
- package/dist/tools/manage.js +20 -7
- package/dist/tools/manage.js.map +1 -1
- package/dist/tools/network-sanitizer.d.ts +15 -0
- package/dist/tools/network-sanitizer.d.ts.map +1 -0
- package/dist/tools/network-sanitizer.js +62 -0
- package/dist/tools/network-sanitizer.js.map +1 -0
- package/dist/tools/png.js +5 -3
- package/dist/tools/png.js.map +1 -1
- package/dist/tools/post-condition.d.ts.map +1 -1
- package/dist/tools/post-condition.js +17 -4
- package/dist/tools/post-condition.js.map +1 -1
- package/dist/tools/target-diagnostics.d.ts +7 -0
- package/dist/tools/target-diagnostics.d.ts.map +1 -1
- package/dist/tools/target-diagnostics.js +25 -2
- package/dist/tools/target-diagnostics.js.map +1 -1
- package/dist/tools/wait.d.ts.map +1 -1
- package/dist/tools/wait.js +42 -40
- package/dist/tools/wait.js.map +1 -1
- package/extension/dist/assets/content.ts-Cj_iiU2s.js +25 -0
- package/extension/dist/assets/{index.ts-BMmrcSQ6.js → index.ts-Bqcu2qiN.js} +620 -290
- package/extension/dist/manifest.json +3 -3
- package/extension/dist/service-worker-loader.js +1 -1
- package/extension/dist/src/popup/popup.html +44 -44
- package/package.json +8 -7
- package/dist/extension/native-host-installer.d.ts +0 -21
- package/dist/extension/native-host-installer.d.ts.map +0 -1
- package/dist/extension/native-host-installer.js +0 -147
- package/dist/extension/native-host-installer.js.map +0 -1
- package/dist/extension/socket-server.d.ts +0 -32
- package/dist/extension/socket-server.d.ts.map +0 -1
- package/dist/extension/socket-server.js +0 -177
- package/dist/extension/socket-server.js.map +0 -1
- package/dist/extension/ws-server.d.ts +0 -40
- package/dist/extension/ws-server.d.ts.map +0 -1
- package/dist/extension/ws-server.js +0 -246
- package/dist/extension/ws-server.js.map +0 -1
- package/dist/native-host/index.js +0 -280
- package/dist/native-host/mcp-chrome-host +0 -2
- package/extension/dist/assets/content.ts-pEASbjEL.js +0 -6
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,
|
|
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
|
|
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,21 +90,23 @@ Claude Desktop / Other Clients:
|
|
|
89
90
|
|
|
90
91
|
```json
|
|
91
92
|
{
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
|
|
103
102
|
**Step 3: Connect**
|
|
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
|
-
connection status.
|
|
105
|
+
connection status. `browse(action="connect")` and the local `/api/info` endpoint report the active Extension background
|
|
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.
|
|
107
110
|
|
|
108
111
|
```
|
|
109
112
|
browse(action="list") // List all tabs
|
|
@@ -114,15 +117,15 @@ extract(type="screenshot")
|
|
|
114
117
|
**Pairing token**
|
|
115
118
|
|
|
116
119
|
Extension mode keeps zero-config local auto-connect by default. On shared machines, CI runners, or containers where
|
|
117
|
-
untrusted local processes can reach `127.0.0.1:19222-19299`, set `MCP_CHROME_PAIRING_TOKEN` on the MCP server and enter
|
|
118
|
-
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:
|
|
119
122
|
|
|
120
123
|
```bash
|
|
121
124
|
MCP_CHROME_PAIRING_TOKEN="your-token" node /path/to/mcp-chrome/dist/index.js
|
|
122
125
|
```
|
|
123
126
|
|
|
124
|
-
To require a pairing token instead of zero-config local use, set `MCP_CHROME_ALLOW_INSECURE_NO_TOKEN=0` on the server
|
|
125
|
-
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.
|
|
126
129
|
|
|
127
130
|
### Mode 2: CDP Mode (Fallback)
|
|
128
131
|
|
|
@@ -139,81 +142,126 @@ browse(action="connect", port=9222)
|
|
|
139
142
|
browse(action="open", url="https://example.com")
|
|
140
143
|
```
|
|
141
144
|
|
|
142
|
-
>
|
|
143
|
-
>
|
|
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.
|
|
144
149
|
|
|
145
150
|
## Available Tools (8 Tools)
|
|
146
151
|
|
|
147
152
|
### browse - Browser Management & Navigation
|
|
148
153
|
|
|
149
|
-
| Action | Description
|
|
150
|
-
|
|
151
|
-
| `launch` |
|
|
152
|
-
| `connect` |
|
|
153
|
-
| `list` | List all pages/tabs
|
|
154
|
-
| `attach` | Attach to a specific page/tab
|
|
155
|
-
| `open` | Navigate to URL
|
|
156
|
-
| `back` | Go back in history
|
|
157
|
-
| `forward` | Go forward in history
|
|
158
|
-
| `refresh` | Reload page
|
|
159
|
-
| `close` | Close
|
|
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` |
|
|
160
165
|
|
|
161
166
|
Extension-specific: `list` returns the flat `targets` array plus a `windows` tree. Each target includes `managed`
|
|
162
167
|
(whether tab is controlled by MCP Chrome), `isActive` (whether it's the current operation target), `windowId`, `index`,
|
|
163
168
|
`pinned`, `incognito`, and `status` (`loading`/`complete`). The tree includes `windowCount`, `focusedWindowId`,
|
|
164
169
|
`activeTargetId`, and each window's ordered `tabs` list, so callers can distinguish the active tab inside each window
|
|
165
|
-
from the page currently visible in the focused window.
|
|
166
|
-
`
|
|
167
|
-
|
|
168
|
-
|
|
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.
|
|
169
212
|
|
|
170
213
|
### input - Keyboard & Mouse Input
|
|
171
214
|
|
|
172
215
|
Event sequence model supporting arbitrary combinations:
|
|
173
216
|
|
|
174
|
-
| Event Type | Description
|
|
175
|
-
|
|
176
|
-
| `keydown` / `keyup` | Key press/release
|
|
177
|
-
| `click` | Click
|
|
178
|
-
| `mousedown` / `mouseup` | Mouse button press/release
|
|
179
|
-
| `mousemove` | Mouse movement
|
|
180
|
-
| `wheel` | Mouse wheel scroll
|
|
181
|
-
| `touchstart` / `touchmove` / `touchend` | Touch events
|
|
182
|
-
| `type` | Type text (with optional `delay`, `dispatch` for React/Vue)
|
|
183
|
-
| `wait` | Pause between events
|
|
184
|
-
| `select` | Select text by content (mouse sim)
|
|
185
|
-
| `replace` | Find and replace text
|
|
186
|
-
| `drag` | HTML5 drag-and-drop (
|
|
187
|
-
| `editorContext` | Read focused editor and selection context
|
|
188
|
-
| `editorInsert` | Insert text at the current editor selection
|
|
189
|
-
| `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` |
|
|
190
233
|
|
|
191
234
|
Special-case parameters:
|
|
192
235
|
|
|
193
236
|
- `keydown` accepts `commands` (e.g. `["selectAll"]`, `["copy"]`, `["paste"]`, `["cut"]`, `["undo"]`, `["redo"]`) to
|
|
194
|
-
trigger native browser editing commands.
|
|
195
|
-
|
|
237
|
+
trigger native browser editing commands. A successful response means the browser accepted the command dispatch; use
|
|
238
|
+
`postCondition` or `extract` to verify the page result. `commands` is precise-mode only; stealth mode throws because
|
|
239
|
+
the CDP commands API has no JS-event equivalent.
|
|
196
240
|
- `keydown` on a key already held emits `rawKeyDown` with `autoRepeat: true` (Puppeteer-compatible long-press).
|
|
197
241
|
|
|
198
|
-
Parameters: `humanize` enables Bézier curve movement and random delays.
|
|
199
|
-
warnings/errors and failed network requests after the action. `postCondition`
|
|
200
|
-
callers can distinguish dispatched input from completed page behavior.
|
|
201
|
-
is capped at 60000 ms; `postCondition.interval` defaults to 100 ms and
|
|
202
|
-
tab. `frame` targets an iframe (CSS selector or index). Both
|
|
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.
|
|
203
249
|
|
|
204
250
|
**`click`-specific**: `force: true` skips actionability checks (useful for testing or hidden elements). Actionability
|
|
205
251
|
failures return `ACTIONABILITY_FAILED` with `rect`, `clickPoint`, covering element details, candidate blockers, and
|
|
206
|
-
suggestions.
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
text occurrence while nested `target.nth` selects the Nth matching
|
|
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.
|
|
212
260
|
|
|
213
261
|
### extract - Content Extraction
|
|
214
262
|
|
|
215
263
|
| Type | Description |
|
|
216
|
-
|
|
264
|
+
| ------------ | ------------------------------------------------- |
|
|
217
265
|
| `text` | Extract text content |
|
|
218
266
|
| `html` | Extract HTML source |
|
|
219
267
|
| `frameHtml` | Extract HTML from the selected iframe |
|
|
@@ -225,10 +273,12 @@ text occurrence while nested `target.nth` selects the Nth matching element; both
|
|
|
225
273
|
Parameters: `output` saves result to file (or directory for `images=data`). `images` (`info`/`data`) extracts image
|
|
226
274
|
metadata or data alongside HTML. `frameHtml` extracts the current iframe document after `frame` routing. Screenshot
|
|
227
275
|
accepts `clip` for coordinate-region capture, `compareWith` for PNG baseline comparison, and `diffOutput` for a PNG diff
|
|
228
|
-
image.
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
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
|
|
232
282
|
`limitations`; unsupported fallback options return structured `SCREENSHOT_FALLBACK_UNSUPPORTED` errors. `state` returns
|
|
233
283
|
`interactiveElements`; `metadata` returns `frames` in both Extension and CDP modes. `tabId` targets a specific tab.
|
|
234
284
|
`frame` targets an iframe. Both Extension mode only.
|
|
@@ -244,34 +294,35 @@ browser. If another debugger blocks the precise screenshot path, viewport fallba
|
|
|
244
294
|
### wait - Wait for Conditions
|
|
245
295
|
|
|
246
296
|
| For | Description |
|
|
247
|
-
|
|
297
|
+
| ------------ | --------------------------------------------------- |
|
|
248
298
|
| `element` | Wait for element (visible/hidden/attached/detached) |
|
|
249
299
|
| `navigation` | Wait for navigation complete |
|
|
250
300
|
| `time` | Fixed delay |
|
|
251
|
-
| `idle` | Wait for
|
|
301
|
+
| `idle` | Wait for DOM or network quiet period |
|
|
252
302
|
|
|
253
303
|
Parameters: `tabId` targets a specific tab. `frame` targets an iframe. Both Extension mode only.
|
|
254
304
|
|
|
255
|
-
**`idle`-specific**:
|
|
256
|
-
no DOM changes.
|
|
257
|
-
|
|
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`.
|
|
258
308
|
|
|
259
309
|
### evaluate - JavaScript Execution
|
|
260
310
|
|
|
261
311
|
Execute JavaScript in page context.
|
|
262
312
|
|
|
263
|
-
| Parameter
|
|
264
|
-
|
|
265
|
-
| `script`
|
|
266
|
-
| `scriptFile`
|
|
267
|
-
| `args`
|
|
268
|
-
| `mode`
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
271
|
-
| `
|
|
272
|
-
| `
|
|
273
|
-
| `
|
|
274
|
-
| `
|
|
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 |
|
|
275
326
|
|
|
276
327
|
`script` and `scriptFile` are mutually exclusive; at least one must be provided. Relative `scriptFile` and `output`
|
|
277
328
|
paths default to the OS temp directory managed by `mcp-chrome`. Use `cwd:relative/path` when the file must live in the
|
|
@@ -280,15 +331,21 @@ streams.
|
|
|
280
331
|
|
|
281
332
|
Results >100KB are auto-saved to the controlled OS temp directory with a structured hint returned. DOM nodes,
|
|
282
333
|
`NodeList`, and `HTMLCollection` results return `NON_SERIALIZABLE_EVALUATE_RESULT` with a hint to return simple fields
|
|
283
|
-
such as `textContent` or `outerHTML`.
|
|
284
|
-
`
|
|
285
|
-
`
|
|
286
|
-
|
|
334
|
+
such as `textContent` or `outerHTML`. Result materialization and serialization failures report `actionExecuted=true`,
|
|
335
|
+
`actionStatus="completed"`, and `failureStage="output"` because the page script has already finished. Evaluate defaults
|
|
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.
|
|
287
344
|
|
|
288
345
|
### manage - Page & Environment Management
|
|
289
346
|
|
|
290
347
|
| Action | Description |
|
|
291
|
-
|
|
348
|
+
| -------------- | ---------------------------------------------------------- |
|
|
292
349
|
| `newPage` | Create new controlled page/tab |
|
|
293
350
|
| `closePage` | Close controlled page and return `affected.before/after` |
|
|
294
351
|
| `adoptPage` | Mark an existing tab as controlled without focusing it |
|
|
@@ -311,9 +368,11 @@ tool returns `POST_CONDITION_FAILED` with the last observed checks.
|
|
|
311
368
|
| `cdp` | Send raw CDP command (advanced, e.g. `Runtime.evaluate`) |
|
|
312
369
|
|
|
313
370
|
Tab/window management actions are Extension-mode only. Actions that change visible browser state require explicit
|
|
314
|
-
`targetId` or `windowId` and return `affected.before/after`. `
|
|
315
|
-
|
|
316
|
-
|
|
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`.
|
|
317
376
|
|
|
318
377
|
**Stealth mode levels** (CDP launch parameter, set via `browse action=launch stealth=...`):
|
|
319
378
|
|
|
@@ -324,28 +383,31 @@ unmanaged tabs and returns `WINDOW_HAS_UNMANAGED_TABS`.
|
|
|
324
383
|
### logs - Browser Logs
|
|
325
384
|
|
|
326
385
|
| Type | Description |
|
|
327
|
-
|
|
386
|
+
| --------- | -------------------------------------- |
|
|
328
387
|
| `console` | Console logs (with level filter) |
|
|
329
388
|
| `network` | Network request logs (with URL filter) |
|
|
330
389
|
|
|
331
|
-
Parameters: `output` saves result to file. Console entries use the public levels `error`, `warning`, `info`, and
|
|
332
|
-
raw browser levels such as `warn` and `log` are normalized before filtering and return. Network logs include
|
|
333
|
-
requests, HTTP 4xx/5xx responses, and failed loads with `errorText`, `method`, `url`, `status`, `timestamp`,
|
|
334
|
-
when available.
|
|
335
|
-
|
|
336
|
-
|
|
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.
|
|
337
399
|
|
|
338
400
|
### cookies - Cookie Management
|
|
339
401
|
|
|
340
|
-
| Action | Description
|
|
341
|
-
|
|
342
|
-
| `get` | Get cookies
|
|
343
|
-
| `set` | Set cookie
|
|
344
|
-
| `delete` | Delete cookie
|
|
345
|
-
| `clear` | Delete cookies
|
|
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` |
|
|
346
408
|
|
|
347
|
-
**Note**: `clear` requires
|
|
348
|
-
|
|
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.
|
|
349
411
|
|
|
350
412
|
## Target: Unified Element Locator
|
|
351
413
|
|
|
@@ -353,57 +415,43 @@ All tools use a unified `Target` type for element location:
|
|
|
353
415
|
|
|
354
416
|
```typescript
|
|
355
417
|
// By accessibility (recommended - most stable)
|
|
356
|
-
{ role:
|
|
418
|
+
const byRole = { role: 'button', name: 'Submit' }
|
|
357
419
|
|
|
358
420
|
// By accessibility with exact accessible name
|
|
359
|
-
{ role:
|
|
421
|
+
const byExactRole = { role: 'button', name: 'Submit', exact: true }
|
|
360
422
|
|
|
361
423
|
// By text content
|
|
362
|
-
{ text:
|
|
424
|
+
const byText = { text: 'Click here', exact: true }
|
|
363
425
|
|
|
364
426
|
// By form label
|
|
365
|
-
{
|
|
366
|
-
label: "Email"
|
|
367
|
-
}
|
|
427
|
+
const byLabel = { label: 'Email' }
|
|
368
428
|
|
|
369
429
|
// By placeholder
|
|
370
|
-
{
|
|
371
|
-
placeholder: "Enter your name"
|
|
372
|
-
}
|
|
430
|
+
const byPlaceholder = { placeholder: 'Enter your name' }
|
|
373
431
|
|
|
374
432
|
// By title attribute
|
|
375
|
-
{
|
|
376
|
-
title: "Close dialog"
|
|
377
|
-
}
|
|
433
|
+
const byTitle = { title: 'Close dialog' }
|
|
378
434
|
|
|
379
435
|
// By alt text (images)
|
|
380
|
-
{
|
|
381
|
-
alt: "Profile picture"
|
|
382
|
-
}
|
|
436
|
+
const byAlt = { alt: 'Profile picture' }
|
|
383
437
|
|
|
384
438
|
// By test ID
|
|
385
|
-
{
|
|
386
|
-
testId: "submit-button"
|
|
387
|
-
}
|
|
439
|
+
const byTestId = { testId: 'submit-button' }
|
|
388
440
|
|
|
389
441
|
// By CSS selector
|
|
390
|
-
{
|
|
391
|
-
css: "#login-form .submit-btn"
|
|
392
|
-
}
|
|
442
|
+
const byCss = { css: '#login-form .submit-btn' }
|
|
393
443
|
|
|
394
444
|
// Disambiguate multiple matches (0-based)
|
|
395
|
-
{ css:
|
|
445
|
+
const secondMatch = { css: '.ant-select-input', nth: 1 }
|
|
396
446
|
|
|
397
447
|
// By CSS + text (filter by text content)
|
|
398
|
-
{ css:
|
|
448
|
+
const byCssText = { css: 'button', text: 'Submit', exact: true }
|
|
399
449
|
|
|
400
450
|
// By XPath
|
|
401
|
-
{
|
|
402
|
-
xpath: "//button[@type='submit']"
|
|
403
|
-
}
|
|
451
|
+
const byXPath = { xpath: "//button[@type='submit']" }
|
|
404
452
|
|
|
405
453
|
// By coordinates
|
|
406
|
-
{ x: 100, y: 200 }
|
|
454
|
+
const byCoordinates = { x: 100, y: 200 }
|
|
407
455
|
```
|
|
408
456
|
|
|
409
457
|
## Usage Examples
|
|
@@ -497,6 +545,10 @@ input(events=[
|
|
|
497
545
|
], frame="iframe.login-frame")
|
|
498
546
|
```
|
|
499
547
|
|
|
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.
|
|
551
|
+
|
|
500
552
|
### Wait for Element
|
|
501
553
|
|
|
502
554
|
```
|
|
@@ -585,8 +637,8 @@ mcp-chrome/
|
|
|
585
637
|
|
|
586
638
|
## Security Notes
|
|
587
639
|
|
|
588
|
-
- **Trust boundary**: Extension mode auto-connects to local MCP servers by default. Use `MCP_CHROME_PAIRING_TOKEN`, or
|
|
589
|
-
`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
|
|
590
642
|
untrusted code can reach `127.0.0.1:19222-19299`. WebSocket upgrades require a `chrome-extension://` Origin header,
|
|
591
643
|
which blocks browser pages and curl, but does not stop a malicious local process running as the same user.
|
|
592
644
|
- Extension mode: shares your browser sessions — only use on trusted machines
|
|
@@ -594,7 +646,8 @@ mcp-chrome/
|
|
|
594
646
|
- Default ports bind to 127.0.0.1 only (localhost)
|
|
595
647
|
- The `evaluate` tool can execute arbitrary JavaScript
|
|
596
648
|
- The `manage cdp` action can send arbitrary CDP commands
|
|
597
|
-
- Network
|
|
649
|
+
- Network URL credential parameters are redacted by default, but console text and nonstandard parameter names may still
|
|
650
|
+
contain sensitive information
|
|
598
651
|
|
|
599
652
|
### Anti-detection (stealth) — what it actually does
|
|
600
653
|
|
|
@@ -602,10 +655,11 @@ The `stealth` mode (`safe` / `aggressive`) only patches a small set of fingerpri
|
|
|
602
655
|
|
|
603
656
|
- **Covers**: `navigator.webdriver`, `cdc_*` properties, User-Agent string, a few WebGL vendor/renderer values, Chrome
|
|
604
657
|
runtime properties
|
|
605
|
-
- **Does NOT cover**: Canvas fingerprinting, AudioContext fingerprinting, Font enumeration, TLS-level fingerprints
|
|
606
|
-
JA3/JA4), CDP attach banner ("Chrome is being controlled by automated software"), Extension presence detection
|
|
607
|
-
- **Warning**:
|
|
608
|
-
|
|
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
|
|
609
663
|
|
|
610
664
|
## Known Limitations
|
|
611
665
|
|
|
@@ -623,9 +677,26 @@ MIT License - see [LICENSE](LICENSE) for details.
|
|
|
623
677
|
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
|
|
624
678
|
- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) - CDP documentation
|
|
625
679
|
|
|
626
|
-
|
|
627
680
|
## Operation status and diagnostics
|
|
628
681
|
|
|
629
|
-
Input and evaluate responses append `actionExecuted`, `actionStatus`, `verificationStatus`, `failureStage`, and
|
|
630
|
-
|
|
631
|
-
|
|
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.
|