Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/act.ts:38-69 (handler)

  The main handler function that executes the tool by calling stagehand.page.act() with the provided action and variables.

  async function handleAct(
    context: Context,
    params: ActInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const stagehand = await context.getStagehand();
  
        await stagehand.page.act({
          action: params.action,
          variables: params.variables,
        });
  
        return {
          content: [
            {
              type: "text",
              text: `Action performed: ${params.action}`,
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to perform action: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/act.ts:6-36 (schema)

  Defines the Zod input schema for the action and variables, and the tool schema with name 'browserbase_stagehand_act'.

  const ActInputSchema = z.object({
    action: z
      .string()
      .describe(
        "The action to perform. Should be as atomic and specific as possible, " +
          "i.e. 'Click the sign in button' or 'Type 'hello' into the search input'. AVOID actions that are more than one " +
          "step, i.e. 'Order me pizza' or 'Send an email to Paul asking him to call me'. The instruction should be just as specific as possible, " +
          "and have a strong correlation to the text on the page. If unsure, use observe before using act.",
      ),
    variables: z
      .object({})
      .optional()
      .describe(
        "Variables used in the action template. ONLY use variables if you're dealing " +
          "with sensitive data or dynamic content. For example, if you're logging in to a website, " +
          "you can use a variable for the password. When using variables, you MUST have the variable " +
          'key in the action template. For example: {"action": "Fill in the password", "variables": {"password": "123456"}}',
      ),
  });
  
  type ActInput = z.infer<typeof ActInputSchema>;
  
  const actSchema: ToolSchema<typeof ActInputSchema> = {
    name: "browserbase_stagehand_act",
    description:
      "Performs an action on a web page element. Act actions should be as atomic and " +
      'specific as possible, i.e. "Click the sign in button" or "Type \'hello\' into the search input". ' +
      'AVOID actions that are more than one step, i.e. "Order me pizza" or "Send an email to Paul ' +
      'asking him to call me".',
    inputSchema: ActInputSchema,
  };

• src/tools/act.ts:71-75 (registration)

  Creates and exports the actTool object that bundles the schema and handler.

  const actTool: Tool<typeof ActInputSchema> = {
    capability: "core",
    schema: actSchema,
    handle: handleAct,
  };

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

  Includes the actTool in the TOOLS array exported for use in MCP server registration.

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

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

  Registers all tools from the TOOLS array to the MCP server by calling server.tool() for each, including browserbase_stagehand_act.

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