Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/screenshot.ts:20-77 (handler)

  The main handler function for the browserbase_screenshot tool. It captures a screenshot of the current active Browserbase page, converts it to base64, stores it in the screenshots resource map, notifies the client of resource changes, and returns the screenshot as image content.

  async function handleScreenshot(
    context: Context,
    params: ScreenshotInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const page = await context.getActivePage();
        if (!page) {
          throw new Error("No active page available");
        }
  
        const screenshotBuffer = await page.screenshot({
          fullPage: false,
        });
  
        // Convert buffer to base64 string and store in memory
        const screenshotBase64 = screenshotBuffer.toString("base64");
        const name = params.name
          ? `screenshot-${params.name}-${new Date()
              .toISOString()
              .replace(/:/g, "-")}`
          : `screenshot-${new Date().toISOString().replace(/:/g, "-")}` +
            context.config.browserbaseProjectId;
        screenshots.set(name, screenshotBase64);
  
        // Notify the client that the resources changed
        const serverInstance = context.getServer();
  
        if (serverInstance) {
          serverInstance.notification({
            method: "notifications/resources/list_changed",
          });
        }
  
        return {
          content: [
            {
              type: "text",
              text: `Screenshot taken with name: ${name}`,
            },
            {
              type: "image",
              data: screenshotBase64,
              mimeType: "image/png",
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to take screenshot: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/screenshot.ts:13-18 (schema)

  The schema definition for the browserbase_screenshot tool, including name, description, and input schema (ScreenshotInputSchema defined above).

  const screenshotSchema: ToolSchema<typeof ScreenshotInputSchema> = {
    name: "browserbase_screenshot",
    description:
      "Takes a screenshot of the current page. Use this tool to learn where you are on the page when controlling the browser with Stagehand. Only use this tool when the other tools are not sufficient to get the information you need.",
    inputSchema: ScreenshotInputSchema,
  };

• src/tools/screenshot.ts:79-85 (registration)

  Local registration of the screenshot tool object, combining schema and handler, exported as default.

  const screenshotTool: Tool<typeof ScreenshotInputSchema> = {
    capability: "core",
    schema: screenshotSchema,
    handle: handleScreenshot,
  };
  
  export default screenshotTool;

• src/tools/index.ts:43-52 (registration)

  Includes the screenshotTool in the main TOOLS array exported from tools/index.ts, which collects all available tools.

  export const TOOLS = [
    ...multiSessionTools,
    ...sessionTools,
    navigateTool,
    actTool,
    extractTool,
    observeTool,
    screenshotTool,
    getUrlTool,
  ];

• src/index.ts:196-226 (registration)

  Registers all tools from TOOLS array with the MCP server using server.tool(), wrapping the tool handler with context.run(tool, params). This is where 'browserbase_screenshot' is registered in the MCP protocol.

  const tools: MCPToolsArray = [...TOOLS];
  
  // 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}`,
      );
    }
  });