unix-disk-mcp 0.3.0 → 0.4.1

package/README.md

@@ -13,11 +13,15 @@ Traditional disk cleaners use fixed rules. This tool lets AI *reason* about your
 ## 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
+
+**What AI can do:**
+- Explore filesystem
+- Suggest items to delete
+- Stage items for deletion
+
+**What AI cannot do:**
+- Execute deletion
+- Run delete script
 
 You run `unix-disk-mcp delete` manually to review and confirm.
 
@@ -32,7 +36,7 @@ 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)
+VS Code: `~/Library/Application Support/Code/User/mcp.json` (macOS) or `~/.config/Code/User/mcp.json` (Linux)
 ```json
 {
   "servers": {
@@ -44,11 +48,24 @@ VS Code: `~/.config/Code/User/mcp.json` (Linux) or `~/Library/Application Suppor
 }
 ```
 
-Claude Desktop: `~/.config/Claude/claude_desktop_config.json` (Linux) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+Cursor: `~/.cursor/mcp.json`
 ```json
 {
   "mcpServers": {
     "unix-disk-mcp": {
+      "command": "unix-disk-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Claude: `~/.claude.json`
+```json
+{
+  "servers": {
+    "unix-disk-mcp": {
+      "type": "stdio",
       "command": "unix-disk-mcp"
     }
   }
@@ -60,10 +77,7 @@ Claude Desktop: `~/.config/Claude/claude_desktop_config.json` (Linux) or `~/Libr
 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
+  "protected_paths": ["/System", "/Library", "~/.ssh", "~/.gnupg"]
 }
 ```
 
@@ -95,6 +109,7 @@ unix-disk-mcp delete
 - `get_disk_usage` - Disk space overview
 - `find_large_items` - Find big files/folders (supports progressive depth exploration)
 - `get_item_info` - Details on specific paths
+- `search_files` - Find files/directories by name pattern
 
 **Discovery:**
 - `list_applications` - Installed apps with last-opened dates (macOS only)
@@ -147,4 +162,4 @@ unix-disk-mcp help     # Show help
 
 ## License
 
-MIT
+GPL-3.0-or-later

package/config.sample.json

@@ -4,10 +4,5 @@
     "/Library",
     "~/.ssh",
     "~/.gnupg"
-  ],
-  "ignore_patterns": [
-    ".git"
-  ],
-  "max_delete_size_gb": 10,
-  "dry_run": false
+  ]
 }

package/dist/config/index.d.ts

@@ -1,8 +1,5 @@
 export interface Config {
     protected_paths: string[];
-    ignore_patterns: string[];
-    max_delete_size_gb: number;
-    dry_run: boolean;
 }
 export declare function expandPath(path: string): string;
 export declare function loadConfig(): Config;

package/dist/server.js

@@ -5,7 +5,8 @@ import { registerStagingTools } from "./tools/staging.js";
 export function createServer(config) {
     const server = new McpServer({
         name: "unix-disk-mcp",
-        version: "0.1.0",
+        version: "0.4.1",
+        description: "AI-assisted disk cleanup for Unix systems. **Recommended workflow:** 1) Start with get_disk_usage for overview 2) Use search_files or find_large_items to identify targets 3) Stage items for deletion 4) User executes deletion manually. You can explore but never delete files.",
     });
     // Register all tools
     registerExplorationTools(server, config);

package/dist/tools/exploration.js

@@ -67,7 +67,7 @@ export function registerExplorationTools(server, config) {
         }
     });
     // get_disk_usage
-    server.tool("get_disk_usage", "Get overview of disk space usage", {}, async () => {
+    server.tool("get_disk_usage", "Get overview of disk space usage. **Use this first** when exploring disk usage to understand which filesystems/volumes need attention and get a breakdown of home directory space.", {}, async () => {
         try {
             let disk;
             if (process.platform === 'darwin') {
@@ -331,4 +331,97 @@ export function registerExplorationTools(server, config) {
             };
         }
     });
+    // search_files
+    server.tool("search_files", "Search for files and directories by name pattern. Use this to find all instances of an app, package, or file type across the system.", {
+        query: z.string().describe("Search query - can be exact name or pattern (e.g., 'Anki', 'node_modules', '*.mp4')"),
+        search_path: z.string().optional().describe("Starting directory (defaults to home directory)"),
+        max_results: z.number().optional().default(50).describe("Maximum number of results to return"),
+    }, async ({ query, search_path, max_results }) => {
+        try {
+            const startPath = search_path ? expandPath(search_path) : homedir();
+            let results = [];
+            if (process.platform === 'darwin') {
+                // macOS: Use mdfind (Spotlight) for fast searching
+                try {
+                    const mdfindCmd = search_path
+                        ? `mdfind -onlyin "${startPath}" -name "${query}"`
+                        : `mdfind -name "${query}"`;
+                    const output = execSync(mdfindCmd, {
+                        encoding: "utf-8",
+                        maxBuffer: 10 * 1024 * 1024, // 10MB buffer
+                    });
+                    results = output.trim().split("\n").filter(Boolean);
+                }
+                catch (error) {
+                    // Fall back to find if mdfind fails
+                    const findCmd = `find "${startPath}" -iname "*${query}*" 2>/dev/null`;
+                    const output = execSync(findCmd, {
+                        encoding: "utf-8",
+                        maxBuffer: 10 * 1024 * 1024,
+                    });
+                    results = output.trim().split("\n").filter(Boolean);
+                }
+            }
+            else {
+                // Linux: Use find
+                const findCmd = `find "${startPath}" -iname "*${query}*" 2>/dev/null`;
+                const output = execSync(findCmd, {
+                    encoding: "utf-8",
+                    maxBuffer: 10 * 1024 * 1024,
+                });
+                results = output.trim().split("\n").filter(Boolean);
+            }
+            // Limit results and get sizes
+            const limitedResults = results.slice(0, max_results);
+            const items = limitedResults.map(path => {
+                try {
+                    const stats = statSync(path);
+                    return {
+                        path,
+                        type: stats.isDirectory() ? "directory" : "file",
+                        size: stats.size,
+                        modified: stats.mtime.toISOString(),
+                    };
+                }
+                catch {
+                    return {
+                        path,
+                        type: "unknown",
+                        size: 0,
+                        error: "Could not read stats",
+                    };
+                }
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            data: {
+                                query,
+                                total_found: results.length,
+                                returned: items.length,
+                                items,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : "Unknown error",
+                            code: "SEARCH_FILES_FAILED",
+                        }),
+                    },
+                ],
+            };
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unix-disk-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "MCP server for AI-assisted disk cleanup on Unix systems (macOS and Linux)",
   "type": "module",
   "main": "dist/index.js",