Merge branch 'main' into orkon/release-cli

Author: OrKoN

.github/workflows/presubmit.yml

@@ -51,15 +51,15 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Generate documents
-        run: npm run docs
+      - name: Generate
+        run: npm run gen
 
-      - name: Check if autogenerated docs differ
+      - name: Check if autogenerated code and docs are out of date
         run: |
           diff_file=$(mktemp doc_diff_XXXXXX)
           git diff --color > $diff_file
           if [[ -s $diff_file ]]; then
-            echo "Please update the documentation by running 'npm run generate-docs'. The following was the diff"
+            echo "Please update the documentation by running 'npm run gen'. The following was the diff"
             cat $diff_file
             rm $diff_file
             exit 1

CONTRIBUTING.md

@@ -37,6 +37,22 @@ information on using pull requests.
 Please follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
 for PR and commit titles.
 
+### Feature release checklist
+
+Use `chore:` for commits containing incomplete features that are not available
+to users yet. Once the feature is ready to be released, create a PR with a
+`feat:` prefix that enables the feature. The following criteria need to be
+completed:
+
+- Documentation for the feature is up to date. For example, README.md and tools
+  reference are updated.
+- The feature can be used with Chrome stable or version restrictions are
+  documented otherwise.
+- Corresponding skills are updated or new skills are added if needed.
+- The feature fulfills the use case by its own or in conjunction with existing
+  features (we want to avoid features that offer some tools but cannot be used
+  successfully to debug things).
+
 ## Installation
 
 Check that you are using node version specified in .nvmrc, then run following commands:
@@ -86,7 +102,7 @@ You can use the `DEBUG` environment variable as usual to control categories that
 
 ### Updating documentation
 
-When adding a new tool or updating a tool name or description, make sure to run `npm run docs` to generate the tool reference documentation.
+When adding a new tool or updating a tool name or description, make sure to run `npm run gen` to generate the tool reference documentation.
 
 ### Contributing to Evals
 

docs/cli.md

