screenshot

Instructions

Implementation Reference

• src/tools/screenshotTool.ts:322-504 (handler)

  Core handler function that launches Puppeteer browser, navigates to URL, performs optional actions, captures screenshots at specified breakpoints, collects errors, and returns base64 images with metadata.

  export async function screenshotTool(args: any): Promise<ScreenshotResult> {
    const {
      url,
      breakpoints = DEFAULT_BREAKPOINTS,
      headless = true,
      waitFor = "networkidle0",
      timeout = 30000,
      maxWidth = 1280, // Default max width for optimization
      imageFormat = "jpeg", // Default to JPEG for smaller file size
      quality = 80, // Default JPEG quality
      actions = [], // Default empty actions array
      sessionId,
      userDataDir,
      cookies,
    }: ScreenshotArgs = args;
  
    // Determine user data directory for session info
    let finalUserDataDir: string | undefined;
    if (sessionId || userDataDir) {
      if (userDataDir) {
        finalUserDataDir = userDataDir;
      } else if (sessionId) {
        finalUserDataDir = path.join(os.tmpdir(), 'puppeteer-mcp-sessions', sessionId);
      }
    }
  
    if (!url) {
      return {
        success: false,
        screenshots: [],
        pageErrors: [],
        errorSummary: {
          totalErrors: 0,
          totalWarnings: 0,
          totalLogs: 0,
          hasJavaScriptErrors: false,
          hasNetworkErrors: false,
          hasConsoleLogs: false,
        },
        error: "URL is required"
      };
    }
  
    try {
      const browser = await getBrowser(headless, sessionId, userDataDir);
      const page = await browser.newPage();
      
      // Start collecting errors
      const pageErrors = await collectPageErrors(page);
      
      const results = [];
      
      for (const breakpoint of breakpoints) {
        const startTime = Date.now();
        
        // Determine if we need to optimize this breakpoint
        const shouldOptimize = breakpoint.width > maxWidth;
        const screenshotWidth = shouldOptimize ? maxWidth : breakpoint.width;
        
        // Set viewport
        await page.setViewport({ 
          width: breakpoint.width, 
          height: 800 // Initial height, will capture full page
        });
        
        // Set cookies before navigation if provided
        if (cookies && cookies.length > 0) {
          await setCookies(page, cookies, url);
        }
        
        // Navigate to URL
        await page.goto(url, { 
          waitUntil: waitFor as any,
          timeout 
        });
        
        // Execute page actions if provided
        if (actions.length > 0) {
          await executePageActions(page, actions);
        }
        
        // Get actual content dimensions
        const actualContentSize = await getFullPageDimensions(page);
        
        // Configure screenshot options
        const screenshotOptions: any = {
          fullPage: true,
          encoding: 'base64'
        };
        
        // Set format and quality
        if (imageFormat === "jpeg") {
          screenshotOptions.type = 'jpeg';
          screenshotOptions.quality = quality;
        } else {
          screenshotOptions.type = 'png';
        }
        
        // If we need to optimize, clip the screenshot width
        if (shouldOptimize) {
          screenshotOptions.clip = {
            x: 0,
            y: 0,
            width: maxWidth,
            height: actualContentSize.height
          };
        }
        
        // Take screenshot
        const screenshot = await page.screenshot(screenshotOptions);
        
        const loadTime = Date.now() - startTime;
        
        // Determine the data URL prefix based on format
        const mimeType = imageFormat === "jpeg" ? "image/jpeg" : "image/png";
        const dataPrefix = `data:${mimeType};base64,`;
        
        results.push({
          width: shouldOptimize ? maxWidth : breakpoint.width,
          height: actualContentSize.height,
          screenshot: `${dataPrefix}${screenshot}`,
          format: imageFormat,
          metadata: {
            viewport: { width: breakpoint.width, height: 800 },
            actualContentSize,
            loadTime,
            timestamp: new Date().toISOString(),
            optimized: shouldOptimize,
            originalSize: shouldOptimize ? { width: breakpoint.width, height: actualContentSize.height } : undefined,
          },
        });
      }
      
      await page.close();
      
      // Create error summary
      const errors = pageErrors.filter(e => e.level === 'error');
      const warnings = pageErrors.filter(e => e.level === 'warning');
      const logs = pageErrors.filter(e => e.level === 'info');
      const errorSummary = {
        totalErrors: errors.length,
        totalWarnings: warnings.length,
        totalLogs: logs.length,
        hasJavaScriptErrors: pageErrors.some(e => e.type === 'javascript' && e.level === 'error'),
        hasNetworkErrors: pageErrors.some(e => e.type === 'network' && e.level === 'error'),
        hasConsoleLogs: pageErrors.some(e => e.type === 'console' && e.level === 'info'),
      };
      
      const result: ScreenshotResult = {
        success: true,
        screenshots: results,
        pageErrors,
        errorSummary,
      };
  
      // Add session info if session was used
      if (sessionId) {
        result.sessionInfo = {
          sessionId,
          userDataDir: finalUserDataDir || path.join(os.tmpdir(), 'puppeteer-mcp-sessions', sessionId),
          persistent: true,
        };
      }
      
      return result;
      
    } catch (error) {
      return {
        success: false,
        screenshots: [],
        pageErrors: [],
        errorSummary: {
          totalErrors: 0,
          totalWarnings: 0,
          totalLogs: 0,
          hasJavaScriptErrors: false,
          hasNetworkErrors: false,
          hasConsoleLogs: false,
        },
        error: error instanceof Error ? error.message : String(error)
      };
    }
  }

