chore: add usage statistics CLI flag (#757)

This PR initiates the implementation of clearcut telemetry. It
introduces the CLI configuration required to opt-out of usage
statistics, along with the necessary transparency disclaimers for the
user. It's hidden by default during development & while we get the
launch approvals.

**Implementation Roadmap:**
This is the first in a series of PRs designed to implement the telemetry
system:
1.  **CLI & Opt-out Mechanism (This PR):**
* Adds the `--usage-statistics` flag (hidden, default `false` for now).
* Adds transparency logging to specify data collection when enabled.
2.  **Logger Scaffolding & Integration:**
    *   Implement `ClearcutLogger` and integrate it into `main.ts`.
    *   Add hooks for `logServerStart` and `logToolInvocation`.
* Introduce `ClearcutSender` as an abstraction layer for transport
logic.
3.  **Persistence Layer:**
* Implement local state management to reliably track "First Time
Installation" and "Daily Active" metrics.
* Implement sending the daily active and first time installation event
based on this local state.
4.  **Watchdog Process Architecture:**
* Move `ClearcutSender` execution to a dedicated watchdog process to
ensure reliable event transmission even during abrupt server shutdowns.
5.  **Transport, Batching & Retries:**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching, respecting `next_request_wait_millis` and retries.

Author: ergunsh

src/cli.ts

@@ -193,6 +193,13 @@ export const cliOptions = {
     default: true,
     describe: 'Set to false to exclude tools related to network.',
   },
+  usageStatistics: {
+    type: 'boolean',
+    // Marked as `false` until the feature is ready to be enabled by default.
+    default: false,
+    hidden: true,
+    describe: 'Set to false to opt-out of usage statistics collection.',
+  },
 } satisfies Record<string, YargsOptions>;
 
 export function parseArguments(version: string, argv = process.argv) {

src/main.ts

@@ -102,6 +102,14 @@ const logDisclaimers = () => {
 debug, and modify any data in the browser or DevTools.
 Avoid sharing sensitive or personal information that you do not want to share with MCP clients.`,
   );
+
+  if (args.usageStatistics) {
+    console.error(
+      `
+Google collects usage statistics to improve Chrome DevTools MCP. To opt-out, run with --no-usage-statistics.
+For more details, visit: https://github.com/ChromeDevTools/chrome-devtools-mcp#usage-statistics`,
+    );
+  }
 };
 
 const toolMutex = new Mutex();

tests/cli.test.ts

@@ -19,6 +19,8 @@ describe('cli args parsing', () => {
     categoryNetwork: true,
     'auto-connect': undefined,
     autoConnect: undefined,
+    'usage-statistics': false,
+    usageStatistics: false,
   };
 
   it('parses with default args', async () => {
@@ -246,4 +248,26 @@ describe('cli args parsing', () => {
       autoConnect: true,
     });
   });
+
+  it('parses usage statistics flag', async () => {
+    // Test default (should be false)
+    const defaultArgs = parseArguments('1.0.0', ['node', 'main.js']);
+    assert.strictEqual(defaultArgs.usageStatistics, false);
+
+    // Test enabling it
+    const enabledArgs = parseArguments('1.0.0', [
+      'node',
+      'main.js',
+      '--usage-statistics',
+    ]);
+    assert.strictEqual(enabledArgs.usageStatistics, true);
+
+    // Test disabling it
+    const disabledArgs = parseArguments('1.0.0', [
+      'node',
+      'main.js',
+      '--no-usage-statistics',
+    ]);
+    assert.strictEqual(disabledArgs.usageStatistics, false);
+  });
 });