Website Screenshot MCP

Instructions

Implementation Reference

• src/tools/screenshot.ts:39-83 (handler)

  The screenshotHandler function that executes the tool logic: launches Puppeteer browser, emulates device, navigates to URL, takes screenshot and saves to outputPath, returns success/error response.

  export const screenshotHandler = async ({ url, outputPath, format = "png", fullPage = true, device }: ScreenshotParams) => {
    try {
      // Ensure the output path has the correct extension
      const extension = `.${format}`;
      let path = outputPath.endsWith(extension) ? outputPath : `${outputPath}${extension}`;
  
      if (!isScreenshotPath(path)) {
        // This should not happen due to the logic above, but it satisfies TypeScript
        throw new Error("Invalid screenshot path");
      }
  
      const browser = await puppeteer.launch({
        headless: true,
        args: ['--no-sandbox', '--disable-setuid-sandbox']
      });
      const page = await browser.newPage();
  
      const deviceName = DEVICE_ID_MAP[device];
      const deviceToEmulate = KnownDevices[deviceName as keyof typeof KnownDevices];
      await page.emulate(deviceToEmulate);
      
      await page.goto(url, { waitUntil: "networkidle2" });
      await page.screenshot({ path, type: format, fullPage });
      await browser.close();
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ success: true, outputPath: path }),
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ success: false, error: error.message }),
          },
        ],
        isError: true,
      };
    }
  };

• src/tools/screenshot.ts:23-29 (schema)

  Zod schema defining input parameters for the screenshot tool: url (required), outputPath (required), optional format, fullPage, device.

  const screenshotSchema = z.object({
    url: z.string().url(),
    outputPath: z.string(),
    format: z.enum(["png", "jpeg"]).optional(),
    fullPage: z.boolean().optional(),
    device: z.enum(Object.keys(DEVICE_ID_MAP) as [DeviceId, ...DeviceId[]]).default('laptop-hidpi'),
  });

• src/main.ts:24-31 (registration)

  Registration of the 'screenshot' tool using McpServer.registerTool, providing name, tool metadata (title, description, inputSchema), and handler function.

  server.registerTool(
    "screenshot",
    {
      ...screenshotTool,
      inputSchema: screenshotTool.inputSchema,
    },
    screenshotHandler
  );

• src/tools/screenshot.ts:6-8 (helper)

  Helper function to validate if a path is a valid screenshot path (ends with .png or .jpeg).

  function isScreenshotPath(path: string): path is ScreenshotPath {
    return path.endsWith(".png") || path.endsWith(".jpeg");
  }

• src/tools/screenshot.ts:10-19 (helper)

  Mapping of device IDs to Puppeteer known device names for emulation.

  const DEVICE_ID_MAP: Record<string, string> = {
    'ios-large': 'iPhone 14 Pro Max',
    'ios-small': 'iPhone SE',
    'android-large': 'Pixel 6 Pro',
    'android-medium': 'Galaxy S8',
    'tablet-large': 'iPad Pro 11',
    'tablet-small': 'iPad Mini',
    'laptop-hidpi': 'Laptop with HiDPI screen',
    'laptop-mdpi': 'Laptop with MDPI screen',
  };