MCP Browser Debugger

Instructions

Implementation Reference

• src/browserTools.ts:215-261 (handler)

  Main handler function that captures screenshot of the current page or a specific element using Puppeteer Page.screenshot or ElementHandle.screenshot. Returns base64 encoded image and optional file path info.

  export async function handleScreenshot(args: unknown, currentPage: Page): Promise<ToolResponse> {
    const typedArgs = args as unknown as ScreenshotArgs;
    const { selector, fullPage = false, path } = typedArgs;
  
    const screenshotOptions: {
      fullPage: boolean;
      path?: string;
    } = { fullPage };
    if (path) screenshotOptions.path = path;
  
    let screenshot: Buffer | string;
    if (selector) {
      const element = await currentPage.$(selector);
      if (!element) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({ error: `Elemento não encontrado: ${selector}` }),
            },
          ],
        };
      }
      const result = await element.screenshot(screenshotOptions);
      screenshot = Buffer.from(result);
    } else {
      const result = await currentPage.screenshot(screenshotOptions);
      screenshot = Buffer.from(result);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(
            {
              success: true,
              message: path ? `Screenshot salva em: ${path}` : 'Screenshot capturada',
              base64: typeof screenshot === 'string' ? screenshot : screenshot.toString('base64'),
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools.ts:84-105 (schema)

  JSON schema definition for the screenshot tool input parameters, used for MCP tool listing and validation.

  {
    name: 'screenshot',
    description: 'Captura uma screenshot da página ou de um elemento específico',
    inputSchema: {
      type: 'object',
      properties: {
        selector: {
          type: 'string',
          description: 'Seletor CSS do elemento (opcional, captura página inteira se omitido)',
        },
        fullPage: {
          type: 'boolean',
          description: 'Capturar página inteira incluindo scroll',
          default: false,
        },
        path: {
          type: 'string',
          description: "Caminho para salvar a screenshot (ex: './screenshot.png')",
        },
      },
    },
  },

• src/types.ts:49-53 (schema)

  TypeScript interface defining the input arguments for the screenshot handler.

  export interface ScreenshotArgs {
    selector?: string;
    fullPage?: boolean;
    path?: string;
  }

• src/index.ts:83-86 (registration)

  Dispatch registration in the MCP server request handler switch statement, which routes 'screenshot' tool calls to the handleScreenshot function.

  case 'screenshot': {
    const currentPage = await initBrowser();
    return await handleScreenshot(args, currentPage);
  }