feat: add experimentalGcfFormat flag for GCF-encoded tool responses

[blackwell-systems]

Summary

Add --experimentalGcfFormat as a hidden experimental flag alongside the existing --experimentalToonFormat. When enabled, tool responses encode structured data using GCF (Graph Compact Format) instead of formatted JSON. No changes to existing behavior or default output.

Why

Benchmarked on Chrome DevTools data shapes

Data shapes verified from source code and test snapshots (ConsoleMessageConcise, NetworkRequestConcise, HeapSnapshotFormatter.toJSON(), SnapshotFormatter.toJSON()):

Dataset	JSON	TOON	GCF	TOON vs JSON	GCF vs JSON	GCF vs TOON
Console (100)	2,534	1,716	1,663	32.3%	34.4%	+3.1%
Console (500)	12,879	8,761	8,475	32.0%	34.2%	+3.3%
Network (100)	3,287	1,776	1,682	46.0%	48.8%	+5.3%
Network (500)	16,547	8,936	8,442	46.0%	49.0%	+5.5%
Heap (100)	2,210	797	753	63.9%	65.9%	+5.5%
DOM (3x3)	282	295	244	-4.6%	13.5%	+17.3%
DOM (4x3)	396	464	407	-17.2%	-2.8%	+12.3%

TOON increases token count on DOM snapshots (-4.6% to -17.2% vs JSON). GCF saves tokens on every data type.

Console message corruption

TOON's decoder crashes on console messages containing bracket-colon patterns, which are standard browser output:

[Error]: net::ERR_CONNECTION_REFUSED
[React DevTools]: Component rendered 3 times
[Violation]: Forced reflow while executing JavaScript took 42ms
[Performance]: Long task detected (duration: 234ms)

10 of 20 console messages fail TOON round-trip. GCF: zero failures. While Chrome DevTools MCP encodes only (no decode), the structurally ambiguous output can affect downstream consumers.

LLM comprehension

GCF scores 100% on general structured data and 90.7% on adversarial payloads across GPT-4o, GPT-5.5, Claude, and Gemini. JSON scores 53.6%. TOON scores 68.5%. (1,700+ evaluations.)

Full eval data: GCF benchmarks

Data integrity

GCF verified lossless across 43 billion+ round-trips in 5 formats and 6 languages. Zero failures. Zero runtime dependencies.

Implementation

Mirrors the existing experimentalToonFormat pattern exactly:

• Hidden boolean CLI flag, defaults to false
• useGcf parameter threaded through handle() → format()
• compactEncode helper selects GCF, TOON, or null (formatted JSON)
• GCF takes precedence if both flags are set

Changes

File	Change
src/bin/chrome-devtools-mcp-cli-options.ts	Add experimentalGcfFormat flag
src/third_party/index.ts	Export gcfEncode from @blackwell-systems/gcf
src/McpResponse.ts	Add useGcf parameter, compactEncode helper
src/ToolHandler.ts	Pass experimentalGcfFormat to handle()
package.json	Add @blackwell-systems/gcf (pinned 2.1.2, zero deps)

Links

• GCF spec: https://gcformat.com
• TypeScript SDK: https://www.npmjs.com/package/@blackwell-systems/gcf
• Benchmarks: https://gcformat.com/guide/benchmarks
• Lossless verification: https://gcformat.com/guide/lossless-verification

[zyzyzyryxy]

Thank you for the contribution and detailed benchmarking!

I left some comments to be addressed, but overall GCF idea looks good.

[zyzyzyryxy]

TOON and GCF experiments are mutually exclusive, we should be explicit about this. Either replace both experimental...Format flags with a single one with enum values or at least add checks and/or appropriate message handling the case both are used together.

[zyzyzyryxy]

I just moved TOON dependency to be optional in #2260, I think this PR should follow suit - we should not force on all users a dependency that's only needed for an experiment.

[zyzyzyryxy]

Regardless if two flags will stay or you merge them, we should resolve them into a single enum choice on the top level.

[zyzyzyryxy]

You need to regenerate package-lock.json after this change.

[blackwell-systems]

Thanks for the detailed review @zyzyzyryxy! I've addressed all four points.

Rebased on top of #2260 (TOON optional dep) and reworked the approach:

1. Single enum: Replaced both experimentalToonFormat and experimentalGcfFormat boolean flags with --experimentalDataFormat=json|toon|gcf. The legacy --experimentalToonFormat still works via fallback for backward compatibility.

2. Optional peer dependency: @blackwell-systems/gcf is now an optional peer dep using dynamic import() via getGcfEncode(), following the exact pattern from chore: make TOON dependency optional #2260.

3. Single encoder resolution: ToolHandler resolves the format choice into one dataFormat string, McpResponse.format() resolves it into one compactEncode function at the top. No more dual-boolean checks.

4. package-lock.json: Regenerated.

5. Rollup externals: Added @blackwell-systems/gcf.

Force-pushed with the reworked changes.