feat(screenshot): add CLI options to cap screenshot size at the source

[antoinekm]

Summary

Adds opt-in CLI flags so operators can cap the size of screenshots returned by take_screenshot before they are embedded in the MCP response. Refs #879.

The flags address two related symptoms reported when MCP clients display screenshots inline:

1. Per-image dimension limit: hosted LLM APIs commonly reject images exceeding per-image dimension constraints (typical caps are in the 2000-8000 px range, sometimes scaling down further when many images are in the same request). This is the exact error reported in Claude errors if the image dimensions exceed 8000 pixels #879.
2. Cumulative request size: after many captures, the cumulative base64 payload eventually pushes a request over the per-call body size limit imposed by the LLM API.

Both can be mitigated at the source by reducing format/quality and downscaling the capture.

New flags (all opt-in)

• --screenshot-format <jpeg|png|webp>: override the default format used by take_screenshot when the caller does not specify one
• --screenshot-quality <0-100>: override the default JPEG/WebP quality. Ignored for PNG
• --screenshot-max-width <px>: downscale screenshots wider than this before they are returned
• --screenshot-max-height <px>: downscale screenshots taller than this. Combines with --screenshot-max-width; the smaller scale wins so both bounds are respected while preserving aspect ratio

For the exact error in #879, the recipe is --screenshot-max-width=8000 --screenshot-max-height=8000 (or a smaller value such as 2000 if many images may end up in the same request, depending on the operator's chosen API).

Implementation

• Resizing leverages Puppeteer's clip.scale (CDP Page.captureScreenshot), so no new dependencies.
• Source dimensions per capture mode:
  • viewport: page.viewport()
  • full page: document.documentElement.scrollWidth/scrollHeight via page.evaluate()
  • element (uid): elementHandle.boundingBox()
• For element and full-page captures with a downscale clip, the call routes through page.screenshot({clip}) so the scale parameter applies. captureBeyondViewport is left to Puppeteer's default (true when a clip is set), preserving correct behavior for elements below the fold and full-page captures.
• ~150 lines of source code, ~200 lines of new tests.

Backwards compatibility

Fully opt-in: when no flags are set, take_screenshot returns the exact same bytes as before. No behavioral change for existing users.

Design alignment

• Aligned with the "Reference over Value" principle in docs/design-principles.md: the existing 2 MB threshold still routes oversized screenshots to a temporary file. This change only reduces the size of the inline base64 fallback path, which the principles document calls out as an acceptable exception when MCP clients display images natively.
• The MCP server hardcodes no LLM-specific size limits. Operators pick the values that match their client/model combination. This keeps the maintenance surface here minimal as model limits evolve, and is intended as a complement to, not a replacement for, fixes in the MCP client itself.

Addressing concerns raised in #879

"It's not feasible for us to maintain this. Limits will change when models change." (@natorion)

The flags are pure parameters; nothing about the upstream LLM is encoded in the server. When a vendor raises (or lowers) a limit, no code change is needed here, only the operator's CLI args change.

"filePath / page_resize already work as a workaround." (@OrKoN)

filePath is great when the call site knows it's about to take a huge screenshot, but as you noted earlier in the thread, an oversized image already in the request history keeps causing failures even on subsequent calls. page_resize works but mutates the page being debugged. The resize in this PR happens between Puppeteer and the MCP response, so the inspected page is untouched and the failure mode is prevented at the source.

"Should be fixed client side."

Agreed, this PR is intended as a complement, not a substitute. A client-side fix (e.g. compaction evicts/downsamples old images) handles the cumulative case for any MCP. A server-side cap handles the per-call dimension limit for users who hit it before compaction can kick in. The two address overlapping but distinct failure modes.

Happy to drop or rework any of this if the maintainers prefer a different shape, for example making the threshold automatic from a single --max-image-bytes knob, or rejecting the PR entirely in favor of waiting for a client-side fix. Just wanted to put a concrete option on the table.

Tests

Added 6 new tests:

• honors screenshotFormat default from CLI args
• keeps "png" as default format when no CLI override is set
• downscales viewport screenshot when screenshotMaxWidth is set
• downscales using the smaller scale when both max-width and max-height are set
• does not resize when source is smaller than the max bounds
• downscales full page screenshot when screenshotMaxWidth is set

