Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/multiSession.ts:21-79 (handler)

  createMultiSessionAwareTool function: Core handler logic for all multi-session tools including 'multi_browserbase_stagehand_extract_session'. Generates tool schema with prefixed name, adds sessionId to input, retrieves session from store, overrides context methods to use specific session's Stagehand/page/browser, and delegates execution to wrapped original tool.

  function createMultiSessionAwareTool<TInput extends InputType>(
    originalTool: Tool<TInput>,
    options: {
      namePrefix?: string;
      nameSuffix?: string;
    } = {},
  ): Tool<InputType> {
    const { namePrefix = "", nameSuffix = "_session" } = options;
  
    // Create new input schema that includes sessionId
    const originalSchema = originalTool.schema.inputSchema;
    let newInputSchema: z.ZodSchema;
  
    if (originalSchema instanceof z.ZodObject) {
      // If it's a ZodObject, we can spread its shape
      newInputSchema = z.object({
        sessionId: z.string().describe("The session ID to use"),
        ...originalSchema.shape,
      });
    } else {
      // For other schema types, create an intersection
      newInputSchema = z.intersection(
        z.object({ sessionId: z.string().describe("The session ID to use") }),
        originalSchema,
      );
    }
  
    return defineTool({
      capability: originalTool.capability,
      schema: {
        name: `${namePrefix}${originalTool.schema.name}${nameSuffix}`,
        description: `${originalTool.schema.description} (for a specific session)`,
        inputSchema: newInputSchema,
      },
      handle: async (
        context: Context,
        params: z.infer<typeof newInputSchema>,
      ): Promise<ToolResult> => {
        const { sessionId, ...originalParams } = params;
  
        // Get the session
        const session = stagehandStore.get(sessionId);
        if (!session) {
          throw new Error(`Session ${sessionId} not found`);
        }
  
        // Create a temporary context that points to the specific session
        const sessionContext = Object.create(context);
        sessionContext.currentSessionId =
          session.metadata?.bbSessionId || sessionId;
        sessionContext.getStagehand = async () => session.stagehand;
        sessionContext.getActivePage = async () => session.page;
        sessionContext.getActiveBrowser = async () => session.browser;
  
        // Call the original tool's handler with the session-specific context
        return originalTool.handle(sessionContext, originalParams);
      },
    });
  }

• src/tools/multiSession.ts:252-255 (registration)

  Specific registration/definition of extractWithSessionTool, which names it 'multi_browserbase_stagehand_extract_session' (multi_ + browserbase_stagehand_extract + _session).

  export const extractWithSessionTool = createMultiSessionAwareTool(extractTool, {
    namePrefix: "multi_",
    nameSuffix: "_session",
  });

• src/tools/extract.ts:34-62 (handler)

  Inner handler of the original extractTool (browserbase_stagehand_extract), which performs the page.extract() call using Stagehand and returns the structured extraction result. Delegated to by the multi-session wrapper.

  async function handleExtract(
    context: Context,
    params: ExtractInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const stagehand = await context.getStagehand();
  
        const extraction = await stagehand.page.extract(params.instruction);
  
        return {
          content: [
            {
              type: "text",
              text: `Extracted content:\n${JSON.stringify(extraction, null, 2)}`,
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to extract content: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/index.ts:26-34 (registration)

  Registration: Includes extractWithSessionTool in the multiSessionTools array, which is merged into the main TOOLS export used by the MCP server.

  export const multiSessionTools = [
    createSessionTool,
    listSessionsTool,
    closeSessionTool,
    navigateWithSessionTool,
    actWithSessionTool,
    extractWithSessionTool,
    observeWithSessionTool,
  ];

• src/tools/extract.ts:21-23 (schema)

  Original schema definition for browserbase_stagehand_extract tool, which is extended by adding 'sessionId' parameter for the multi-session version.

  const extractSchema: ToolSchema<typeof ExtractInputSchema> = {
    name: "browserbase_stagehand_extract",
    description: