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