Skip to content

Chrome DevTools for coding agents

chore: refactor the profiler into scenarios. (#2488)

yulunz884c8dee7cda
diff --git a/scripts/profile/inspector.ts b/scripts/profile/inspector.ts
new file mode 100644
index 00000000..9dcd7e98
--- /dev/null
+++ b/scripts/profile/inspector.ts
@@ -0,0 +1,163 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import fs from 'node:fs';
+
+import type {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
+
+import {isObject} from './utils.ts';
+
+export interface HeapUsage {
+ usedSize: number;
+ totalSize: number;
+}
+
+export interface Measurement extends HeapUsage {
+ label: string;
+ timestamp: string;
+}
+
+interface PendingRequest {
+ reject(error: Error): void;
+ resolve(result: unknown): void;
+}
+
+export class InspectorClient {
+ readonly #pending = new Map<number, PendingRequest>();
+ #nextId = 1;
+ #snapshotStream: fs.WriteStream | undefined;
+ readonly #webSocket: WebSocket;
+
+ private constructor(webSocket: WebSocket) {
+ this.#webSocket = webSocket;
+ webSocket.addEventListener('message', event => {
+ this.#handleMessage(event.data);
+ });
+ }
+
+ static connect(url: string): Promise<InspectorClient> {
+ return new Promise((resolve, reject) => {
+ const webSocket = new WebSocket(url);
+ webSocket.addEventListener('open', () => {
+ resolve(new InspectorClient(webSocket));
+ });
+ webSocket.addEventListener('error', () => {
+ reject(new Error(`Failed to connect to Node inspector at ${url}`));
+ });
+ });
+ }
+
+ #handleMessage(data: unknown): void {
+ if (typeof data !== 'string') {
+ return;
+ }
+ const message: unknown = JSON.parse(data);
+ if (!isObject(message)) {
+ return;
+ }
+
+ if (message.method === 'HeapProfiler.addHeapSnapshotChunk') {
+ const params = message.params;
+ if (
+ this.#snapshotStream &&
+ isObject(params) &&
+ typeof params.chunk === 'string'
+ ) {
+ this.#snapshotStream.write(params.chunk);
+ }
+ return;
+ }
+
+ if (typeof message.id !== 'number') {
+ return;
+ }
+ const pending = this.#pending.get(message.id);
+ if (!pending) {
+ return;
+ }
+ this.#pending.delete(message.id);
+ if (isObject(message.error)) {
+ const errorMessage =
+ typeof message.error.message === 'string'
+ ? message.error.message
+ : 'Unknown inspector error';
+ pending.reject(new Error(errorMessage));
+ return;
+ }
+ pending.resolve(message.result);
+ }
+
+ send(method: string, params?: Record<string, unknown>): Promise<unknown> {
+ const id = this.#nextId++;
+ return new Promise((resolve, reject) => {
+ this.#pending.set(id, {resolve, reject});
+ this.#webSocket.send(JSON.stringify({id, method, params}));
+ });
+ }
+
+ async getHeapUsage(): Promise<HeapUsage> {
+ await this.send('HeapProfiler.collectGarbage');
+ const result = await this.send('Runtime.getHeapUsage');
+ if (
+ !isObject(result) ||
+ typeof result.usedSize !== 'number' ||
+ typeof result.totalSize !== 'number'
+ ) {
+ throw new Error('Node inspector returned invalid heap usage data');
+ }
+ return {usedSize: result.usedSize, totalSize: result.totalSize};
+ }
+
+ async takeHeapSnapshot(filePath: string): Promise<void> {
+ const stream = fs.createWriteStream(filePath, {encoding: 'utf8'});
+ this.#snapshotStream = stream;
+ try {
+ await this.send('HeapProfiler.takeHeapSnapshot', {reportProgress: false});
+ } finally {
+ this.#snapshotStream = undefined;
+ await new Promise<void>((resolve, reject) => {
+ stream.end(resolve);
+ stream.on('error', reject);
+ });
+ }
+ }
+
+ close(): void {
+ this.#webSocket.close();
+ }
+}
+
+export function inspectorUrlFrom(
+ transport: StdioClientTransport,
+): Promise<string> {
+ const stderr = transport.stderr;
+ if (!stderr) {
+ throw new Error('MCP server stderr is unavailable');
+ }
+ return new Promise((resolve, reject) => {
+ let buffered = '';
+ const timeout = setTimeout(() => {
+ reject(
+ new Error(
+ `Timed out waiting for the Node inspector URL. Server stderr: ${buffered}`,
+ ),
+ );
+ }, 10_000);
+ stderr.setEncoding('utf8');
+ stderr.on('data', chunk => {
+ if (typeof chunk !== 'string') {
+ return;
+ }
+ buffered += chunk;
+ const match = /Debugger listening on (ws:\/\/\S+)/.exec(buffered);
+ const url = match?.[1];
+ if (url) {
+ clearTimeout(timeout);
+ resolve(url);
+ }
+ });
+ });
+}
diff --git a/scripts/profile/profile_mcp.ts b/scripts/profile/profile_mcp.ts
new file mode 100644
index 00000000..132340d7
--- /dev/null
+++ b/scripts/profile/profile_mcp.ts
@@ -0,0 +1,321 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {pathToFileURL} from 'node:url';
+import {parseArgs} from 'node:util';
+
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
+
+import {
+ InspectorClient,
+ inspectorUrlFrom,
+ type Measurement,
+} from './inspector.ts';
+import {startSourceMapTestServer} from './source_map_server.ts';
+import type {ProfileScenario, ScenarioArgs} from './types.ts';
+import {formatBytes, isScenarioModule, parsePositiveInteger} from './utils.ts';
+
+interface ProfileOptions {
+ iterations: number;
+ warmupIterations: number;
+}
+
+interface ScenarioEntry {
+ name: string;
+ scenario: ProfileScenario;
+}
+
+async function loadScenario(filePath: string): Promise<ProfileScenario> {
+ const fileUrl = pathToFileURL(filePath).href;
+ const importedModule: unknown = await import(fileUrl);
+ if (!isScenarioModule(importedModule)) {
+ throw new Error(
+ `Scenario file ${filePath} does not export a 'get' function.`,
+ );
+ }
+ return importedModule;
+}
+
+async function discoverScenarios(
+ scenariosDir: string,
+ scenarioFilter?: string,
+): Promise<ScenarioEntry[]> {
+ const entries = fs.readdirSync(scenariosDir);
+ const scenarioFiles: string[] = [];
+
+ for (const entry of entries) {
+ if (entry.endsWith('.ts') || entry.endsWith('.js')) {
+ scenarioFiles.push(entry);
+ }
+ }
+
+ if (scenarioFilter !== undefined && scenarioFilter.length > 0) {
+ const normalizedFilter =
+ scenarioFilter.endsWith('.ts') || scenarioFilter.endsWith('.js')
+ ? scenarioFilter
+ : `${scenarioFilter}.ts`;
+ const targetFile = scenarioFiles.find(
+ file => file === scenarioFilter || file === normalizedFilter,
+ );
+ if (!targetFile) {
+ throw new Error(
+ `Scenario "${scenarioFilter}" not found in ${scenariosDir}. Available scenarios: ${scenarioFiles.map(f => path.basename(f, path.extname(f))).join(', ')}`,
+ );
+ }
+ const scenario = await loadScenario(path.join(scenariosDir, targetFile));
+ return [
+ {name: path.basename(targetFile, path.extname(targetFile)), scenario},
+ ];
+ }
+
+ const results: ScenarioEntry[] = [];
+ for (const file of scenarioFiles) {
+ const scenario = await loadScenario(path.join(scenariosDir, file));
+ results.push({name: path.basename(file, path.extname(file)), scenario});
+ }
+ return results;
+}
+
+interface ScenarioResult {
+ name: string;
+ summary: string;
+ isGrowth: boolean;
+}
+
+async function profileScenario(
+ scenarioEntry: ScenarioEntry,
+ scenarioArgs: ScenarioArgs,
+ options: ProfileOptions,
+ rootDir: string,
+): Promise<ScenarioResult> {
+ const {name: scenarioName, scenario} = scenarioEntry;
+ const {outputDir} = scenarioArgs;
+ fs.mkdirSync(outputDir, {recursive: true});
+
+ const env: Record<string, string> = {};
+ for (const [key, value] of Object.entries(process.env)) {
+ if (value !== undefined) {
+ env[key] = value;
+ }
+ }
+ env.CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS = 'true';
+
+ const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [
+ '--inspect=127.0.0.1:0',
+ path.join(rootDir, 'build/src/bin/chrome-devtools-mcp.js'),
+ '--headless',
+ '--isolated',
+ ],
+ env,
+ stderr: 'pipe',
+ });
+ const inspectorUrlPromise = inspectorUrlFrom(transport);
+ const client = new Client(
+ {name: 'mcp-heap-profiler', version: '1.0.0'},
+ {capabilities: {}},
+ );
+ let inspector: InspectorClient | undefined;
+ const measurements: Measurement[] = [];
+
+ const toolCalls = await scenario.get(scenarioArgs);
+
+ const runIteration = async (): Promise<void> => {
+ const results: unknown[] = [];
+ for (const call of toolCalls) {
+ let args: Record<string, unknown> | undefined;
+ if (typeof call.arguments === 'function') {
+ const resolved = await call.arguments({results});
+ args = resolved;
+ } else {
+ args = call.arguments;
+ }
+ const result = await client.callTool({
+ name: call.name,
+ arguments: args,
+ });
+ results.push(result);
+ }
+ };
+
+ const record = async (
+ label: string,
+ takeSnapshot: boolean,
+ ): Promise<void> => {
+ if (!inspector) {
+ throw new Error('Inspector is not connected');
+ }
+ const usage = await inspector.getHeapUsage();
+ const measurement: Measurement = {
+ label,
+ timestamp: new Date().toISOString(),
+ ...usage,
+ };
+ measurements.push(measurement);
+ console.log(
+ `[${scenarioName}] ${label}: used ${formatBytes(usage.usedSize)}, total ${formatBytes(usage.totalSize)}`,
+ );
+ if (!takeSnapshot) {
+ return;
+ }
+ const snapshotPath = path.join(outputDir, `${label}.heapsnapshot`);
+ await inspector.takeHeapSnapshot(snapshotPath);
+ console.log(` snapshot: ${snapshotPath}`);
+ };
+
+ try {
+ await client.connect(transport);
+ inspector = await InspectorClient.connect(await inspectorUrlPromise);
+ console.log(`\n=== Scenario: ${scenarioName} ===`);
+ console.log(`MCP server PID: ${transport.pid}`);
+ console.log(`Target URL: ${scenarioArgs.targetUrl}`);
+ console.log(`Output directory: ${outputDir}`);
+
+ await record('connected', false);
+ for (
+ let iteration = 1;
+ iteration <= options.warmupIterations;
+ iteration++
+ ) {
+ console.log(
+ `[${scenarioName}] Warm-up ${iteration}/${options.warmupIterations}`,
+ );
+ await runIteration();
+ }
+
+ // Taking a heap snapshot exercises Node inspector and serialization paths.
+ // Prime those paths before capturing the baseline so their JIT-compiled code
+ // is not mistaken for workload growth in the final comparison.
+ await record('snapshot-primer', true);
+ await record('baseline', true);
+
+ for (let iteration = 1; iteration <= options.iterations; iteration++) {
+ console.log(
+ `[${scenarioName}] Measured iteration ${iteration}/${options.iterations}`,
+ );
+ await runIteration();
+ await record(`iteration-${iteration}`, false);
+ }
+ await record('final', true);
+
+ let summary = `[${scenarioName}] Unable to compute heap comparison.`;
+ let isGrowth = false;
+ const baseline = measurements.find(
+ measurement => measurement.label === 'baseline',
+ );
+ const final = measurements.find(
+ measurement => measurement.label === 'final',
+ );
+ if (baseline && final) {
+ const growth = final.usedSize - baseline.usedSize;
+ if (growth > 0) {
+ isGrowth = true;
+ const percentage = (growth / baseline.usedSize) * 100;
+ summary = `[${scenarioName}] The MCP heap grew by ${formatBytes(growth)} (${percentage.toFixed(2)}%) across ${options.iterations} measured iterations. Compare baseline.heapsnapshot with final.heapsnapshot to determine whether retained workload objects accumulated.`;
+ console.warn(summary);
+ } else {
+ summary = `[${scenarioName}] The MCP heap did not grow across the measured iterations (${formatBytes(growth)}).`;
+ console.log(summary);
+ }
+ }
+
+ const reportPath = path.join(outputDir, 'heap-usage.json');
+ fs.writeFileSync(
+ reportPath,
+ `${JSON.stringify({scenario: scenarioName, pid: transport.pid, url: scenarioArgs.targetUrl, options, measurements}, null, 2)}\n`,
+ );
+ console.log(`Report: ${reportPath}`);
+
+ return {name: scenarioName, summary, isGrowth};
+ } finally {
+ inspector?.close();
+ await client.close();
+ }
+}
+
+async function main(): Promise<void> {
+ const {values} = parseArgs({
+ options: {
+ 'output-dir': {type: 'string'},
+ iterations: {type: 'string', default: '10'},
+ 'warmup-iterations': {type: 'string', default: '10'},
+ scenario: {type: 'string'},
+ url: {type: 'string'},
+ },
+ });
+
+ const options: ProfileOptions = {
+ iterations: parsePositiveInteger(values.iterations, '--iterations'),
+ warmupIterations: parsePositiveInteger(
+ values['warmup-iterations'],
+ '--warmup-iterations',
+ ),
+ };
+
+ const rootDir = path.resolve(import.meta.dirname, '../..');
+ const scenariosDir = path.join(import.meta.dirname, 'scenarios');
+ const scenarios = await discoverScenarios(scenariosDir, values.scenario);
+
+ const timestamp = new Date().toISOString().replaceAll(/[:.]/g, '-');
+ const baseOutputDir = path.resolve(
+ values['output-dir'] ?? path.join(rootDir, 'mcp-heap-profiles', timestamp),
+ );
+ fs.mkdirSync(baseOutputDir, {recursive: true});
+
+ const sourceMapTestServer = await startSourceMapTestServer();
+ const targetUrl = values.url ?? sourceMapTestServer.url;
+
+ try {
+ console.log(
+ `Source map test server listening at: ${sourceMapTestServer.url}`,
+ );
+ if (values.url !== undefined) {
+ console.log(`Using custom target URL: ${targetUrl}`);
+ }
+ console.log(`Scenarios to run: ${scenarios.map(s => s.name).join(', ')}`);
+
+ const results: ScenarioResult[] = [];
+ for (const scenarioEntry of scenarios) {
+ const scenarioOutputDir =
+ scenarios.length === 1 && values['output-dir'] !== undefined
+ ? baseOutputDir
+ : path.join(baseOutputDir, scenarioEntry.name);
+
+ const scenarioArgs: ScenarioArgs = {
+ targetUrl,
+ outputDir: scenarioOutputDir,
+ };
+
+ const result = await profileScenario(
+ scenarioEntry,
+ scenarioArgs,
+ options,
+ rootDir,
+ );
+ results.push(result);
+ }
+
+ console.log('\n=== Summary ===');
+ for (const result of results) {
+ if (result.isGrowth) {
+ console.warn(result.summary);
+ } else {
+ console.log(result.summary);
+ }
+ }
+ } finally {
+ await sourceMapTestServer.close();
+ }
+}
+
+main().catch(error => {
+ console.error(error);
+ process.exitCode = 1;
+});
diff --git a/scripts/profile/scenarios/navigation.ts b/scripts/profile/scenarios/navigation.ts
new file mode 100644
index 00000000..51963b92
--- /dev/null
+++ b/scripts/profile/scenarios/navigation.ts
@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import path from 'node:path';
+
+import type {ScenarioArgs, ToolCall} from '../types.ts';
+
+export function get(args: ScenarioArgs): ToolCall[] {
+ return [
+ {
+ name: 'navigate_page',
+ arguments: {type: 'url', url: args.targetUrl},
+ },
+ {
+ name: 'navigate_page',
+ arguments: {type: 'url', url: args.targetUrl},
+ },
+ {
+ name: 'navigate_page',
+ arguments: {type: 'url', url: args.targetUrl},
+ },
+ {
+ name: 'navigate_page',
+ arguments: {type: 'url', url: args.targetUrl},
+ },
+ {
+ name: 'take_snapshot',
+ arguments: {},
+ },
+ {
+ name: 'take_screenshot',
+ arguments: {
+ filePath: path.join(args.outputDir, 'page.png'),
+ },
+ },
+ {
+ name: 'list_network_requests',
+ arguments: {},
+ },
+ ];
+}
diff --git a/scripts/profile/scenarios/page_churn.ts b/scripts/profile/scenarios/page_churn.ts
new file mode 100644
index 00000000..16117139
--- /dev/null
+++ b/scripts/profile/scenarios/page_churn.ts
@@ -0,0 +1,41 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {ScenarioArgs, ToolCall} from '../types.ts';
+import {selectedPageIdFromToolResult} from '../utils.ts';
+
+export function get(args: ScenarioArgs): ToolCall[] {
+ return [
+ {
+ name: 'new_page',
+ arguments: {url: args.targetUrl},
+ },
+ // Exercise the per-page collectors after its DevTools Universe has loaded
+ // all scripts and source maps.
+ {
+ name: 'take_snapshot',
+ arguments: {},
+ },
+ {
+ name: 'list_network_requests',
+ arguments: {},
+ },
+ {
+ name: 'close_page',
+ arguments: context => {
+ const newPageResult = context.results[0];
+ const pageId = selectedPageIdFromToolResult(newPageResult);
+ return {pageId};
+ },
+ },
+ // Force the MCP context to reconcile its page list before measuring. This
+ // prevents target-destruction event latency from looking like retention.
+ {
+ name: 'list_pages',
+ arguments: {},
+ },
+ ];
+}
diff --git a/scripts/profile/source_map_server.ts b/scripts/profile/source_map_server.ts
new file mode 100644
index 00000000..5302b57f
--- /dev/null
+++ b/scripts/profile/source_map_server.ts
@@ -0,0 +1,124 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import http from 'node:http';
+
+export interface SourceMapTestServer {
+ close(): Promise<void>;
+ url: string;
+}
+
+export function sourceMapFor(index: number): string {
+ return JSON.stringify({
+ version: 3,
+ file: `script-${index}.js`,
+ sources: [`source-${index}.ts`],
+ sourcesContent: [
+ `export function profileFunction${index}(value: number): number {\n return value + ${index};\n}\n`,
+ ],
+ names: [],
+ mappings: 'AAAA;AACA;AACA',
+ });
+}
+
+export function scriptFor(index: number): string {
+ return [
+ `function profileFunction${index}(value) {`,
+ ` return value + ${index};`,
+ '}',
+ 'globalThis.profileScriptResults ??= [];',
+ `globalThis.profileScriptResults.push(profileFunction${index}(${index}));`,
+ `//# sourceMappingURL=/maps/script-${index}.js.map`,
+ '',
+ ].join('\n');
+}
+
+export async function startSourceMapTestServer(
+ scriptCount = 100,
+): Promise<SourceMapTestServer> {
+ const scriptTags = Array.from(
+ {length: scriptCount},
+ (_, index) => `<script src="/scripts/script-${index}.js"></script>`,
+ ).join('\n');
+ const html = `<!doctype html>
+<html>
+ <head>
+ <meta charset="utf-8">
+ <title>Source map profiler fixture</title>
+ </head>
+ <body>
+ <h1>Source map profiler fixture</h1>
+ <p>${scriptCount} scripts, each with a distinct source map.</p>
+ ${scriptTags}
+ </body>
+</html>`;
+
+ const server = http.createServer((request, response) => {
+ const requestUrl = new URL(request.url ?? '/', 'http://127.0.0.1');
+ if (requestUrl.pathname === '/') {
+ response.writeHead(200, {
+ 'cache-control': 'no-store',
+ 'content-type': 'text/html; charset=utf-8',
+ });
+ response.end(html);
+ return;
+ }
+
+ const scriptMatch = /^\/scripts\/script-(\d+)\.js$/.exec(
+ requestUrl.pathname,
+ );
+ const mapMatch = /^\/maps\/script-(\d+)\.js\.map$/.exec(
+ requestUrl.pathname,
+ );
+ const match = scriptMatch ?? mapMatch;
+ const indexText = match?.[1];
+ const index = indexText === undefined ? -1 : Number(indexText);
+ if (!Number.isInteger(index) || index < 0 || index >= scriptCount) {
+ response.writeHead(404);
+ response.end('Not found');
+ return;
+ }
+
+ if (scriptMatch) {
+ response.writeHead(200, {
+ 'cache-control': 'no-store',
+ 'content-type': 'text/javascript; charset=utf-8',
+ });
+ response.end(scriptFor(index));
+ return;
+ }
+
+ response.writeHead(200, {
+ 'cache-control': 'no-store',
+ 'content-type': 'application/json; charset=utf-8',
+ });
+ response.end(sourceMapFor(index));
+ });
+
+ await new Promise<void>((resolve, reject) => {
+ server.once('error', reject);
+ server.listen(0, '127.0.0.1', resolve);
+ });
+ const address = server.address();
+ if (address === null || typeof address === 'string') {
+ server.close();
+ throw new Error('Source map test server did not expose a TCP port');
+ }
+
+ return {
+ url: `http://127.0.0.1:${address.port}`,
+ close: () =>
+ new Promise<void>((resolve, reject) => {
+ server.close(error => {
+ if (error) {
+ reject(error);
+ } else {
+ resolve();
+ }
+ });
+ }),
+ };
+}
diff --git a/scripts/profile/types.ts b/scripts/profile/types.ts
new file mode 100644
index 00000000..83b8541b
--- /dev/null
+++ b/scripts/profile/types.ts
@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export interface ScenarioArgs {
+ targetUrl: string;
+ outputDir: string;
+ [key: string]: unknown;
+}
+
+export interface ToolCallContext {
+ results: unknown[];
+}
+
+export type ToolArguments =
+ | Record<string, unknown>
+ | ((
+ context: ToolCallContext,
+ ) => Record<string, unknown> | Promise<Record<string, unknown>>);
+
+export interface ToolCall {
+ name: string;
+ arguments?: ToolArguments;
+}
+
+export interface ProfileScenario {
+ name?: string;
+ description?: string;
+ get: (args: ScenarioArgs) => ToolCall[] | Promise<ToolCall[]>;
+}
diff --git a/scripts/profile/utils.ts b/scripts/profile/utils.ts
new file mode 100644
index 00000000..1ca33e32
--- /dev/null
+++ b/scripts/profile/utils.ts
@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {ProfileScenario} from './types.ts';
+
+export function isObject(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value !== null;
+}
+
+export function formatBytes(bytes: number): string {
+ return `${(bytes / 1024 / 1024).toFixed(2)} MiB`;
+}
+
+export function parsePositiveInteger(
+ value: string | undefined,
+ name: string,
+): number {
+ if (value === undefined || !/^\d+$/.test(value)) {
+ throw new Error(`${name} must be a positive integer`);
+ }
+ const parsed = Number(value);
+ if (!Number.isSafeInteger(parsed) || parsed < 1) {
+ throw new Error(`${name} must be a positive integer`);
+ }
+ return parsed;
+}
+
+export function selectedPageIdFromToolResult(result: unknown): number {
+ if (isObject(result) && isObject(result.structuredContent)) {
+ const pages = result.structuredContent.pages;
+ if (Array.isArray(pages)) {
+ for (const page of pages) {
+ if (
+ isObject(page) &&
+ page.selected === true &&
+ typeof page.id === 'number'
+ ) {
+ return page.id;
+ }
+ }
+ }
+ }
+
+ if (isObject(result) && Array.isArray(result.content)) {
+ for (const content of result.content) {
+ if (!isObject(content) || typeof content.text !== 'string') {
+ continue;
+ }
+ const match = /^(\d+): .*\[selected\](?:\s|$)/m.exec(content.text);
+ const pageId = match?.[1];
+ if (pageId !== undefined) {
+ return Number(pageId);
+ }
+ }
+ }
+
+ throw new Error(
+ 'new_page did not identify the selected page in its response',
+ );
+}
+
+export function isScenarioModule(value: unknown): value is ProfileScenario {
+ return isObject(value) && typeof value.get === 'function';
+}
diff --git a/scripts/profile_mcp.ts b/scripts/profile_mcp.ts
deleted file mode 100644
index c5a90a8b..00000000
--- a/scripts/profile_mcp.ts
+++ /dev/null
@@ -1,557 +0,0 @@
-/**
- * @license
- * Copyright 2026 Google LLC
- * SPDX-License-Identifier: Apache-2.0
- */
-
-import fs from 'node:fs';
-import http from 'node:http';
-import path from 'node:path';
-import {parseArgs} from 'node:util';
-
-import {Client} from '@modelcontextprotocol/sdk/client/index.js';
-import {StdioClientTransport} from '@modelcontextprotocol/sdk/client/stdio.js';
-
-interface HeapUsage {
- usedSize: number;
- totalSize: number;
-}
-
-interface Measurement extends HeapUsage {
- label: string;
- timestamp: string;
-}
-
-interface ProfileOptions {
- iterations: number;
- pageChurn: boolean;
- sourceMapScriptCount: number;
- warmupIterations: number;
-}
-
-interface SourceMapTestServer {
- close(): Promise<void>;
- url: string;
-}
-
-interface PendingRequest {
- reject(error: Error): void;
- resolve(result: unknown): void;
-}
-
-function isObject(value: unknown): value is Record<string, unknown> {
- return typeof value === 'object' && value !== null;
-}
-
-function formatBytes(bytes: number): string {
- return `${(bytes / 1024 / 1024).toFixed(2)} MiB`;
-}
-
-function parsePositiveInteger(value: string | undefined, name: string): number {
- if (value === undefined || !/^\d+$/.test(value)) {
- throw new Error(`${name} must be a positive integer`);
- }
- const parsed = Number(value);
- if (!Number.isSafeInteger(parsed) || parsed < 1) {
- throw new Error(`${name} must be a positive integer`);
- }
- return parsed;
-}
-
-function selectedPageIdFromToolResult(result: unknown): number {
- if (isObject(result) && isObject(result.structuredContent)) {
- const pages = result.structuredContent.pages;
- if (Array.isArray(pages)) {
- for (const page of pages) {
- if (
- isObject(page) &&
- page.selected === true &&
- typeof page.id === 'number'
- ) {
- return page.id;
- }
- }
- }
- }
-
- if (isObject(result) && Array.isArray(result.content)) {
- for (const content of result.content) {
- if (!isObject(content) || typeof content.text !== 'string') {
- continue;
- }
- const match = /^(\d+): .*\[selected\](?:\s|$)/m.exec(content.text);
- const pageId = match?.[1];
- if (pageId !== undefined) {
- return Number(pageId);
- }
- }
- }
-
- throw new Error(
- 'new_page did not identify the selected page in its response',
- );
-}
-
-function sourceMapFor(index: number): string {
- return JSON.stringify({
- version: 3,
- file: `script-${index}.js`,
- sources: [`source-${index}.ts`],
- sourcesContent: [
- `export function profileFunction${index}(value: number): number {\n return value + ${index};\n}\n`,
- ],
- names: [],
- mappings: 'AAAA;AACA;AACA',
- });
-}
-
-function scriptFor(index: number): string {
- return [
- `function profileFunction${index}(value) {`,
- ` return value + ${index};`,
- '}',
- 'globalThis.profileScriptResults ??= [];',
- `globalThis.profileScriptResults.push(profileFunction${index}(${index}));`,
- `//# sourceMappingURL=/maps/script-${index}.js.map`,
- '',
- ].join('\n');
-}
-
-async function startSourceMapTestServer(
- scriptCount: number,
-): Promise<SourceMapTestServer> {
- const scriptTags = Array.from(
- {length: scriptCount},
- (_, index) => `<script src="/scripts/script-${index}.js"></script>`,
- ).join('\n');
- const html = `<!doctype html>
-<html>
- <head>
- <meta charset="utf-8">
- <title>Source map profiler fixture</title>
- </head>
- <body>
- <h1>Source map profiler fixture</h1>
- <p>${scriptCount} scripts, each with a distinct source map.</p>
- ${scriptTags}
- </body>
-</html>`;
-
- const server = http.createServer((request, response) => {
- const requestUrl = new URL(request.url ?? '/', 'http://127.0.0.1');
- if (requestUrl.pathname === '/') {
- response.writeHead(200, {
- 'cache-control': 'no-store',
- 'content-type': 'text/html; charset=utf-8',
- });
- response.end(html);
- return;
- }
-
- const scriptMatch = /^\/scripts\/script-(\d+)\.js$/.exec(
- requestUrl.pathname,
- );
- const mapMatch = /^\/maps\/script-(\d+)\.js\.map$/.exec(
- requestUrl.pathname,
- );
- const match = scriptMatch ?? mapMatch;
- const indexText = match?.[1];
- const index = indexText === undefined ? -1 : Number(indexText);
- if (!Number.isInteger(index) || index < 0 || index >= scriptCount) {
- response.writeHead(404);
- response.end('Not found');
- return;
- }
-
- if (scriptMatch) {
- response.writeHead(200, {
- 'cache-control': 'no-store',
- 'content-type': 'text/javascript; charset=utf-8',
- });
- response.end(scriptFor(index));
- return;
- }
-
- response.writeHead(200, {
- 'cache-control': 'no-store',
- 'content-type': 'application/json; charset=utf-8',
- });
- response.end(sourceMapFor(index));
- });
-
- await new Promise<void>((resolve, reject) => {
- server.once('error', reject);
- server.listen(0, '127.0.0.1', resolve);
- });
- const address = server.address();
- if (address === null || typeof address === 'string') {
- server.close();
- throw new Error('Source map test server did not expose a TCP port');
- }
-
- return {
- url: `http://127.0.0.1:${address.port}`,
- close: () =>
- new Promise<void>((resolve, reject) => {
- server.close(error => {
- if (error) {
- reject(error);
- } else {
- resolve();
- }
- });
- }),
- };
-}
-
-class InspectorClient {
- readonly #pending = new Map<number, PendingRequest>();
- #nextId = 1;
- #snapshotStream: fs.WriteStream | undefined;
- readonly #webSocket: WebSocket;
-
- private constructor(webSocket: WebSocket) {
- this.#webSocket = webSocket;
- webSocket.addEventListener('message', event => {
- this.#handleMessage(event.data);
- });
- }
-
- static connect(url: string): Promise<InspectorClient> {
- return new Promise((resolve, reject) => {
- const webSocket = new WebSocket(url);
- webSocket.addEventListener('open', () => {
- resolve(new InspectorClient(webSocket));
- });
- webSocket.addEventListener('error', () => {
- reject(new Error(`Failed to connect to Node inspector at ${url}`));
- });
- });
- }
-
- #handleMessage(data: unknown): void {
- if (typeof data !== 'string') {
- return;
- }
- const message: unknown = JSON.parse(data);
- if (!isObject(message)) {
- return;
- }
-
- if (message.method === 'HeapProfiler.addHeapSnapshotChunk') {
- const params = message.params;
- if (
- this.#snapshotStream &&
- isObject(params) &&
- typeof params.chunk === 'string'
- ) {
- this.#snapshotStream.write(params.chunk);
- }
- return;
- }
-
- if (typeof message.id !== 'number') {
- return;
- }
- const pending = this.#pending.get(message.id);
- if (!pending) {
- return;
- }
- this.#pending.delete(message.id);
- if (isObject(message.error)) {
- const errorMessage =
- typeof message.error.message === 'string'
- ? message.error.message
- : 'Unknown inspector error';
- pending.reject(new Error(errorMessage));
- return;
- }
- pending.resolve(message.result);
- }
-
- send(method: string, params?: Record<string, unknown>): Promise<unknown> {
- const id = this.#nextId++;
- return new Promise((resolve, reject) => {
- this.#pending.set(id, {resolve, reject});
- this.#webSocket.send(JSON.stringify({id, method, params}));
- });
- }
-
- async getHeapUsage(): Promise<HeapUsage> {
- await this.send('HeapProfiler.collectGarbage');
- const result = await this.send('Runtime.getHeapUsage');
- if (
- !isObject(result) ||
- typeof result.usedSize !== 'number' ||
- typeof result.totalSize !== 'number'
- ) {
- throw new Error('Node inspector returned invalid heap usage data');
- }
- return {usedSize: result.usedSize, totalSize: result.totalSize};
- }
-
- async takeHeapSnapshot(filePath: string): Promise<void> {
- const stream = fs.createWriteStream(filePath, {encoding: 'utf8'});
- this.#snapshotStream = stream;
- try {
- await this.send('HeapProfiler.takeHeapSnapshot', {reportProgress: false});
- } finally {
- this.#snapshotStream = undefined;
- await new Promise<void>((resolve, reject) => {
- stream.end(resolve);
- stream.on('error', reject);
- });
- }
- }
-
- close(): void {
- this.#webSocket.close();
- }
-}
-
-function inspectorUrlFrom(transport: StdioClientTransport): Promise<string> {
- const stderr = transport.stderr;
- if (!stderr) {
- throw new Error('MCP server stderr is unavailable');
- }
- return new Promise((resolve, reject) => {
- let buffered = '';
- const timeout = setTimeout(() => {
- reject(
- new Error(
- `Timed out waiting for the Node inspector URL. Server stderr: ${buffered}`,
- ),
- );
- }, 10_000);
- stderr.setEncoding('utf8');
- stderr.on('data', chunk => {
- if (typeof chunk !== 'string') {
- return;
- }
- buffered += chunk;
- const match = /Debugger listening on (ws:\/\/\S+)/.exec(buffered);
- const url = match?.[1];
- if (url) {
- clearTimeout(timeout);
- resolve(url);
- }
- });
- });
-}
-
-async function main(): Promise<void> {
- const {values} = parseArgs({
- options: {
- url: {type: 'string', default: 'https://developers.google.com'},
- 'output-dir': {type: 'string'},
- iterations: {type: 'string', default: '10'},
- 'page-churn': {type: 'boolean', default: false},
- 'source-map-test-page': {type: 'boolean', default: false},
- 'source-map-script-count': {type: 'string', default: '100'},
- 'warmup-iterations': {type: 'string', default: '10'},
- },
- });
- const options: ProfileOptions = {
- iterations: parsePositiveInteger(values.iterations, '--iterations'),
- pageChurn: values['page-churn'],
- sourceMapScriptCount: parsePositiveInteger(
- values['source-map-script-count'],
- '--source-map-script-count',
- ),
- warmupIterations: parsePositiveInteger(
- values['warmup-iterations'],
- '--warmup-iterations',
- ),
- };
- 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-heap-profiles', timestamp),
- );
- fs.mkdirSync(outputDir, {recursive: true});
-
- const sourceMapTestServer =
- values['source-map-test-page'] || options.pageChurn
- ? await startSourceMapTestServer(options.sourceMapScriptCount)
- : undefined;
- const targetUrl = sourceMapTestServer?.url ?? values.url;
-
- const env: Record<string, string> = {};
- for (const [key, value] of Object.entries(process.env)) {
- if (value !== undefined) {
- env[key] = value;
- }
- }
- env.CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS = 'true';
-
- const transport = new StdioClientTransport({
- command: process.execPath,
- args: [
- '--inspect=127.0.0.1:0',
- path.join(rootDir, 'build/src/bin/chrome-devtools-mcp.js'),
- '--headless',
- '--isolated',
- ],
- env,
- stderr: 'pipe',
- });
- const inspectorUrlPromise = inspectorUrlFrom(transport);
- const client = new Client(
- {name: 'mcp-heap-profiler', version: '1.0.0'},
- {capabilities: {}},
- );
- let inspector: InspectorClient | undefined;
- const measurements: Measurement[] = [];
-
- const runNavigationIteration = async (): Promise<void> => {
- await client.callTool({
- name: 'navigate_page',
- arguments: {type: 'url', url: targetUrl},
- });
- await client.callTool({
- name: 'navigate_page',
- arguments: {type: 'url', url: targetUrl},
- });
- await client.callTool({
- name: 'navigate_page',
- arguments: {type: 'url', url: targetUrl},
- });
- await client.callTool({
- name: 'navigate_page',
- arguments: {type: 'url', url: targetUrl},
- });
- await client.callTool({name: 'take_snapshot', arguments: {}});
- await client.callTool({
- name: 'take_screenshot',
- arguments: {
- filePath: path.join(outputDir, 'page.png'),
- },
- });
- await client.callTool({name: 'list_network_requests', arguments: {}});
- };
-
- const runPageChurnIteration = async (): Promise<void> => {
- const result = await client.callTool({
- name: 'new_page',
- arguments: {url: targetUrl},
- });
- const pageId = selectedPageIdFromToolResult(result);
-
- // Exercise the per-page collectors after its DevTools Universe has loaded
- // all scripts and source maps.
- await client.callTool({name: 'take_snapshot', arguments: {}});
- await client.callTool({name: 'list_network_requests', arguments: {}});
-
- await client.callTool({
- name: 'close_page',
- arguments: {pageId},
- });
- // Force the MCP context to reconcile its page list before measuring. This
- // prevents target-destruction event latency from looking like retention.
- await client.callTool({name: 'list_pages', arguments: {}});
- };
-
- const runIteration = options.pageChurn
- ? runPageChurnIteration
- : runNavigationIteration;
-
- const record = async (
- label: string,
- takeSnapshot: boolean,
- ): Promise<void> => {
- if (!inspector) {
- throw new Error('Inspector is not connected');
- }
- const usage = await inspector.getHeapUsage();
- const measurement = {
- label,
- timestamp: new Date().toISOString(),
- ...usage,
- };
- measurements.push(measurement);
- console.log(
- `${label}: used ${formatBytes(usage.usedSize)}, total ${formatBytes(usage.totalSize)}`,
- );
- if (!takeSnapshot) {
- return;
- }
- const snapshotPath = path.join(outputDir, `${label}.heapsnapshot`);
- await inspector.takeHeapSnapshot(snapshotPath);
- console.log(` snapshot: ${snapshotPath}`);
- };
-
- try {
- await client.connect(transport);
- inspector = await InspectorClient.connect(await inspectorUrlPromise);
- console.log(`MCP server PID: ${transport.pid}`);
- console.log(`Target URL: ${targetUrl}`);
- if (sourceMapTestServer) {
- console.log(
- `Source map test page: ${options.sourceMapScriptCount} scripts`,
- );
- }
- console.log(
- `Workload: ${options.pageChurn ? 'create and close mapped-script pages' : 'repeated navigation'}`,
- );
- console.log(`Output directory: ${outputDir}`);
-
- await record('connected', false);
- for (
- let iteration = 1;
- iteration <= options.warmupIterations;
- iteration++
- ) {
- console.log(`Warm-up ${iteration}/${options.warmupIterations}`);
- await runIteration();
- }
-
- // Taking a heap snapshot exercises Node inspector and serialization paths.
- // Prime those paths before capturing the baseline so their JIT-compiled code
- // is not mistaken for workload growth in the final comparison.
- await record('snapshot-primer', true);
- await record('baseline', true);
-
- for (let iteration = 1; iteration <= options.iterations; iteration++) {
- console.log(`Measured iteration ${iteration}/${options.iterations}`);
- await runIteration();
- await record(`iteration-${iteration}`, false);
- }
- await record('final', true);
-
- const baseline = measurements.find(
- measurement => measurement.label === 'baseline',
- );
- const final = measurements.find(
- measurement => measurement.label === 'final',
- );
- if (baseline && final) {
- const growth = final.usedSize - baseline.usedSize;
- if (growth > 0) {
- const percentage = (growth / baseline.usedSize) * 100;
- console.warn(
- `The MCP heap grew by ${formatBytes(growth)} (${percentage.toFixed(2)}%) across ${options.iterations} measured iterations. Compare baseline.heapsnapshot with final.heapsnapshot to determine whether retained workload objects accumulated.`,
- );
- } else {
- console.log(
- `The MCP heap did not grow across the measured iterations (${formatBytes(growth)}).`,
- );
- }
- }
-
- const reportPath = path.join(outputDir, 'heap-usage.json');
- fs.writeFileSync(
- reportPath,
- `${JSON.stringify({pid: transport.pid, url: targetUrl, options, measurements}, null, 2)}\n`,
- );
- console.log(`Report: ${reportPath}`);
- } finally {
- inspector?.close();
- await client.close();
- await sourceMapTestServer?.close();
- }
-}
-
-main().catch(error => {
- console.error(error);
- process.exitCode = 1;
-});