cleanup_data

Instructions

Implementation Reference

• src/tools/handlers.ts:790-882 (handler)

  The primary handler function that executes the cleanup_data tool. It handles both preview (confirm=false) and deletion (confirm=true) modes, instantiates CleanupManager, logs progress, and returns structured ToolResult with preview data or deletion results.

  /**
   * Handle cleanup_data tool
   *
   * ULTRATHINK Deep Cleanup - scans entire system for ALL NotebookLM MCP files
   */
  async handleCleanupData(
    args: { confirm: boolean; preserve_library?: boolean }
  ): Promise<
    ToolResult<{
      status: string;
      mode: string;
      preview?: {
        categories: Array<{ name: string; description: string; paths: string[]; totalBytes: number; optional: boolean }>;
        totalPaths: number;
        totalSizeBytes: number;
      };
      result?: {
        deletedPaths: string[];
        failedPaths: string[];
        totalSizeBytes: number;
        categorySummary: Record<string, { count: number; bytes: number }>;
      };
    }> 
  > {
    const { confirm, preserve_library = false } = args;
  
    log.info(`🔧 [TOOL] cleanup_data called`);
    log.info(`  Confirm: ${confirm}`);
    log.info(`  Preserve Library: ${preserve_library}`);
  
    const cleanupManager = new CleanupManager();
  
    try {
      // Always run in deep mode
      const mode = "deep";
  
      if (!confirm) {
        // Preview mode - show what would be deleted
        log.info(`  📋 Generating cleanup preview (mode: ${mode})...`);
  
        const preview = await cleanupManager.getCleanupPaths(mode, preserve_library);
        const platformInfo = cleanupManager.getPlatformInfo();
  
        log.info(`  Found ${preview.totalPaths.length} items (${cleanupManager.formatBytes(preview.totalSizeBytes)})`);
        log.info(`  Platform: ${platformInfo.platform}`);
  
        return {
          success: true,
          data: {
            status: "preview",
            mode,
            preview: {
              categories: preview.categories,
              totalPaths: preview.totalPaths.length,
              totalSizeBytes: preview.totalSizeBytes,
            },
          },
        };
      } else {
        // Cleanup mode - actually delete files
        log.info(`  🗑️  Performing cleanup (mode: ${mode})...`);
  
        const result = await cleanupManager.performCleanup(mode, preserve_library);
  
        if (result.success) {
          log.success(`✅ [TOOL] cleanup_data completed - deleted ${result.deletedPaths.length} items`);
        } else {
          log.warning(`⚠️  [TOOL] cleanup_data completed with ${result.failedPaths.length} errors`);
        }
  
        return {
          success: result.success,
          data: {
            status: result.success ? "completed" : "partial",
            mode,
            result: {
              deletedPaths: result.deletedPaths,
              failedPaths: result.failedPaths,
              totalSizeBytes: result.totalSizeBytes,
              categorySummary: result.categorySummary,
            },
          },
        };
      }
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      log.error(`❌ [TOOL] cleanup_data failed: ${errorMessage}`);
      return {
        success: false,
        error: errorMessage,
      };
    }
  }

• src/tools/definitions/system.ts:112-153 (schema)

  Tool definition including name, detailed description, and inputSchema specifying 'confirm' (required boolean) and 'preserve_library' (optional boolean with default false).

  {
    name: "cleanup_data",
    description:
      "ULTRATHINK Deep Cleanup - Scans entire system for ALL NotebookLM MCP data files across 8 categories. Always runs in deep mode, shows categorized preview before deletion.\n\n" +
      "⚠️ CRITICAL: Close ALL Chrome/Chromium instances BEFORE running this tool! Open browsers can prevent cleanup and cause issues.\n\n" +
      "Categories scanned:\n" +
      "1. Legacy Installation (notebooklm-mcp-nodejs) - Old paths with -nodejs suffix\n" +
      "2. Current Installation (notebooklm-mcp) - Active data, browser profiles, library\n" +
      "3. NPM/NPX Cache - Cached installations from npx\n" +
      "4. Claude CLI MCP Logs - MCP server logs from Claude CLI\n" +
      "5. Temporary Backups - Backup directories in system temp\n" +
      "6. Claude Projects Cache - Project-specific cache (optional)\n" +
      "7. Editor Logs (Cursor/VSCode) - MCP logs from code editors (optional)\n" +
      "8. Trash Files - Deleted notebooklm files in system trash (optional)\n\n" +
      "Works cross-platform (Linux, Windows, macOS). Safe by design: shows detailed preview before deletion, requires explicit confirmation.\n\n" +
      "LIBRARY PRESERVATION: Set preserve_library=true to keep your notebook library.json file while cleaning everything else.\n\n" +
      "RECOMMENDED WORKFLOW for fresh start:\n" +
      "1. Ask user to close ALL Chrome/Chromium instances\n" +
      "2. Run cleanup_data(confirm=false, preserve_library=true) to preview\n" +
      "3. Run cleanup_data(confirm=true, preserve_library=true) to execute\n" +
      "4. Run setup_auth or re_auth for fresh browser session\n\n" +
      "Use cases: Clean reinstall, troubleshooting auth issues, removing all traces before uninstall, cleaning old browser sessions and installation data.",
    inputSchema: {
      type: "object",
      properties: {
        confirm: {
          type: "boolean",
          description:
            "Confirmation flag. Tool shows preview first, then user confirms deletion. " +
            "Set to true only after user has reviewed the preview and explicitly confirmed.",
        },
        preserve_library: {
          type: "boolean",
          description:
            "Preserve library.json file during cleanup. Default: false. " +
            "Set to true to keep your notebook library while deleting everything else (browser data, caches, logs).",
          default: false,
        },
      },
      required: ["confirm"],
    },
  },

• src/tools/definitions.ts:20-33 (registration)

  The buildToolDefinitions function aggregates all tool definitions, including systemTools (which contains cleanup_data), making it available to the MCP server via list_tools.

  export function buildToolDefinitions(library: NotebookLibrary): Tool[] {
    // Update the description for ask_question based on the library state
    const dynamicAskQuestionTool = {
      ...askQuestionTool,
      description: buildAskQuestionDescription(library),
    };
  
    return [
      dynamicAskQuestionTool,
      ...notebookManagementTools,
      ...sessionManagementTools,
      ...systemTools,
    ];
  }

• src/index.ts:266-270 (registration)

  Dispatch case in the main MCP call_tool handler that routes 'cleanup_data' calls to the specific handleCleanupData method.

  case "cleanup_data":
    result = await this.toolHandlers.handleCleanupData(
      args as { confirm: boolean }
    );
    break;