Skip to content

Chrome DevTools for coding agents

10.3 KB
Raw Blame
/**
 * @license
 * Copyright 2025 Google LLC
 * SPDX-License-Identifier: Apache-2.0
 */

import type {ParsedArguments} from '../config/mcp-options.js';
import {
  zod,
  type BoundingBox,
  type ElementHandle,
  type Page,
  type ScreenshotClip,
} from '../third_party/index.js';

import {ToolCategory} from './categories.js';
import {definePageTool, type PageToolFactory} from './ToolDefinition.js';

type ScreenshotFormat = 'png' | 'jpeg' | 'webp';

const MAX_CHROMIUM_SCREENSHOT_DIMENSION = 16384;

type SourceBox = BoundingBox & {
  devicePixelRatio: number;
};

async function getSourceBox(
  page: Page,
  element: ElementHandle | undefined,
  fullPage: boolean,
): Promise<SourceBox | undefined> {
  if (element) {
    const viewport = page.viewport();
    const [box, metrics] = await Promise.all([
      element.boundingBox(),
      page.evaluate(() => ({
        x: window.scrollX,
        y: window.scrollY,
        devicePixelRatio: window.devicePixelRatio,
      })),
    ]);
    return box
      ? {
          ...box,
          x: box.x + metrics.x,
          y: box.y + metrics.y,
          devicePixelRatio: viewport
            ? (viewport.deviceScaleFactor ?? 1)
            : metrics.devicePixelRatio,
        }
      : undefined;
  }
  if (fullPage) {
    const dims = await page.evaluate(() => ({
      width: Math.max(
        document.documentElement.scrollWidth,
        document.body?.scrollWidth ?? 0,
      ),
      height: Math.max(
        document.documentElement.scrollHeight,
        document.body?.scrollHeight ?? 0,
      ),
      devicePixelRatio: window.devicePixelRatio,
    }));
    if (dims.width <= 0 || dims.height <= 0) {
      return undefined;
    }
    return {
      x: 0,
      y: 0,
      width: dims.width,
      height: dims.height,
      devicePixelRatio: dims.devicePixelRatio,
    };
  }
  const viewport = page.viewport();
  // Clips use page coordinates. Read the scroll offset alongside the native
  // dimensions used when no viewport is emulated.
  const dims = await page.evaluate(() => ({
    x: window.scrollX,
    y: window.scrollY,
    width: window.innerWidth,
    height: window.innerHeight,
    devicePixelRatio: window.devicePixelRatio,
  }));
  if (viewport) {
    return {
      x: dims.x,
      y: dims.y,
      width: viewport.width,
      height: viewport.height,
      devicePixelRatio: viewport.deviceScaleFactor ?? 1,
    };
  }
  // The browser is launched and connected with `defaultViewport: null`, so
  // `page.viewport()` stays null until something emulates one. Fall back to the
  // window's own dimensions, which is the area a viewport screenshot captures.
  if (dims.width <= 0 || dims.height <= 0) {
    return undefined;
  }
  return {
    x: dims.x,
    y: dims.y,
    width: dims.width,
    height: dims.height,
    devicePixelRatio: dims.devicePixelRatio,
  };
}

function computeDownscaleClip(
  box: SourceBox,
  maxWidth: number | undefined,
  maxHeight: number | undefined,
): ScreenshotClip | undefined {
  const widthScale =
    maxWidth !== undefined
      ? Math.min(1, maxWidth / (box.width * box.devicePixelRatio))
      : 1;
  const heightScale =
    maxHeight !== undefined
      ? Math.min(1, maxHeight / (box.height * box.devicePixelRatio))
      : 1;
  const scale = Math.min(widthScale, heightScale);
  if (scale >= 1) {
    return undefined;
  }
  // Skip degenerate sub-pixel results.
  if (
    Math.round(box.width * box.devicePixelRatio * scale) < 1 ||
    Math.round(box.height * box.devicePixelRatio * scale) < 1
  ) {
    return undefined;
  }
  return {
    x: box.x,
    y: box.y,
    width: box.width,
    height: box.height,
    scale,
  };
}

