mcp-playwright

Instructions

Implementation Reference

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

  The ScreenshotTool class provides the core implementation of the playwright_screenshot tool, including the execute method that captures screenshots of the page or specific 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");
  
        let savedLocation = path.relative(process.cwd(), outputPath);
        let resourceLink: Awaited<ReturnType<typeof registerFileResource>> | undefined;
        try {
          resourceLink = await registerFileResource({
            filePath: outputPath,
            name: filename,
            mimeType: "image/png",
            server: this.server,
          });
          if (resourceLink?.uri) {
            savedLocation = resourceLink.uri;
          }
        } catch (error) {
          console.warn("Failed to register screenshot as resource:", error);
        }
  
        // Handle base64 storage
        if (args.storeBase64 !== false) {
          this.screenshots.set(args.name || "screenshot", base64Screenshot);
        }
  
        return {
          ...createSuccessResponse(`Screenshot saved to: ${savedLocation}`),
          ...(resourceLink ? { resourceLinks: [resourceLink] } : {}),
        };
      });
    }
  
    /**
     * Get all stored screenshots
     */
    getScreenshots(): Map<string, string> {
      return this.screenshots;
    }
  }

• src/tools.ts:99-119 (schema)

  The input schema definition for the playwright_screenshot tool, specifying parameters like name, selector, fullPage, etc.

  {
    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:576-577 (registration)

  Registration of the playwright_screenshot handler in the main tool switch statement, delegating to the ScreenshotTool instance.

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

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

  Instantiation of the ScreenshotTool instance used for handling screenshot requests.

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

• src/tools.ts:495-495 (registration)

  Inclusion of playwright_screenshot in the BROWSER_TOOLS array, used to determine browser requirements.

  "playwright_screenshot",