Browser Agent MCP

Instructions

Implementation Reference

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

  Main handler function for browser_screenshot tool. Captures screenshot of page or element using Playwright, supports selector, fullPage, mask options, saves PNG to Downloads folder with timestamp, encodes to base64 for ImageContent, updates screenshot registry, sends notification, returns text and image content.

  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)

  Input schema and metadata for the browser_screenshot tool, defining parameters like name (required), selector, fullPage, mask array, 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/executor.ts:191-192 (registration)

  Switch case in executeToolCall function that dispatches browser_screenshot tool calls to the handleBrowserScreenshot handler.

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

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

  browser_screenshot included in BROWSER_TOOLS constant array, used to identify and initialize browser tools in executor.

  "browser_screenshot",