docs: enhance cli docs + sort required vs opt params (#674)

Author: OrKoN

README.md

@@ -350,20 +350,20 @@ The Chrome DevTools MCP server supports the following configuration option:
 
 <!-- BEGIN AUTO GENERATED OPTIONS -->
 
-- **`--autoConnect`**
+- **`--autoConnect`/ `--auto-connect`**
   If specified, automatically connects to a browser (Chrome 145+) running in the user data directory identified by the channel param. Requires remote debugging being enabled in Chrome here: chrome://inspect/#remote-debugging.
   - **Type:** boolean
   - **Default:** `false`
 
-- **`--browserUrl`, `-u`**
+- **`--browserUrl`/ `--browser-url`, `-u`**
   Connect to a running, debuggable Chrome instance (e.g. `http://127.0.0.1:9222`). For more details see: https://github.com/ChromeDevTools/chrome-devtools-mcp#connecting-to-a-running-chrome-instance.
   - **Type:** string
 
-- **`--wsEndpoint`, `-w`**
+- **`--wsEndpoint`/ `--ws-endpoint`, `-w`**
   WebSocket endpoint to connect to a running Chrome instance (e.g., ws://127.0.0.1:9222/devtools/browser/<id>). Alternative to --browserUrl.
   - **Type:** string
 
-- **`--wsHeaders`**
+- **`--wsHeaders`/ `--ws-headers`**
   Custom headers for WebSocket connection in JSON format (e.g., '{"Authorization":"Bearer token"}'). Only works with --wsEndpoint.
   - **Type:** string
 
@@ -372,15 +372,15 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `false`
 
-- **`--executablePath`, `-e`**
+- **`--executablePath`/ `--executable-path`, `-e`**
   Path to custom Chrome executable.
   - **Type:** string
 
 - **`--isolated`**
   If specified, creates a temporary user-data-dir that is automatically cleaned up after the browser is closed. Defaults to false.
   - **Type:** boolean
 
-- **`--userDataDir`**
+- **`--userDataDir`/ `--user-data-dir`**
   Path to the user data directory for Chrome. Default is $HOME/.cache/chrome-devtools-mcp/chrome-profile$CHANNEL_SUFFIX_IF_NON_STABLE
   - **Type:** string
 
@@ -389,37 +389,37 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** string
   - **Choices:** `stable`, `canary`, `beta`, `dev`
 
-- **`--logFile`**
+- **`--logFile`/ `--log-file`**
   Path to a file to write debug logs to. Set the env variable `DEBUG` to `*` to enable verbose logs. Useful for submitting bug reports.
   - **Type:** string
 
 - **`--viewport`**
   Initial viewport size for the Chrome instances started by the server. For example, `1280x720`. In headless mode, max size is 3840x2160px.
   - **Type:** string
 
-- **`--proxyServer`**
+- **`--proxyServer`/ `--proxy-server`**
   Proxy server configuration for Chrome passed as --proxy-server when launching the browser. See https://www.chromium.org/developers/design-documents/network-settings/ for details.
   - **Type:** string
 
-- **`--acceptInsecureCerts`**
+- **`--acceptInsecureCerts`/ `--accept-insecure-certs`**
   If enabled, ignores errors relative to self-signed and expired certificates. Use with caution.
   - **Type:** boolean
 
-- **`--chromeArg`**
+- **`--chromeArg`/ `--chrome-arg`**
   Additional arguments for Chrome. Only applies when Chrome is launched by chrome-devtools-mcp.
   - **Type:** array
 
-- **`--categoryEmulation`**
+- **`--categoryEmulation`/ `--category-emulation`**
   Set to false to exclude tools related to emulation.
   - **Type:** boolean
   - **Default:** `true`
 
-- **`--categoryPerformance`**
+- **`--categoryPerformance`/ `--category-performance`**
   Set to false to exclude tools related to performance.
   - **Type:** boolean
   - **Default:** `true`
 
-- **`--categoryNetwork`**
+- **`--categoryNetwork`/ `--category-network`**
   Set to false to exclude tools related to network.
   - **Type:** boolean
   - **Default:** `true`

docs/tool-reference.md

@@ -43,8 +43,8 @@
 
 **Parameters:**
 
-- **dblClick** (boolean) _(optional)_: Set to true for double clicks. Default is false.
 - **uid** (string) **(required)**: The uid of an element on the page from the page content snapshot
+- **dblClick** (boolean) _(optional)_: Set to true for double clicks. Default is false.
 
 ---
 
@@ -161,8 +161,8 @@
 
 **Parameters:**
 
-- **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 - **url** (string) **(required)**: URL to load in a new page.
+- **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 
 ---
 
@@ -172,8 +172,8 @@
 
 **Parameters:**
 
-- **bringToFront** (boolean) _(optional)_: Whether to focus the page and bring it to the top.
 - **pageIdx** (number) **(required)**: The index of the page to select. Call [`list_pages`](#list_pages) to get available pages.
+- **bringToFront** (boolean) _(optional)_: Whether to focus the page and bring it to the top.
 
 ---
 
@@ -279,7 +279,6 @@ so returned values have to JSON-serializable.
 
 **Parameters:**
 
-- **args** (array) _(optional)_: An optional list of arguments to pass to the function.
 - **function** (string) **(required)**: A JavaScript function declaration to be executed by the tool in the currently selected page.
   Example without arguments: `() => {
   return document.title
@@ -290,6 +289,8 @@ so returned values have to JSON-serializable.
   return el.innerText;
 }`
 
+- **args** (array) _(optional)_: An optional list of arguments to pass to the function.
+
 ---
 
 ### `get_console_message`

scripts/generate-docs.ts

@@ -141,8 +141,17 @@ function generateConfigOptionsMarkdown(): string {
     const aliasText = optionConfig.alias ? `, \`-${optionConfig.alias}\`` : '';
     const description = optionConfig.description || optionConfig.describe || '';
 
+    // Convert camelCase to dash-case
+    const dashCaseName = optionName
+      .replace(/([a-z])([A-Z])/g, '$1-$2')
+      .toLowerCase();
+    const nameDisplay =
+      dashCaseName !== optionName
+        ? `\`--${optionName}\`/ \`--${dashCaseName}\``
+        : `\`--${optionName}\``;
+
     // Start with option name and description
-    markdown += `- **\`--${optionName}\`${aliasText}**\n`;
+    markdown += `- **${nameDisplay}${aliasText}**\n`;
     markdown += `  ${description}\n`;
 
     // Add type information
@@ -365,7 +374,13 @@ async function generateToolDocumentation(): Promise<void> {
 
           markdown += '**Parameters:**\n\n';
 
-          const propertyNames = Object.keys(properties).sort();
+          const propertyNames = Object.keys(properties).sort((a, b) => {
+            const aRequired = required.includes(a);
+            const bRequired = required.includes(b);
+            if (aRequired && !bRequired) return -1;
+            if (!aRequired && bRequired) return 1;
+            return a.localeCompare(b);
+          });
           for (const propName of propertyNames) {
             const prop = properties[propName] as TypeInfo;
             const isRequired = required.includes(propName);