Browserbase MCP Server

Instructions

Implementation Reference

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

  The handler function `handleAct` that performs the browser action using Stagehand's `page.act()` method.

  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:28-36 (schema)

  The tool schema definition including the name 'browserbase_stagehand_act', description, and reference to input schema.

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

  The Zod input schema `ActInputSchema` defining the `action` string and optional `variables` object.

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

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

  The `actTool` is included in the `TOOLS` array export, making it available for registration in the MCP server.

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

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

  Generic tool registration loop that registers all tools from the `TOOLS` array with the MCP server using `server.tool()`, 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}`,
      );
    }
  });