Skip to content

Chrome DevTools for coding agents

docs: fix inaccurate examples in skills and CLI docs (#2922)

yulunzec372b0552b5
diff --git a/docs/cli.md b/docs/cli.md
index af7a664c..46d9b6c5 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -111,10 +111,13 @@ If the CLI hangs or fails to connect, try stopping the background process:
chrome-devtools stop
```
-For more verbose logs, set the `DEBUG` environment variable:
+For more verbose logs, set the `NODE_DEBUG` environment variable. The background
+process does not write to the terminal, so restart it with `--logFile` to
+capture its logs in a file:
```sh
-DEBUG=* chrome-devtools list_pages
+NODE_DEBUG=* chrome-devtools start --logFile=/tmp/chrome-devtools.log
+chrome-devtools list_pages
```
## CLI generation
diff --git a/skills/chrome-devtools-cli/SKILL.md b/skills/chrome-devtools-cli/SKILL.md
index f348b186..5a4348aa 100644
--- a/skills/chrome-devtools-cli/SKILL.md
+++ b/skills/chrome-devtools-cli/SKILL.md
@@ -79,7 +79,7 @@ chrome-devtools select_page 1 --bringToFront true # Select a page and bring it t
```bash
chrome-devtools emulate 1 --networkConditions "Offline" # Emulate network conditions
-chrome-devtools emulate 1 --cpuThrottlingRate 4 --geolocation "0x0" # Emulate CPU throttling and geolocation
+chrome-devtools emulate 1 --cpuThrottlingRate 4 --geolocation "0,0" # Emulate CPU throttling and geolocation
chrome-devtools emulate 1 --colorScheme "dark" --viewport "1920x1080" # Emulate color scheme and viewport
chrome-devtools emulate 1 --userAgent "Mozilla/5.0..." # Emulate user agent
chrome-devtools resize_page 1 1920 1080 # Resizes the selected page's window
@@ -106,8 +106,8 @@ chrome-devtools take_heapsnapshot 1 "./snap.heapsnapshot" # Capture a memory hea
```bash
chrome-devtools get_heapsnapshot_summary "./snap.heapsnapshot" # Get snapshot summary stats
chrome-devtools compare_heapsnapshots "./base.heapsnapshot" "./target.heapsnapshot" # Compare two snapshots
-chrome-devtools get_heapsnapshot_class_nodes "./snap.heapsnapshot" "Array" # Inspect class instances
-chrome-devtools get_heapsnapshot_details "./snap.heapsnapshot" 123 # Detailed object properties
+chrome-devtools get_heapsnapshot_details "./snap.heapsnapshot" # Snapshot statistics and per-class aggregates (with class IDs)
+chrome-devtools get_heapsnapshot_class_nodes "./snap.heapsnapshot" 18 # Inspect instances of a class (class ID from get_heapsnapshot_details)
chrome-devtools get_heapsnapshot_dominators "./snap.heapsnapshot" 123 # Dominator tree for node
chrome-devtools get_heapsnapshot_duplicate_strings "./snap.heapsnapshot" # Find duplicated strings
chrome-devtools get_heapsnapshot_edges "./snap.heapsnapshot" 123 # Node edges/references
@@ -165,7 +165,7 @@ chrome-devtools trigger_extension_action "extension_id" # Triggers the default a
## Progressive Web Apps (requires `--categoryPwa=true`)
```bash
-chrome-devtools install_pwa "https://example.com/" # Install PWA by manifest ID or URL
+chrome-devtools install_pwa "https://example.com/" "https://example.com/" # Install PWA by manifest ID and install URL
chrome-devtools launch_pwa "https://example.com/" # Launch installed PWA
chrome-devtools get_os_app_state "https://example.com/" # Get OS app installation state
chrome-devtools uninstall_pwa "https://example.com/" # Uninstall PWA and close windows
diff --git a/skills/cookie-debugging/SKILL.md b/skills/cookie-debugging/SKILL.md
index 85929b96..806bd704 100644
--- a/skills/cookie-debugging/SKILL.md
+++ b/skills/cookie-debugging/SKILL.md
@@ -5,6 +5,8 @@ description: Uses Chrome DevTools MCP for inspecting, debugging, and testing coo
## Core Concepts
+**Page Targeting**: Page-scoped tools (`list_network_requests`, `get_network_request`, `list_console_messages`, `evaluate_script`, `navigate_page`, `take_snapshot`, `click`, `lighthouse_audit`, `close_page`, etc.) require a `pageId` parameter. Retrieve available page IDs using `list_pages` or from `new_page`.
+
### HttpOnly vs Client-Side Storage
Cookies marked `HttpOnly` cannot be accessed or modified by client-side JavaScript (`cookieStore` or `document.cookie`). However, the browser **automatically attaches active HttpOnly cookies to outgoing HTTP request headers (`Cookie`)**.
@@ -19,7 +21,7 @@ Choose the right session environment to avoid state contamination (e.g., residua
| Strategy | When to Use | Setup / Teardown |
| :---------------------------------- | :---------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
-| **Live Tab (Active Page)** | Diagnosing an active user session, live 401/403 error, or current state. | Operates directly on the currently selected page. |
+| **Live Tab (Active Page)** | Diagnosing an active user session, live 401/403 error, or current state. | Operates on the user's existing page; get its `pageId` from `list_pages`. |
| **Clean-Slate (`isolatedContext`)** | Testing cookie consent banners, first-time visits, or zero-cookie guarantees. | Call `new_page` with a unique `isolatedContext` (e.g. `"consent-audit-1"`). When finished, call `close_page`. |
### Client-Side Capabilities & Limitations
@@ -49,7 +51,7 @@ When an authenticated page request fails, returns 401/403, or redirects to login
- Verify if the `Cookie` header was attached and whether required tokens (e.g. `SESSION_ID`, `auth_token`) were sent.
4. **Trigger Active Inspection (If no recent request exists)**:
- If the cookie was set in a previous session and no network call is listed, trigger a request:
- - Use `navigate_page` with `reload: true`, OR
+ - Use `navigate_page` with `type: "reload"`, OR
- Call `evaluate_script` with `() => fetch(window.location.href)`
- Then call `get_network_request` on the new request to inspect the active `Cookie` header.
5. **Trace the Setting Request**: If the cookie is missing or rejected:
@@ -91,6 +93,7 @@ To verify that no non-essential or tracking cookies are set before consent or wh
- Call `list_console_messages` with:
```json
{
+ "pageId": 1,
"types": ["issue"],
"includePreservedMessages": true
}
diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md
index bf5b98c3..8b84bd7a 100644
--- a/skills/troubleshooting/SKILL.md
+++ b/skills/troubleshooting/SKILL.md
@@ -41,9 +41,9 @@ If the server starts successfully but `list_pages` returns an empty list or crea
- **Check for flag typos:** For example, `--autoBronnect` instead of `--autoConnect`.
- **Verify the configuration:** Ensure the arguments match the expected flags exactly.
-#### Symptom: Missing Tools / Only 9 tools available
+#### Symptom: Missing Tools / Only a few tools available
-If the server starts successfully but only a limited subset of tools (like `list_pages`, `get_console_message`, `lighthouse_audit`, `take_heapsnapshot`) are available, this is likely because the MCP client is enforcing a **read-only mode**.
+If the server starts successfully but only a limited subset of tools (like `list_pages`, `list_console_messages`, `get_console_message`, `list_network_requests`) are available, this is likely because the MCP client is enforcing a **read-only mode**.
All tools in `chrome-devtools-mcp` are annotated with `readOnlyHint: true` (for safe, non-modifying tools) or `readOnlyHint: false` (for tools that modify browser state, like `emulate`, `click`, `navigate_page`). To access the full suite of tools, the user must disable read-only mode in their MCP client (e.g., by exiting "Plan Mode" in Gemini CLI or adjusting their client's tool safety settings).
@@ -59,7 +59,7 @@ If the tools related to extensions (like `install_extension`) are not available,
Identify other error messages from the failed tool call or the MCP initialization logs:
- `Target closed`
-- "Tool not found" (check if they are using `--slim` which only enables navigation and screenshot tools).
+- "Tool not found" (check if they are using `--slim` which only enables navigation, script evaluation and screenshot tools).
- Missing `pageId`: Page-scoped tools require a `pageId` argument. Call `list_pages` to find active page IDs.
- `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly`
- `Error [ERR_MODULE_NOT_FOUND]: Cannot find module`
@@ -89,7 +89,7 @@ _If you are unsure of the user's configuration, ask the user to provide their cu
If the issue is still unclear, run diagnostic commands to test the server directly:
- Run `npx chrome-devtools-mcp@latest --help` to verify the installation and Node.js environment.
-- If you need more information, run `DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs. Analyze the output for errors.
+- If you need more information, run `NODE_DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs. Analyze the output for errors.
### Step 6: Check GitHub for Existing Issues