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 by retrieving the stagehand from context and calling stagehand.page.observe() with the input parameters, returning the observations as JSON-formatted text.

  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:6-42 (schema)

  Zod schema definition for the tool's input (ObserveInputSchema) and the complete tool schema (observeSchema) including the tool name 'browserbase_stagehand_observe', detailed description, and input validation.

  const ObserveInputSchema = z.object({
    instruction: z
      .string()
      .describe(
        "Detailed instruction for what specific elements or components to observe on the web page. " +
          "This instruction must be extremely specific and descriptive. For example: 'Find the red login button " +
          "in the top right corner', 'Locate the search input field with placeholder text', or 'Identify all " +
          "clickable product cards on the page'. The more specific and detailed your instruction, the better " +
          "the observation results will be. Avoid generic instructions like 'find buttons' or 'see elements'. " +
          "Instead, describe the visual characteristics, location, text content, or functionality of the elements " +
          "you want to observe. This tool is designed to help you identify interactive elements that you can " +
          "later use with the act tool for performing actions like clicking, typing, or form submission.",
      ),
    returnAction: z
      .boolean()
      .optional()
      .describe(
        "Whether to return the action to perform on the element. If true, the action will be returned as a string. " +
          "If false, the action will not be returned.",
      ),
  });
  
  type ObserveInput = z.infer<typeof ObserveInputSchema>;
  
  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/observe.ts:77-81 (registration)

  Registers the tool components (capability, schema, and handler) into the observeTool object, which is exported as default.

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

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

  The observeTool is included in the main TOOLS export array from tools/index.ts, which collects all tools for registration in the MCP server.

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