unix-disk-mcp 0.1.0

package/dist/tools/exploration.js

@@ -0,0 +1,311 @@
+import { z } from "zod";
+import { readdirSync, statSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import { homedir } from "os";
+import { expandPath } from "../config/index.js";
+export function registerExplorationTools(server, config) {
+    // list_directory
+    server.tool("list_directory", "List contents of a directory with file sizes and dates", {
+        path: z.string().describe("Absolute path to the directory"),
+        show_hidden: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include hidden files (starting with .)"),
+    }, async ({ path, show_hidden }) => {
+        try {
+            const expandedPath = expandPath(path);
+            const entries = readdirSync(expandedPath, { withFileTypes: true });
+            const items = entries
+                .filter((entry) => show_hidden || !entry.name.startsWith("."))
+                .map((entry) => {
+                const fullPath = join(expandedPath, entry.name);
+                try {
+                    const stats = statSync(fullPath);
+                    return {
+                        name: entry.name,
+                        type: entry.isDirectory() ? "directory" : "file",
+                        size: entry.isFile() ? stats.size : null,
+                        modified: stats.mtime.toISOString(),
+                        accessed: stats.atime.toISOString(),
+                    };
+                }
+                catch {
+                    return {
+                        name: entry.name,
+                        type: entry.isDirectory() ? "directory" : "file",
+                        size: null,
+                        modified: null,
+                        accessed: null,
+                        error: "Could not read stats",
+                    };
+                }
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, data: items }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : "Unknown error",
+                            code: "LIST_DIRECTORY_FAILED",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // get_disk_usage
+    server.tool("get_disk_usage", "Get overview of disk space usage", {}, async () => {
+        try {
+            let disk;
+            if (process.platform === 'darwin') {
+                // macOS: Use diskutil for accurate APFS container usage
+                const diskutilOutput = execSync("diskutil info / | grep -E 'Volume Name|Container Total Space|Container Free Space'", {
+                    encoding: "utf-8"
+                });
+                const lines = diskutilOutput.trim().split("\n");
+                const volumeName = lines[0]?.split(":")[1]?.trim() || "Unknown";
+                // Parse container space - format: "494.4 GB (494384795648 Bytes) (exactly...)"
+                const totalLine = lines[1]?.split(":")[1]?.trim() || "";
+                const freeLine = lines[2]?.split(":")[1]?.trim() || "";
+                // Extract human-readable values before the first parenthesis (e.g., "494.4 GB")
+                const totalGB = totalLine.split("(")[0]?.trim() || "Unknown";
+                const freeGB = freeLine.split("(")[0]?.trim() || "Unknown";
+                // Extract bytes for calculations - inside first parenthesis
+                const totalBytesMatch = totalLine.match(/\((\d+) Bytes\)/);
+                const freeBytesMatch = freeLine.match(/\((\d+) Bytes\)/);
+                const totalBytes = totalBytesMatch ? parseInt(totalBytesMatch[1]) : 0;
+                const freeBytes = freeBytesMatch ? parseInt(freeBytesMatch[1]) : 0;
+                const usedBytes = totalBytes - freeBytes;
+                const percentUsed = totalBytes > 0 ? Math.round((usedBytes / totalBytes) * 100) : 0;
+                // Format used space
+                const usedGB = (usedBytes / 1e9).toFixed(1) + " GB";
+                disk = {
+                    volume: volumeName,
+                    total: totalGB,
+                    used: usedGB,
+                    available: freeGB,
+                    percent_used: `${percentUsed}%`,
+                    note: "APFS container usage (accurate)",
+                };
+            }
+            else {
+                // Linux: Use df
+                const dfOutput = execSync("df -h / | tail -1", { encoding: "utf-8" });
+                const parts = dfOutput.trim().split(/\s+/);
+                disk = {
+                    filesystem: parts[0],
+                    total: parts[1],
+                    used: parts[2],
+                    available: parts[3],
+                    percent_used: parts[4],
+                    mounted: parts[5],
+                };
+            }
+            // Get home directory breakdown
+            const home = homedir();
+            const entries = readdirSync(home, { withFileTypes: true });
+            const breakdown = entries
+                .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+                .slice(0, 15) // Limit to avoid too many du calls
+                .map((entry) => {
+                const fullPath = join(home, entry.name);
+                try {
+                    const duOutput = execSync(`du -sk "${fullPath}" 2>/dev/null || echo "0 ${fullPath}"`, {
+                        encoding: "utf-8",
+                    });
+                    const size = parseInt(duOutput.split("\t")[0]) * 1024;
+                    return { path: fullPath, size };
+                }
+                catch {
+                    return { path: fullPath, size: 0, error: "Could not calculate size" };
+                }
+            })
+                .sort((a, b) => b.size - a.size);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            data: {
+                                disk,
+                                home_breakdown: breakdown,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : "Unknown error",
+                            code: "DISK_USAGE_FAILED",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // find_large_items
+    server.tool("find_large_items", "Find files and directories above a size threshold. WORKFLOW: (1) Start with max_depth=3 on home dir for overview, (2) Identify large branches (e.g., Library/Application Support/Steam), (3) Drill down into those specific paths with max_depth=5-8, (4) For final details, search specific subdirs with no depth limit. This progressive approach is fast and gives clear actionable results.", {
+        path: z.string().describe("Path to search within"),
+        min_size_mb: z.number().describe("Minimum size in megabytes"),
+        max_depth: z
+            .number()
+            .optional()
+            .describe("Maximum depth from this path. Start with 3 for overview, use 5-8 for branch exploration, omit for deep dive. REQUIRED for initial scans to avoid slow searches."),
+        max_results: z
+            .number()
+            .optional()
+            .default(20)
+            .describe("Maximum number of results to return"),
+    }, async ({ path, min_size_mb, max_depth, max_results }) => {
+        try {
+            const expandedPath = expandPath(path);
+            // Find large files (no depth limit, but use timeout)
+            const fileCmd = `timeout 30 find "${expandedPath}" -type f -size +${min_size_mb}M 2>/dev/null || true`;
+            const fileOutput = execSync(fileCmd, { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024 });
+            const files = fileOutput
+                .trim()
+                .split("\n")
+                .filter((line) => line.length > 0)
+                .slice(0, max_results * 2) // Limit how many we stat
+                .map((filePath) => {
+                try {
+                    const stats = statSync(filePath);
+                    return { path: filePath, size: stats.size, type: "file" };
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((item) => item !== null);
+            // Find large directories using du
+            const minSizeKb = min_size_mb * 1024;
+            const depthFlag = max_depth !== undefined ? `-d ${max_depth}` : `-a`;
+            const dirCmd = `du ${depthFlag} -k "${expandedPath}" 2>/dev/null | awk '$1 > ${minSizeKb}' | sort -rn | head -${max_results * 2}`;
+            const dirOutput = execSync(dirCmd, { encoding: "utf-8", maxBuffer: 10 * 1024 * 1024, timeout: 60000 });
+            const dirs = dirOutput
+                .trim()
+                .split("\n")
+                .filter((line) => line.length > 0)
+                .map((line) => {
+                const parts = line.split("\t");
+                if (parts.length === 2) {
+                    const size = parseInt(parts[0]) * 1024;
+                    const itemPath = parts[1];
+                    // Check if it's a directory
+                    try {
+                        const stats = statSync(itemPath);
+                        if (stats.isDirectory()) {
+                            return { path: itemPath, size, type: "directory" };
+                        }
+                    }
+                    catch { }
+                }
+                return null;
+            })
+                .filter((item) => item !== null);
+            // Filter out parent directories - only keep leaves or items without children in results
+            const filteredDirs = dirs.filter((dir) => {
+                // Check if any other directory in the list is a child of this one
+                const hasChildInList = dirs.some((other) => other !== dir && other.path.startsWith(dir.path + "/"));
+                return !hasChildInList;
+            });
+            // Combine and sort by size
+            const items = [...files, ...filteredDirs]
+                .sort((a, b) => b.size - a.size)
+                .slice(0, max_results);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, data: items }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : "Unknown error",
+                            code: "FIND_LARGE_ITEMS_FAILED",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // get_item_info
+    server.tool("get_item_info", "Get detailed information about a file or directory", {
+        path: z.string().describe("Path to the file or directory"),
+    }, async ({ path }) => {
+        try {
+            const expandedPath = expandPath(path);
+            const stats = statSync(expandedPath);
+            const isDirectory = stats.isDirectory();
+            let size = stats.size;
+            if (isDirectory) {
+                // Calculate directory size
+                const duOutput = execSync(`du -sk "${expandedPath}" 2>/dev/null`, {
+                    encoding: "utf-8",
+                });
+                size = parseInt(duOutput.split("\t")[0]) * 1024;
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            data: {
+                                path: expandedPath,
+                                type: isDirectory ? "directory" : "file",
+                                size,
+                                modified: stats.mtime.toISOString(),
+                                accessed: stats.atime.toISOString(),
+                                created: stats.birthtime.toISOString(),
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : "Unknown error",
+                            code: "GET_ITEM_INFO_FAILED",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+}

package/dist/tools/staging.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { Config } from "../config/index.js";
+export declare function registerStagingTools(server: McpServer, config: Config): void;
+export declare function getStagedFilePath(): string;
+export declare function getHistoryFilePath(): string;
+export declare function getDataDir(): string;

package/dist/tools/staging.js

@@ -0,0 +1,236 @@
+import { z } from "zod";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { execSync } from "child_process";
+import { expandPath, isProtectedPath } from "../config/index.js";
+// XDG Base Directory paths
+const XDG_DATA_HOME = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+const DATA_DIR = join(XDG_DATA_HOME, "unix-disk-mcp");
+const STAGED_FILE = join(DATA_DIR, "staged.json");
+const HISTORY_FILE = join(DATA_DIR, "history.json");
+function ensureDataDir() {
+    if (!existsSync(DATA_DIR)) {
+        mkdirSync(DATA_DIR, { recursive: true });
+    }
+}
+function loadStaged() {
+    ensureDataDir();
+    if (!existsSync(STAGED_FILE)) {
+        return { items: [] };
+    }
+    const raw = readFileSync(STAGED_FILE, "utf-8");
+    return JSON.parse(raw);
+}
+function saveStaged(data) {
+    ensureDataDir();
+    writeFileSync(STAGED_FILE, JSON.stringify(data, null, 2));
+}
+function getItemSize(path) {
+    try {
+        const stats = statSync(path);
+        if (stats.isDirectory()) {
+            const duOutput = execSync(`du -sk "${path}" 2>/dev/null`, { encoding: "utf-8" });
+            return parseInt(duOutput.split("\t")[0]) * 1024;
+        }
+        return stats.size;
+    }
+    catch {
+        return 0;
+    }
+}
+export function registerStagingTools(server, config) {
+    // stage_for_deletion
+    server.tool("stage_for_deletion", "Add a path to the staged deletion list", {
+        path: z.string().describe("Path to stage for deletion"),
+        reason: z.string().optional().describe("Reason for staging this item"),
+    }, async ({ path, reason }) => {
+        try {
+            const expandedPath = expandPath(path);
+            // Check if path exists
+            if (!existsSync(expandedPath)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Path does not exist: ${expandedPath}`,
+                                code: "PATH_NOT_FOUND",
+                            }),
+                        },
+                    ],
+                };
+            }
+            // Check if path is protected
+            if (isProtectedPath(expandedPath, config)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Path is protected and cannot be staged: ${expandedPath}`,
+                                code: "PATH_PROTECTED",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const staged = loadStaged();
+            // Check if already staged
+            if (staged.items.some((item) => item.path === expandedPath)) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Path is already staged: ${expandedPath}`,
+                                code: "ALREADY_STAGED",
+                            }),
+                        },
+                    ],
+                };
+            }
+            // Add to staged
+            const size = getItemSize(expandedPath);
+            staged.items.push({
+                path: expandedPath,
+                size,
+                reason,
+                staged_at: new Date().toISOString(),
+            });
+            saveStaged(staged);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            data: {
+                                message: `Staged for deletion: ${expandedPath}`,
+                                staged_count: staged.items.length,
+                            },
+                            reminder: "Tell the user to run 'unix-disk-mcp delete' in their terminal when ready. DO NOT attempt to execute it yourself.",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : "Unknown error",
+                            code: "STAGE_FAILED",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // unstage
+    server.tool("unstage", "Remove a path from the staged deletion list", {
+        path: z.string().describe("Path to remove from staging"),
+    }, async ({ path }) => {
+        try {
+            const expandedPath = expandPath(path);
+            const staged = loadStaged();
+            const index = staged.items.findIndex((item) => item.path === expandedPath);
+            if (index === -1) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: false,
+                                error: `Path is not staged: ${expandedPath}`,
+                                code: "NOT_STAGED",
+                            }),
+                        },
+                    ],
+                };
+            }
+            staged.items.splice(index, 1);
+            saveStaged(staged);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            data: {
+                                message: `Removed from staging: ${expandedPath}`,
+                                staged_count: staged.items.length,
+                            },
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : "Unknown error",
+                            code: "UNSTAGE_FAILED",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // get_staged
+    server.tool("get_staged", "View all currently staged items. CRITICAL: You MUST NOT attempt to run 'unix-disk-mcp delete' or any deletion command. Tell the user to run it manually in their own terminal.", {}, async () => {
+        try {
+            const staged = loadStaged();
+            const totalSize = staged.items.reduce((sum, item) => sum + item.size, 0);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            data: {
+                                items: staged.items,
+                                total_count: staged.items.length,
+                                total_size: totalSize,
+                            },
+                            warning: "⚠️ CRITICAL: AI agents MUST NOT attempt to run 'unix-disk-mcp delete'. Instruct the user to run this command manually in their terminal. DO NOT use run_in_terminal or execute any deletion commands.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : "Unknown error",
+                            code: "GET_STAGED_FAILED",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+}
+export function getStagedFilePath() {
+    return STAGED_FILE;
+}
+export function getHistoryFilePath() {
+    return HISTORY_FILE;
+}
+export function getDataDir() {
+    return DATA_DIR;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "unix-disk-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for AI-assisted disk cleanup on Unix systems (macOS and Linux)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "unix-disk-mcp": "dist/cli.js"
+  },
+  "scripts": {
+    "dev": "npx tsx src/index.ts",
+    "build": "tsc && chmod +x dist/cli.js",
+    "start": "node dist/index.js",
+    "delete": "node dist/commands/delete.js",
+    "setup": "node dist/commands/setup.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist/**/*",
+    "config.sample.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "unix",
+    "macos",
+    "linux",
+    "disk-cleanup",
+    "ai",
+    "storage",
+    "model-context-protocol"
+  ],
+  "author": "juljus",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/juliusdehner/unix-disk-mcp.git"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}