playwright_screenshot

Instructions

Implementation Reference

• src/toolsHandler.ts:109-187 (handler)

  The handler function for the 'playwright_screenshot' tool. It captures a screenshot of the current page or a specific element using Playwright, handles optional saving to PNG file in downloads directory, and stores base64 image for MCP resources.

  case "playwright_screenshot": {
    try {
      const screenshotOptions: any = {
        type: args.type || "png",
        fullPage: !!args.fullPage
      };
  
      if (args.selector) {
        const element = await page!.$(args.selector);
        if (!element) {
          return {
            content: [{
              type: "text",
              text: `Element not found: ${args.selector}`,
            }],
            isError: true
          };
        }
        screenshotOptions.element = element;
      }
  
      if (args.mask) {
        screenshotOptions.mask = await Promise.all(
          args.mask.map(async (selector: string) => await page!.$(selector))
        );
      }
  
      const screenshot = await page!.screenshot(screenshotOptions);
      const base64Screenshot = screenshot.toString('base64');
  
      const responseContent: (TextContent | ImageContent)[] = [];
  
      // Handle PNG file saving
      if (args.savePng !== false) {
        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
        const filename = `${args.name}-${timestamp}.png`;
        const downloadsDir = args.downloadsDir || defaultDownloadsPath;
  
        // Create downloads directory if it doesn't exist
        if (!fs.existsSync(downloadsDir)) {
          fs.mkdirSync(downloadsDir, { recursive: true });
        }
  
        const filePath = path.join(downloadsDir, filename);
        await fs.promises.writeFile(filePath, screenshot);
        responseContent.push({
          type: "text",
          text: `Screenshot saved to: ${filePath}`,
        } as TextContent);
      }
  
      // Handle base64 storage
      if (args.storeBase64 !== false && !process.argv.includes('--no-storebase64')) {
        screenshots.set(args.name, base64Screenshot);
        server.notification({
          method: "notifications/resources/list_changed",
        });
  
        responseContent.push({
          type: "image",
          data: base64Screenshot,
          mimeType: "image/png",
        } as ImageContent);
      }
  
      return {
        content: responseContent,
        isError: false,
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Screenshot failed: ${(error as Error).message}`,
        }],
        isError: true,
      };
    }
  }

• src/tools.ts:20-36 (schema)

  Tool schema definition including name, description, and inputSchema for validation of parameters like name, selector, dimensions, storage options.

  {
    name: "playwright_screenshot",
    description: "Take a screenshot of the current page or a specific element",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name for the screenshot" },
        selector: { type: "string", description: "CSS selector for element to screenshot" },
        width: { type: "number", description: "Width in pixels (default: 800)" },
        height: { type: "number", description: "Height in pixels (default: 600)" },
        storeBase64: { type: "boolean", description: "Store screenshot in base64 format (default: true)" },
        savePng: { type: "boolean", description: "Save screenshot as PNG file (default: false)" },
        downloadsDir: { type: "string", description: "Custom downloads directory path (default: user's Downloads folder)" },
      },
      required: ["name"],
    },
  },

• src/requestHandler.ts:59-62 (registration)

  Registration of the listTools request handler, which returns the array of tool definitions including 'playwright_screenshot'.

  // List tools handler
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: tools,
  }));

• src/requestHandler.ts:64-67 (registration)

  Registration of the callTool request handler, which dispatches to handleToolCall containing the switch case for 'playwright_screenshot'.

  // Call tool handler
  server.setRequestHandler(CallToolRequestSchema, async (request) =>
    handleToolCall(request.params.name, request.params.arguments ?? {}, server)
  );

• src/tools.ts:156-164 (helper)

  Helper array BROWSER_TOOLS that includes 'playwright_screenshot' to conditionally launch browser only when needed.

  export const BROWSER_TOOLS = [
    "playwright_navigate",
    "playwright_screenshot",
    "playwright_click",
    "playwright_fill",
    "playwright_select",
    "playwright_hover",
    "playwright_evaluate"
  ];