chore: generate a json file for flag usage metrics (#1881)

This is the second most highly touched metric areas - so let's automate
this portion first. The approach is similar to what we have for tool
call args. The append-only logic will be added in the follow-up PR:
#1882

Author: yulunz

README.md

@@ -558,7 +558,7 @@ The Chrome DevTools MCP server supports the following configuration option:
 - **`--channel`**
   Specify a different Chrome channel that should be used. The default is the stable channel version.
   - **Type:** string
-  - **Choices:** `stable`, `canary`, `beta`, `dev`
+  - **Choices:** `canary`, `dev`, `beta`, `stable`
 
 - **`--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.

package.json

@@ -16,7 +16,7 @@
     "typecheck": "tsc --noEmit",
     "format": "eslint --cache --fix . && prettier --write --cache .",
     "check-format": "eslint --cache . && prettier --check --cache .;",
-    "gen": "npm run build && npm run docs:generate && npm run cli:generate && npm run update-tool-call-metrics && npm run format",
+    "gen": "npm run build && npm run docs:generate && npm run cli:generate && npm run update-tool-call-metrics && npm run update-flag-usage-metrics && 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",
@@ -28,6 +28,7 @@
     "verify-server-json-version": "node --experimental-strip-types scripts/verify-server-json-version.ts",
     "update-lighthouse": "node --experimental-strip-types scripts/update-lighthouse.ts",
     "update-tool-call-metrics": "node --experimental-strip-types scripts/update_tool_call_metrics.ts",
+    "update-flag-usage-metrics": "node --experimental-strip-types scripts/update_flag_usage_metrics.ts",
     "verify-npm-package": "node scripts/verify-npm-package.mjs",
     "eval": "npm run build && node --experimental-strip-types scripts/eval_gemini.ts",
     "count-tokens": "node --experimental-strip-types scripts/count_tokens.ts"

scripts/update_flag_usage_metrics.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {cliOptions} from '../build/src/bin/chrome-devtools-mcp-cli-options.js';
+import {
+  getPossibleFlagMetrics,
+  type FlagMetric,
+} from '../build/src/telemetry/flagUtils.js';
+
+function writeFlagUsageMetrics() {
+  const outputPath = path.resolve('src/telemetry/flag_usage_metrics.json');
+
+  const dir = path.dirname(outputPath);
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Error: Directory ${dir} does not exist.`);
+  }
+
+  const metrics = getPossibleFlagMetrics(cliOptions);
+
+  // Sort metrics by name for deterministic output
+  metrics.sort((a: FlagMetric, b: FlagMetric) => a.name.localeCompare(b.name));
+
+  fs.writeFileSync(outputPath, JSON.stringify(metrics, null, 2) + '\n');
+
+  console.log(
+    `Successfully wrote ${metrics.length} flag usage metrics to ${outputPath}`,
+  );
+}
+
+writeFlagUsageMetrics();

src/bin/chrome-devtools-mcp-cli-options.ts

@@ -113,7 +113,7 @@ export const cliOptions = {
     type: 'string',
     description:
       'Specify a different Chrome channel that should be used. The default is the stable channel version.',
-    choices: ['stable', 'canary', 'beta', 'dev'] as const,
+    choices: ['canary', 'dev', 'beta', 'stable'] as const,
     conflicts: ['browserUrl', 'wsEndpoint', 'executablePath'],
   },
   logFile: {

src/telemetry/flagUtils.ts

@@ -11,6 +11,15 @@ import type {FlagUsage} from './types.js';
 
 type CliOptions = typeof cliOptions;
 
+/**
+ * For enums, log the value as uppercase.
+ * We're going to have an enum for such flags with choices represented
+ * as an `enum` where the keys of the enum will map to the uppercase `choice`.
+ */
+function formatEnumChoice(snakeCaseName: string, choice: string): string {
+  return `${snakeCaseName}_${choice}`.toUpperCase();
+}
+
 /**
  * Computes telemetry flag usage from parsed arguments and CLI options.
  *
@@ -21,6 +30,8 @@ type CliOptions = typeof cliOptions;
  *    - The provided value differs from the default value.
  * - Boolean flags are logged with their literal value.
  * - String flags with defined `choices` (Enums) are logged as their uppercase value.
+ *
+ * IMPORTANT: keep getPossibleFlagMetrics() in sync with this function.
  */
 export function computeFlagUsage(
   args: Record<string, unknown>,
@@ -49,12 +60,58 @@ export function computeFlagUsage(
       'choices' in config &&
       config.choices
     ) {
-      // For enums, log the value as uppercase
-      // We're going to have an enum for such flags with choices represented
-      // as an `enum` where the keys of the enum will map to the uppercase `choice`.
-      usage[snakeCaseName] = `${snakeCaseName}_${value}`.toUpperCase();
+      usage[snakeCaseName] = formatEnumChoice(snakeCaseName, value);
     }
   }
 
   return usage;
 }
+
+export interface FlagMetric {
+  name: string;
+  flagType: 'boolean' | 'enum';
+  choices?: string[];
+}
+
+/**
+ * Computes the list of possible flag metrics based on the CLI options.
+ *
+ * IMPORTANT: keep this function in sync with computeFlagUsage().
+ */
+export function getPossibleFlagMetrics(options: CliOptions): FlagMetric[] {
+  const metrics: FlagMetric[] = [];
+
+  for (const [flagName, config] of Object.entries(options)) {
+    const snakeCaseName = toSnakeCase(flagName);
+
+    // _present is always a possible metric
+    metrics.push({
+      name: `${snakeCaseName}_present`,
+      flagType: 'boolean',
+    });
+
+    if (config.type === 'boolean') {
+      metrics.push({
+        name: snakeCaseName,
+        flagType: 'boolean',
+      });
+    } else if (
+      config.type === 'string' &&
+      'choices' in config &&
+      config.choices
+    ) {
+      metrics.push({
+        name: snakeCaseName,
+        flagType: 'enum',
+        choices: [
+          `${snakeCaseName.toUpperCase()}_UNSPECIFIED`,
+          ...config.choices.map(choice =>
+            formatEnumChoice(snakeCaseName, choice),
+          ),
+        ],
+      });
+    }
+  }
+
+  return metrics;
+}