Screenshot Website Fast

Instructions

Implementation Reference

• src/internal/screenshotCapture.ts:752-958 (handler)

  Core handler function that implements the screencast logic using Puppeteer: launches browser, navigates to URL, optionally executes JS instructions, captures series of PNG screenshots at specified intervals over duration, collects frames into ScreencastResult.

  export async function captureScreencast(
      options: ScreencastOptions
  ): Promise<ScreencastResult> {
      logger.info('captureScreencast called with options:', {
          url: options.url,
          duration: options.duration,
          interval: options.interval,
          viewport: options.viewport,
          waitUntil: options.waitUntil,
          waitFor: options.waitFor,
          hasJsEvaluate: !!options.jsEvaluate,
      });
  
      // Update activity time when screencast is requested
      updateActivityTime();
  
      const frames: ScreencastResult['frames'] = [];
      const startTime = new Date();
  
      let browser: Browser | null = null;
      let page: Page | null = null;
  
      try {
          // Get browser instance
          browser = await getBrowser();
          page = await setupPage(browser);
  
          // Set viewport (only capture top tile - 1072x1072)
          const viewport = {
              width: options.viewport?.width || 1072,
              height: options.viewport?.height || 1072,
          };
          await page.setViewport(viewport);
  
          logger.info(`Starting screencast of ${options.url}`);
  
          // Navigate to the page
          await page.goto(options.url, {
              waitUntil: options.waitUntil || 'domcontentloaded',
              timeout: 60000,
          });
  
          // Wait additional time if specified
          if (options.waitFor) {
              await page.evaluate(
                  ms => new Promise(resolve => setTimeout(resolve, ms)),
                  options.waitFor
              );
          }
  
          // Handle JavaScript execution with configurable screenshot intervals
          let jsInstructionCount = 0;
          const screenshotInterval = options.interval * 1000; // Convert seconds to milliseconds
          const jsExecutionInterval = 1000; // Execute JS instructions every 1 second
  
          if (options.jsEvaluate) {
              const jsInstructions = Array.isArray(options.jsEvaluate)
                  ? options.jsEvaluate
                  : [options.jsEvaluate];
  
              jsInstructionCount = jsInstructions.length;
              logger.info(
                  `Processing ${jsInstructionCount} JavaScript instruction(s) with ${screenshotInterval}ms screenshot intervals`
              );
  
              const startTime = Date.now();
              let nextJsIndex = 0;
              let frameIndex = 0;
  
              // Run for the duration needed to execute all JS instructions
              const jsDuration = jsInstructions.length * jsExecutionInterval;
  
              while (Date.now() - startTime < jsDuration) {
                  const elapsed = Date.now() - startTime;
  
                  // Check if it's time to execute the next JS instruction
                  if (
                      nextJsIndex < jsInstructions.length &&
                      elapsed >= nextJsIndex * jsExecutionInterval
                  ) {
                      logger.info(
                          `Executing JavaScript instruction ${nextJsIndex + 1}/${jsInstructions.length}: ${jsInstructions[nextJsIndex].substring(0, 50)}...`
                      );
                      try {
                          await page.evaluate(jsInstructions[nextJsIndex]);
                          logger.debug(
                              `JavaScript instruction ${nextJsIndex + 1} completed`
                          );
                      } catch (error) {
                          logger.error(
                              `JavaScript instruction ${nextJsIndex + 1} failed:`,
                              error
                          );
                          throw new Error(
                              `Failed to execute JavaScript instruction ${nextJsIndex + 1}: ${error}`
                          );
                      }
                      nextJsIndex++;
                  }
  
                  // Take screenshot
                  const screenshot = (await page.screenshot({
                      type: 'png',
                      fullPage: false,
                      encoding: 'binary',
                  })) as Buffer;
  
                  frames.push({
                      screenshot,
                      timestamp: new Date(),
                      index: frameIndex,
                  });
  
                  frameIndex++;
                  logger.debug(
                      `Captured high-frequency frame ${frameIndex} at ${elapsed}ms`
                  );
  
                  // Wait for next screenshot interval
                  const nextScreenshotTime =
                      startTime + frameIndex * screenshotInterval;
                  const waitTime = Math.max(0, nextScreenshotTime - Date.now());
                  if (waitTime > 0) {
                      await new Promise(resolve => setTimeout(resolve, waitTime));
                  }
              }
  
              // Update jsInstructionCount to reflect actual frames captured during JS execution
              jsInstructionCount = frameIndex;
          }
  
          // Calculate remaining time and frames needed at configured intervals
          const remainingDuration =
              options.duration * 1000 - jsInstructionCount * screenshotInterval; // Remaining time in ms
          const remainingFrames = Math.max(
              0,
              Math.floor(remainingDuration / screenshotInterval)
          );
  
          logger.info(
              `Captured ${jsInstructionCount} frames during JS execution. Capturing ${remainingFrames} additional frames at ${screenshotInterval}ms intervals for remaining ${remainingDuration}ms`
          );
  
          // Capture remaining frames at configured intervals
          for (let i = 0; i < remainingFrames; i++) {
              const frameStart = Date.now();
  
              // Take screenshot of viewport (top tile only)
              const screenshot = (await page.screenshot({
                  type: 'png',
                  fullPage: false,
                  encoding: 'binary',
              })) as Buffer;
  
              const frameIndex = jsInstructionCount + i;
              frames.push({
                  screenshot,
                  timestamp: new Date(),
                  index: frameIndex,
              });
  
              logger.debug(
                  `Captured duration frame ${frameIndex + 1} (${i + 1}/${remainingFrames})`
              );
  
              // Wait for next interval (if not the last frame)
              if (i < remainingFrames - 1) {
                  const elapsed = Date.now() - frameStart;
                  const waitTime = Math.max(0, screenshotInterval - elapsed);
                  if (waitTime > 0) {
                      await new Promise(resolve => setTimeout(resolve, waitTime));
                  }
              }
          }
  
          const endTime = new Date();
  
          const result: ScreencastResult = {
              url: options.url,
              frames,
              startTime,
              endTime,
              duration: options.duration,
              interval: options.interval,
              viewport,
              format: 'png',
          };
  
          logger.info(`Screencast completed: ${frames.length} frames captured`);
  
          // Clean up the page after successful capture
          if (page && !page.isClosed()) {
              await page.close().catch(() => {});
          }
  
          return result;
      } catch (error: any) {
          logger.error('Error capturing screencast:', error);
  
          // Clean up the page
          if (page && !page.isClosed()) {
              await page.close().catch(() => {});
          }
  
          throw error;
      }
  }

