manage_browser_sessions

Instructions

Implementation Reference

• src/tools/BrowserTools.ts:1660-1693 (handler)

  Main handler for manage_browser_sessions tool. Accepts action parameter: 'list', 'close', 'close_all', 'cleanup_idle', or 'get_status' and dispatches to the appropriate enhanced session management method.

  private async manageBrowserSessions(args: z.infer<typeof BrowserManageSessionsSchema>) {
    const params = BrowserManageSessionsSchema.parse(args);
    
    let result;
    switch (params.action) {
      case 'list':
        result = await this.listBrowserSessionsEnhanced();
        break;
        
      case 'close':
        if (!params.session_id) {
          return { success: false, error: 'session_id required for close action' };
        }
        result = await this.closeBrowserSessionEnhanced(params.session_id, params.force_close);
        break;
        
      case 'close_all':
        result = await this.closeAllSessions(params.force_close);
        break;
        
      case 'cleanup_idle':
        result = await this.cleanupIdleSessions(params.cleanup_criteria);
        break;
        
      case 'get_status':
        result = await this.getSessionsStatus();
        break;
        
      default:
        return { success: false, error: `Unknown action: ${params.action}` };
    }
    
    return this.transformResultData(result, 'manage_browser_sessions');
  }

• src/schemas/tools/browser.ts:70-80 (schema)

  Zod schema defining the input validation for manage_browser_sessions. Supports actions: list, close, close_all, cleanup_idle, get_status with optional session_id, force_close, and cleanup_criteria fields.

  export const BrowserManageSessionsSchema = z.object({
    action: z.enum(["list", "close", "close_all", "cleanup_idle", "get_status"]).describe("Management action to perform: 'list' shows all sessions, 'close' closes specific session, 'close_all' closes all sessions, 'cleanup_idle' removes idle sessions, 'get_status' provides detailed session statistics"),
    session_id: z.string().optional().describe("Session ID to operate on. Required for 'close' action, ignored for other actions"),
    force_close: z.boolean().default(false).describe("Whether to force close sessions even if they are marked as documentation sessions (which are normally protected from auto-close)"),
    cleanup_criteria: z
      .object({
        max_idle_minutes: z.number().default(10).describe("Maximum idle time in minutes before a session is considered for cleanup"),
        exclude_documentation: z.boolean().default(true).describe("Whether to exclude documentation sessions from cleanup (recommended to prevent data loss)"),
      })
      .optional().describe("Criteria for cleanup_idle action. Defines which sessions should be considered for cleanup"),
  }).describe("Manage browser sessions with actions like listing, closing, bulk cleanup, and getting detailed status information. Includes protection for documentation sessions to prevent data loss.");

• src/tools/BrowserTools.ts:228-234 (registration)

  Tool registration within BrowserTools.getTools() method. Registers manage_browser_sessions with its name, description, input/output schemas, and handler.

  {
    name: 'manage_browser_sessions',
    description: 'Manage browser sessions: list, close, cleanup idle sessions, get status',
    inputSchema: zodToJsonSchema(BrowserManageSessionsSchema),
    outputSchema: zodToJsonSchema(BrowserOperationResponseSchema),
    handler: (args: any) => this.manageBrowserSessions(args)
  },

• src/installer/index.ts:366-366 (registration)

  Registration in the installer's list of browser automation tools under the MCP prefixed name.

  "mcp__claude-mcp-tools__manage_browser_sessions",

• src/tools/BrowserTools.ts:1696-1712 (helper)

  Helper that enriches raw session data with metadata (workflow type, auto-close, last activity, task completion) for the 'list' action.

  private async listBrowserSessionsEnhanced() {
    const sessions = await this.listSessionsCore();
    
    return {
      success: true,
      sessions: sessions.map(session => {
        const metadata = this.sessionMetadata.get(session.id);
        return {
          ...session,
          workflowType: metadata?.workflowType || 'unknown',
          autoClose: metadata?.autoClose || false,
          lastActivity: metadata?.lastActivity || session.lastUsed,
          taskCompleted: metadata?.taskCompleted || false
        };
      })
    };
  }