• src/index.ts:25-193 (registration)

  Registers the 'screenshot' tool by defining it in the ListTools response, including name, description, and input schema.

  // Register available tools
  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: "screenshot",
          description: "Capture screenshots of web pages at multiple viewport breakpoints using Puppeteer",
          inputSchema: {
            type: "object",
            properties: {
              url: {
                type: "string",
                description: "URL to capture screenshots from"
              },
              breakpoints: {
                type: "array",
                items: {
                  type: "object",
                  properties: {
                    width: { 
                      type: "number",
                      description: "Viewport width in pixels"
                    }
                  },
                  required: ["width"]
                },
                description: "Viewport breakpoints (optional, defaults to mobile: 375px, tablet: 768px, desktop: 1280px)"
              },
              headless: {
                type: "boolean",
                description: "Run browser in headless mode",
                default: true
              },
              waitFor: {
                type: "string",
                enum: ["load", "domcontentloaded", "networkidle0", "networkidle2"],
                description: "Wait condition before capturing screenshot",
                default: "networkidle0"
              },
              timeout: {
                type: "number",
                description: "Navigation timeout in milliseconds",
                default: 30000
              },
              maxWidth: {
                type: "number",
                description: "Maximum width for image optimization (images wider than this will be clipped)",
                default: 1280
              },
              imageFormat: {
                type: "string",
                enum: ["png", "jpeg"],
                description: "Image format (JPEG recommended for smaller file sizes)",
                default: "jpeg"
              },
              quality: {
                type: "number",
                minimum: 1,
                maximum: 100,
                description: "JPEG quality (1-100, only applies when imageFormat is 'jpeg')",
                default: 80
              },
              actions: {
                type: "array",
                items: {
                  type: "object",
                  properties: {
                    type: {
                      type: "string",
                      enum: ["click", "type", "scroll", "wait", "hover", "select", "clear", "navigate", "waitForElement"],
                      description: "Type of action to perform"
                    },
                    selector: {
                      type: "string",
                      description: "CSS selector for element-based actions"
                    },
                    text: {
                      type: "string",
                      description: "Text to type (for type action)"
                    },
                    value: {
                      type: "string",
                      description: "Value to select (for select action)"
                    },
                    x: {
                      type: "number",
                      description: "X coordinate (for scroll action)"
                    },
                    y: {
                      type: "number",
                      description: "Y coordinate (for scroll action)"
                    },
                    duration: {
                      type: "number",
                      description: "Duration in milliseconds (for wait action)",
                      default: 1000
                    },
                    url: {
                      type: "string",
                      description: "URL to navigate to (for navigate action)"
                    },
                    timeout: {
                      type: "number",
                      description: "Timeout in milliseconds (for waitForElement action)",
                      default: 5000
                    }
                  },
                  required: ["type"]
                },
                description: "Array of page interactions to perform before taking screenshots"
              },
              sessionId: {
                type: "string",
                description: "Session identifier for persistent browser state (maintains cookies, login data, localStorage, etc.)"
              },
              userDataDir: {
                type: "string",
                description: "Custom user data directory path for browser session storage"
              },
              cookies: {
                type: "array",
                items: {
                  type: "object",
                  properties: {
                    name: {
                      type: "string",
                      description: "Cookie name"
                    },
                    value: {
                      type: "string", 
                      description: "Cookie value"
                    },
                    domain: {
                      type: "string",
                      description: "Cookie domain (optional, defaults to URL domain)"
                    },
                    path: {
                      type: "string",
                      description: "Cookie path (optional, defaults to '/')"
                    },
                    expires: {
                      type: "number",
                      description: "Cookie expiration timestamp (optional)"
                    },
                    httpOnly: {
                      type: "boolean",
                      description: "HttpOnly flag (optional)"
                    },
                    secure: {
                      type: "boolean", 
                      description: "Secure flag (optional)"
                    },
                    sameSite: {
                      type: "string",
                      enum: ["Strict", "Lax", "None"],
                      description: "SameSite policy (optional)"
                    }
                  },
                  required: ["name", "value"]
                },
                description: "Cookies to inject into the browser session before navigation"
              }
            },
            required: ["url"]
          }
        }
      ]
    };
  });

