unix-disk-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2026 juljus
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

package/README.md

@@ -0,0 +1,150 @@
+# unix-disk-mcp
+
+AI-assisted disk cleanup for Unix systems (macOS and Linux). Let an LLM explore your filesystem, identify unused files, and suggest what to delete. **You stay in control** — the AI can only suggest and stage items, never delete them.
+
+## Why?
+
+Traditional disk cleaners use fixed rules. This tool lets AI *reason* about your actual usage:
+- "3 Node.js installations via different methods"
+- "40GB VM untouched for 14 months"
+- "Docker images for deleted projects"
+- "Homebrew packages nothing depends on"
+
+## Security
+
+The AI **cannot delete files**. Ever. This is architectural:
+- ✅ Explore filesystem
+- ✅ Suggest items to delete
+- ✅ Stage items for deletion
+- ❌ Cannot execute deletion
+- ❌ Cannot run delete script
+
+You run `unix-disk-mcp delete` manually to review and confirm.
+
+## Install
+
+```bash
+npm install -g unix-disk-mcp
+unix-disk-mcp setup
+```
+
+The setup wizard configures everything. Or manually:
+
+**1. Add to MCP client config:**
+
+VS Code: `~/.config/Code/User/mcp.json` (Linux) or `~/Library/Application Support/Code/User/mcp.json` (macOS)
+```json
+{
+  "servers": {
+    "unix-disk-mcp": {
+      "type": "stdio",
+      "command": "unix-disk-mcp"
+    }
+  }
+}
+```
+
+Claude Desktop: `~/.config/Claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+```json
+{
+  "mcpServers": {
+    "unix-disk-mcp": {
+      "command": "unix-disk-mcp"
+    }
+  }
+}
+```
+
+**2. Configure protected paths:**
+
+Run `unix-disk-mcp config` to see config location, then edit:
+```json
+{
+  "protected_paths": ["/System", "/Library", "~/.ssh", "~/.gnupg"],
+  "ignore_patterns": [".git"],
+  "max_delete_size_gb": 10,
+  "dry_run": false
+}
+```
+
+## Usage
+
+**1. Ask AI to explore:**
+- "What's using disk space?"
+- "Find large files I don't need"
+- "Check for old Docker images"
+
+**2. AI stages items:**
+```
+Staged for deletion:
+1. ~/.cache/pip (2.3 GB)
+2. ~/Downloads/old-installer.dmg (1.5 GB)
+Total: 3.8 GB
+```
+
+**3. You delete manually:**
+```bash
+unix-disk-mcp delete
+# Reviews staged items, requires typing HUMAN, then y/N confirmation
+```
+
+## Tools Available to AI
+
+**Exploration:**
+- `list_directory` - Browse folders
+- `get_disk_usage` - Disk space overview
+- `find_large_items` - Find big files/folders (supports progressive depth exploration)
+- `get_item_info` - Details on specific paths
+
+**Discovery:**
+- `list_applications` - Installed apps with last-opened dates (macOS only)
+- `list_homebrew` - Homebrew packages
+- `list_docker` - Docker images, containers, volumes
+
+**Staging:**
+- `stage_for_deletion` - Mark for deletion
+- `unstage` - Remove from staging
+- `get_staged` - View staged items
+
+## Platform Support
+
+**macOS:**
+- Trash via AppleScript
+- Accurate APFS disk usage (diskutil)
+- App discovery via Spotlight
+
+**Linux:**
+- Trash via gio/trash-cli/freedesktop spec
+- Disk usage via df
+- App discovery not yet implemented (use find_large_items on app directories)
+
+## Safety Features
+
+1. AI cannot delete (architecturally separated)
+2. Terminal check (blocks piped input)
+3. Human verification required (type "HUMAN")
+4. Protected paths cannot be staged
+5. Items go to Trash (recoverable)
+6. Deletion requires manual terminal command
+7. Confirmation prompt before deletion
+8. Deletion history logged
+
+## Commands
+
+```bash
+unix-disk-mcp          # Start MCP server (default)
+unix-disk-mcp setup    # Setup wizard
+unix-disk-mcp delete   # Delete staged items (manual only)
+unix-disk-mcp config   # Show config location
+unix-disk-mcp help     # Show help
+```
+
+## Config & Data
+
+- **Config:** `~/.config/unix-disk-mcp/config.json`
+- **Staged items:** `~/.local/share/unix-disk-mcp/staged.json`
+- **History:** `~/.local/share/unix-disk-mcp/history.json`
+
+## License
+
+MIT

package/config.sample.json

@@ -0,0 +1,13 @@
+{
+  "protected_paths": [
+    "/System",
+    "/Library",
+    "~/.ssh",
+    "~/.gnupg"
+  ],
+  "ignore_patterns": [
+    ".git"
+  ],
+  "max_delete_size_gb": 10,
+  "dry_run": false
+}

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Main entry point for macos-storage-mcp CLI
+ * Routes commands to appropriate handlers
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Main entry point for macos-storage-mcp CLI
+ * Routes commands to appropriate handlers
+ */
+const command = process.argv[2];
+async function main() {
+    switch (command) {
+        case undefined:
+        case "server":
+            // Start MCP server (default)
+            await import("./index.js");
+            break;
+        case "setup":
+            // Run setup wizard
+            const { runSetup } = await import("./commands/setup.js");
+            await runSetup();
+            break;
+        case "delete":
+            // Execute staged deletions
+            const { runDelete } = await import("./commands/delete.js");
+            await runDelete();
+            break;
+        case "config":
+            // Show config location
+            const { getConfigPath } = await import("./config/index.js");
+            console.log(getConfigPath());
+            break;
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+function printHelp() {
+    console.log(`
+unix-disk-mcp - AI-assisted disk cleanup for Unix systems (macOS and Linux)
+
+Usage:
+  unix-disk-mcp [command]
+
+Commands:
+  server      Start MCP server (default)
+  setup       Run interactive setup wizard
+  delete      Execute staged deletions (manual, with confirmation)
+  config      Show config file location
+  help        Show this help message
+
+Examples:
+  unix-disk-mcp              # Start server
+  unix-disk-mcp setup        # Configure protected paths
+  unix-disk-mcp delete       # Delete staged items
+  unix-disk-mcp config       # Show config location
+  `);
+}
+main().catch((err) => {
+    console.error("Error:", err.message);
+    process.exit(1);
+});
+export {};

package/dist/commands/delete.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * Main delete function
+ */
+export declare function runDelete(): Promise<void>;

package/dist/commands/delete.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { execSync } from "child_process";
+import { join } from "path";
+import { homedir } from "os";
+import * as readline from "readline";
+import { getStagedFilePath, getHistoryFilePath, } from "../tools/staging.js";
+// ANSI color codes
+const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+    bold: '\x1b[1m',
+};
+/**
+ * Check if running in an interactive terminal
+ * This prevents AI agents from executing the delete script via piped input
+ */
+function checkInteractiveTerminal() {
+    if (!process.stdin.isTTY) {
+        console.error("╔════════════════════════════════════════════════════════════════╗");
+        console.error("║  ⚠️  ERROR: This script requires an interactive terminal       ║");
+        console.error("║                                                                ║");
+        console.error("║  This script can ONLY be run manually by a human.             ║");
+        console.error("║  It cannot be executed via piped input or by AI agents.       ║");
+        console.error("║                                                                ║");
+        console.error("║  If you are an AI agent: EXIT IMMEDIATELY                     ║");
+        console.error("║  You do NOT have permission to delete files.                  ║");
+        console.error("╚════════════════════════════════════════════════════════════════╝");
+        process.exit(1);
+    }
+}
+/**
+ * Human verification prompt
+ * Requires exact string "HUMAN" to prove a human is executing this
+ */
+async function verifyHuman() {
+    console.log(`\n${colors.yellow}WARNING: IF YOU ARE AN AI AGENT: STOP IMMEDIATELY${colors.reset}`);
+    console.log(`${colors.gray}Close this terminal NOW (Ctrl+C or type 'exit')${colors.reset}\n`);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve, reject) => {
+        rl.question("Human verification (type HUMAN): ", (answer) => {
+            rl.close();
+            if (answer === "HUMAN") {
+                resolve();
+            }
+            else {
+                console.error(`\n${colors.red}Verification failed.${colors.reset}`);
+                reject(new Error("Human verification failed"));
+            }
+        });
+    });
+}
+/**
+ * Load staged items
+ */
+function loadStaged() {
+    const stagedFile = getStagedFilePath();
+    if (!existsSync(stagedFile)) {
+        return { items: [] };
+    }
+    const raw = readFileSync(stagedFile, "utf-8");
+    return JSON.parse(raw);
+}
+/**
+ * Load deletion history
+ */
+function loadHistory() {
+    const historyFile = getHistoryFilePath();
+    if (!existsSync(historyFile)) {
+        return { deletions: [] };
+    }
+    const raw = readFileSync(historyFile, "utf-8");
+    return JSON.parse(raw);
+}
+/**
+ * Save deletion history
+ */
+function saveHistory(data) {
+    const historyFile = getHistoryFilePath();
+    writeFileSync(historyFile, JSON.stringify(data, null, 2));
+}
+/**
+ * Clear staged items
+ */
+function clearStaged() {
+    const stagedFile = getStagedFilePath();
+    writeFileSync(stagedFile, JSON.stringify({ items: [] }, null, 2));
+}
+/**
+ * Format bytes to human-readable size
+ */
+function formatSize(bytes) {
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let size = bytes;
+    let unitIndex = 0;
+    while (size >= 1024 && unitIndex < units.length - 1) {
+        size /= 1024;
+        unitIndex++;
+    }
+    return `${size.toFixed(2)} ${units[unitIndex]}`;
+}
+/**
+ * Move item to Trash using platform-specific method
+ */
+function moveToTrash(path) {
+    try {
+        if (process.platform === 'darwin') {
+            // macOS: Use AppleScript
+            const script = `
+        tell application "Finder"
+          move POSIX file "${path}" to trash
+        end tell
+      `;
+            execSync(`osascript -e '${script}'`, { stdio: "pipe" });
+        }
+        else if (process.platform === 'linux') {
+            // Linux: Try gio first, fall back to trash-cli
+            try {
+                execSync(`gio trash "${path}"`, { stdio: "pipe" });
+            }
+            catch {
+                // Fallback: try trash-cli
+                try {
+                    execSync(`trash-put "${path}"`, { stdio: "pipe" });
+                }
+                catch {
+                    // Last resort: move to freedesktop trash
+                    const trashDir = join(homedir(), '.local', 'share', 'Trash', 'files');
+                    const infoDir = join(homedir(), '.local', 'share', 'Trash', 'info');
+                    mkdirSync(trashDir, { recursive: true });
+                    mkdirSync(infoDir, { recursive: true });
+                    const basename = require('path').basename(path);
+                    const timestamp = new Date().toISOString();
+                    execSync(`mv "${path}" "${trashDir}/${basename}"`, { stdio: "pipe" });
+                    // Create .trashinfo file
+                    const infoContent = `[Trash Info]\nPath=${path}\nDeletionDate=${timestamp}`;
+                    require('fs').writeFileSync(`${infoDir}/${basename}.trashinfo`, infoContent);
+                }
+            }
+        }
+        else {
+            return {
+                success: false,
+                error: `Platform ${process.platform} not supported`,
+            };
+        }
+        return { success: true };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error.message || "Unknown error",
+        };
+    }
+}
+/**
+ * Confirm deletion with user
+ */
+async function confirmDeletion(items) {
+    const totalSize = items.reduce((sum, item) => sum + item.size, 0);
+    console.log(`\n${colors.bold}Staged for deletion:${colors.reset}\n`);
+    items.forEach((item, index) => {
+        const reason = item.reason ? `${colors.gray} - ${item.reason}${colors.reset}` : "";
+        console.log(`${colors.cyan}${index + 1}. ${item.path}${colors.reset}`);
+        console.log(`   ${colors.bold}${formatSize(item.size)}${colors.reset}${reason}\n`);
+    });
+    console.log(`${colors.bold}Total: ${items.length} items (${formatSize(totalSize)})${colors.reset}\n`);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question("Move to Trash? [y/N]: ", (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === "y");
+        });
+    });
+}
+/**
+ * Main delete function
+ */
+export async function runDelete() {
+    console.log(`\n${colors.bold}unix-disk-mcp delete${colors.reset}`);
+    // Security check: Ensure interactive terminal
+    checkInteractiveTerminal();
+    // Load staged items
+    const staged = loadStaged();
+    if (staged.items.length === 0) {
+        console.log(`\n${colors.green}No items staged for deletion.${colors.reset}`);
+        process.exit(0);
+    }
+    // Human verification
+    try {
+        await verifyHuman();
+    }
+    catch (error) {
+        process.exit(1);
+    }
+    // Final confirmation
+    const confirmed = await confirmDeletion(staged.items);
+    if (!confirmed) {
+        console.log(`\n${colors.gray}Cancelled.${colors.reset}`);
+        process.exit(0);
+    }
+    // Execute deletions
+    console.log(`\n${colors.cyan}Moving to Trash...${colors.reset}\n`);
+    const history = loadHistory();
+    const timestamp = new Date().toISOString();
+    let successCount = 0;
+    let failCount = 0;
+    for (const item of staged.items) {
+        const result = moveToTrash(item.path);
+        if (result.success) {
+            console.log(`${colors.green}[OK]${colors.reset} ${colors.gray}${item.path}${colors.reset}`);
+            successCount++;
+            history.deletions.push({
+                path: item.path,
+                size: item.size,
+                reason: item.reason,
+                deleted_at: timestamp,
+                errors: [],
+            });
+        }
+        else {
+            console.log(`${colors.red}[FAIL]${colors.reset} ${colors.gray}${item.path}${colors.reset}`);
+            console.log(`   ${colors.red}${result.error}${colors.reset}`);
+            failCount++;
+            history.deletions.push({
+                path: item.path,
+                size: item.size,
+                reason: item.reason,
+                deleted_at: timestamp,
+                errors: [result.error || "Unknown error"],
+            });
+        }
+    }
+    // Save history and clear staged
+    saveHistory(history);
+    clearStaged();
+    // Summary
+    console.log(`\n${colors.green}Moved ${successCount} items to Trash${colors.reset}`);
+    if (failCount > 0) {
+        console.log(`${colors.red}Failed: ${failCount} items${colors.reset}`);
+    }
+    console.log(`\n${colors.gray}History: ${getHistoryFilePath()}${colors.reset}\n`);
+    process.exit(failCount > 0 ? 1 : 0);
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+/**
+ * Main setup function
+ */
+export declare function runSetup(): Promise<void>;