v0 multi-session tools

Author: Kylejeong2

README.md

@@ -19,6 +19,7 @@ This server provides cloud browser automation capabilities using [Browserbase](h
 | Model Flexibility  | Supports multiple models (OpenAI, Claude, Gemini, and more) |
 | Vision Support     | Use annotated screenshots for complex DOMs                  |
 | Session Management | Create, manage, and close browser sessions                  |
+| Multi-Session      | Run multiple browser sessions in parallel                   |
 
 ### Alternative Installation Methods
 
@@ -332,6 +333,82 @@ The Browserbase MCP server provides the following tools for browser automation:
   - Output:
     - Confirmation message and session replay URL
 
+### Multi-Session Management Tools
+
+The server now supports managing multiple browser sessions in parallel, allowing you to control multiple browsers simultaneously:
+
+- **stagehand_session_create_multi**
+  - Create a new independent Stagehand browser session
+  - Inputs:
+    - `name` (string, optional): Optional name for the session
+    - `browserbaseSessionID` (string, optional): Resume an existing Browserbase session
+    - `browserbaseSessionCreateParams` (object, optional): Custom Browserbase session parameters
+  - Output:
+    - Session ID and Browserbase session ID
+
+- **stagehand_session_list**
+  - List all active Stagehand browser sessions
+  - No inputs required
+  - Output:
+    - List of active sessions with IDs, names, and metadata
+
+- **stagehand_session_close_multi**
+  - Close a specific Stagehand browser session
+  - Input:
+    - `sessionId` (string): The session ID to close
+  - Output:
+    - Confirmation message
+
+- **stagehand_navigate_session**
+  - Navigate to a URL in a specific browser session
+  - Inputs:
+    - `sessionId` (string): The session ID to use
+    - `url` (string): The URL to navigate to
+
+- **stagehand_act_session**
+  - Perform an action in a specific browser session
+  - Inputs:
+    - `sessionId` (string): The session ID to use
+    - `action` (string): The action to perform
+    - `variables` (object, optional): Variables for the action
+
+- **stagehand_extract_session**
+  - Extract information from a specific browser session
+  - Inputs:
+    - `sessionId` (string): The session ID to use
+    - `instruction` (string): What to extract
+
+- **stagehand_observe_session**
+  - Observe elements in a specific browser session
+  - Inputs:
+    - `sessionId` (string): The session ID to use
+    - `instruction` (string): What to observe
+    - `returnAction` (boolean, optional): Whether to return the action
+
+### Multi-Session Example
+
+Here's an example of using multiple browser sessions in parallel:
+
+```javascript
+// Create two sessions
+const searchSession = await createSession({ name: "Search Engine" });
+const newsSession = await createSession({ name: "News Reader" });
+
+// Navigate both sessions in parallel
+await Promise.all([
+  navigateSession(searchSession.id, "https://google.com"),
+  navigateSession(newsSession.id, "https://news.ycombinator.com")
+]);
+
+// Perform actions on both sessions
+await actSession(searchSession.id, "Search for 'AI tools'");
+const news = await extractSession(newsSession.id, "Extract top 5 headlines");
+
+// Clean up
+await closeSession(searchSession.id);
+await closeSession(newsSession.id);
+```
+
 ### Resources
 
 The server provides access to screenshot resources:
@@ -414,9 +491,10 @@ mcp-server-browserbase/
 
 This server implements the following MCP capabilities:
 
-- **Tools**: 7 tools for comprehensive browser automation
+- **Tools**: 14 tools for comprehensive browser automation
   - 5 Stagehand tools: navigate, act, extract, observe, screenshot
   - 2 Session management tools: create and close Browserbase sessions
+  - 7 Multi-session tools: create, list, close, navigate, act, extract, observe with specific sessions
 - **Prompts**: Prompt templates for common automation tasks
 - **Resources**: Screenshot resource management with URI-based access
 

src/program.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from "url";
 import createServerFunction from "./index.js";
 import { ServerList } from "./server.js";
 import { startHttpTransport, startStdioTransport } from "./transport.js";
+import * as stagehandStore from "./stagehandStore.js";
 
 import { resolveConfig } from "./config.js";
 
@@ -79,6 +80,7 @@ program
 function setupExitWatchdog(serverList: ServerList) {
   const handleExit = async () => {
     setTimeout(() => process.exit(0), 15000);
+    await stagehandStore.removeAll();
     await serverList.closeAll();
     process.exit(0);
   };

src/stagehandStore.ts

@@ -0,0 +1,153 @@
+import { randomUUID } from "crypto";
+import { Stagehand, AvailableModel } from "@browserbasehq/stagehand";
+import { Page } from "playwright-core";
+import { StagehandSession, CreateSessionParams } from "./types/types.js";
+import type { Config } from "../config.js";
+
+// Store for all active sessions
+const store = new Map<string, StagehandSession>();
+
+/**
+ * Create a new Stagehand session
+ */
+export const create = async (
+  config: Config,
+  params: CreateSessionParams = {}
+): Promise<StagehandSession> => {
+  const id = randomUUID();
+  
+  // Merge config with params
+  const apiKey = params.apiKey || config.browserbaseApiKey;
+  const projectId = params.projectId || config.browserbaseProjectId;
+  
+  if (!apiKey || !projectId) {
+    throw new Error("Browserbase API Key and Project ID are required");
+  }
+
+  process.stderr.write(`[StagehandStore] Creating new session ${id}...\n`);
+
+  const stagehand = new Stagehand({
+    env: "BROWSERBASE",
+    apiKey,
+    projectId,
+    modelName: (params.modelName || config.modelName || "google/gemini-2.0-flash") as AvailableModel,
+    modelClientOptions: {
+      apiKey: process.env.GEMINI_API_KEY, //TODO: 
+    },
+    ...(params.browserbaseSessionID && { browserbaseSessionID: params.browserbaseSessionID }),
+    browserbaseSessionCreateParams: params.browserbaseSessionCreateParams || {
+      projectId,
+      proxies: config.proxies,
+      browserSettings: {
+        viewport: {
+          width: config.viewPort?.browserWidth ?? 1024,
+          height: config.viewPort?.browserHeight ?? 768,
+        },
+        context: config.context?.contextId
+          ? {
+              id: config.context?.contextId,
+              persist: config.context?.persist ?? true,
+            }
+          : undefined,
+        advancedStealth: config.advancedStealth ?? undefined,
+      },
+    },
+    logger: (logLine) => {
+      console.error(`Stagehand[${id}]: ${logLine.message}`);
+    },
+  });
+
+  await stagehand.init();
+
+  const page = stagehand.page as unknown as Page;
+  const browser = page.context().browser();
+
+  if (!browser) {
+    throw new Error("Failed to get browser from Stagehand page context");
+  }
+
+  const session: StagehandSession = {
+    id,
+    stagehand,
+    page,
+    browser,
+    created: Date.now(),
+    metadata: {
+      ...params.meta,
+      bbSessionId: stagehand.browserbaseSessionID,
+    },
+  };
+
+  store.set(id, session);
+
+  process.stderr.write(
+    `[StagehandStore] Session created: ${id} (BB: ${stagehand.browserbaseSessionID})\n`
+  );
+  process.stderr.write(
+    `[StagehandStore] Live debugger: https://www.browserbase.com/sessions/${stagehand.browserbaseSessionID}\n`
+  );
+
+  // Set up disconnect handler
+  browser.on("disconnected", () => {
+    process.stderr.write(`[StagehandStore] Session disconnected: ${id}\n`);
+    store.delete(id);
+  });
+
+  return session;
+};
+
+/**
+ * Get a session by ID
+ */
+export const get = (id: string): StagehandSession | null => {
+  return store.get(id) ?? null;
+};
+
+/**
+ * List all active sessions
+ */
+export const list = (): StagehandSession[] => {
+  return Array.from(store.values());
+};
+
+/**
+ * Remove and close a session
+ */
+export const remove = async (id: string): Promise<void> => {
+  const session = store.get(id);
+  if (!session) {
+    process.stderr.write(`[StagehandStore] Session not found for removal: ${id}\n`);
+    return;
+  }
+
+  process.stderr.write(`[StagehandStore] Removing session: ${id}\n`);
+  
+  try {
+    await session.stagehand.close();
+    process.stderr.write(`[StagehandStore] Session closed: ${id}\n`);
+  } catch (error) {
+    process.stderr.write(
+      `[StagehandStore] Error closing session ${id}: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+  }
+
+  store.delete(id);
+};
+
+/**
+ * Remove all sessions
+ */
+export const removeAll = async (): Promise<void> => {
+  process.stderr.write(`[StagehandStore] Removing all ${store.size} sessions...\n`);
+  await Promise.all(list().map(s => remove(s.id)));
+  process.stderr.write(`[StagehandStore] All sessions removed\n`);
+};
+
+/**
+ * Get store size
+ */
+export const size = (): number => {
+  return store.size;
+}; 

src/tools/index.ts

@@ -1,10 +1,18 @@
-// Import all individual tools
 import navigateTool from "./navigate.js";
 import actTool from "./act.js";
 import extractTool from "./extract.js";
 import observeTool from "./observe.js";
 import screenshotTool from "./screenshot.js";
 import sessionTools from "./session.js";
+import {
+  createSessionTool,
+  listSessionsTool,
+  closeSessionTool,
+  navigateWithSessionTool,
+  actWithSessionTool,
+  extractWithSessionTool,
+  observeWithSessionTool,
+} from "./multiSession.js";
 
 // Export individual tools
 export { default as navigateTool } from "./navigate.js";
@@ -14,6 +22,17 @@ export { default as observeTool } from "./observe.js";
 export { default as screenshotTool } from "./screenshot.js";
 export { default as sessionTools } from "./session.js";
 
+// Multi-session tools array
+export const multiSessionTools = [
+  createSessionTool,
+  listSessionsTool,
+  closeSessionTool,
+  navigateWithSessionTool,
+  actWithSessionTool,
+  extractWithSessionTool,
+  observeWithSessionTool,
+];
+
 // Export all tools as array
 export const TOOLS = [
   ...sessionTools,
@@ -22,6 +41,7 @@ export const TOOLS = [
   extractTool,
   observeTool,
   screenshotTool,
+  ...multiSessionTools,
 ];
 
 export const sessionManagementTools = sessionTools;