Playwright Browserbase MCP Server

Instructions

Implementation Reference

• src/tools/session.ts:36-105 (handler)

  The handleCreateSession function implements the core logic of the 'browserbase_session_create' tool. It creates or reuses a Browserbase session using SessionManager functions, updates the context, and returns the session URL.

  async function handleCreateSession(
    context: Context,
    params: CreateSessionInput
  ): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      try {
        const config = context.config; // Get config from context
        let targetSessionId: string;
  
        if (params.sessionId) {
          const projectId = config.browserbaseProjectId || '';
          targetSessionId = `${params.sessionId}_${projectId}`;
          process.stderr.write(
            `[tool.createSession] Attempting to create/assign session with specified ID: ${targetSessionId}`
          );
        } else {
          targetSessionId = defaultSessionId;
        }
  
        let session: BrowserSession;
        if (targetSessionId === defaultSessionId) {
          session = await ensureDefaultSessionInternal(config);
        } else {
          session = await createNewBrowserSession(targetSessionId, config);
        }
  
        if (!session || !session.browser || !session.page || !session.sessionId) {
          throw new Error(
            `SessionManager failed to return a valid session object with actualSessionId for ID: ${targetSessionId}`
          );
        }
  
        context.currentSessionId = targetSessionId;
        process.stderr.write(
          `[tool.connected] Successfully connected to Browserbase session. Internal ID: ${targetSessionId}, Actual ID: ${session.sessionId}`
        );
  
        process.stderr.write(`[SessionManager] Browserbase Live Debugger URL: https://www.browserbase.com/sessions/${session.sessionId}`);
  
        return {
          content: [
            {
              type: "text",
              text: `https://www.browserbase.com/sessions/${session.sessionId}`,
            },
          ],
        };
      } catch (error: any) {
        process.stderr.write(
          `[tool.createSession] Action failed: ${
            error.message || String(error)
          }`
        );
        // Re-throw to be caught by Context.run's error handling for actions
        throw new Error(
          `Failed to create Browserbase session: ${
            error.message || String(error)
          }`
        );
      }
    };
  
    // Return the ToolResult structure expected by Context.run
    return {
      action: action, 
      captureSnapshot: false, 
      code: [],  
      waitForNetwork: false, 
    };
  }

• src/tools/session.ts:27-32 (schema)

  The ToolSchema definition for 'browserbase_session_create', including name, description, and reference to the input schema (defined above). The input schema is z.object({ sessionId: z.string().optional()... }) on lines 16-24.

  const createSessionSchema: ToolSchema<typeof CreateSessionInputSchema> = {
    name: "browserbase_session_create", 
    description:
      "Create or reuse a cloud browser session using Browserbase. Updates the active session.", 
    inputSchema: CreateSessionInputSchema,
  };

• src/tools/session.ts:108-112 (registration)

  The creation of the createSessionTool object, which bundles the schema and handler. This tool is exported in an array at line 239 and imported into src/index.ts for server registration.

  const createSessionTool: Tool<typeof CreateSessionInputSchema> = {
    capability: "core", // Add capability
    schema: createSessionSchema,
    handle: handleCreateSession,
  };

• src/index.ts:73-106 (registration)

  In src/index.ts, the session tools are included via '...session' in the tools array (line 79), and then registered on the MCP server via the forEach loop using server.tool() with the tool's schema and a wrapper around context.run(tool, params).

  const tools: Tool<any>[] = [
    ...common,
    ...snapshot,
    ...keyboard,
    ...getText,
    ...navigate,
    ...session,
    ...contextTools,
  ];
  
  // 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}`
      );
    }
  });

• src/context.ts:409-410 (helper)

  Special handling in Context.run() skips session validation for 'browserbase_session_create' since this tool is responsible for creating the session.

  if (toolName !== "browserbase_session_create") {
    try {