Chrome DevTools for coding agents
feat: add experimentalGcfFormat flag for GCF-encoded tool responses (#2235)
Dayna Blackwell3d2138945c7d
diff --git a/package-lock.json b/package-lock.jsonindex 01c920a2..d5eb68c8 100644--- a/package-lock.json+++ b/package-lock.json@@ -13,6 +13,7 @@"chrome-devtools-mcp": "build/src/bin/chrome-devtools-mcp.js"},"devDependencies": {+ "@blackwell-systems/gcf": "^2.2.2","@eslint/js": "^9.35.0","@google/genai": "^2.0.1","@modelcontextprotocol/sdk": "1.29.0",@@ -53,14 +54,28 @@"node": "^20.19.0 || ^22.12.0 || >=23"},"peerDependencies": {+ "@blackwell-systems/gcf": "^2.2.2","@toon-format/toon": "^2.2.0"},"peerDependenciesMeta": {+ "@blackwell-systems/gcf": {+ "optional": true+ },"@toon-format/toon": {"optional": true}}},+ "node_modules/@blackwell-systems/gcf": {+ "version": "2.2.2",+ "resolved": "https://registry.npmjs.org/@blackwell-systems/gcf/-/gcf-2.2.2.tgz",+ "integrity": "sha512-b35EeiMiopwLpgphMVaiVVS5KS88FT/LUt2XsYG5iRKEYl7/p8L23zBMJ2ggh/Ha6USwU92uFu8fTahH0s6q+Q==",+ "dev": true,+ "license": "MIT",+ "bin": {+ "gcf": "dist/cli.js"+ }+ },"node_modules/@emnapi/core": {"version": "1.5.0","resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.5.0.tgz",diff --git a/package.json b/package.jsonindex 30ff6c21..6b9cf51d 100644--- a/package.json+++ b/package.json@@ -55,6 +55,7 @@"@rollup/plugin-json": "^6.1.0","@rollup/plugin-node-resolve": "^16.0.3","@stylistic/eslint-plugin": "^5.4.0",+ "@blackwell-systems/gcf": "^2.2.2","@toon-format/toon": "^2.2.0","@types/debug": "^4.1.12","@types/filesystem": "^0.0.36",@@ -85,11 +86,15 @@"yargs": "18.0.0"},"peerDependencies": {- "@toon-format/toon": "^2.2.0"+ "@toon-format/toon": "^2.2.0",+ "@blackwell-systems/gcf": "^2.2.2"},"peerDependenciesMeta": {"@toon-format/toon": {"optional": true+ },+ "@blackwell-systems/gcf": {+ "optional": true}},"engines": {diff --git a/rollup.config.mjs b/rollup.config.mjsindex d1ed52c6..0a15c51b 100644--- a/rollup.config.mjs+++ b/rollup.config.mjs@@ -284,6 +284,13 @@ export default [return true;}+ if (+ source === '@blackwell-systems/gcf' ||+ source.startsWith('@blackwell-systems/gcf/')+ ) {+ return true;+ }+const existingExternals = ['./bidi.js','../bidi/bidi.js',diff --git a/src/McpResponse.ts b/src/McpResponse.tsindex 3b70bd2d..a7640155 100644--- a/src/McpResponse.ts+++ b/src/McpResponse.ts@@ -25,7 +25,12 @@ import type {McpContext} from './McpContext.js';import type {McpPage} from './McpPage.js';import {UncaughtError} from './PageCollector.js';import {TextSnapshot} from './TextSnapshot.js';-import {DevTools, getToonEncode, type Protocol} from './third_party/index.js';+import {+ DevTools,+ getToonEncode,+ getGcfEncode,+ type Protocol,+} from './third_party/index.js';import type {ConsoleMessage,ImageContent,@@ -50,6 +55,8 @@ import {paginate} from './utils/pagination.js';import type {PaginationOptions} from './utils/types.js';import type {WaitForEventsResult} from './WaitForHelper.js';+export type DataFormat = 'default' | 'toon' | 'gcf';+interface TraceInsightData {trace: TraceResult;insightSetId: string;@@ -565,7 +572,7 @@ export class McpResponse implements Response {async handle(toolName: string,context: McpContext,- useToon = false,+ dataFormat: DataFormat = 'default',): Promise<{content: Array<TextContent | ImageContent>;structuredContent: object;@@ -813,7 +820,7 @@ export class McpResponse implements Response {webmcpTools,errorMessage: this.#error?.message,},- useToon,+ dataFormat,);}@@ -834,7 +841,7 @@ export class McpResponse implements Response {webmcpTools?: WebMCPTool[];errorMessage?: string;},- useToon: boolean,+ dataFormat: DataFormat = 'default',): Promise<{content: Array<TextContent | ImageContent>;structuredContent: object;@@ -885,18 +892,30 @@ export class McpResponse implements Response {geolocation?: {latitude: number; longitude: number};} = {};- let toonEncode: ((val: unknown) => string) | undefined;- if (useToon) {+ // Resolve the compact encoder based on the chosen format+ let compactEncode: ((val: unknown) => string) | undefined;+ if (dataFormat === 'toon') {try {- toonEncode = await getToonEncode();+ compactEncode = await getToonEncode();} catch {throw new Error(- 'The `@toon-format/toon` package is required to use the experimental TOON format. ' ++ 'The `@toon-format/toon` package is required to use --experimentalDataFormat=toon. ' +'Make sure the peer dependency is installed:\n' +- '- For npx: npx --package chrome-devtools-mcp@latest --package @toon-format/toon@latest chrome-devtools-mcp --experimentalToonFormat\n' ++ '- For npx: npx --package chrome-devtools-mcp@latest --package @toon-format/toon@latest chrome-devtools-mcp --experimentalDataFormat=toon\n' +'- For npm: npm install @toon-format/toon (add -g if installed globally)',);}+ } else if (dataFormat === 'gcf') {+ try {+ compactEncode = await getGcfEncode();+ } catch {+ throw new Error(+ 'The `@blackwell-systems/gcf` package is required to use --experimentalDataFormat=gcf. ' ++ 'Make sure the peer dependency is installed:\n' ++ '- For npx: npx --package chrome-devtools-mcp@latest --package @blackwell-systems/gcf@latest chrome-devtools-mcp --experimentalDataFormat=gcf\n' ++ '- For npm: npm install @blackwell-systems/gcf (add -g if installed globally)',+ );+ }}const response = [];@@ -1117,8 +1136,8 @@ Call ${handleDialog.name} to handle it before continuing.`);structuredContent.snapshot = data.snapshot.toJSON();response.push('## Latest page snapshot');response.push(- useToon && toonEncode- ? toonEncode(structuredContent.snapshot)+ compactEncode+ ? compactEncode(structuredContent.snapshot): data.snapshot.toString(),);}@@ -1155,8 +1174,8 @@ Call ${handleDialog.name} to handle it before continuing.`);structuredContent.heapSnapshotData = formatter.toJSON();response.push(- useToon && toonEncode- ? toonEncode(structuredContent.heapSnapshotData)+ compactEncode+ ? compactEncode(structuredContent.heapSnapshotData): formatter.toString(),);}@@ -1220,8 +1239,8 @@ Call ${handleDialog.name} to handle it before continuing.`);if (classDiffs) {response.push('### Heap Snapshot Diff');response.push(- useToon && toonEncode- ? toonEncode(classDiffs)+ compactEncode+ ? compactEncode(classDiffs): HeapSnapshotFormatter.formatDiffSummary(classDiffs),);structuredContent.heapSnapshotClassDiffs = classDiffs;@@ -1230,8 +1249,8 @@ Call ${handleDialog.name} to handle it before continuing.`);if (detailedClassDiff) {response.push('### Heap Snapshot Detailed Diff');response.push(- useToon && toonEncode- ? toonEncode(detailedClassDiff)+ compactEncode+ ? compactEncode(detailedClassDiff): HeapSnapshotFormatter.formatDiffDetails(detailedClassDiff),);structuredContent.heapSnapshotDetailedClassDiff = detailedClassDiff;@@ -1342,8 +1361,8 @@ Call ${handleDialog.name} to handle it before continuing.`);i.toJSON(),);response.push(- ...(useToon && toonEncode- ? [toonEncode(structuredContent.networkRequests)]+ ...(compactEncode+ ? [compactEncode(structuredContent.networkRequests)]: paginationData.items.map(i => i.toString())),);}@@ -1367,8 +1386,8 @@ Call ${handleDialog.name} to handle it before continuing.`);item.toJSON(),);response.push(...paginationData.info);- if (useToon && toonEncode) {- response.push(toonEncode(structuredContent.consoleMessages));+ if (compactEncode) {+ response.push(compactEncode(structuredContent.consoleMessages));} else {response.push(...paginationData.items.map(item => item.toString()));}diff --git a/src/ToolHandler.ts b/src/ToolHandler.tsindex 68de0308..d84d9b89 100644--- a/src/ToolHandler.ts+++ b/src/ToolHandler.ts@@ -7,6 +7,7 @@import type {parseArguments} from './bin/chrome-devtools-mcp-cli-options.js';import {logger} from './logger.js';import type {McpContext} from './McpContext.js';+import type {DataFormat} from './McpResponse.js';import {McpResponse} from './McpResponse.js';import type {Mutex} from './Mutex.js';import {SlimMcpResponse} from './SlimMcpResponse.js';@@ -259,10 +260,18 @@ export class ToolHandler {} catch (err) {response.setError(err);}+ // Resolve data format: --experimentalDataFormat takes precedence, fall back to legacy --experimentalToonFormat+ let dataFormat: DataFormat = 'default';+ if (this.serverArgs.experimentalDataFormat) {+ dataFormat = this.serverArgs.experimentalDataFormat as DataFormat;+ } else if (this.serverArgs.experimentalToonFormat) {+ dataFormat = 'toon';+ }+const {content, structuredContent} = await response.handle(this.tool.name,context,- this.serverArgs.experimentalToonFormat ?? false,+ dataFormat,);const result: CallToolResult & {structuredContent?: Record<string, unknown>;diff --git a/src/bin/chrome-devtools-mcp-cli-options.ts b/src/bin/chrome-devtools-mcp-cli-options.tsindex 33a10ea3..5d0bedd5 100644--- a/src/bin/chrome-devtools-mcp-cli-options.ts+++ b/src/bin/chrome-devtools-mcp-cli-options.ts@@ -173,7 +173,14 @@ export const cliOptions = {experimentalToonFormat: {type: 'boolean',describe:- 'Whether to format structured data in text response using Token-Oriented Object Notation (requires @toon-format/toon). If running via npx, use: npx --package chrome-devtools-mcp@latest --package @toon-format/toon@latest chrome-devtools-mcp --experimentalToonFormat',+ 'Deprecated: use --experimentalDataFormat=toon instead. Whether to format structured data using TOON (requires @toon-format/toon).',+ hidden: true,+ },+ experimentalDataFormat: {+ type: 'string',+ describe:+ 'Override format for structured data in text responses. Default uses built-in formatters. "toon" (requires @toon-format/toon) or "gcf" (requires @blackwell-systems/gcf) replace structured content with the specified encoding.',+ choices: ['default', 'toon', 'gcf'] as const,hidden: true,},experimentalIncludeAllPages: {diff --git a/src/telemetry/flag_usage_metrics.json b/src/telemetry/flag_usage_metrics.jsonindex 635009be..64c11120 100644--- a/src/telemetry/flag_usage_metrics.json+++ b/src/telemetry/flag_usage_metrics.json@@ -347,5 +347,19 @@{"name": "screenshot_max_height_present","flagType": "boolean"+ },+ {+ "name": "experimental_data_format_present",+ "flagType": "boolean"+ },+ {+ "name": "experimental_data_format",+ "flagType": "enum",+ "choices": [+ "EXPERIMENTAL_DATA_FORMAT_UNSPECIFIED",+ "EXPERIMENTAL_DATA_FORMAT_DEFAULT",+ "EXPERIMENTAL_DATA_FORMAT_TOON",+ "EXPERIMENTAL_DATA_FORMAT_GCF"+ ]}]diff --git a/src/third_party/index.ts b/src/third_party/index.tsindex 222f1499..e9e6cfc3 100644--- a/src/third_party/index.ts+++ b/src/third_party/index.ts@@ -61,6 +61,10 @@ export async function getToonEncode(): Promise<(val: unknown) => string> {const {encode} = await import('@toon-format/toon');return encode;}+export async function getGcfEncode(): Promise<(val: unknown) => string> {+ const {encodeGeneric} = await import('@blackwell-systems/gcf');+ return encodeGeneric;+}import {snapshot as snapshotImpl,