Browserbase MCP Server

Instructions

Implementation Reference

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

  The handleObserve function is the core handler for the 'browserbase_stagehand_observe' tool. It retrieves the stagehand instance from context, calls stagehand.page.observe with the instruction and optional returnAction, formats the observations as JSON text, and returns it as ToolResult.

  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)

  The Zod schema definitions for the tool input (ObserveInputSchema) and the overall tool schema (observeSchema), including the tool name 'browserbase_stagehand_observe', detailed description, and input validation for 'instruction' and optional 'returnAction'.

  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)

  The observeTool object that combines the schema and handler, exported as default for use in tool registration.

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

• src/tools/index.ts:37-45 (registration)

  The TOOLS array in tools/index.ts includes the observeTool, making it available for registration in the MCP server.

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

• src/index.ts:191-218 (registration)

  The registration loop in src/index.ts that iterates over all TOOLS (including observeTool) and calls server.tool() with the tool's schema.name ('browserbase_stagehand_observe'), description, input schema, and a wrapper handler that invokes 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}`,
      );
    }
  });