• src/serve.ts:91-169 (schema)

  Tool schema definition specifying name, description, input parameters (url required, duration=10s, viewport 1072x1072, jsEvaluate for interactions, output options), and annotations (readOnly, etc.).

  const SCREENCAST_TOOL: Tool = {
      name: 'take_screencast',
      description:
          'Capture a series of screenshots of a web page over time, producing a screencast. Uses adaptive frame rates: 100ms intervals for ≤5s, 200ms for 5-10s, 500ms for >10s. PNG format: individual frames. WebP format: animated WebP with 4-second pause at end for looping.',
      inputSchema: {
          type: 'object',
          properties: {
              url: {
                  type: 'string',
                  description: 'HTTP/HTTPS URL to capture',
              },
              duration: {
                  type: 'number',
                  description: 'Total duration of screencast in seconds',
                  default: 10,
              },
              width: {
                  type: 'number',
                  description: 'Viewport width in pixels (max 1072)',
                  default: 1072,
              },
              height: {
                  type: 'number',
                  description: 'Viewport height in pixels (max 1072)',
                  default: 1072,
              },
              jsEvaluate: {
                  oneOf: [
                      {
                          type: 'string',
                          description:
                              'Single JavaScript code to execute after the first screenshot',
                      },
                      {
                          type: 'array',
                          items: { type: 'string' },
                          description:
                              'Array of JavaScript instructions - screenshot taken before each one',
                      },
                  ],
                  description:
                      'JavaScript code to execute. String: single instruction after first screenshot. Array: takes screenshot before each instruction, then continues capturing until duration ends.',
              },
              waitUntil: {
                  type: 'string',
                  description:
                      'Wait until event: load, domcontentloaded, networkidle0, networkidle2',
                  default: 'domcontentloaded',
              },
              directory: {
                  type: 'string',
                  description:
                      'Save screencast to directory. Specify format with "format" parameter.',
              },
              format: {
                  type: 'string',
                  description:
                      'Output format when using directory: "png" for individual PNG files, "webp" for animated WebP (default)',
                  enum: ['png', 'webp'],
                  default: 'webp',
              },
              quality: {
                  type: 'string',
                  description:
                      'WebP quality level (only applies when format is "webp"): low (50), medium (75), high (90)',
                  enum: ['low', 'medium', 'high'],
                  default: 'medium',
              },
          },
          required: ['url'],
      },
      annotations: {
          title: 'Take Screencast',
          readOnlyHint: true, // Screencasts don't modify anything
          destructiveHint: false,
          idempotentHint: false, // Each call captures fresh content
          openWorldHint: true, // Interacts with external websites
      },
  };