• src/index.ts:32-189 (schema)

  Defines the input schema for the screenshot tool, specifying parameters like url, breakpoints, actions, cookies, etc.

  inputSchema: {
    type: "object",
    properties: {
      url: {
        type: "string",
        description: "URL to capture screenshots from"
      },
      breakpoints: {
        type: "array",
        items: {
          type: "object",
          properties: {
            width: { 
              type: "number",
              description: "Viewport width in pixels"
            }
          },
          required: ["width"]
        },
        description: "Viewport breakpoints (optional, defaults to mobile: 375px, tablet: 768px, desktop: 1280px)"
      },
      headless: {
        type: "boolean",
        description: "Run browser in headless mode",
        default: true
      },
      waitFor: {
        type: "string",
        enum: ["load", "domcontentloaded", "networkidle0", "networkidle2"],
        description: "Wait condition before capturing screenshot",
        default: "networkidle0"
      },
      timeout: {
        type: "number",
        description: "Navigation timeout in milliseconds",
        default: 30000
      },
      maxWidth: {
        type: "number",
        description: "Maximum width for image optimization (images wider than this will be clipped)",
        default: 1280
      },
      imageFormat: {
        type: "string",
        enum: ["png", "jpeg"],
        description: "Image format (JPEG recommended for smaller file sizes)",
        default: "jpeg"
      },
      quality: {
        type: "number",
        minimum: 1,
        maximum: 100,
        description: "JPEG quality (1-100, only applies when imageFormat is 'jpeg')",
        default: 80
      },
      actions: {
        type: "array",
        items: {
          type: "object",
          properties: {
            type: {
              type: "string",
              enum: ["click", "type", "scroll", "wait", "hover", "select", "clear", "navigate", "waitForElement"],
              description: "Type of action to perform"
            },
            selector: {
              type: "string",
              description: "CSS selector for element-based actions"
            },
            text: {
              type: "string",
              description: "Text to type (for type action)"
            },
            value: {
              type: "string",
              description: "Value to select (for select action)"
            },
            x: {
              type: "number",
              description: "X coordinate (for scroll action)"
            },
            y: {
              type: "number",
              description: "Y coordinate (for scroll action)"
            },
            duration: {
              type: "number",
              description: "Duration in milliseconds (for wait action)",
              default: 1000
            },
            url: {
              type: "string",
              description: "URL to navigate to (for navigate action)"
            },
            timeout: {
              type: "number",
              description: "Timeout in milliseconds (for waitForElement action)",
              default: 5000
            }
          },
          required: ["type"]
        },
        description: "Array of page interactions to perform before taking screenshots"
      },
      sessionId: {
        type: "string",
        description: "Session identifier for persistent browser state (maintains cookies, login data, localStorage, etc.)"
      },
      userDataDir: {
        type: "string",
        description: "Custom user data directory path for browser session storage"
      },
      cookies: {
        type: "array",
        items: {
          type: "object",
          properties: {
            name: {
              type: "string",
              description: "Cookie name"
            },
            value: {
              type: "string", 
              description: "Cookie value"
            },
            domain: {
              type: "string",
              description: "Cookie domain (optional, defaults to URL domain)"
            },
            path: {
              type: "string",
              description: "Cookie path (optional, defaults to '/')"
            },
            expires: {
              type: "number",
              description: "Cookie expiration timestamp (optional)"
            },
            httpOnly: {
              type: "boolean",
              description: "HttpOnly flag (optional)"
            },
            secure: {
              type: "boolean", 
              description: "Secure flag (optional)"
            },
            sameSite: {
              type: "string",
              enum: ["Strict", "Lax", "None"],
              description: "SameSite policy (optional)"
            }
          },
          required: ["name", "value"]
        },
        description: "Cookies to inject into the browser session before navigation"
      }
    },
    required: ["url"]
  }

