Scan a drive or folder with WizTree and import results into the database.

This is the primary data ingestion tool. It:

1. Locates the WizTree CLI executable

2. Runs WizTree to export CSV (and optional treemap PNG)

3. Streams the CSV into SQLite (memory-efficient, <50 MB)

4. Returns a scan summary

After scanning, use other tools (disk_summary, top_entries, etc.) to query the results.

Args: target_path: Drive or folder to scan (e.g., "C:", "D:\Projects"). label: Optional human-readable label for this scan (e.g., "Cleanup Prep"). max_depth: Maximum folder depth to export (None = unlimited). Use a small value like 5 to reduce CSV size for quick scans. export_folders: Include folder entries in the export. export_files: Include file entries in the export. treemap: Also generate a treemap PNG image alongside the CSV. timeout: Maximum seconds to wait for the WizTree scan to complete. ctx: MCP context (injected automatically).

Returns: JSON string with scan result summary.

Get a detailed summary of a disk scan.

Returns drive info, capacity, total files/folders, and the top N largest files and folders.

Args: scan_id: The scan ID (use list_scans to find available scans). top_n: Number of top files and folders to include (default 20, max 100). ctx: MCP context (injected automatically).

Returns: Formatted summary string.

List the largest entries in a scan (files, folders, or both).

Args: scan_id: The scan ID. kind: Entry type — "files" (default), "folders", or "all". limit: Number of entries to return (default 20, max 500). offset: Pagination offset (default 0). ctx: MCP context (injected automatically).

Returns: Formatted table of entries sorted by size descending.

Search for paths in a scan by keyword.

Useful for finding specific directories or files (e.g., "node_modules", "cache", "npm", "temp").

Args: scan_id: The scan ID. query: Search keyword or path fragment (case-insensitive). kind: Entry type — "all" (default), "files", or "folders". limit: Maximum results to return (default 50, max 200). ctx: MCP context (injected automatically).

Returns: Matching entries with total aggregate size.

Browse the contents of a specific folder (drill down).

Shows all entries inside the given folder path, sorted by size descending. Useful for interactively exploring large directories step by step.

Args: scan_id: The scan ID. folder_path: The folder path to drill into (e.g., "C:\Users", "D:\Projects\src"). limit: Number of entries to return (default 50, max 200). offset: Pagination offset for seeing more items. ctx: MCP context (injected automatically).

Returns: List of sub-entries (files and folders) inside the given path.

Summarize disk usage by file extension type.

Groups all files by their extension and returns a ranked list of which file types consume the most space.

Args: scan_id: The scan ID. limit: Number of extensions to show (default 30, max 100). ctx: MCP context (injected automatically).

Returns: Ranked table of file extensions by total size.

Find files that are both large and haven't been modified recently.

These are prime candidates for cleanup — files taking up significant space that haven't been touched in a long time.

Args: scan_id: The scan ID. older_than_days: Minimum age in days (default 180, ~6 months). min_size_mb: Minimum file size in MB (default 100). limit: Maximum results (default 50, max 200). ctx: MCP context (injected automatically).

Returns: List of large, old files sorted by size descending.

Compare two scans of the same drive to see what changed.

Use this to measure cleanup results, track growth over time, or identify which directories changed the most between two points.

Args: scan_id_before: The earlier scan ID (the "before" snapshot). scan_id_after: The later scan ID (the "after" snapshot). limit: Number of top changes to show (default 20, max 100). ctx: MCP context (injected automatically).

Returns: Comparison report with capacity changes and top growth/shrink paths.

List all previous disk scans stored in the database.

Returns a table with scan ID, drive, label, scan time, and capacity info. Use this to find scan IDs for other tools like disk_summary or top_entries.

Args: ctx: MCP context (injected automatically).

Returns: Formatted list of all scans.

Get a treemap visualization image for a scan (if generated during scan).

Note: treemap images are only available if the scan was run with treemap=True in scan_disk.

Args: scan_id: The scan ID to retrieve the treemap for. ctx: MCP context (injected automatically).

Returns: PNG image content of the treemap visualization.

Remove older scans from the database to free up space.

Keeps the N most recent scans and deletes everything older. Entries are cascade-deleted when their parent scan is removed.

Args: keep_latest: Number of most recent scans to keep (default 5, min 1). ctx: MCP context (injected automatically).

Returns: Report of which scans were deleted.