browser_screenshot

Instructions

Implementation Reference

• src/executor.ts:276-351 (handler)

  The main handler function for browser_screenshot. Takes a Playwright Page, args, and server. Captures a full-page or element-specific screenshot (PNG), optionally masks elements, saves to disk (defaults to Downloads folder), registers in screenshotRegistry, sends a resource list change notification, and returns the image as base64 in the response.

  async function handleBrowserScreenshot(page: Page, args: any, server: any): Promise<{ toolResult: CallToolResult }> {
    try {
      const options: any = {
        type: "png",
        fullPage: !!args.fullPage
      };
  
      if (args.selector) {
        const element = await page.$(args.selector);
        if (!element) {
          return {
            toolResult: {
              content: [{
                type: "text",
                text: `Element not found: ${args.selector}`,
              }],
              isError: true,
            },
          };
        }
        options.element = element;
      }
  
      if (args.mask && Array.isArray(args.mask)) {
        options.mask = await Promise.all(
          args.mask.map(async (selector: string) => await page.$(selector))
        );
      }
  
      const screenshot = await page.screenshot(options);
      const base64Screenshot = screenshot.toString('base64');
      const responseContent: (TextContent | ImageContent)[] = [];
      const savePath = args.savePath || defaultDownloadsPath;
      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
      const filename = `${args.name}-${timestamp}.png`;
      const filePath = path.join(savePath, filename);
      const dir = path.dirname(filePath);
      if (!fs.existsSync(dir)) {
        fs.mkdirSync(dir, { recursive: true });
      }
  
      fs.writeFileSync(filePath, screenshot);
      responseContent.push({
        type: "text",
        text: `Screenshot saved to: ${filePath}`,
      } as TextContent);
  
      screenshotRegistry.set(args.name, base64Screenshot);
      server.notification({
        method: "notifications/resources/list_changed",
      });
  
      responseContent.push({
        type: "image",
        data: base64Screenshot,
        mimeType: "image/png",
      } as ImageContent);
  
      return {
        toolResult: {
          content: responseContent,
          isError: false,
        },
      };
    } catch (error) {
      return {
        toolResult: {
          content: [{
            type: "text",
            text: `Screenshot failed: ${(error as Error).message}`,
          }],
          isError: true,
        },
      };
    }
  }

• src/tools.ts:54-72 (schema)

  Schema definition for browser_screenshot tool. Defines input properties: name (required), selector, fullPage, mask (array of CSS selectors), and savePath.

  {
    name: "browser_screenshot",
    description: "Capture a screenshot of the current page or a specific element",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Identifier for the screenshot" },
        selector: { type: "string", description: "CSS selector for element to capture" },
        fullPage: { type: "boolean", description: "Capture full page height" },
        mask: { 
          type: "array", 
          description: "Selectors for elements to mask",
          items: { type: "string" }
        },
        savePath: { type: "string", description: "Path to save screenshot (default: user's Downloads folder)" }
      },
      required: ["name"]
    }
  },

• src/tools.ts:54-72 (registration)

  Tool registration in registerTools() function. Returns a Tool object with name, description, and inputSchema for the MCP server.

  {
    name: "browser_screenshot",
    description: "Capture a screenshot of the current page or a specific element",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Identifier for the screenshot" },
        selector: { type: "string", description: "CSS selector for element to capture" },
        fullPage: { type: "boolean", description: "Capture full page height" },
        mask: { 
          type: "array", 
          description: "Selectors for elements to mask",
          items: { type: "string" }
        },
        savePath: { type: "string", description: "Path to save screenshot (default: user's Downloads folder)" }
      },
      required: ["name"]
    }
  },

• src/tools.ts:3-12 (registration)

  Registration of browser_screenshot in the BROWSER_TOOLS array, used to determine whether to initialize the browser before executing the tool.

  export const BROWSER_TOOLS = [
    "browser_navigate",
    "browser_screenshot",
    "browser_click",
    "browser_fill",
    "browser_select",
    "browser_hover",
    "browser_evaluate",
    "browser_set_viewport"
  ];

• src/executor.ts:191-192 (handler)

  Dispatch call in executeToolCall() switch statement that routes browser_screenshot to handleBrowserScreenshot.

  case "browser_screenshot":
    return await handleBrowserScreenshot(activePage!, args, server);