• src/index.ts:195-321 (handler)

  MCP dispatch handler for tool calls; checks if name is 'screenshot', invokes screenshotTool, formats response with summaries and embedded images.

  // Handle tool execution
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    try {
      if (request.params.name === "screenshot") {
        const result = await screenshotTool(request.params.arguments);
        
        if (!result.success) {
          throw new McpError(
            ErrorCode.InternalError,
            result.error || "Screenshot capture failed"
          );
        }
        
        // Build content array with text description and images
        const content = [];
        
        // Add summary text with error information
        let summaryText = `Successfully captured ${result.screenshots.length} screenshot(s) for ${request.params.arguments?.url || 'the requested URL'}`;
        
        // Add actions summary if actions were provided
        if (request.params.arguments?.actions && Array.isArray(request.params.arguments.actions) && request.params.arguments.actions.length > 0) {
          const actionTypes = request.params.arguments.actions.map((action: any) => action.type);
          summaryText += `\n🎯 Executed ${actionTypes.length} page action(s): ${actionTypes.join(', ')}`;
        }
        
        // Add session info if session was used
        if (result.sessionInfo) {
          summaryText += `\n🔒 Session: ${result.sessionInfo.sessionId} (persistent login data maintained)`;
        }
        
        // Add error summary if there are any issues
        if (result.errorSummary.totalErrors > 0 || result.errorSummary.totalWarnings > 0 || result.errorSummary.totalLogs > 0) {
          summaryText += `\n\n📊 Page Activity Detected:`;
          if (result.errorSummary.totalErrors > 0) {
            summaryText += `\n• ${result.errorSummary.totalErrors} error(s)`;
          }
          if (result.errorSummary.totalWarnings > 0) {
            summaryText += `\n• ${result.errorSummary.totalWarnings} warning(s)`;
          }
          if (result.errorSummary.totalLogs > 0) {
            summaryText += `\n• ${result.errorSummary.totalLogs} console log(s)`;
          }
          if (result.errorSummary.hasJavaScriptErrors) {
            summaryText += `\n• JavaScript errors present`;
          }
          if (result.errorSummary.hasNetworkErrors) {
            summaryText += `\n• Network/loading errors present`;
          }
          if (result.errorSummary.hasConsoleLogs) {
            summaryText += `\n• Console logs available`;
          }
        } else {
          summaryText += `\n✅ No errors, warnings, or console activity detected`;
        }
        
        content.push({
          type: "text",
          text: summaryText
        });
        
        // Add detailed error information if present
        if (result.pageErrors.length > 0) {
          let errorDetails = "\n📋 Detailed Error Report:\n";
          
          // Group errors by type
          const errorsByType = result.pageErrors.reduce((acc, error) => {
            if (!acc[error.type]) acc[error.type] = [];
            acc[error.type].push(error);
            return acc;
          }, {} as Record<string, typeof result.pageErrors>);
          
          Object.entries(errorsByType).forEach(([type, errors]) => {
            errorDetails += `\n${type.toUpperCase()} ISSUES (${errors.length}):\n`;
            errors.forEach((error, index) => {
              const icon = error.level === 'error' ? '❌' : '⚠️';
              errorDetails += `${icon} ${error.message}`;
              if (error.source) errorDetails += `\n   Source: ${error.source}`;
              if (error.line && error.column) errorDetails += ` (line ${error.line}, col ${error.column})`;
              if (error.url && error.url !== error.source) errorDetails += `\n   URL: ${error.url}`;
              if (error.statusCode) errorDetails += ` [${error.statusCode}]`;
              errorDetails += `\n   Time: ${new Date(error.timestamp).toLocaleTimeString()}\n`;
            });
          });
          
          content.push({
            type: "text",
            text: errorDetails
          });
        }
        
        // Add each screenshot as an image
        for (const screenshot of result.screenshots) {
          // Extract base64 data - handle both PNG and JPEG formats
          const base64Data = screenshot.screenshot.replace(/^data:image\/(png|jpeg);base64,/, '');
          const mimeType = screenshot.format === "jpeg" ? "image/jpeg" : "image/png";
          
          // Add minimal description
          content.push({
            type: "text",
            text: `${screenshot.width}px viewport (${screenshot.format.toUpperCase()})`
          });
          
          content.push({
            type: "image",
            data: base64Data,
            mimeType: mimeType
          });
        }
        
        return { content };
      }
      
      throw new McpError(
        ErrorCode.MethodNotFound,
        `Unknown tool: ${request.params.name}`
      );
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      
      throw new McpError(
        ErrorCode.InternalError,
        `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`
      );
    }
  });

