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

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. Addresses two related symptoms reported when MCP clients
display screenshots inline:

1. The hosted LLM API rejects images exceeding its per-image dimension
   limits (e.g. Anthropic's 8000x8000 px / 2000x2000 px when >20
   images are in the same request).
2. After many captures the cumulative base64 payload pushes the
   request over the per-call body size limit.

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

New CLI flags (all opt-in, no behavior change when unset):

- --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 when the caller does not specify one. 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 before they are returned. Combines with --screenshot-max-width;
  the smaller scale wins so both bounds are respected while preserving
  aspect ratio.

Resizing leverages Puppeteer's clip.scale (CDP Page.captureScreenshot)
so no new dependencies are introduced. Source dimensions are computed
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 is
routed through page.screenshot({clip}) so the scale parameter applies.
captureBeyondViewport is left to Puppeteer's default (true when a clip
is set), which preserves correct behavior for elements below the fold
and for full-page captures.

Design notes:

- 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.
- Fully opt-in: when no flags are set, take_screenshot returns the
  exact same bytes as before. No breaking change.
- The MCP server hardcodes no LLM-specific size limits — operators
  pick the values that match their client/model combination. This
  keeps the maintenance surface minimal as model limits evolve and
  is intended as a complement to, not a replacement for, fixes in
  the MCP client itself.
- Compares against CSS pixels (page.viewport()), not raw bitmap
  pixels, so HiDPI emulation behaves predictably from the user's
  perspective.

Tests added (6 new):

- 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

Refs #879

Author: antoinekm

README.md

@@ -675,6 +675,23 @@ The Chrome DevTools MCP server supports the following configuration option:
   - **Type:** boolean
   - **Default:** `true`
 
+- **`--screenshotFormat`/ `--screenshot-format`**
+  Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png").
+  - **Type:** string
+  - **Choices:** `jpeg`, `png`, `webp`
+
+- **`--screenshotQuality`/ `--screenshot-quality`**
+  Override the default compression quality (0-100) used by take_screenshot for JPEG and WebP when the caller does not specify one. Lower values mean smaller files. Ignored for PNG. Unset preserves the Puppeteer default.
+  - **Type:** number
+
+- **`--screenshotMaxWidth`/ `--screenshot-max-width`**
+  Maximum width in pixels for screenshots. If the captured image is wider, it is downscaled (preserving aspect ratio) before being returned. Reduces context size in AI conversations. Unset means no resize.
+  - **Type:** number
+
+- **`--screenshotMaxHeight`/ `--screenshot-max-height`**
+  Maximum height in pixels for screenshots. If the captured image is taller, it is downscaled (preserving aspect ratio) before being returned. Can be combined with --screenshot-max-width; the smaller scale factor wins. Unset means no resize.
+  - **Type:** number
+
 - **`--slim`**
   Exposes a "slim" set of 3 tools covering navigation, script execution and screenshots only. Useful for basic browser tasks.
   - **Type:** boolean

src/bin/chrome-devtools-mcp-cli-options.ts

@@ -264,6 +264,60 @@ export const cliOptions = {
     hidden: true,
     describe: 'Include watchdog PID in Clearcut request headers (for testing).',
   },
+  screenshotFormat: {
+    type: 'string',
+    description:
+      'Override the default output format used by take_screenshot when the caller does not specify one. JPEG and WebP are ~3-5x smaller than PNG, which helps reduce context size in AI conversations. Unset preserves the existing default ("png").',
+    choices: ['jpeg', 'png', 'webp'] as const,
+  },
+  screenshotQuality: {
+    type: 'number',
+    description:
+      'Override the default compression quality (0-100) used by take_screenshot for JPEG and WebP when the caller does not specify one. Lower values mean smaller files. Ignored for PNG. Unset preserves the Puppeteer default.',
+    coerce: (value: number | undefined) => {
+      if (value === undefined) {
+        return;
+      }
+      if (!Number.isInteger(value) || value < 0 || value > 100) {
+        throw new Error(
+          `Invalid screenshotQuality ${value}. Expected an integer between 0 and 100.`,
+        );
+      }
+      return value;
+    },
+  },
+  screenshotMaxWidth: {
+    type: 'number',
+    description:
+      'Maximum width in pixels for screenshots. If the captured image is wider, it is downscaled (preserving aspect ratio) before being returned. Reduces context size in AI conversations. Unset means no resize.',
+    coerce: (value: number | undefined) => {
+      if (value === undefined) {
+        return;
+      }
+      if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(
+          `Invalid screenshotMaxWidth ${value}. Expected a positive integer.`,
+        );
+      }
+      return value;
+    },
+  },
+  screenshotMaxHeight: {
+    type: 'number',
+    description:
+      'Maximum height in pixels for screenshots. If the captured image is taller, it is downscaled (preserving aspect ratio) before being returned. Can be combined with --screenshot-max-width; the smaller scale factor wins. Unset means no resize.',
+    coerce: (value: number | undefined) => {
+      if (value === undefined) {
+        return;
+      }
+      if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(
+          `Invalid screenshotMaxHeight ${value}. Expected a positive integer.`,
+        );
+      }
+      return value;
+    },
+  },
   slim: {
     type: 'boolean',
     describe:

src/telemetry/flag_usage_metrics.json

@@ -295,5 +295,31 @@
   {
     "name": "category_experimental_third_party",
     "flagType": "boolean"
+  },
+  {
+    "name": "screenshot_format_present",
+    "flagType": "boolean"
+  },
+  {
+    "name": "screenshot_format",
+    "flagType": "enum",
+    "choices": [
+      "SCREENSHOT_FORMAT_UNSPECIFIED",
+      "SCREENSHOT_FORMAT_JPEG",
+      "SCREENSHOT_FORMAT_PNG",
+      "SCREENSHOT_FORMAT_WEBP"
+    ]
+  },
+  {
+    "name": "screenshot_quality_present",
+    "flagType": "boolean"
+  },
+  {
+    "name": "screenshot_max_width_present",
+    "flagType": "boolean"
+  },
+  {
+    "name": "screenshot_max_height_present",
+    "flagType": "boolean"
   }
 ]