• src/serve.ts:214-224 (registration)

  Registration via the ListToolsRequestSchema handler that returns the SCREENCAST_TOOL in the tools list, making it discoverable by MCP clients.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
      logger.debug('Received ListTools request');
      const response = {
          tools: [SCREENSHOT_TOOL, SCREENCAST_TOOL, CONSOLE_CAPTURE_TOOL],
      };
      logger.debug(
          'Returning tools:',
          response.tools.map(t => t.name)
      );
      return response;
  });

• src/serve.ts:472-677 (handler)

  MCP server execution handler for 'take_screencast': validates params, computes parameters (e.g. adaptive frame rate), delegates to captureScreencast, processes result into MCP content (images/text or file paths). Handles WebP creation and PNG fallback.

  } else if (request.params.name === 'take_screencast') {
      // Lazy load the module on first use (may already be loaded from warmup)
      if (!screenshotModule) {
          logger.debug('Loading screenshot module...');
          screenshotModule = await import(
              './internal/screenshotCapture.js'
          );
          logger.info('Screenshot module loaded successfully');
      }
  
      const args = request.params.arguments as any;
      logger.info(`Processing screencast request for URL: ${args.url}`);
  
      // Validate format parameter usage
      if (args.format && !args.directory) {
          throw new Error(
              'The "format" parameter can only be used when "directory" parameter is specified'
          );
      }
  
      const duration = args.duration ?? 10;
      const format = args.format ?? 'webp';
      const width = Math.min(args.width ?? 1072, 1072); // Cap at 1072
      const height = Math.min(args.height ?? 1072, 1072); // Cap at 1072
      const quality = args.quality ?? 'medium';
  
      // Adaptive frame rate based on duration to manage memory
      let interval: number;
      if (args.directory && format === 'webp') {
          // For WebP exports, use adaptive intervals based on duration
          if (duration <= 5) {
              interval = 0.1; // 100ms for <= 5s (up to 50 frames)
          } else if (duration <= 10) {
              interval = 0.2; // 200ms for 5-10s (up to 50 frames)
          } else {
              interval = 0.5; // 500ms for > 10s (manageable frame count)
          }
      } else {
          interval = 2; // 2s for base64 returns
      }
  
      logger.debug('Screencast parameters:', {
          url: args.url,
          duration,
          interval,
          width,
          height,
          waitUntil: args.waitUntil,
          jsEvaluate: args.jsEvaluate
              ? Array.isArray(args.jsEvaluate)
                  ? `array(${args.jsEvaluate.length})`
                  : 'string'
              : 'none',
          directory: args.directory,
          format,
          quality,
      });
  
      logger.debug('Calling captureScreencast...');
      const result = await screenshotModule.captureScreencast({
          url: args.url,
          duration,
          interval,
          viewport: {
              width: width,
              height: height,
          },
          waitUntil: args.waitUntil ?? 'domcontentloaded',
          waitFor: undefined, // Removed waitForMS
          jsEvaluate: args.jsEvaluate,
      });
  
      logger.info('Screencast captured successfully');
      logger.debug(`Captured ${result.frames.length} frames`);
  
      // If directory is specified, save based on format
      if (args.directory) {
          logger.debug(
              `Saving screencast to directory: ${args.directory} (format: ${format})`
          );
  
          // Ensure directory exists
          if (!existsSync(args.directory)) {
              logger.debug('Creating directory...');
              await mkdir(args.directory, { recursive: true });
              logger.info('Directory created successfully');
          }
  
          const frames = result.frames.map((f: any) => f.screenshot);
  
          if (format === 'png') {
              // Save individual PNG frames only
              const framePaths: string[] = [];
              for (let i = 0; i < result.frames.length; i++) {
                  const frameFilename = generateFilename(
                      args.url,
                      i,
                      'frame'
                  );
                  const frameFilepath = join(
                      args.directory,
                      frameFilename
                  );
                  await writeFile(
                      frameFilepath,
                      result.frames[i].screenshot
                  );
                  framePaths.push(frameFilepath);
              }
  
              return {
                  content: [
                      {
                          type: 'text',
                          text: `✅ Screencast saved as PNG frames:\n${framePaths.join('\n')}\n\nDuration: ${result.duration}s\nFrames: ${result.frames.length}\nInterval: ${interval}s`,
                      },
                  ],
              };
          } else {
              // Save as animated WebP and clean up PNGs
              let webpBuffer: Buffer | null = null;
  
              try {
                  // Create animated WebP using img2webp with adaptive intervals
                  const frameDelay = interval * 1000; // Convert to milliseconds
                  webpBuffer = await createAnimatedWebP(
                      frames,
                      frameDelay,
                      4000,
                      quality as 'low' | 'medium' | 'high'
                  );
                  logger.info('WebP created using img2webp CLI');
              } catch (error) {
                  logger.error('Failed to create WebP:', error);
                  webpBuffer = null;
              }
  
              if (webpBuffer) {
                  const filename = generateFilename(
                      args.url,
                      undefined,
                      'screencast'
                  ).replace('.png', '.webp');
                  const filepath = join(args.directory, filename);
                  await writeFile(filepath, webpBuffer);
  
                  return {
                      content: [
                          {
                              type: 'text',
                              text: `✅ Screencast saved as animated WebP: ${filepath}\n\nDuration: ${result.duration}s\nFrames: ${result.frames.length}\nCapture Interval: ${interval * 1000}ms (4s pause at end)\nQuality: ${quality}\nMethod: img2webp (optimized with frame deduplication)`,
                          },
                      ],
                  };
              } else {
                  // Fallback to PNG frames if WebP fails
                  const framePaths: string[] = [];
                  for (let i = 0; i < result.frames.length; i++) {
                      const frameFilename = generateFilename(
                          args.url,
                          i,
                          'frame'
                      );
                      const frameFilepath = join(
                          args.directory,
                          frameFilename
                      );
                      await writeFile(
                          frameFilepath,
                          result.frames[i].screenshot
                      );
                      framePaths.push(frameFilepath);
                  }
  
                  return {
                      content: [
                          {
                              type: 'text',
                              text: `⚠️  WebP creation failed, saved as PNG frames:\n${framePaths.join('\n')}\n\nDuration: ${result.duration}s\nFrames: ${result.frames.length}\nInterval: ${interval}s`,
                          },
                      ],
                  };
              }
          }
      } else {
          // Return frames as base64 encoded images
          const content = [];
  
          // Add each frame as an image
          for (let i = 0; i < result.frames.length; i++) {
              content.push({
                  type: 'image',
                  data: result.frames[i].screenshot.toString('base64'),
                  mimeType: 'image/png',
              });
          }
  
          // Add summary text
          content.push({
              type: 'text',
              text: `✅ Captured ${result.frames.length} frames over ${result.duration} seconds (${result.interval}s interval)`,
          });
  
          return { content };
      }
  } else if (request.params.name === 'capture_console') {