chore: implement ClearcutLogger and ClearcutSender dummy

Author: ergunsh

src/main.ts

@@ -15,6 +15,7 @@ import {loadIssueDescriptions} from './issue-descriptions.js';
 import {logger, saveLogsToFile} from './logger.js';
 import {McpContext} from './McpContext.js';
 import {McpResponse} from './McpResponse.js';
+import {ClearcutLogger} from './telemetry/clearcut-logger.js';
 import {Mutex} from './Mutex.js';
 import {
   McpServer,
@@ -34,6 +35,10 @@ const VERSION = '0.12.1';
 export const args = parseArguments(VERSION);
 
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
+let clearcutLogger: ClearcutLogger | undefined;
+if (args.usageStatistics) {
+  clearcutLogger = new ClearcutLogger();
+}
 
 process.on('unhandledRejection', (reason, promise) => {
   logger('Unhandled promise rejection', promise, reason);
@@ -148,6 +153,8 @@ function registerTool(tool: ToolDefinition): void {
     },
     async (params): Promise<CallToolResult> => {
       const guard = await toolMutex.acquire();
+      const startTime = Date.now();
+      let success = false;
       try {
         logger(`${tool.name} request: ${JSON.stringify(params, null, '  ')}`);
         const context = await getContext();
@@ -170,6 +177,7 @@ function registerTool(tool: ToolDefinition): void {
         } = {
           content,
         };
+        success = true;
         if (args.experimentalStructuredContent) {
           result.structuredContent = structuredContent as Record<
             string,
@@ -193,6 +201,11 @@ function registerTool(tool: ToolDefinition): void {
           isError: true,
         };
       } finally {
+        void clearcutLogger?.logToolInvocation({
+          toolName: tool.name,
+          success,
+          latencyMs: Date.now() - startTime,
+        });
         guard.dispose();
       }
     },
@@ -207,4 +220,11 @@ await loadIssueDescriptions();
 const transport = new StdioServerTransport();
 await server.connect(transport);
 logger('Chrome DevTools MCP Server connected');
+void clearcutLogger?.logServerStart({
+  browser_url_present: !!args.browserUrl,
+  headless: args.headless,
+  executable_path_present: !!args.executablePath,
+  isolated: args.isolated,
+  log_file_present: !!args.logFile,
+});
 logDisclaimers();

src/telemetry/clearcut-logger.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+  FlagUsage,
+} from './types.js';
+import {ClearcutSender} from './clearcut-sender.js';
+
+export class ClearcutLogger {
+  #sender: ClearcutSender;
+
+  constructor(sender?: ClearcutSender) {
+    this.#sender = sender ?? new ClearcutSender();
+  }
+
+  async logToolInvocation(args: {
+    toolName: string;
+    success: boolean;
+    latencyMs: number;
+  }): Promise<void> {
+    await this.#sender.send({
+      tool_invocation: {
+        tool_name: args.toolName,
+        success: args.success,
+        latency_ms: args.latencyMs,
+      },
+    });
+  }
+
+  async logServerStart(flagUsage: FlagUsage): Promise<void> {
+    await this.#sender.send({
+      server_start: {
+        flag_usage: flagUsage,
+      },
+    });
+  }
+}

src/telemetry/clearcut-sender.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {ChromeDevToolsMcpExtension} from './types.js';
+import {logger} from '../logger.js';
+
+export class ClearcutSender {
+  async send(event: ChromeDevToolsMcpExtension): Promise<void> {
+    logger('Telemetry event', JSON.stringify(event, null, 2));
+  }
+}

src/telemetry/types.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// Protobuf message interfaces
+export interface ChromeDevToolsMcpExtension {
+  os_type?: OsType;
+  mcp_client?: McpClient;
+  app_version?: string;
+  session_id?: string;
+  tool_invocation?: ToolInvocation;
+  server_start?: ServerStart;
+  daily_active?: DailyActive;
+  first_time_installation?: FirstTimeInstallation;
+}
+
+export interface ToolInvocation {
+  tool_name: string;
+  success: boolean;
+  latency_ms: number;
+}
+
+export interface ServerStart {
+  flag_usage?: FlagUsage;
+}
+
+export interface DailyActive {
+  days_since_last_active: number;
+}
+
+export interface FirstTimeInstallation {}
+
+export interface FlagUsage {
+  browser_url_present?: boolean;
+  headless?: boolean;
+  executable_path_present?: boolean;
+  isolated?: boolean;
+  channel?: ChromeChannel;
+  log_file_present?: boolean;
+}
+
+// Clearcut API interfaces
+export interface LogRequest {
+  log_source: number;
+  request_time_ms: string;
+  client_info: {
+    client_type: number;
+  };
+  log_event: Array<{
+    event_time_ms: string;
+    source_extension_json: string;
+  }>;
+}
+
+// Enums
+export enum OsType {
+  OS_TYPE_UNSPECIFIED = 0,
+  OS_TYPE_WINDOWS = 1,
+  OS_TYPE_MACOS = 2,
+  OS_TYPE_LINUX = 3,
+}
+
+export enum ChromeChannel {
+  CHROME_CHANNEL_UNSPECIFIED = 0,
+  CHROME_CHANNEL_CANARY = 1,
+  CHROME_CHANNEL_DEV = 2,
+  CHROME_CHANNEL_BETA = 3,
+  CHROME_CHANNEL_STABLE = 4,
+}
+
+export enum McpClient {
+  MCP_CLIENT_UNSPECIFIED = 0,
+  MCP_CLIENT_CLAUDE_CODE = 1,
+  MCP_CLIENT_GEMINI_CLI = 2,
+}

tests/telemetry/clearcut-logger.test.ts

@@ -0,0 +1,46 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import assert from 'node:assert';
+import {describe, it, mock} from 'node:test';
+import {ClearcutLogger} from '../../src/telemetry/clearcut-logger.js';
+import {ClearcutSender} from '../../src/telemetry/clearcut-sender.js';
+
+describe('ClearcutLogger', () => {
+  it('should log tool invocation via sender', async () => {
+    const sender = new ClearcutSender();
+    const sendSpy = mock.method(sender, 'send');
+    const loggerInstance = new ClearcutLogger(sender);
+
+    await loggerInstance.logToolInvocation({
+      toolName: 'test-tool',
+      success: true,
+      latencyMs: 100,
+    });
+
+    assert.strictEqual(sendSpy.mock.callCount(), 1);
+    const event = sendSpy.mock.calls[0].arguments[0];
+    assert.deepStrictEqual(event.tool_invocation, {
+      tool_name: 'test-tool',
+      success: true,
+      latency_ms: 100,
+    });
+  });
+
+  it('should log server start via sender', async () => {
+    const sender = new ClearcutSender();
+    const sendSpy = mock.method(sender, 'send');
+    const loggerInstance = new ClearcutLogger(sender);
+
+    await loggerInstance.logServerStart({headless: true});
+
+    assert.strictEqual(sendSpy.mock.callCount(), 1);
+    const event = sendSpy.mock.calls[0].arguments[0];
+    assert.deepStrictEqual(event.server_start, {
+      flag_usage: {headless: true},
+    });
+  });
+});