Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/url.ts:22-52 (handler)

  Core handler function that retrieves the current URL from the active Stagehand page. This is the primary logic delegated to by the multi-session wrapper.

  async function handleGetUrl(
    context: Context,
    // eslint-disable-next-line @typescript-eslint/no-unused-vars
    params: GetUrlInput,
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const stagehand = await context.getStagehand();
  
        // Get the current URL from the Playwright page
        const currentUrl = stagehand.page.url();
  
        return {
          content: [
            {
              type: "text",
              text: currentUrl,
            },
          ],
        };
      } catch (error) {
        const errorMsg = error instanceof Error ? error.message : String(error);
        throw new Error(`Failed to get current URL: ${errorMsg}`);
      }
    };
  
    return {
      action,
      waitForNetwork: false,
    };
  }

• src/tools/multiSession.ts:56-78 (handler)

  Multi-session wrapper handler that resolves the specific session by ID, creates a session-scoped context, and delegates to the original getUrlTool handler.

  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:263-266 (registration)

  Defines and exports the tool object 'getUrlWithSessionTool' with name 'multi_browserbase_stagehand_get_url_session' by wrapping the original getUrlTool.

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

• src/tools/url.ts:15-20 (schema)

  Original schema definition for the base 'browserbase_stagehand_get_url' tool, which is extended with 'sessionId' input for the multi-session version.

  const getUrlSchema: ToolSchema<typeof GetUrlInputSchema> = {
    name: "browserbase_stagehand_get_url",
    description:
      "Gets the current URL of the browser page. Returns the complete URL including protocol, domain, path, and any query parameters or fragments.",
    inputSchema: GetUrlInputSchema,
  };

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

  Registers all tools (including multi_browserbase_stagehand_get_url_session via TOOLS array) to the MCP server using server.tool() with dynamic handlers.

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