Merge branch 'main' into fix/940-improve-mcp-invocation

Author: OrKoN

.github/workflows/run-tests.yml

@@ -41,12 +41,6 @@ jobs:
         shell: bash
         run: npm ci
 
-      - name: Install Chrome Canary
-        shell: bash
-        run: |
-          CANARY_PATH=$(npx @puppeteer/browsers install chrome@canary --format "{{path}}")
-          echo "CANARY_EXECUTABLE_PATH=$CANARY_PATH" >> $GITHUB_ENV
-
       - name: Build
         run: npm run bundle
         env:

README.md

@@ -73,7 +73,7 @@ Add the following config to your MCP client:
 > [!NOTE]  
 > Using `chrome-devtools-mcp@latest` ensures that your MCP client will always use the latest version of the Chrome DevTools MCP server.
 
-If you are intersted in doing only basic browser tasks, use the `--slim` mode:
+If you are interested in doing only basic browser tasks, use the `--slim` mode:
 
 ```json
 {
@@ -459,7 +459,7 @@ The Chrome DevTools MCP server supports the following configuration option:
 <!-- BEGIN AUTO GENERATED OPTIONS -->
 
 - **`--autoConnect`/ `--auto-connect`**
-  If specified, automatically connects to a browser (Chrome 144+) running in the user data directory identified by the channel param. Requires the remoted debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.
+  If specified, automatically connects to a browser (Chrome 144+) running locally from the user data directory identified by the channel param (default channel is stable). Requires the remoted debugging server to be started in the Chrome instance via chrome://inspect/#remote-debugging.
   - **Type:** boolean
   - **Default:** `false`
 

docs/cli.md

@@ -0,0 +1,93 @@
+# Chrome DevTools CLI
+
+The `chrome-devtools-mcp` package includes a CLI interface that allows you to interact with the browser directly from your terminal. This is particularly useful for debugging or when you want an agent to generate scripts that automate browser actions.
+
+## Getting started
+
+Install the package globally to make the `chrome-devtools` command available:
+
+```sh
+npm i chrome-devtools-mcp@latest -g
+chrome-devtools status # check if install worked.
+```
+
+## How it works
+
+The CLI acts as a client to a background `chrome-devtools-mcp` daemon.
+
+- **Automatic Start**: The first time you call a tool (e.g., `list_pages`), the CLI automatically starts the MCP server and the browser in the background if they aren't already running.
+- **Persistence**: The same background instance is reused for subsequent commands, preserving the browser state (open pages, cookies, etc.).
+- **Manual Control**: You can explicitly manage the background process using `start`, `stop`, and `status`. The `start` command forwards all subsequent arguments to the underlying MCP server (e.g., `--headless`, `--userDataDir`).
+
+```sh
+# Check if the daemon is running
+chrome-devtools status
+
+# Navigate the current page to a URL
+chrome-devtools navigate_page "https://google.com"
+
+# Take a screenshot and save it to a file
+chrome-devtools take_screenshot --filePath screenshot.png
+
+# Stop the background daemon when finished
+chrome-devtools stop
+```
+
+## Command Usage
+
+The CLI supports all tools available in the [Tool reference](./tool-reference.md).
+
+```sh
+chrome-devtools <tool> [arguments] [flags]
+```
+
+- **Required Arguments**: Passed as positional arguments.
+- **Optional Arguments**: Passed as flags (e.g., `--filePath`, `--fullPage`).
+
+### Examples
+
+**New Page and Navigation:**
+
+```sh
+chrome-devtools new_page "https://example.com"
+chrome-devtools navigate_page "https://web.dev" --type url
+```
+
+**Interaction:**
+
+```sh
+# Click an element by its UID from a snapshot
+chrome-devtools click "element-uid-123"
+
+# Fill a form field
+chrome-devtools fill "input-uid-456" "search query"
+```
+
+**Analysis:**
+
+```sh
+# Run a Lighthouse audit (defaults to navigation mode)
+chrome-devtools lighthouse_audit --mode snapshot
+```
+
+## Output format
+
+By default, the CLI outputs a human-readable summary of the tool's result. For programmatic use, you can request raw JSON:
+
+```sh
+chrome-devtools list_pages --format=json
+```
+
+## Troubleshooting
+
+If the CLI hangs or fails to connect, try stopping the background process:
+
+```sh
+chrome-devtools stop
+```
+
+For more verbose logs, set the `DEBUG` environment variable:
+
+```sh
+DEBUG=* chrome-devtools list_pages
+```

docs/tool-reference.md

@@ -1,6 +1,6 @@
 <!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
 
-# Chrome DevTools MCP Tool Reference (~6919 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~6915 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (9 tools)
   - [`click`](#click)
@@ -260,9 +260,9 @@
 
 **Parameters:**
 
-- **autoStop** (boolean) **(required)**: Determines if the trace recording should be automatically stopped.
-- **reload** (boolean) **(required)**: Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the [`navigate_page`](#navigate_page) tool BEFORE starting the trace if reload or autoStop is set to true.
+- **autoStop** (boolean) _(optional)_: Determines if the trace recording should be automatically stopped.
 - **filePath** (string) _(optional)_: The absolute file path, or a file path relative to the current working directory, to save the raw trace data. For example, trace.json.gz (compressed) or trace.json (uncompressed).
+- **reload** (boolean) _(optional)_: Determines if, once tracing has started, the current selected page should be automatically reloaded. Navigate the page to the right URL using the [`navigate_page`](#navigate_page) tool BEFORE starting the trace if reload or autoStop is set to true.
 
 ---
 

docs/troubleshooting.md

@@ -8,6 +8,7 @@
   auto-accept installation prompt.
 - Find a specific error in the output of the `chrome-devtools-mcp` server.
   Usually, if your client is an IDE, logs would be in the Output pane.
+- Search the [GitHub repository issues and discussions](https://github.com/ChromeDevTools/chrome-devtools-mcp) for help or existing similar problems.
 
 ## Debugging
 
@@ -98,3 +99,12 @@ Possible workarounds include:
      `npx chrome-devtools-mcp --browser-url http://127.0.0.1:9222`
 
 - **Use Powershell or Git Bash** instead of WSL.