export const screenshot: PageToolFactory = definePageTool(
  (args: ParsedArguments) => {
    const {
      screenshotFormat,
      screenshotQuality,
      screenshotMaxWidth,
      screenshotMaxHeight,
    } = args;

    const defaultFormat: ScreenshotFormat = screenshotFormat ?? 'png';

    return {
      name: 'take_screenshot',
      description: `Take a screenshot of the page or element.`,
      annotations: {
        category: ToolCategory.DEBUGGING,
        // Not read-only due to filePath param.
        readOnlyHint: false,
      },
      schema: {
        format: zod
          .enum(['png', 'jpeg', 'webp'])
          .default(defaultFormat)
          .describe(
            `Type of format to save the screenshot as. Default is "${defaultFormat}"`,
          ),
        quality: zod
          .number()
          .min(0)
          .max(100)
          .optional()
          .describe(
            'Compression quality for JPEG and WebP formats (0-100). Higher values mean better quality but larger file sizes. Ignored for PNG format.',
          ),
        uid: zod
          .string()
          .optional()
          .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.',
          ),
        filePath: zod
          .string()
          .optional()
          .describe(
            'The absolute path, or a path relative to the current working directory, to save the screenshot to instead of attaching it to the response.',
          ),
      },
      blockedByDialog: true,
      concurrency: 'page',
      verifyFilesSchema: {
        filePath: true,
      },
      handler: async (request, response, context) => {
        if (request.params.uid && request.params.fullPage) {
          throw new Error(
            'Providing both "uid" and "fullPage" is not allowed.',
          );
        }

        const page = request.page.pptrPage;
        using element = request.params.uid
          ? await request.page.getElementByUid(request.params.uid)
          : undefined;

        const format = request.params.format;
        const quality =
          format === 'png'
            ? undefined
            : (request.params.quality ?? screenshotQuality);
        const fullPage = request.params.fullPage ?? false;

        // `getElementByUid` mints a fresh ElementHandle per call, so dispose it
        // once the capture is done to avoid leaking a remote object for the life
        // of the page's execution context.
        let screenshot: Uint8Array;

        // Compute a downscale clip when --screenshot-max-width or
        // --screenshot-max-height is set and the source exceeds either bound.
        // The smaller scale factor wins so both bounds are respected while
        // preserving aspect ratio.
        let clip: ScreenshotClip | undefined;
        const shouldInspectBox =
          fullPage ||
          element !== undefined ||
          screenshotMaxWidth !== undefined ||
          screenshotMaxHeight !== undefined;

        const box = shouldInspectBox
          ? await getSourceBox(page, element, fullPage)
          : undefined;

        if (
          box &&
          (screenshotMaxWidth !== undefined ||
            screenshotMaxHeight !== undefined)
        ) {
          clip = computeDownscaleClip(
            box,
            screenshotMaxWidth,
            screenshotMaxHeight,
          );
        }

        if (clip) {
          // page.screenshot with clip lets the CDP scale param downscale the
          // capture for viewport, full-page and element shots alike. We rely on
          // Puppeteer's default of captureBeyondViewport=true when a clip is
          // present so element/full-page captures below the fold still work.
          screenshot = await page.screenshot({
            type: format,
            quality,
            optimizeForSpeed: true,
            clip,
          });
        } else if (element) {
          screenshot = await element.screenshot({
            type: format,
            quality,
            optimizeForSpeed: true,
          });
        } else {
          screenshot = await page.screenshot({
            type: format,
            fullPage,
            quality,
            optimizeForSpeed: true,
          });
        }

        if (request.params.uid) {
          response.appendResponseLine(
            `Took a screenshot of node with uid "${request.params.uid}".`,
          );
        } else if (fullPage) {
          response.appendResponseLine(
            'Took a screenshot of the full current page.',
          );
        } else {
          response.appendResponseLine(
            "Took a screenshot of the current page's viewport.",
          );
        }

        // Narrow `format` at the point of use: in the factory form of
        // definePageTool TS widens the Schema generic, which loses the literal
        // union from zod.enum on request.params.format.
        const extension: '.png' | '.jpeg' | '.webp' =
          format === 'jpeg' ? '.jpeg' : format === 'webp' ? '.webp' : '.png';

        if (request.params.filePath) {
          const result = await context.saveFile(
            screenshot,
            request.params.filePath,
            extension,
          );
          response.appendResponseLine(
            `Saved screenshot to ${result.filename}.`,
          );
        } else if (screenshot.length >= 2_000_000) {
          const {filepath} = await context.saveTemporaryFile(
            screenshot,
            `screenshot${extension}`,
          );
          response.appendResponseLine(`Saved screenshot to ${filepath}.`);
        } else {
          response.attachImage({
            mimeType: `image/${format}`,
            data: Buffer.from(screenshot).toString('base64'),
          });
        }

        if (box) {
          const effectiveScale = clip?.scale ?? 1;
          const effectiveWidth =
            box.width * box.devicePixelRatio * effectiveScale;
          const effectiveHeight =
            box.height * box.devicePixelRatio * effectiveScale;
          if (
            effectiveWidth > MAX_CHROMIUM_SCREENSHOT_DIMENSION ||
            effectiveHeight > MAX_CHROMIUM_SCREENSHOT_DIMENSION
          ) {
            response.appendResponseLine(
              `Warning: Screenshot dimensions exceed the maximum capturable dimension of ${MAX_CHROMIUM_SCREENSHOT_DIMENSION}px. Content beyond 16384px may repeat or be corrupted due to browser texture limits. Set --screenshotMaxHeight or --screenshotMaxWidth to downscale.`,
            );
          }
        }
      },
    };
  },
);