Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/session.ts:141-229 (handler)

  The handleCloseSession function that implements the tool's core logic: gets the current session, closes the Stagehand instance if available, cleans up the session tracking, resets the context's current session ID to default, and returns appropriate success or info messages with error handling.

  async function handleCloseSession(context: Context): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      // Store the current session ID before it's potentially changed.
      const previousSessionId = context.currentSessionId;
      let stagehandClosedSuccessfully = false;
      let stagehandCloseErrorMessage = "";
  
      // Step 1: Attempt to get the session and close Stagehand
      let browserbaseSessionId: string | undefined;
      try {
        const session = await getSession(
          previousSessionId,
          context.config,
          false,
        );
  
        if (session && session.stagehand) {
          // Store the actual Browserbase session ID for the replay URL
          browserbaseSessionId = session.sessionId;
  
          process.stderr.write(
            `[tool.closeSession] Attempting to close Stagehand for session: ${previousSessionId || "default"} (Browserbase ID: ${browserbaseSessionId})`,
          );
  
          // Use Stagehand's close method which handles browser cleanup properly
          await session.stagehand.close();
          stagehandClosedSuccessfully = true;
  
          process.stderr.write(
            `[tool.closeSession] Stagehand and browser connection for session (${previousSessionId}) closed successfully.`,
          );
  
          // Clean up the session from tracking
          await cleanupSession(previousSessionId);
  
          if (browserbaseSessionId) {
            process.stderr.write(
              `[tool.closeSession] View session replay at https://www.browserbase.com/sessions/${browserbaseSessionId}`,
            );
          }
        } else {
          process.stderr.write(
            `[tool.closeSession] No Stagehand instance found for session: ${previousSessionId || "default/unknown"}`,
          );
        }
      } catch (error: unknown) {
        stagehandCloseErrorMessage =
          error instanceof Error ? error.message : String(error);
        process.stderr.write(
          `[tool.closeSession] Error retrieving or closing Stagehand (session ID was ${previousSessionId || "default/unknown"}): ${stagehandCloseErrorMessage}`,
        );
      }
  
      // Step 2: Always reset the context's current session ID to default
      const oldContextSessionId = context.currentSessionId;
      context.currentSessionId = defaultSessionId;
      process.stderr.write(
        `[tool.closeSession] Session context reset to default. Previous context session ID was ${oldContextSessionId || "default/unknown"}.`,
      );
  
      // Step 3: Determine the result message
      if (stagehandCloseErrorMessage && !stagehandClosedSuccessfully) {
        throw new Error(
          `Failed to close the Stagehand session (session ID in context was ${previousSessionId || "default/unknown"}). Error: ${stagehandCloseErrorMessage}. Session context has been reset to default.`,
        );
      }
  
      if (stagehandClosedSuccessfully) {
        let successMessage = `Browserbase session (${previousSessionId || "default"}) closed successfully via Stagehand. Context reset to default.`;
        if (browserbaseSessionId && previousSessionId !== defaultSessionId) {
          successMessage += ` View replay at https://www.browserbase.com/sessions/${browserbaseSessionId}`;
        }
        return { content: [{ type: "text", text: successMessage }] };
      }
  
      // No Stagehand instance was found
      let infoMessage =
        "No active Stagehand session found to close. Session context has been reset to default.";
      if (previousSessionId && previousSessionId !== defaultSessionId) {
        infoMessage = `No active Stagehand session found for session ID '${previousSessionId}'. The context has been reset to default.`;
      }
      return { content: [{ type: "text", text: infoMessage }] };
    };
  
    return {
      action: action,
      waitForNetwork: false,
    };
  }

• src/tools/session.ts:132-139 (schema)

  Defines the input schema (empty, no params needed) and the tool schema including the unique name 'browserbase_session_close', description, and inputSchema reference.

  const CloseSessionInputSchema = z.object({});
  
  const closeSessionSchema: ToolSchema<typeof CloseSessionInputSchema> = {
    name: "browserbase_session_close",
    description:
      "Closes the current Browserbase session by properly shutting down the Stagehand instance, which handles browser cleanup and terminates the session recording.",
    inputSchema: CloseSessionInputSchema,
  };

• src/tools/session.ts:231-237 (registration)

  Registers the tool by creating the closeSessionTool object that combines the schema and handler function, and exports it within the array of session tools.

  const closeSessionTool: Tool<typeof CloseSessionInputSchema> = {
    capability: "core",
    schema: closeSessionSchema,
    handle: handleCloseSession,
  };
  
  export default [createSessionTool, closeSessionTool];

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

  Aggregates all tools, including sessionTools (which contains browserbase_session_close), into the central TOOLS array exported for use in MCP server setup.

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

• src/index.ts:192-222 (registration)

  Final MCP server registration: loops over TOOLS array and calls server.tool() for each, using the tool's schema.name ('browserbase_session_close'), description, input schema shape, and a wrapper handler that invokes context.run(tool, params).

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