Merge branch 'main' into orkon/cli-skill

Author: OrKoN

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.

scripts/test.mjs

@@ -62,7 +62,7 @@ const nodeArgs = [
 function installChrome(version) {
   try {
     return execSync(
-      `npx @puppeteer/browsers install chrome@${version} --format "{{path}}"`,
+      `npx puppeteer browsers install chrome@${version} --format "{{path}}"`,
     )
       .toString()
       .trim();

skills/chrome-devtools-cli/SKILL.md

@@ -1,9 +1,83 @@
 ---
 name: chrome-devtools-cli
-description: Use to call Chrome DevTools MCP from shell scripts.
+description: Use this skill to call Chrome DevTools MCP from shell scripts.
 ---
 
-Documentation and examples for using the `chrome-devtools` CLI to automate browser tasks, perform audits, and interact with pages via CLI.
+## Getting started (one-time)
+
+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`).
+
+## 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
+```
 
 Snapshots looks like this:
 
@@ -18,7 +92,7 @@ uid=1_0 RootWebArea "Example Domain" url="https://example.com/"
 ## Input Automation (<uid> from snapshot)
 
 ```bash
-chrome-devtools take_snapshot --help # Help message for commands, works for any command.
+chrome-devtools take_snapshot --help
 chrome-devtools take_snapshot # Take a text snapshot of the page to get UIDs for elements
 chrome-devtools click "id" # Clicks on the provided element
 chrome-devtools click "id" --dblClick true --includeSnapshot true # Double clicks and returns a snapshot
@@ -96,7 +170,7 @@ chrome-devtools list_network_requests --includePreservedRequests true # Include
 
 ```bash
 chrome-devtools evaluate_script "() => document.title" # Evaluate a JavaScript function on the page
-evaluate_script "(a) => a.innerText" --args 1_4 # Evaluate JS with UID arguments
+chrome-devtools evaluate_script "(a) => a.innerText" --args 1_4 # Evaluate JS with UID arguments
 chrome-devtools get_console_message 1 # Gets a console message by its ID
 chrome-devtools lighthouse_audit --mode "navigation" # Run Lighthouse audit for navigation
 chrome-devtools lighthouse_audit --mode "snapshot" --device "mobile" # Run Lighthouse audit for a snapshot on mobile
@@ -115,7 +189,7 @@ chrome-devtools take_snapshot --verbose true --filePath "s.txt" # Take a verbose
 ## Service Management
 
 ```bash
-chrome-devtools start   # Start or restart chrome-devtools-mcp
+chrome-devtools start   # Start or restart chrome-devtools-mcp, all chrome-devtools-mcp args will be forwarded
 chrome-devtools status  # Checks if chrome-devtools-mcp is running
 chrome-devtools stop    # Stop chrome-devtools-mcp if any
 ```

skills/troubleshooting/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: troubleshooting
+description: Uses Chrome DevTools MCP and documentation to troubleshoot connection and target issues. Trigger this skill when list_pages, new_page, or navigate_page fail, or when the server initialization fails.
+---
+
+## Troubleshooting Wizard
+
+You are acting as a troubleshooting wizard to help the user configure and fix their Chrome DevTools MCP server setup. When this skill is triggered (e.g., because `list_pages`, `new_page`, or `navigate_page` failed, or the server wouldn't start), follow this step-by-step diagnostic process:
+
+### Step 1: Find and Read Configuration
+
+Your first action should be to locate and read the MCP configuration file. Search for the following files in the user's workspace: `.mcp.json`, `gemini-extension.json`, `.claude/settings.json`, `.vscode/launch.json`, or `.gemini/settings.json`.
+
+If you find a configuration file, read and interpret it to identify potential issues such as:
+
+- Incorrect arguments or flags.
+- Missing environment variables.
+- Usage of `--autoConnect` in incompatible environments.
+
+If you cannot find any of these files, only then should you ask the user to provide their configuration file content.
+
+### Step 2: Triage Common Connection Errors
+
+Before reading documentation or suggesting configuration changes, check if the error message matches one of the following common patterns.
+
+#### Error: `Could not find DevToolsActivePort`
+
+This error is highly specific to the `--autoConnect` feature. It means the MCP server cannot find the file created by a running, debuggable Chrome instance. This is not a generic connection failure.
+
+Your primary goal is to guide the user to ensure Chrome is running and properly configured. Do not immediately suggest switching to `--browserUrl`. Follow this exact sequence:
+
+1. **Ask the user to confirm that the correct Chrome version** (e.g., "Chrome Canary" if the error mentions it) is currently running.
+2. **If the user confirms it is running, instruct them to enable remote debugging.** Be very specific about the URL and the action: "Please open a new tab in Chrome, navigate to `chrome://inspect/#remote-debugging`, and make sure the 'Enable remote debugging' checkbox is checked."
+3. **Once the user confirms both steps, your only next action should be to call the `list_pages` tool.** This is the simplest and safest way to verify if the connection is now successful. Do not retry the original, more complex command yet.
+4. **If `list_pages` succeeds, the problem is resolved.** If it still fails with the same error, then you can proceed to the more advanced steps like suggesting `--browserUrl` or checking for sandboxing issues.
+
+#### Symptom: Server starts but creates a new empty profile
+
+If the server starts successfully but `list_pages` returns an empty list or creates a new profile instead of connecting to the existing Chrome instance, check for typos in the arguments.
+
+- **Check for flag typos:** For example, `--autoBronnect` instead of `--autoConnect`.
+- **Verify the configuration:** Ensure the arguments match the expected flags exactly.
+
+#### Other Common Errors
+
+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).
+- `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly`
+- `Error [ERR_MODULE_NOT_FOUND]: Cannot find module`
+- Any sandboxing or host validation errors.
+
+### Step 3: Read Known Issues
+
+Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md to map the error to a known issue. Pay close attention to:
+
+- Sandboxing restrictions (macOS Seatbelt, Linux containers).
+- WSL requirements.
+- `--autoConnect` handshakes, timeouts, and requirements (requires **running** Chrome 144+).
+
+### Step 4: Formulate a Configuration
+
+Based on the exact error and the user's environment (OS, MCP client), formulate the correct MCP configuration snippet. Check if they need to:
+
+- Pass `--browser-url=http://127.0.0.1:9222` instead of `--autoConnect` (e.g. if they are in a sandboxed environment like Claude Desktop).
+- Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. **Ask the user to verify this is enabled if using `--autoConnect`.**
+- Add `--logFile <absolute_path_to_log_file>` to capture debug logs for analysis.
+- Increase `startup_timeout_ms` (e.g. to 20000) if using Codex on Windows.
+
+_If you are unsure of the user's configuration, ask the user to provide their current MCP server JSON configuration._
+
+### Step 5: Run Diagnostic Commands
+
+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.
+
+### Step 6: Check GitHub for Existing Issues
+
+If https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md does not cover the specific error, check if the `gh` (GitHub CLI) tool is available in the environment. If so, search the GitHub repository for similar issues:
+`gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<error snippet>" --state all`
+
+Alternatively, you can recommend that the user checks https://github.com/ChromeDevTools/chrome-devtools-mcp/issues and https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions for help.

src/bin/chrome-devtools.ts

@@ -24,14 +24,6 @@ import type {CallToolResult} from '../third_party/index.js';
 import {VERSION} from '../version.js';
 
 import {commands} from './cliDefinitions.js';
-import {generateCustomHelp} from './customHelp.js';
-
-const argv = hideBin(process.argv);
-
-if (argv.length === 0 || argv[0] === '--custom-help') {
-  console.log(generateCustomHelp(VERSION, commands));
-  process.exit(0);
-}
 
 async function start(args: string[]) {
   const combinedArgs = [...args, ...defaultArgs];
@@ -41,13 +33,18 @@ async function start(args: string[]) {
 
 const defaultArgs = ['--viaCli', '--experimentalStructuredContent'];
 
-const y = yargs(argv)
+const y = yargs(hideBin(process.argv))
   .scriptName('chrome-devtools')
   .showHelpOnFail(true)
+  .usage('chrome-devtools <command> [...args] --flags')
+  .usage(
+    `Run 'chrome-devtools <command> --help' for help on the specific command.`,
+  )
   .demandCommand()
   .version(VERSION)
   .strict()
-  .help(true);
+  .help(true)
+  .wrap(120);
 
 y.command(
   'start',
@@ -84,7 +81,6 @@ y.command('status', 'Checks if chrome-devtools-mcp is running', async () => {
 y.command('stop', 'Stop chrome-devtools-mcp if any', async () => {
   if (!isDaemonRunning()) {
     process.exit(0);
-    return;
   }
   await stopDaemon();
   process.exit(0);
@@ -96,11 +92,19 @@ for (const [commandName, commandDef] of Object.entries(commands)) {
     name => args[name].required,
   );
 
+  const optionalArgNames = Object.keys(args).filter(
+    name => !args[name].required,
+  );
+
   let commandStr = commandName;
   for (const arg of requiredArgNames) {
     commandStr += ` <${arg}>`;
   }
 
+  for (const arg of optionalArgNames) {
+    commandStr += ` [--${arg}]`;
+  }
+
   y.command(
     commandStr,
     commandDef.description,