add context handler

Author: filip-michalsky

browserbase/README.md

@@ -40,6 +40,33 @@ The server communicates over stdio according to the Model Context Protocol.
 *   `Dockerfile`: For building a Docker image
 *   Configuration files (`.json`, `.ts`, `.mjs`, `.npmignore`)
 
+## Contexts for Persistence
+
+This server supports Browserbase's Contexts feature, which allows persisting cookies, authentication, and cached data across browser sessions:
+
+1. **Creating a Context**:
+   ```
+   browserbase_create_context: Creates a new context, optionally with a friendly name
+   ```
+
+2. **Using a Context with a Session**:
+   ```
+   browserbase_create_session: Now accepts a 'context' parameter with:
+     - id: The context ID to use
+     - name: Alternative to ID, the friendly name of the context
+     - persist: Whether to save changes (cookies, cache) back to the context (default: true)
+   ```
+
+3. **Deleting a Context**:
+   ```
+   browserbase_delete_context: Deletes a context when you no longer need it
+   ```
+
+Contexts make it much easier to:
+- Maintain login state across sessions
+- Reduce page load times by preserving cache
+- Avoid CAPTCHAs and detection by reusing browser fingerprints
+
 ## TODO
 
 *   Implement true `ref`-based interaction logic for click, type, drag, hover, select_option.

browserbase/package-lock.json

@@ -17,16 +17,34 @@ const defaultSessionId = "default"; // Consistent ID for the default session
 // Function to create a new browser session
 async function createNewBrowserSession(
   newSessionId: string,
+  options?: {
+    contextId?: string;
+    persistContext?: boolean;
+  }
 ): Promise<BrowserSession> {
   console.error(`Creating new browser session with ID: ${newSessionId}`);
   const bb = new Browserbase({
     apiKey: process.env.BROWSERBASE_API_KEY!,
   });
 
-  const session = await bb.sessions.create({
+  // Prepare session creation options
+  const sessionOptions: any = {
     projectId: process.env.BROWSERBASE_PROJECT_ID!,
     proxies: true, // Consider making configurable
-  });
+  };
+  
+  // Add context settings if provided
+  if (options?.contextId) {
+    sessionOptions.browserSettings = {
+      context: {
+        id: options.contextId,
+        persist: options.persistContext !== false, // Default to true if not specified
+      },
+    };
+    console.error(`Using context: ${options.contextId} with persist: ${options.persistContext !== false}`);
+  }
+
+  const session = await bb.sessions.create(sessionOptions);
   console.error("Browserbase session created:", session.id);
 
   const browser = await chromium.connectOverCDP(session.connectUrl);

browserbase/src/sessionManager.ts

@@ -0,0 +1,138 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { Browserbase } from "@browserbasehq/sdk";
+
+// Store contexts in memory 
+// In a production app, these should be persisted to a database
+const contexts = new Map<string, string>();
+
+export async function handleCreateContext(args: any): Promise<CallToolResult> {
+  try {
+    const bb = new Browserbase({
+      apiKey: process.env.BROWSERBASE_API_KEY!,
+    });
+
+    console.error("Creating new Browserbase context");
+    const context = await bb.contexts.create({
+      projectId: process.env.BROWSERBASE_PROJECT_ID!,
+    });
+
+    console.error(`Successfully created context: ${context.id}`);
+    
+    // Store context ID with optional name if provided
+    const contextName = args.name || context.id;
+    contexts.set(contextName, context.id);
+    
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Created new Browserbase context with ID: ${context.id}${args.name ? ` and name: ${args.name}` : ''}`,
+        },
+      ],
+      isError: false,
+    };
+  } catch (error) {
+    console.error(
+      `Failed to create Browserbase context: ${(error as Error).message}`
+    );
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Failed to create Browserbase context: ${(error as Error).message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+export async function handleDeleteContext(args: any): Promise<CallToolResult> {
+  try {
+    if (!args.contextId && !args.name) {
+      return {
+        content: [{ type: "text", text: "Missing required argument: either contextId or name must be provided" }],
+        isError: true,
+      };
+    }
+
+    const bb = new Browserbase({
+      apiKey: process.env.BROWSERBASE_API_KEY!,
+    });
+
+    // Resolve context ID either directly or by name
+    let contextId = args.contextId;
+    if (!contextId && args.name) {
+      contextId = contexts.get(args.name);
+      if (!contextId) {
+        return {
+          content: [{ type: "text", text: `Context with name "${args.name}" not found` }],
+          isError: true,
+        };
+      }
+    }
+
+    console.error(`Deleting Browserbase context: ${contextId}`);
+    
+    // Delete from Browserbase API
+    // The SDK may not have a delete method directly, so we use the REST API
+    const response = await fetch(`https://api.browserbase.com/v1/contexts/${contextId}`, {
+      method: 'DELETE',
+      headers: {
+        'X-BB-API-Key': process.env.BROWSERBASE_API_KEY!,
+      },
+    });
+    
+    if (response.status !== 204) {
+      const errorText = await response.text();
+      throw new Error(`Failed to delete context with status ${response.status}: ${errorText}`);
+    }
+    
+    // Remove from local store
+    if (args.name) {
+      contexts.delete(args.name);
+    }
+    
+    // Delete by ID too (in case it was stored multiple ways)
+    for (const [name, id] of contexts.entries()) {
+      if (id === contextId) {
+        contexts.delete(name);
+      }
+    }
+    
+    console.error(`Successfully deleted context: ${contextId}`);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Deleted Browserbase context with ID: ${contextId}`,
+        },
+      ],
+      isError: false,
+    };
+  } catch (error) {
+    console.error(
+      `Failed to delete Browserbase context: ${(error as Error).message}`
+    );
+    return {
+      content: [
+        {
+          type: "text", 
+          text: `Failed to delete Browserbase context: ${(error as Error).message}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+// Helper function to get a context ID from name or direct ID
+export function getContextId(nameOrId: string): string | undefined {
+  // First check if it's a direct context ID
+  if (nameOrId.length > 20) {  // Assumption: context IDs are long strings
+    return nameOrId;
+  }
+  
+  // Otherwise, look it up by name
+  return contexts.get(nameOrId);
+} 

browserbase/src/tools/context.ts

@@ -2,6 +2,38 @@ import { Tool } from "@modelcontextprotocol/sdk/types.js";
 
 // Tool Definitions
 export const TOOLS: Tool[] = [
+  {
+    name: "browserbase_create_context",
+    description: "Create a new Browserbase context for reusing cookies, authentication, and cached data across browser sessions",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Optional friendly name to reference this context later (otherwise, you'll need to use the returned ID)",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "browserbase_delete_context",
+    description: "Delete a Browserbase context when you no longer need it",
+    inputSchema: {
+      type: "object",
+      properties: {
+        contextId: {
+          type: "string",
+          description: "The context ID to delete (required if name not provided)",
+        },
+        name: {
+          type: "string",
+          description: "The friendly name of the context to delete (required if contextId not provided)",
+        },
+      },
+      required: [],
+    },
+  },
   {
     // Kept as browserbase_* as it's specific to this multi-session implementation
     name: "browserbase_create_session",
@@ -14,6 +46,25 @@ export const TOOLS: Tool[] = [
           description:
             "A unique ID for the session (optional, uses a generated ID if not provided)",
         },
+        context: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string",
+              description: "The context ID to use for this session (to reuse cookies and cache)",
+            },
+            name: {
+              type: "string",
+              description: "The friendly name of the context to use (alternative to id)",
+            },
+            persist: {
+              type: "boolean",
+              description: "Whether to save changes to the context. Set to true to store cookies and cache for future use.",
+              default: true,
+            },
+          },
+          description: "Context settings to enable persistence of cookies, authentication, and cached data across sessions",
+        },
       },
       required: [],
     },