• src/tools/screenshotTool.ts:18-85 (helper)

  TypeScript interfaces defining inputs (ScreenshotArgs), outputs (ScreenshotResult), actions (PageAction), and errors (PageError) for the screenshot tool.

  export interface ScreenshotArgs {
    url: string;
    breakpoints?: { width: number }[];
    headless?: boolean;
    waitFor?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
    timeout?: number;
    maxWidth?: number; // Max width for optimization
    imageFormat?: "png" | "jpeg";
    quality?: number; // JPEG quality (0-100)
    actions?: PageAction[]; // Array of actions to perform before screenshot
    sessionId?: string; // Session identifier for persistent browser state
    userDataDir?: string; // Custom user data directory path
    cookies?: Array<{ // NEW: Cookies to inject into the session
      name: string;
      value: string;
      domain?: string;
      path?: string;
      expires?: number;
      httpOnly?: boolean;
      secure?: boolean;
      sameSite?: "Strict" | "Lax" | "None";
    }>;
  }
  
  export interface PageError {
    type: "javascript" | "console" | "network" | "security";
    level: "error" | "warning" | "info";
    message: string;
    source?: string;
    line?: number;
    column?: number;
    timestamp: string;
    url?: string;
    statusCode?: number;
  }
  
  export interface ScreenshotResult {
    success: boolean;
    screenshots: {
      width: number;
      height: number;
      screenshot: string;
      format: string;
      metadata: {
        viewport: { width: number; height: number };
        actualContentSize: { width: number; height: number };
        loadTime: number;
        timestamp: string;
        optimized: boolean;
        originalSize?: { width: number; height: number };
      };
    }[];
    pageErrors: PageError[];
    errorSummary: {
      totalErrors: number;
      totalWarnings: number;
      totalLogs: number;
      hasJavaScriptErrors: boolean;
      hasNetworkErrors: boolean;
      hasConsoleLogs: boolean;
    };
    error?: string;
    sessionInfo?: {
      sessionId: string;
      userDataDir: string;
      persistent: boolean;
    };
  }