All 627 tests in the suite pass. npm run typecheck and npm run check-format are clean.

Notes for reviewers

• The dimensions compared against --screenshot-max-width/height are CSS pixels (page.viewport()), not raw bitmap pixels. With deviceScaleFactor > 1 (HiDPI emulation) the actual bitmap may still be larger. Happy to clarify this in the option description if preferred.
• For element captures with a downscale clip, the call routes through page.screenshot({clip}) instead of element.screenshot(). Same-frame elements are correct (boundingBox returns main-frame coords). I have not exercised this path against cross-origin iframe elements; let me know if you'd like a fallback there.
• The PR is currently in Draft state pending CLA verification and any feedback on the framing above.

Refs #879

[OrKoN]

@antoinekm could you please rebase the PR?

[OrKoN]

why do we need isScreenshotFormat? MCP schema validates the format.

[antoinekm]

Good catch, removed. The yargs choices: ['jpeg', 'png', 'webp'] as const already narrows args.screenshotFormat to 'jpeg' | 'png' | 'webp' | undefined, so the runtime guard was dead code. Now simply const defaultFormat: ScreenshotFormat = screenshotFormat ?? 'png';.

[OrKoN]

let's do number validation when parsing CLI args with yargs? I think here we should expect an integer number or undefined so we do not need to check again if the CLI args were parse.

[antoinekm]

Done. Moved the validation into coerce on each numeric CLI option in chrome-devtools-mcp-cli-options.ts:

• screenshotQuality: integer in [0, 100]
• screenshotMaxWidth / screenshotMaxHeight: positive integer

Invalid values now throw a clear error at parse time (e.g. Invalid screenshotMaxWidth -5. Expected a positive integer.), and the tool consumes the args directly with no re-validation.

[antoinekm]

Rebased on main (now 8c76d72). Conflicts with the recent verifyFilesSchema refactor (#2152) and the new saveFile(extension) signature were resolved. Also addressed both review comments below in the same commit so the PR stays at a single conventional commit. PTAL 🙏

[ranieleda-ui]

Ok Em seg., 1 de jun. de 2026 às 05:13, Antoine Kingue < ***@***.***> escreveu:

…

***@***.**** commented on this pull request. ------------------------------ In src/tools/screenshot.ts <#1823 (comment)> : > - .describe( - 'The uid of an element on the page from the page content snapshot. If omitted, takes a page screenshot.', - ), - fullPage: zod - .boolean() - .optional() - .describe( - 'If set to true takes a screenshot of the full page instead of the currently visible viewport. Incompatible with uid.', +type ScreenshotFormat = 'png' | 'jpeg' | 'webp'; + +function isScreenshotFormat(value: unknown): value is ScreenshotFormat { + return value === 'png' || value === 'jpeg' || value === 'webp'; +} + +function isPositiveFiniteNumber(value: number | undefined): value is number { + return value !== undefined && Number.isFinite(value) && value > 0; Done. Moved the validation into coerce on each numeric CLI option in chrome-devtools-mcp-cli-options.ts: - screenshotQuality: integer in [0, 100] - screenshotMaxWidth / screenshotMaxHeight: positive integer Invalid values now throw a clear error at parse time (e.g. Invalid screenshotMaxWidth -5. Expected a positive integer.), and the tool consumes the args directly with no re-validation. — Reply to this email directly, view it on GitHub <#1823?email_source=notifications&email_token=CDNASIPMN2MJBVQ3CCGLEWL45U3KNA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIMZZHE2TGNJVGY22M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#discussion_r3332629536>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/CDNASIII6DLSFWL6SNUBYJ345U3KNAVCNFSM6AAAAACXPFRSPCVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHM2DGOJZGUZTKNJWGU> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/CDNASIIGBMALJ6OCFSQRXUL45U3KNA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIMZZHE2TGNJVGY22M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSVGM33PORSXEX3JN5ZQ> and Android <https://github.com/notifications/mobile/android/CDNASINMJTBM5KKJM2SDH6L45U3KNA5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIMZZHE2TGNJVGY22M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSXGM33PORSXEX3BNZSHE33JMQ>. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.*** .com>