browserbase/src/tools/definitions.ts

@@ -18,6 +18,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js"; // Needed fo
 
 // Import specific tool handlers
 import { handleNavigate } from "./navigate.js";
+import { handleCreateContext, handleDeleteContext, getContextId } from "./context.js";
 import {
   handleSnapshot,
   handleTakeScreenshot,
@@ -62,6 +63,15 @@ export async function handleToolCall(
     let sessionObj: BrowserSession | null = null;
     const targetSessionId = args.sessionId || defaultSessionId;
 
+    // --- Context management tools (require no session) ---
+    if (name === "browserbase_create_context") {
+      return handleCreateContext(args);
+    }
+    
+    if (name === "browserbase_delete_context") {
+      return handleDeleteContext(args);
+    }
+
     // --- browserbase_create_session ---
     if (name === "browserbase_create_session") {
       const newSessionId = args.sessionId || `session_${Date.now()}`;
@@ -78,15 +88,48 @@ export async function handleToolCall(
             isError: false,
           };
         }
-        await createNewBrowserSession(newSessionId);
+        
+        // Check for context settings
+        const contextSettings = args.context;
+        let contextId: string | undefined;
+        
+        if (contextSettings) {
+          // Get context ID either directly or by name
+          if (contextSettings.id) {
+            contextId = contextSettings.id;
+          } else if (contextSettings.name) {
+            contextId = getContextId(contextSettings.name);
+            if (!contextId) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: `Context with name "${contextSettings.name}" not found`,
+                  },
+                ],
+                isError: true,
+              };
+            }
+          }
+        }
+        
+        // Pass context settings to session creation
+        const sessionOptions = {
+          contextId,
+          persistContext: contextSettings?.persist !== false, // Default to true if not specified
+        };
+        
+        await createNewBrowserSession(newSessionId, sessionOptions);
         // Note: We don't need to update defaultBrowserSession here as
         // createNewBrowserSession doesn't automatically set the default.
         console.error(`Successfully created session: ${newSessionId}`);
         return {
           content: [
             {
               type: "text",
-              text: `Created new browser session with ID: ${newSessionId}`,
+              text: `Created new browser session with ID: ${newSessionId}${
+                contextId ? ` using context: ${contextId}` : ''
+              }`,
             },
           ],
           isError: false,
@@ -153,8 +196,6 @@ export async function handleToolCall(
 
     // --- Execute Tool Logic ---
     switch (name) {
-      // browserbase_create_session handled above
-
       case "browserbase_navigate":
         return handleNavigate(page, args, targetSessionId);