mcp-playwright

Instructions

Implementation Reference

• src/tools/browser/screenshot.ts:13-77 (handler)

  The ScreenshotTool class provides the core implementation of the playwright_screenshot tool, including the execute method that takes screenshots of the page or elements using Playwright's page.screenshot.

  export class ScreenshotTool extends BrowserToolBase {
    private screenshots = new Map<string, string>();
  
    /**
     * Execute the screenshot tool
     */
    async execute(args: any, context: ToolContext): Promise<ToolResponse> {
      return this.safeExecute(context, async (page) => {
        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;
        }
  
        // Generate output path
        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
        const filename = `${args.name || 'screenshot'}-${timestamp}.png`;
        const downloadsDir = args.downloadsDir || defaultDownloadsPath;
  
        if (!fs.existsSync(downloadsDir)) {
          fs.mkdirSync(downloadsDir, { recursive: true });
        }
  
        const outputPath = path.join(downloadsDir, filename);
        screenshotOptions.path = outputPath;
  
        const screenshot = await page.screenshot(screenshotOptions);
        const base64Screenshot = screenshot.toString('base64');
  
        const messages = [`Screenshot saved to: ${path.relative(process.cwd(), outputPath)}`];
  
        // Handle base64 storage
        if (args.storeBase64 !== false) {
          this.screenshots.set(args.name || 'screenshot', base64Screenshot);
          this.server.notification({
            method: "notifications/resources/list_changed",
          });
  
          messages.push(`Screenshot also stored in memory with name: '${args.name || 'screenshot'}'`);
        }
  
        return createSuccessResponse(messages);
      });
    }
  
    /**
     * Get all stored screenshots
     */
    getScreenshots(): Map<string, string> {
      return this.screenshots;
    }
  } 

• src/tools.ts:95-112 (schema)

  Tool schema definition including name, description, and inputSchema for validation.

  {
    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)" },
        fullPage: { type: "boolean", description: "Store screenshot of the entire page (default: false)" },
        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/toolHandler.ts:475-476 (registration)

  Registration in the main tool handler switch statement, dispatching to the ScreenshotTool execute method.

  case "playwright_screenshot":
    return await screenshotTool.execute(args, context);

• src/tools.ts:96-112 (registration)

  Tool is defined and registered in createToolDefinitions() function for MCP tool registry.

    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)" },
        fullPage: { type: "boolean", description: "Store screenshot of the entire page (default: false)" },
        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/tools.ts:450-452 (helper)

  The tool is listed in BROWSER_TOOLS array, used to conditionally launch browser before execution.

  export const BROWSER_TOOLS = [
    "playwright_navigate",
    "playwright_screenshot",