Skip to content

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.json
index 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.json
index 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.mjs
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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,