@@ -17,7 +17,7 @@ The CLI acts as a client to a background `chrome-devtools-mcp` daemon (uses Unix
 
 - **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`).
+- **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`) but not all args are supported. Run `chrome-devtools start --help` for supported args. Headless and isolated are enabled by default.
 
 ```sh
 # Check if the daemon is running

docs/slim-tool-reference.md

@@ -1,4 +1,4 @@
-<!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
+<!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
 
 # Chrome DevTools MCP Slim Tool Reference (~359 cl100k_base tokens)
 

docs/tool-reference.md

@@ -1,6 +1,6 @@
-<!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
+<!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
 
-# Chrome DevTools MCP Tool Reference (~6927 cl100k_base tokens)
+# Chrome DevTools MCP Tool Reference (~6940 cl100k_base tokens)
 
 - **[Input automation](#input-automation)** (9 tools)
   - [`click`](#click)
@@ -348,7 +348,7 @@ so returned values have to be JSON-serializable.
 
 ### `lighthouse_audit`
 
-**Description:** Get Lighthouse score and reports for accessibility, SEO and best practices.
+**Description:** Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run [`performance_start_trace`](#performance_start_trace)
 
 **Parameters:**
 

package.json

@@ -16,7 +16,7 @@
     "typecheck": "tsc --noEmit",
     "format": "eslint --cache --fix . && prettier --write --cache .",
     "check-format": "eslint --cache . && prettier --check --cache .;",
-    "docs": "npm run build && npm run docs:generate && npm run format",
+    "gen": "npm run build && npm run docs:generate && npm run cli:generate && npm run format",
     "docs:generate": "node --experimental-strip-types scripts/generate-docs.ts",
     "start": "npm run build && node build/src/index.js",
     "start-debug": "DEBUG=mcp:* DEBUG_COLORS=false npm run build && node build/src/index.js",

release-please-config.json

@@ -4,8 +4,8 @@
     {"type": "fix", "section": "🛠️ Fixes", "hidden": false},
     {"type": "docs", "section": "📄 Documentation", "hidden": false},
 
-    {"type": "perf", "section": "♻️ Chores", "hidden": false},
-    {"type": "refactor", "section": "♻️ Chores", "hidden": false},
+    {"type": "perf", "section": "⚡ Performance", "hidden": false},
+    {"type": "refactor", "section": "🏗️ Refactor", "hidden": false},
     {"type": "chore", "section": "♻️ Chores", "hidden": true},
     {"type": "test", "section": "♻️ Chores", "hidden": true},
 

scripts/generate-docs.ts

@@ -323,7 +323,7 @@ async function generateReference(
   console.log(`Found ${toolsWithAnnotations.length} tools`);
 
   // Generate markdown documentation
-  let markdown = `<!-- AUTO GENERATED DO NOT EDIT - run 'npm run docs' to update-->
+  let markdown = `<!-- AUTO GENERATED DO NOT EDIT - run 'npm run gen' to update-->
 
 # ${title} (~${(await measureServer(serverArgs)).tokenCount} cl100k_base tokens)
 

src/bin/chrome-devtools.ts

@@ -10,14 +10,14 @@ import process from 'node:process';
 
 import type {Options, PositionalOptions} from 'yargs';
 
-import {parseArguments} from '../cli.js';
+import {cliOptions, parseArguments} from '../cli.js';
 import {
   startDaemon,
   stopDaemon,
   sendCommand,
   handleResponse,
 } from '../daemon/client.js';
-import {isDaemonRunning} from '../daemon/utils.js';
+import {isDaemonRunning, serializeArgs} from '../daemon/utils.js';
 import {logDisclaimers} from '../server.js';
 import {hideBin, yargs, type CallToolResult} from '../third_party/index.js';
 import {VERSION} from '../version.js';
@@ -26,12 +26,41 @@ import {commands} from './cliDefinitions.js';
 
 async function start(args: string[]) {
   const combinedArgs = [...args, ...defaultArgs];
-  await startDaemon([...args, ...defaultArgs]);
+  await startDaemon(combinedArgs);
   logDisclaimers(parseArguments(VERSION, combinedArgs));
 }
 
 const defaultArgs = ['--viaCli', '--experimentalStructuredContent'];
 
+const startCliOptions = {
+  ...cliOptions,
+} as Partial<typeof cliOptions>;
+
+// Not supported in CLI on purpose.
+delete startCliOptions.autoConnect;
+// Missing CLI serialization.
+delete startCliOptions.viewport;
+// CLI is generated based on the default tool definitions. To enable conditional
+// tools, they needs to be enabled during CLI generation.
+delete startCliOptions.experimentalPageIdRouting;
+delete startCliOptions.experimentalVision;
+delete startCliOptions.experimentalInteropTools;
+delete startCliOptions.experimentalScreencast;
+delete startCliOptions.categoryEmulation;
+delete startCliOptions.categoryPerformance;
+delete startCliOptions.categoryNetwork;
+delete startCliOptions.categoryExtensions;
+// Always on in CLI.
+delete startCliOptions.experimentalStructuredContent;
+// Change the defaults.
+if (!('default' in cliOptions.headless)) {
+  throw new Error('headless cli option unexpectedly does not have a default');
+}
+if ('default' in cliOptions.isolated) {
+  throw new Error('headless cli option unexpectedly does not have a default');
+}
+startCliOptions.headless!.default = true;
+
 const y = yargs(hideBin(process.argv))
   .scriptName('chrome-devtools')
   .showHelpOnFail(true)
@@ -50,19 +79,24 @@ y.command(
   'Start or restart chrome-devtools-mcp',
   y =>
     y
-      .help(false) // Disable help for start command to avoid parsing issues with passed args.
+      .options(startCliOptions)
       .example(
-        '$0 start --port 8080 --url http://localhost:8080',
-        'Start the server on port 8080 with a specific URL',
+        '$0 start --browserUrl http://localhost:9222',
+        'Start the server connecting to an existing browser',
       )
-      .strict(false), // Don't validate arguments for start, as they are passed through to the daemon.
-  async () => {
+      .strict(),
+  async argv => {
     if (isDaemonRunning()) {
       await stopDaemon();
     }
-    // Extract args after 'start'
-    const startIndex = process.argv.indexOf('start');
-    const args = startIndex !== -1 ? process.argv.slice(startIndex + 1) : [];
+    // Defaults but we do not want to affect the yargs conflict resolution.
+    if (argv.isolated === undefined) {
+      argv.isolated = true;
+    }
+    if (argv.headless === undefined) {
+      argv.headless = true;
+    }
+    const args = serializeArgs(cliOptions, argv);
     await start(args);
     process.exit(0);
   },

src/bin/cliDefinitions.ts

@@ -287,7 +287,7 @@ export const commands: Commands = {
   },
   lighthouse_audit: {
     description:
-      'Get Lighthouse score and reports for accessibility, SEO and best practices.',
+      'Get Lighthouse score and reports for accessibility, SEO and best practices. This excludes performance. For performance audits, run performance_start_trace',
     category: 'Debugging',
     args: {
       mode: {
@@ -393,7 +393,8 @@ export const commands: Commands = {
     args: {},
   },
   navigate_page: {
-    description: 'Navigates the currently selected page to a URL.',
+    description:
+      'Go to a URL, or back, forward, or reload. Use project URL if not specified otherwise.',
     category: 'Navigation automation',
     args: {
       type: {
@@ -441,7 +442,8 @@ export const commands: Commands = {
     },
   },
   new_page: {
-    description: 'Creates a new page',
+    description:
+      'Open a new tab and load a URL. Use project URL if not specified otherwise.',
     category: 'Navigation automation',
     args: {
       url: {
@@ -496,22 +498,24 @@ export const commands: Commands = {
   },
   performance_start_trace: {
     description:
-      'Starts a performance trace recording on the selected page. This can be used to look for performance problems and insights to improve the performance of the page. It will also report Core Web Vital (CWV) scores for the page.',
+      'Start a performance trace on the selected webpage. Use to find frontend performance issues, Core Web Vitals (LCP, INP, CLS), and improve page load speed.',
     category: 'Performance',
     args: {
       reload: {
         name: 'reload',
         type: 'boolean',
         description:
           '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 tool BEFORE starting the trace if reload or autoStop is set to true.',
-        required: true,
+        required: false,
+        default: true,
       },
       autoStop: {
         name: 'autoStop',
         type: 'boolean',
         description:
           'Determines if the trace recording should be automatically stopped.',
-        required: true,
+        required: false,
+        default: true,
       },
       filePath: {
         name: 'filePath',
@@ -524,7 +528,7 @@ export const commands: Commands = {
   },
   performance_stop_trace: {
     description:
-      'Stops the active performance trace recording on the selected page.',
+      'Stop the active performance trace recording on the selected webpage.',
     category: 'Performance',
     args: {
       filePath: {