Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/observe.ts:44-75 (handler)

  The handleObserve function implements the core logic of the 'browserbase_stagehand_observe' tool. It retrieves the stagehand instance from context and calls stagehand.page.observe with the instruction and optional returnAction flag, then formats the observations as a text content result.

  async function handleObserve(
    context: Context,
    params: ObserveInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const stagehand = await context.getStagehand();
  
        const observations = await stagehand.page.observe({
          instruction: params.instruction,
          returnAction: params.returnAction,
        });
  
        return {
          content: [
            {
              type: "text",
              text: `Observations: ${JSON.stringify(observations)}`,
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to observe: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/observe.ts:30-42 (schema)

  The tool schema defining the name 'browserbase_stagehand_observe', detailed description, and input schema (ObserveInputSchema defined earlier in the file).

  const observeSchema: ToolSchema<typeof ObserveInputSchema> = {
    name: "browserbase_stagehand_observe",
    description:
      "Observes and identifies specific interactive elements on the current web page that can be used for subsequent actions. " +
      "This tool is specifically designed for finding actionable (interactable) elements such as buttons, links, form fields, " +
      "dropdowns, checkboxes, and other UI components that you can interact with. Use this tool when you need to locate " +
      "elements before performing actions with the act tool. DO NOT use this tool for extracting text content or data - " +
      "use the extract tool instead for that purpose. The observe tool returns detailed information about the identified " +
      "elements including their properties, location, and interaction capabilities. This information can then be used " +
      "to craft precise actions. The more specific your observation instruction, the more accurate the element identification " +
      "will be. Think of this as your 'eyes' on the page to find exactly what you need to interact with.",
    inputSchema: ObserveInputSchema,
  };

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

  The observeTool is included in the exported TOOLS array, which collects all available tools for registration in the MCP server.

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

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

  The TOOLS array (including observeTool) is spread into 'tools' and each tool is registered on the MCP server via server.tool() using its schema.name. The handler is wrapped to call context.run(tool, params), which invokes the tool's handle function.

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

• src/tools/observe.ts:77-83 (registration)

  The observeTool object is created by combining the schema and handle function, and exported for use in higher-level tool registries.

  const observeTool: Tool<typeof ObserveInputSchema> = {
    capability: "core",
    schema: observeSchema,
    handle: handleObserve,
  };
  
  export default observeTool;