Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/extract.ts:34-62 (handler)

  The handleExtract function implements the core logic of the tool by retrieving the stagehand instance from context and calling page.extract() with the user-provided instruction, then formatting and returning the extracted content.

  async function handleExtract(
    context: Context,
    params: ExtractInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const stagehand = await context.getStagehand();
  
        const extraction = await stagehand.page.extract(params.instruction);
  
        return {
          content: [
            {
              type: "text",
              text: `Extracted content:\n${JSON.stringify(extraction, null, 2)}`,
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to extract content: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/extract.ts:21-32 (schema)

  Defines the tool schema including the exact name 'browserbase_stagehand_extract', detailed description, and input schema (ExtractInputSchema defined above with 'instruction' field).

  const extractSchema: ToolSchema<typeof ExtractInputSchema> = {
    name: "browserbase_stagehand_extract",
    description:
      "Extracts structured information and text content from the current web page based on specific instructions " +
      "and a defined schema. This tool is ideal for scraping data, gathering information, or pulling specific " +
      "content from web pages. Use this tool when you need to get text content, data, or information from a page " +
      "rather than interacting with elements. For interactive elements like buttons, forms, or clickable items, " +
      "use the observe tool instead. The extraction works best when you provide clear, specific instructions " +
      "about what to extract and a well-defined JSON schema for the expected output format. This ensures " +
      "the extracted data is properly structured and usable.",
    inputSchema: ExtractInputSchema,
  };

• src/tools/extract.ts:64-68 (registration)

  Creates the extractTool object by combining the schema and handler function, exported for use in tools index.

  const extractTool: Tool<typeof ExtractInputSchema> = {
    capability: "core",
    schema: extractSchema,
    handle: handleExtract,
  };

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

  Registers extractTool in the main TOOLS array, which is imported and used for MCP server tool registration.

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

• src/index.ts:195-222 (registration)

  Loop that registers every tool in the TOOLS array (including browserbase_stagehand_extract) with the MCP server via server.tool(), delegating execution to context.run(tool, params).

  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}`,
      );
    }
  });