+
+### Connection timeouts with `--autoConnect`
+
+If you are using the `--autoConnect` flag and tools like `list_pages`, `new_page`, or `navigate_page` fail with a timeout (e.g., `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly`), this usually means the MCP server cannot handshake with the running Chrome instance correctly. Ensure:
+
+1. Chrome 144+ is **already** running.
+2. Remote debugging is enabled in Chrome via `chrome://inspect/#remote-debugging`.
+3. You have allowed the remote debugging connection prompt in the browser.
+4. There is no other MCP server or tool trying to connect to the same debugging port.

package-lock.json

@@ -56,7 +56,7 @@
     "@types/yargs": "^17.0.33",
     "@typescript-eslint/eslint-plugin": "^8.43.0",
     "@typescript-eslint/parser": "^8.43.0",
-    "chrome-devtools-frontend": "1.0.1591204",
+    "chrome-devtools-frontend": "1.0.1592362",
     "core-js": "3.48.0",
     "debug": "4.4.3",
     "eslint": "^9.35.0",
@@ -65,7 +65,7 @@
     "globals": "^17.0.0",
     "lighthouse": "13.0.3",
     "prettier": "^3.6.2",
-    "puppeteer": "24.37.5",
+    "puppeteer": "24.38.0",
     "rollup": "4.59.0",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-license": "^3.6.0",

package.json

@@ -7,7 +7,7 @@
 // Note: can be converted to ts file once node 20 support is dropped.
 // Node 20 does not support --experimental-strip-types flag.
 
-import {spawn} from 'node:child_process';
+import {spawn, execSync} from 'node:child_process';
 import path from 'node:path';
 import process from 'node:process';
 
@@ -52,12 +52,26 @@ const nodeArgs = [
   '--test-reporter',
   (process.env['NODE_TEST_REPORTER'] ?? process.env['CI']) ? 'spec' : 'dot',
   '--test-force-exit',
+  '--test-concurrency=1',
   '--test',
   '--test-timeout=60000',
   ...flags,
   ...files,
 ];
 
+function installChrome(version) {
+  try {
+    return execSync(
+      `npx puppeteer browsers install chrome@${version} --format "{{path}}"`,
+    )
+      .toString()
+      .trim();
+  } catch (e) {
+    console.error(`Failed to install Chrome ${version}:`, e);
+    process.exit(1);
+  }
+}
+
 async function runTests(attempt) {
   if (attempt > 1) {
     console.log(`\nRun attempt ${attempt}...\n`);
@@ -78,6 +92,9 @@ async function runTests(attempt) {
   });
 }
 
+const chromePath = installChrome('146.0.7680.31');
+process.env.CHROME_M146_EXECUTABLE_PATH = chromePath;
+
 const maxAttempts = shouldRetry ? 3 : 1;
 let exitCode = 1;