Playwright MCP Server

Instructions

Implementation Reference

• src/tools/browser/screenshot.ts:23-81 (handler)

  The main handler logic for taking screenshots of the page or specific elements using Playwright's page.screenshot() method. Handles saving to file, base64 storage, and notifications.

  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);
    });
  }

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

  The tool definition including name, description, and input schema 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:459-460 (registration)

  Registration in the main tool dispatcher switch statement, routing calls to the ScreenshotTool instance.

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

• src/toolHandler.ts:286-286 (registration)

  Instantiation of the ScreenshotTool class in the initializeTools function.

  if (!screenshotTool) screenshotTool = new ScreenshotTool(server);

• src/tools/browser/screenshot.ts:17-89 (helper)

  Full ScreenshotTool class definition, extending BrowserToolBase for shared browser handling.

  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;
    }
  }