Skip to content

Chrome DevTools for coding agents

chore: add idle memory footprint test for the MCP server (#3435)

Alex Rudenko8b7fa71d8ac8
diff --git a/.github/workflows/test-memory-leaks.yml b/.github/workflows/test-memory-leaks.yml
index b952d280..ae764e3f 100644
--- a/.github/workflows/test-memory-leaks.yml
+++ b/.github/workflows/test-memory-leaks.yml
@@ -47,3 +47,7 @@ jobs:
- name: Run memory leak tests
shell: bash
run: npm run profile -- --threshold-percentage=1
+
+ - name: Check idle memory footprint
+ shell: bash
+ run: npm run profile:footprint
diff --git a/package.json b/package.json
index 714f30eb..025dd33a 100644
--- a/package.json
+++ b/package.json
@@ -34,7 +34,8 @@
"eval": "npm run build && node scripts/eval_gemini.ts",
"count-tokens": "node scripts/count_tokens.ts",
"profile": "npm run build && node scripts/profile/profile_mcp.ts",
- "test:memory": "npm run build && node scripts/profile/profile_mcp.ts --threshold-percentage 1"
+ "test:memory": "npm run build && node scripts/profile/profile_mcp.ts --threshold-percentage 1",
+ "profile:footprint": "npm run build && node scripts/profile/footprint_mcp.ts"
},
"files": [
"out/Default/gen/src",
diff --git a/scripts/profile/footprint_mcp.ts b/scripts/profile/footprint_mcp.ts
new file mode 100644
index 00000000..3118b9f4
--- /dev/null
+++ b/scripts/profile/footprint_mcp.ts
@@ -0,0 +1,585 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Measures the idle memory footprint of a freshly launched MCP server.
+ *
+ * The script launches the server over stdio, completes the MCP handshake
+ * (`initialize` and `tools/list`), waits for the process tree to settle and
+ * then reads the memory of every process in the tree from the OS. The tree
+ * includes the telemetry watchdog when usage statistics are on.
+ */
+
+import {execFile} from 'node:child_process';
+import fs from 'node:fs';
+import http from 'node:http';
+import type {AddressInfo} from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import {parseArgs, promisify} from 'node:util';
+
+import {Client} from '@modelcontextprotocol/client';
+import {StdioClientTransport} from '@modelcontextprotocol/client/stdio';
+
+import {formatBytes, parseNonNegativeInteger} from './utils.ts';
+
+const execFileAsync = promisify(execFile);
+
+interface ProcessMemory {
+ pid: number;
+ ppid: number;
+ command: string;
+ rssBytes: number;
+ /** Proportional set size. Linux only. */
+ pssBytes?: number;
+ /** Private clean + private dirty pages. Linux only. */
+ privateBytes?: number;
+ /** Swapped out pages. Linux only. */
+ swapBytes?: number;
+}
+
+interface TreeMeasurement {
+ iteration: number;
+ timestamp: string;
+ processes: ProcessMemory[];
+ totals: MemoryTotals;
+}
+
+interface MemoryTotals {
+ processCount: number;
+ rssBytes: number;
+ pssBytes?: number;
+ privateBytes?: number;
+ swapBytes?: number;
+}
+
+interface FootprintConfiguration {
+ name: string;
+ description: string;
+ serverArgs: string[];
+ usageStatistics: boolean;
+ /**
+ * Budget for the median private memory of the process tree. The run fails
+ * when the measured value exceeds the budget.
+ */
+ maxPrivateBytes: number;
+}
+
+interface ConfigurationResult {
+ name: string;
+ description: string;
+ measurements: TreeMeasurement[];
+ median: MemoryTotals;
+ maxPrivateBytes: number;
+ exceededBudget: boolean;
+}
+
+interface FootprintOptions {
+ iterations: number;
+ settleMs: number;
+ ignoreBudgets: boolean;
+ /** Overrides of `maxPrivateBytes` by configuration name. */
+ budgetOverrides: Map<string, number>;
+}
+
+const MiB = 1024 * 1024;
+
+// Budgets are strict: about 3% above the median measured on Linux x64
+// (default: 116.8 MiB, no-usage-statistics: 106.6 MiB). Raise a budget only
+// together with a change that needs the memory.
+const CONFIGURATIONS: FootprintConfiguration[] = [
+ {
+ name: 'default',
+ description: 'usage statistics on (server + telemetry watchdog)',
+ serverArgs: ['--usage-statistics'],
+ usageStatistics: true,
+ maxPrivateBytes: 120 * MiB,
+ },
+ {
+ name: 'no-usage-statistics',
+ description: 'usage statistics off (server only)',
+ serverArgs: ['--no-usage-statistics'],
+ usageStatistics: false,
+ maxPrivateBytes: 110 * MiB,
+ },
+];
+
+function parseKiB(text: string, field: string): number | undefined {
+ const match = new RegExp(`^${field}:\\s+(\\d+) kB`, 'm').exec(text);
+ const value = match?.[1];
+ return value === undefined ? undefined : Number(value) * 1024;
+}
+
+function readLinuxSmaps(
+ pid: number,
+): Pick<ProcessMemory, 'pssBytes' | 'privateBytes' | 'swapBytes'> {
+ let text: string;
+ try {
+ text = fs.readFileSync(`/proc/${pid}/smaps_rollup`, 'utf8');
+ } catch {
+ return {};
+ }
+ const privateClean = parseKiB(text, 'Private_Clean');
+ const privateDirty = parseKiB(text, 'Private_Dirty');
+ return {
+ pssBytes: parseKiB(text, 'Pss'),
+ privateBytes:
+ privateClean === undefined || privateDirty === undefined
+ ? undefined
+ : privateClean + privateDirty,
+ swapBytes: parseKiB(text, 'Swap'),
+ };
+}
+
+async function listProcesses(): Promise<ProcessMemory[]> {
+ if (process.platform === 'win32') {
+ throw new Error('footprint_mcp.ts supports Linux and macOS only');
+ }
+ const {stdout} = await execFileAsync('ps', ['-axo', 'pid=,ppid=,rss=,args=']);
+ const processes: ProcessMemory[] = [];
+ for (const line of stdout.split('\n')) {
+ const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+ if (!match) {
+ continue;
+ }
+ const [, pid, ppid, rssKiB, command] = match;
+ processes.push({
+ pid: Number(pid),
+ ppid: Number(ppid),
+ command: command ?? '',
+ rssBytes: Number(rssKiB) * 1024,
+ });
+ }
+ return processes;
+}
+
+async function measureTree(
+ rootPid: number,
+ iteration: number,
+): Promise<TreeMeasurement> {
+ const all = await listProcesses();
+ const byParent = new Map<number, ProcessMemory[]>();
+ for (const info of all) {
+ const children = byParent.get(info.ppid) ?? [];
+ children.push(info);
+ byParent.set(info.ppid, children);
+ }
+ const root = all.find(info => info.pid === rootPid);
+ if (!root) {
+ throw new Error(`MCP server process ${rootPid} is not running`);
+ }
+ const tree: ProcessMemory[] = [];
+ const queue = [root];
+ while (queue.length > 0) {
+ const current = queue.shift();
+ if (!current) {
+ break;
+ }
+ tree.push(current);
+ queue.push(...(byParent.get(current.pid) ?? []));
+ }
+
+ if (process.platform === 'linux') {
+ for (const info of tree) {
+ Object.assign(info, readLinuxSmaps(info.pid));
+ }
+ }
+
+ return {
+ iteration,
+ timestamp: new Date().toISOString(),
+ processes: tree,
+ totals: sumTotals(tree),
+ };
+}
+
+function sumOptional(values: Array<number | undefined>): number | undefined {
+ let sum = 0;
+ for (const value of values) {
+ if (value === undefined) {
+ return undefined;
+ }
+ sum += value;
+ }
+ return sum;
+}
+
+function sumTotals(processes: ProcessMemory[]): MemoryTotals {
+ return {
+ processCount: processes.length,
+ rssBytes: processes.reduce((sum, info) => sum + info.rssBytes, 0),
+ pssBytes: sumOptional(processes.map(info => info.pssBytes)),
+ privateBytes: sumOptional(processes.map(info => info.privateBytes)),
+ swapBytes: sumOptional(processes.map(info => info.swapBytes)),
+ };
+}
+
+function median(values: number[]): number {
+ const sorted = [...values].sort((a, b) => a - b);
+ const middle = Math.floor(sorted.length / 2);
+ const low = sorted[middle - 1];
+ const high = sorted[middle];
+ if (high === undefined) {
+ throw new Error('median() needs at least one value');
+ }
+ return sorted.length % 2 === 0 && low !== undefined ? (low + high) / 2 : high;
+}
+
+function medianOptional(values: Array<number | undefined>): number | undefined {
+ const defined: number[] = [];
+ for (const value of values) {
+ if (value === undefined) {
+ return undefined;
+ }
+ defined.push(value);
+ }
+ return median(defined);
+}
+
+function medianTotals(measurements: TreeMeasurement[]): MemoryTotals {
+ const totals = measurements.map(m => m.totals);
+ return {
+ processCount: median(totals.map(t => t.processCount)),
+ rssBytes: median(totals.map(t => t.rssBytes)),
+ pssBytes: medianOptional(totals.map(t => t.pssBytes)),
+ privateBytes: medianOptional(totals.map(t => t.privateBytes)),
+ swapBytes: medianOptional(totals.map(t => t.swapBytes)),
+ };
+}
+
+function formatOptional(bytes: number | undefined): string {
+ return bytes === undefined ? 'n/a' : formatBytes(bytes);
+}
+
+function formatTotals(totals: MemoryTotals): string {
+ return `${totals.processCount} process(es), RSS ${formatBytes(totals.rssBytes)}, PSS ${formatOptional(totals.pssBytes)}, private ${formatOptional(totals.privateBytes)}, swap ${formatOptional(totals.swapBytes)}`;
+}
+
+function shortCommand(command: string): string {
+ return command
+ .split(' ')
+ .map(part => (part.includes('/') ? path.basename(part) : part))
+ .join(' ');
+}
+
+/**
+ * Accepts telemetry uploads so that the default configuration never sends
+ * data off the machine.
+ */
+async function startMockClearcutServer(): Promise<{
+ url: string;
+ close(): Promise<void>;
+}> {
+ const server = http.createServer((req, res) => {
+ req.resume();
+ req.on('end', () => {
+ res.writeHead(200, {'Content-Type': 'application/json'});
+ res.end(JSON.stringify({next_request_wait_millis: 60_000}));
+ });
+ });
+ await new Promise<void>(resolve => {
+ server.listen(0, '127.0.0.1', () => resolve());
+ });
+ const address = server.address();
+ if (!address || typeof address === 'string') {
+ throw new Error('Mock Clearcut server did not report a TCP port');
+ }
+ const port: number = (address satisfies AddressInfo).port;
+ return {
+ url: `http://127.0.0.1:${port}`,
+ close: () =>
+ new Promise<void>((resolve, reject) => {
+ server.close(error => (error ? reject(error) : resolve()));
+ }),
+ };
+}
+
+function isProcessAlive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function waitForExit(pids: number[], timeoutMs: number): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (pids.every(pid => !isProcessAlive(pid))) {
+ return;
+ }
+ await new Promise(resolve => setTimeout(resolve, 50));
+ }
+ for (const pid of pids) {
+ if (isProcessAlive(pid)) {
+ console.warn(`Process ${pid} did not exit. Sending SIGKILL.`);
+ try {
+ process.kill(pid, 'SIGKILL');
+ } catch {
+ // The process exited between the check and the kill.
+ }
+ }
+ }
+}
+
+async function launchAndMeasure(
+ configuration: FootprintConfiguration,
+ iteration: number,
+ options: FootprintOptions,
+ rootDir: string,
+ clearcutUrl: string,
+): Promise<TreeMeasurement> {
+ const env: Record<string, string> = {};
+ for (const [key, value] of Object.entries(process.env)) {
+ if (value !== undefined) {
+ env[key] = value;
+ }
+ }
+ // Keep the run hermetic: no network update checks and no config files from
+ // the developer's home directory.
+ env.CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS = 'true';
+ env.CHROME_DEVTOOLS_MCP_NO_CONFIG_DISCOVERY = 'true';
+ if (configuration.usageStatistics) {
+ // CI and the env var below force usage statistics off. The flag on the
+ // command line must win so that the watchdog is part of the measurement.
+ delete env.CI;
+ delete env.CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS;
+ } else {
+ env.CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS = 'true';
+ }
+
+ const args = [
+ path.join(rootDir, 'out/Default/gen/src/bin/chrome-devtools-mcp.js'),
+ '--headless',
+ '--isolated',
+ ...configuration.serverArgs,
+ ];
+ if (configuration.usageStatistics) {
+ args.push(`--clearcutEndpoint=${clearcutUrl}`);
+ }
+
+ const transport = new StdioClientTransport({
+ command: process.execPath,
+ args,
+ env,
+ stderr: 'pipe',
+ });
+ const client = new Client(
+ {name: 'mcp-footprint-profiler', version: '1.0.0'},
+ {capabilities: {}},
+ );
+
+ let treePids: number[] = [];
+ try {
+ await client.connect(transport);
+ const pid = transport.pid;
+ if (pid === null) {
+ throw new Error('MCP server did not start');
+ }
+ await client.listTools();
+ await new Promise(resolve => setTimeout(resolve, options.settleMs));
+ const measurement = await measureTree(pid, iteration);
+ treePids = measurement.processes.map(info => info.pid);
+ return measurement;
+ } finally {
+ await client.close();
+ await waitForExit(treePids, 5_000);
+ }
+}
+
+async function profileConfiguration(
+ configuration: FootprintConfiguration,
+ options: FootprintOptions,
+ rootDir: string,
+ clearcutUrl: string,
+): Promise<ConfigurationResult> {
+ console.log(`\n=== Configuration: ${configuration.name} ===`);
+ console.log(configuration.description);
+ const measurements: TreeMeasurement[] = [];
+ for (let iteration = 1; iteration <= options.iterations; iteration++) {
+ const measurement = await launchAndMeasure(
+ configuration,
+ iteration,
+ options,
+ rootDir,
+ clearcutUrl,
+ );
+ measurements.push(measurement);
+ console.log(
+ `[${configuration.name}] launch ${iteration}/${options.iterations}: ${formatTotals(measurement.totals)}`,
+ );
+ for (const info of measurement.processes) {
+ console.log(
+ ` pid ${info.pid}: RSS ${formatBytes(info.rssBytes)}, PSS ${formatOptional(info.pssBytes)}, private ${formatOptional(info.privateBytes)}: ${shortCommand(info.command)}`,
+ );
+ }
+ }
+
+ const medianValues = medianTotals(measurements);
+ const maxPrivateBytes =
+ options.budgetOverrides.get(configuration.name) ??
+ configuration.maxPrivateBytes;
+ const exceededBudget =
+ !options.ignoreBudgets &&
+ medianValues.privateBytes !== undefined &&
+ medianValues.privateBytes > maxPrivateBytes;
+ console.log(
+ `[${configuration.name}] median over ${options.iterations} launch(es): ${formatTotals(medianValues)}`,
+ );
+ return {
+ name: configuration.name,
+ description: configuration.description,
+ measurements,
+ median: medianValues,
+ maxPrivateBytes,
+ exceededBudget,
+ };
+}
+
+function parseBudgetOverrides(
+ entries: string[] | undefined,
+): Map<string, number> {
+ const overrides = new Map<string, number>();
+ for (const entry of entries ?? []) {
+ const separator = entry.indexOf('=');
+ const name = entry.slice(0, separator);
+ const megabytes = Number(entry.slice(separator + 1));
+ if (
+ separator === -1 ||
+ !CONFIGURATIONS.some(c => c.name === name) ||
+ !(megabytes > 0)
+ ) {
+ throw new Error(
+ `--max-private-mb expects <configuration>=<MiB> with a positive number, got "${entry}". Available configurations: ${CONFIGURATIONS.map(c => c.name).join(', ')}`,
+ );
+ }
+ overrides.set(name, megabytes * MiB);
+ }
+ return overrides;
+}
+
+async function main(): Promise<void> {
+ const {values} = parseArgs({
+ options: {
+ 'output-dir': {type: 'string'},
+ iterations: {type: 'string'},
+ 'settle-ms': {type: 'string'},
+ configuration: {type: 'string'},
+ 'max-private-mb': {type: 'string', multiple: true},
+ 'ignore-budgets': {type: 'boolean', default: false},
+ },
+ });
+
+ const options: FootprintOptions = {
+ iterations:
+ values.iterations === undefined
+ ? 3
+ : parseNonNegativeInteger(values.iterations, '--iterations'),
+ settleMs:
+ values['settle-ms'] === undefined
+ ? 3_000
+ : parseNonNegativeInteger(values['settle-ms'], '--settle-ms'),
+ ignoreBudgets: values['ignore-budgets'],
+ budgetOverrides: parseBudgetOverrides(values['max-private-mb']),
+ };
+ if (options.iterations === 0) {
+ throw new Error('--iterations must be at least 1');
+ }
+
+ const configurations =
+ values.configuration === undefined
+ ? CONFIGURATIONS
+ : CONFIGURATIONS.filter(c => c.name === values.configuration);
+ if (configurations.length === 0) {
+ throw new Error(
+ `Configuration "${values.configuration}" not found. Available configurations: ${CONFIGURATIONS.map(c => c.name).join(', ')}`,
+ );
+ }
+
+ const rootDir = path.resolve(import.meta.dirname, '../..');
+ const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-');
+ const outputDir = path.resolve(
+ values['output-dir'] ??
+ path.join(rootDir, 'mcp-footprint-profiles', timestamp),
+ );
+ fs.mkdirSync(outputDir, {recursive: true});
+
+ console.log(
+ `Platform: ${process.platform} ${os.arch()}, Node ${process.version}`,
+ );
+ console.log(
+ `Launches per configuration: ${options.iterations}, settle time: ${options.settleMs} ms`,
+ );
+ if (options.ignoreBudgets) {
+ console.log('Private memory budgets are ignored (--ignore-budgets).');
+ } else if (process.platform !== 'linux') {
+ console.warn(
+ `Private memory is not available on ${process.platform}. Budgets are not checked.`,
+ );
+ }
+
+ const clearcut = await startMockClearcutServer();
+ const results: ConfigurationResult[] = [];
+ try {
+ for (const configuration of configurations) {
+ results.push(
+ await profileConfiguration(
+ configuration,
+ options,
+ rootDir,
+ clearcut.url,
+ ),
+ );
+ }
+ } finally {
+ await clearcut.close();
+ }
+
+ const reportPath = path.join(outputDir, 'footprint.json');
+ fs.writeFileSync(
+ reportPath,
+ `${JSON.stringify(
+ {
+ platform: process.platform,
+ arch: os.arch(),
+ node: process.version,
+ options: {
+ ...options,
+ budgetOverrides: Object.fromEntries(options.budgetOverrides),
+ },
+ results,
+ },
+ null,
+ 2,
+ )}\n`,
+ );
+ console.log(`\nReport: ${reportPath}`);
+
+ console.log('\n=== Summary ===');
+ let hasFailures = false;
+ for (const result of results) {
+ const line = `[${result.name}] median private ${formatOptional(result.median.privateBytes)}, budget ${formatBytes(result.maxPrivateBytes)} (${formatTotals(result.median)})`;
+ if (result.exceededBudget) {
+ hasFailures = true;
+ console.error(`${line}: exceeds the budget.`);
+ } else {
+ console.log(line);
+ }
+ }
+
+ if (hasFailures) {
+ console.error(
+ '\nIdle private memory exceeded the budget for one or more configurations.',
+ );
+ process.exit(1);
+ }
+}
+
+main().catch(error => {
+ console.error(error);
+ process.exitCode = 1;
+});