Playwright Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/snapshot.ts:380-493 (handler)

  The core implementation of the 'browserbase_take_screenshot' tool. The 'handle' function captures a screenshot of the page or a specific element (using ref from snapshot), saves it optionally, and returns it as base64-encoded image content (unless configured to omit). Supports PNG (raw=true) or JPEG.

  const screenshot = defineTool<typeof screenshotSchema>({
    capability: "core",
    schema: {
      name: "browserbase_take_screenshot",
      description: `Take a screenshot of the current page or element using ref.`,
      inputSchema: screenshotSchema,
    },
    handle: async (
      context: Context,
      params: ScreenshotInput
    ): Promise<ToolResult> => {
      if (!!params.element !== !!params.ref) {
        throw new Error("Both element and ref must be provided or neither.");
      }
  
      const page = await context.getActivePage();
      if (!page) {
        throw new Error("No active page found for screenshot");
      }
      // Conditionally get snapshot only if ref is provided
      let pageSnapshot: PageSnapshot | null = null;
      if (params.ref) {
        pageSnapshot = context.snapshotOrDie();
      }
      const fileType = params.raw ? "png" : "jpeg";
      const fileName = await outputFile(
        context.config,
        `screenshot-${Date.now()}.${fileType}`
      );
  
      const baseOptions: PageScreenshotOptions = {
        scale: "css",
        timeout: 15000, // Kept existing timeout
      };
  
      let options: PageScreenshotOptions;
  
      if (fileType === "jpeg") {
        options = {
          ...baseOptions,
          type: "jpeg",
          quality: 50, // Quality is only for jpeg
          path: fileName,
        };
      } else {
        options = {
          ...baseOptions,
          type: "png",
          path: fileName,
        };
      }
  
      const isElementScreenshot = params.element && params.ref;
      const code: string[] = [];
      code.push(
        `// Screenshot ${
          isElementScreenshot ? params.element : "viewport"
        } and save it as ${fileName}`
      );
  
      // Conditionally get locator only if ref and snapshot are available
      const locator =
        params.ref && pageSnapshot ? pageSnapshot.refLocator(params.ref) : null;
  
      // Use JSON.stringify for code generation as javascript.formatObject is not available
      const optionsForCode = { ...options };
      // delete optionsForCode.path; // Path is an internal detail for saving, not usually part of the "command" log
  
      if (locator) {
        code.push(
          `// await page.${await generateLocator(
            locator
          )}.screenshot(${JSON.stringify(optionsForCode)});`
        );
      } else {
        code.push(`// await page.screenshot(${JSON.stringify(optionsForCode)});`);
      }
  
      const action = async (): Promise<ToolActionResult> => {
        // Access config via context.config
        const includeBase64 =
          !context.config.tools?.browserbase_take_screenshot?.omitBase64;
  
        // Use the page directly for full page screenshots if locator is null
        const screenshotBuffer = locator
          ? await locator.screenshot(options)
          : await page.screenshot(options);
  
        if (includeBase64) {
          const rawBase64 = screenshotBuffer.toString("base64");
          return {
            content: [
              {
                type: "image",
                format: fileType, // format might be redundant if mimeType is present, but kept for now
                mimeType: fileType === "png" ? `image/png` : `image/jpeg`,
                data: rawBase64,
              },
            ],
          };
        } else {
          // If base64 is not included, return an empty content array
          return { content: [] };
        }
      };
  
      return {
        code,
        action,
        captureSnapshot: true, 
        waitForNetwork: false, 
      };
    },
  });

• src/tools/snapshot.ts:361-378 (schema)

  Zod schema defining the input parameters for the browserbase_take_screenshot tool: optional 'raw' for format, and optional 'element'/'ref' for element-specific screenshot.

  const screenshotSchema = z.object({
    raw: z
      .boolean()
      .optional()
      .describe(
        "Whether to return without compression (PNG). Default is false (JPEG)."
      ),
    element: z
      .string()
      .optional()
      .describe("Human-readable element description."),
    ref: z
      .string()
      .optional()
      .describe("Exact target element reference from the page snapshot.")
  });
  
  type ScreenshotInput = z.infer<typeof screenshotSchema>;

• src/index.ts:73-108 (registration)

  The browserbase_take_screenshot tool (imported from snapshot.ts) is included in the tools array and registered with the MCP server via server.tool() in the forEach loop.

  const tools: Tool<any>[] = [
    ...common,
    ...snapshot,
    ...keyboard,
    ...getText,
    ...navigate,
    ...session,
    ...contextTools,
  ];
  
  // Register each tool with the Smithery server
  tools.forEach(tool => {
    if (tool.schema.inputSchema instanceof z.ZodObject) {
      server.tool(
        tool.schema.name,
        tool.schema.description,
        tool.schema.inputSchema.shape,
        async (params: z.infer<typeof tool.schema.inputSchema>) => {
          try {
            const result = await context.run(tool, params);
            return result;
          } catch (error) {
            const errorMessage = error instanceof Error ? error.message : String(error);
            process.stderr.write(`[Smithery Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\n`);
            throw new Error(`Failed to run tool '${tool.schema.name}': ${errorMessage}`);
          }
        }
      );
    } else {
      console.warn(
        `Tool "${tool.schema.name}" has an input schema that is not a ZodObject. Schema type: ${tool.schema.inputSchema.constructor.name}`
      );
    }
  });
  
  return server.server;

• src/index.ts:47-51 (schema)

  Configuration schema option for the tool, allowing to omit base64 image data in responses.

  tools: z.object({
    browserbase_take_screenshot: z.object({
      omitBase64: z.boolean().optional().describe("Whether to disable base64-encoded image responses")
    }).optional()
  }).optional()

• config.d.ts:77-83 (schema)

  TypeScript type definition for the tool's configuration in Config interface.

  browserbase_take_screenshot?: {
      /**
       * Whether to disable base64-encoded image responses to the clients that
       * don't support binary data or prefer to save on tokens.
      */
      omitBase64?: boolean;
  }