add --performance-crux flag, defaulted to true

Change-Id: Ia6dcaf83b12fe44a5167a5c7c8fb7e40276af61c

Author: paulirish

README.md

@@ -30,7 +30,8 @@ MCP clients.
 Performance tools may send trace URLs to the Google CrUX API to fetch real-user
 experience data. This helps provide a holistic performance picture by
 presenting field data alongside lab data. This data is collected by the [Chrome
-User Experience Report (CrUX)](https://developer.chrome.com/docs/crux).
+User Experience Report (CrUX)](https://developer.chrome.com/docs/crux). To disable
+this, run with the `--no-performance-crux` flag.
 
 ## **Usage statistics**
 
@@ -469,6 +470,11 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `true`
 
+- **`--performanceCrux`/ `--performance-crux`**
+  Set to false to disable CrUX (field data) integration in performance tools.
+  - **Type:** boolean
+  - **Default:** `true`
+
 - **`--usageStatistics`/ `--usage-statistics`**
   Set to false to opt-out of usage statistics collection. Google collects usage data to improve the tool, handled under the Google Privacy Policy (https://policies.google.com/privacy). This is independent from Chrome browser metrics.
   - **Type:** boolean

src/McpContext.ts

@@ -69,6 +69,8 @@ interface McpContextOptions {
   experimentalDevToolsDebugging: boolean;
   // Whether all page-like targets are exposed as pages.
   experimentalIncludeAllPages?: boolean;
+  // Whether CrUX data should be fetched.
+  performanceCrux: boolean;
 }
 
 const DEFAULT_TIMEOUT = 5_000;
@@ -376,6 +378,10 @@ export class McpContext implements Context {
     return this.#isRunningTrace;
   }
 
+  isCruxEnabled(): boolean {
+    return this.#options.performanceCrux;
+  }
+
   getDialog(): Dialog | undefined {
     return this.#dialog;
   }

src/cli.ts

@@ -204,6 +204,12 @@ export const cliOptions = {
     hidden: true,
     describe: 'Set to false to exclude tools related to extensions.',
   },
+  performanceCrux: {
+    type: 'boolean',
+    default: true,
+    describe:
+      'Set to false to disable CrUX (field data) integration in performance tools.',
+  },
   usageStatistics: {
     type: 'boolean',
     default: true,
@@ -297,6 +303,10 @@ export function parseArguments(version: string, argv = process.argv) {
         '$0 --no-usage-statistics',
         'Do not send usage statistics https://github.com/ChromeDevTools/chrome-devtools-mcp#usage-statistics.',
       ],
+      [
+        '$0 --no-performance-crux',
+        'Disable CrUX (field data) integration in performance tools.',
+      ],
     ]);
 
   return yargsInstance

src/main.ts

@@ -105,6 +105,7 @@ async function getContext(): Promise<McpContext> {
     context = await McpContext.from(browser, logger, {
       experimentalDevToolsDebugging: devtools,
       experimentalIncludeAllPages: args.experimentalIncludeAllPages,
+      performanceCrux: args.performanceCrux,
     });
   }
   return context;
@@ -115,7 +116,7 @@ const logDisclaimers = () => {
     `chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect,
 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.
-Performance tools may send trace URLs to the Google CrUX API to fetch real-user experience data.`,
+Performance tools may send trace URLs to the Google CrUX API to fetch real-user experience data. To disable, run with --no-performance-crux.`,
   );
 
   if (args.usageStatistics) {

src/tools/ToolDefinition.ts

@@ -102,6 +102,7 @@ export interface Response {
 export type Context = Readonly<{
   isRunningPerformanceTrace(): boolean;
   setIsRunningPerformanceTrace(x: boolean): void;
+  isCruxEnabled(): boolean;
   recordedTraces(): TraceResult[];
   storeTraceRecording(result: TraceResult): void;
   getSelectedPage(): Page;

src/tools/performance.ts

@@ -203,7 +203,9 @@ async function stopTracingAndAppendOutput(
     const result = await parseRawTraceBuffer(traceEventsBuffer);
     response.appendResponseLine('The performance trace has been stopped.');
     if (traceResultIsSuccess(result)) {
-      await populateCruxData(result);
+      if (context.isCruxEnabled()) {
+        await populateCruxData(result);
+      }
       context.storeTraceRecording(result);
       response.attachTraceSummary(result);
     } else {

tests/tools/performance.test.ts

@@ -325,6 +325,31 @@ describe('performance', () => {
         );
       });
     });
+
+    it('does not fetch CrUX data if performanceCrux is false', async () => {
+      const rawData = loadTraceAsBuffer('basic-trace.json.gz');
+      await withMcpContext(
+        async (response, context) => {
+          context.setIsRunningPerformanceTrace(true);
+          const selectedPage = context.getSelectedPage();
+          sinon.stub(selectedPage.tracing, 'stop').resolves(rawData);
+
+          await stopTrace.handler({params: {}}, response, context);
+
+          const cruxEndpoint =
+            'https://chromeuxreport.googleapis.com/v1/records:queryRecord';
+          const cruxCall = (globalThis.fetch as sinon.SinonStub)
+            .getCalls()
+            .find(call => call.args[0].toString().startsWith(cruxEndpoint));
+          assert.strictEqual(
+            cruxCall,
+            undefined,
+            'CrUX fetch should not have been called',
+          );
+        },
+        {performanceCrux: false},
+      );
+    });
   });
 });
 

tests/utils.ts

@@ -80,7 +80,11 @@ export async function withBrowser(
 
 export async function withMcpContext(
   cb: (response: McpResponse, context: McpContext) => Promise<void>,
-  options: {debug?: boolean; autoOpenDevTools?: boolean} = {},
+  options: {
+    debug?: boolean;
+    autoOpenDevTools?: boolean;
+    performanceCrux?: boolean;
+  } = {},
 ) {
   await withBrowser(async browser => {
     const response = new McpResponse();
@@ -92,6 +96,7 @@ export async function withMcpContext(
       logger('test'),
       {
         experimentalDevToolsDebugging: false,
+        performanceCrux: options.performanceCrux ?? true,
       },
       Locator,
     );