@wonderwhy-er/desktop-commander 0.1.27 → 0.1.29

package/README.md

@@ -1,4 +1,5 @@
 # Desktop Commander MCP
+### Search, update, manage files and run terminal commands with AI
 
 [![npm downloads](https://img.shields.io/npm/dw/@wonderwhy-er/desktop-commander)](https://www.npmjs.com/package/@wonderwhy-er/desktop-commander)
 [![smithery badge](https://smithery.ai/badge/@wonderwhy-er/desktop-commander)](https://smithery.ai/server/@wonderwhy-er/desktop-commander)
@@ -8,8 +9,8 @@
 
 Short version. Two key things. Terminal commands and diff based file editing.
 
-![Desktop Commander MCP](https://raw.githubusercontent.com/wonderwhy-er/ClaudeComputerCommander/main/logo.png)
 
+![Desktop Commander MCP](https://raw.githubusercontent.com/wonderwhy-er/ClaudeComputerCommander/main/header.png)
 <a href="https://glama.ai/mcp/servers/zempur9oh4">
   <img width="380" height="200" src="https://glama.ai/mcp/servers/zempur9oh4/badge" alt="Claude Desktop Commander MCP server" />
 </a>
@@ -55,6 +56,11 @@ Just run this in terminal
 ```
 npx @wonderwhy-er/desktop-commander@latest setup
 ```
+
+For debugging mode (allows Node.js inspector connection):
+```
+npx @wonderwhy-er/desktop-commander@latest setup --debug
+```
 Restart Claude if running
 
 ### Option 2: Installing via Smithery
@@ -156,6 +162,40 @@ For commands that may take a while:
 3. Use `read_output` with PID to get new output
 4. Use `force_terminate` to stop if needed
 
+## Debugging
+
+If you need to debug the server, you can install it in debug mode:
+
+```bash
+# Using npx
+npx @wonderwhy-er/desktop-commander@latest setup --debug
+
+# Or if installed locally
+npm run setup:debug
+```
+
+This will:
+1. Configure Claude to use a separate "desktop-commander" server
+2. Enable Node.js inspector protocol with `--inspect-brk=9229` flag
+3. Pause execution at the start until a debugger connects
+4. Enable additional debugging environment variables
+
+To connect a debugger:
+- In Chrome, visit `chrome://inspect` and look for the Node.js instance
+- In VS Code, use the "Attach to Node Process" debug configuration
+- Other IDEs/tools may have similar "attach" options for Node.js debugging
+
+Important debugging notes:
+- The server will pause on startup until a debugger connects (due to the `--inspect-brk` flag)
+- If you don't see activity during debugging, ensure you're connected to the correct Node.js process
+- Multiple Node processes may be running; connect to the one on port 9229
+- The debug server is identified as "desktop-commander-debug" in Claude's MCP server list
+
+Troubleshooting:
+- If Claude times out while trying to use the debug server, your debugger might not be properly connected
+- When properly connected, the process will continue execution after hitting the first breakpoint
+- You can add additional breakpoints in your IDE once connected
+
 ## Model Context Protocol Integration
 
 This project extends the MCP Filesystem Server to enable:

package/dist/index.js

@@ -80,6 +80,7 @@ async function runServer() {
             process.stderr.write(`[desktop-commander] Unhandled rejection: ${errorMessage}\n`);
             process.exit(1);
         });
+        capture('run_server_start');
         // Load blocked commands from config file
         await commandManager.loadBlockedCommands();
         await server.connect(transport);

package/dist/server.js

@@ -179,9 +179,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         const { name, arguments: args } = request.params;
+        capture('server_call_tool');
         switch (name) {
             // Terminal tools
             case "execute_command": {
+                capture('server_execute_command');
                 const parsed = ExecuteCommandArgsSchema.parse(args);
                 return executeCommand(parsed);
             }
@@ -232,9 +234,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             // Filesystem tools
             case "edit_block": {
                 capture('server_edit_block');
-                const parsed = EditBlockArgsSchema.parse(args);
-                const { filePath, searchReplace } = await parseEditBlock(parsed.blockContent);
                 try {
+                    const parsed = EditBlockArgsSchema.parse(args);
+                    const { filePath, searchReplace } = await parseEditBlock(parsed.blockContent);
                     await performSearchReplace(filePath, searchReplace);
                     return {
                         content: [{ type: "text", text: `Successfully applied edit to ${filePath}` }],
@@ -243,81 +245,146 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);
                     return {
-                        content: [{ type: "text", text: errorMessage }],
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
                     };
                 }
             }
             case "read_file": {
                 capture('server_read_file');
-                const parsed = ReadFileArgsSchema.parse(args);
-                const content = await readFile(parsed.path);
-                return {
-                    content: [{ type: "text", text: content }],
-                };
+                try {
+                    const parsed = ReadFileArgsSchema.parse(args);
+                    const content = await readFile(parsed.path);
+                    return {
+                        content: [{ type: "text", text: content }],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    };
+                }
             }
             case "read_multiple_files": {
                 capture('server_read_multiple_files');
-                const parsed = ReadMultipleFilesArgsSchema.parse(args);
-                const results = await readMultipleFiles(parsed.paths);
-                return {
-                    content: [{ type: "text", text: results.join("\n---\n") }],
-                };
+                try {
+                    const parsed = ReadMultipleFilesArgsSchema.parse(args);
+                    const results = await readMultipleFiles(parsed.paths);
+                    return {
+                        content: [{ type: "text", text: results.join("\n---\n") }],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    };
+                }
             }
             case "write_file": {
                 capture('server_write_file');
-                const parsed = WriteFileArgsSchema.parse(args);
-                await writeFile(parsed.path, parsed.content);
-                return {
-                    content: [{ type: "text", text: `Successfully wrote to ${parsed.path}` }],
-                };
+                try {
+                    const parsed = WriteFileArgsSchema.parse(args);
+                    await writeFile(parsed.path, parsed.content);
+                    return {
+                        content: [{ type: "text", text: `Successfully wrote to ${parsed.path}` }],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    };
+                }
             }
             case "create_directory": {
                 capture('server_create_directory');
-                const parsed = CreateDirectoryArgsSchema.parse(args);
-                await createDirectory(parsed.path);
-                return {
-                    content: [{ type: "text", text: `Successfully created directory ${parsed.path}` }],
-                };
+                try {
+                    const parsed = CreateDirectoryArgsSchema.parse(args);
+                    await createDirectory(parsed.path);
+                    return {
+                        content: [{ type: "text", text: `Successfully created directory ${parsed.path}` }],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    };
+                }
             }
             case "list_directory": {
                 capture('server_list_directory');
-                const parsed = ListDirectoryArgsSchema.parse(args);
-                const entries = await listDirectory(parsed.path);
-                return {
-                    content: [{ type: "text", text: entries.join('\n') }],
-                };
+                try {
+                    const parsed = ListDirectoryArgsSchema.parse(args);
+                    const entries = await listDirectory(parsed.path);
+                    return {
+                        content: [{ type: "text", text: entries.join('\n') }],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    };
+                }
             }
             case "move_file": {
                 capture('server_move_file');
-                const parsed = MoveFileArgsSchema.parse(args);
-                await moveFile(parsed.source, parsed.destination);
-                return {
-                    content: [{ type: "text", text: `Successfully moved ${parsed.source} to ${parsed.destination}` }],
-                };
+                try {
+                    const parsed = MoveFileArgsSchema.parse(args);
+                    await moveFile(parsed.source, parsed.destination);
+                    return {
+                        content: [{ type: "text", text: `Successfully moved ${parsed.source} to ${parsed.destination}` }],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    };
+                }
             }
             case "search_files": {
                 capture('server_search_files');
-                const parsed = SearchFilesArgsSchema.parse(args);
-                const results = await searchFiles(parsed.path, parsed.pattern);
-                return {
-                    content: [{ type: "text", text: results.length > 0 ? results.join('\n') : "No matches found" }],
-                };
+                try {
+                    const parsed = SearchFilesArgsSchema.parse(args);
+                    const results = await searchFiles(parsed.path, parsed.pattern);
+                    return {
+                        content: [{ type: "text", text: results.length > 0 ? results.join('\n') : "No matches found" }],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    };
+                }
             }
             case "search_code": {
                 capture('server_search_code');
-                const parsed = SearchCodeArgsSchema.parse(args);
-                const results = await searchTextInFiles({
-                    rootPath: parsed.path,
-                    pattern: parsed.pattern,
-                    filePattern: parsed.filePattern,
-                    ignoreCase: parsed.ignoreCase,
-                    maxResults: parsed.maxResults,
-                    includeHidden: parsed.includeHidden,
-                    contextLines: parsed.contextLines,
-                });
-                if (results.length === 0) {
+                let results = [];
+                try {
+                    const parsed = SearchCodeArgsSchema.parse(args);
+                    results = await searchTextInFiles({
+                        rootPath: parsed.path,
+                        pattern: parsed.pattern,
+                        filePattern: parsed.filePattern,
+                        ignoreCase: parsed.ignoreCase,
+                        maxResults: parsed.maxResults,
+                        includeHidden: parsed.includeHidden,
+                        contextLines: parsed.contextLines,
+                    });
+                    if (results.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No matches found" }],
+                        };
+                    }
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
                     return {
-                        content: [{ type: "text", text: "No matches found" }],
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
                     };
                 }
                 // Format the results in a VS Code-like format
@@ -336,20 +403,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "get_file_info": {
                 capture('server_get_file_info');
-                const parsed = GetFileInfoArgsSchema.parse(args);
-                const info = await getFileInfo(parsed.path);
-                return {
-                    content: [{
-                            type: "text",
-                            text: Object.entries(info)
-                                .map(([key, value]) => `${key}: ${value}`)
-                                .join('\n')
-                        }],
-                };
+                try {
+                    const parsed = GetFileInfoArgsSchema.parse(args);
+                    const info = await getFileInfo(parsed.path);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: Object.entries(info)
+                                    .map(([key, value]) => `${key}: ${value}`)
+                                    .join('\n')
+                            }],
+                    };
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorMessage}` }],
+                    };
+                }
             }
             case "list_allowed_directories": {
-                const directories = listAllowedDirectories();
                 capture('server_list_allowed_directories');
+                const directories = listAllowedDirectories();
                 return {
                     content: [{
                             type: "text",

package/dist/setup-claude-server.js

@@ -239,15 +239,16 @@ async function restartClaude() {
             }
         } catch {}
 		await new Promise((resolve) => setTimeout(resolve, 3000))
-
-		if (platform === "win32") {
-            // it will never start claude
-			// await execAsync(`start "" "Claude.exe"`)
-		} else if (platform === "darwin") {
-			await execAsync(`open -a "Claude"`)
-		} else if (platform === "linux") {
-			await execAsync(`claude`)
-		}
+        try {
+            if (platform === "win32") {
+                // it will never start claude
+                // await execAsync(`start "" "Claude.exe"`)
+            } else if (platform === "darwin") {
+                await execAsync(`open -a "Claude"`)
+            } else if (platform === "linux") {
+                await execAsync(`claude`)
+            }
+        } catch{}
 
 		logToFile(`Claude has been restarted.`)
 	} catch (error) {
@@ -287,8 +288,17 @@ if (!existsSync(claudeConfigPath)) {
     logToFile('Default config file created. Please update it with your Claude API credentials.');
 }
 
+// Function to check for debug mode argument
+function isDebugMode() {
+    return process.argv.includes('--debug');
+}
+
 // Main function to export for ESM compatibility
 export default async function setup() {
+    const debugMode = isDebugMode();
+    if (debugMode) {
+        logToFile('Debug mode enabled. Will configure with Node.js inspector options.');
+    }
     try {
         // Read existing config
         const configData = readFileSync(claudeConfigPath, 'utf8');
@@ -300,22 +310,67 @@ export default async function setup() {
 
         // Fix Windows path handling for npx execution
         let serverConfig;
-        if (isNpx) {
-            serverConfig = {
-                "command": isWindows ? "npx.cmd" : "npx",
-                "args": [
-                    "@wonderwhy-er/desktop-commander"
-                ]
-            };
+        
+        if (debugMode) {
+            // Use Node.js with inspector flag for debugging
+            if (isNpx) {
+                // Debug with npx
+                logToFile('Setting up debug configuration with npx. The process will pause on start until a debugger connects.');
+                // Add environment variables to help with debugging
+                const debugEnv = {
+                    "NODE_OPTIONS": "--trace-warnings --trace-exit",
+                    "DEBUG": "*"
+                };
+                
+                serverConfig = {
+                    "command": isWindows ? "node.exe" : "node",
+                    "args": [
+                        "--inspect-brk=9229",
+                        isWindows ? 
+                            join(process.env.APPDATA || '', "npm", "npx.cmd").replace(/\\/g, '\\\\') : 
+                            "$(which npx)",
+                        "@wonderwhy-er/desktop-commander"
+                    ],
+                    "env": debugEnv
+                };
+            } else {
+                // Debug with local installation path
+                const indexPath = join(__dirname, 'dist', 'index.js');
+                logToFile('Setting up debug configuration with local path. The process will pause on start until a debugger connects.');
+                // Add environment variables to help with debugging
+                const debugEnv = {
+                    "NODE_OPTIONS": "--trace-warnings --trace-exit",
+                    "DEBUG": "*"
+                };
+                
+                serverConfig = {
+                    "command": isWindows ? "node.exe" : "node",
+                    "args": [
+                        "--inspect-brk=9229",
+                        indexPath.replace(/\\/g, '\\\\') // Double escape backslashes for JSON
+                    ],
+                    "env": debugEnv
+                };
+            }
         } else {
-            // For local installation, use absolute path to handle Windows properly
-            const indexPath = join(__dirname, 'dist', 'index.js');
-            serverConfig = {
-                "command": "node",
-                "args": [
-                    indexPath.replace(/\\/g, '\\\\') // Double escape backslashes for JSON
-                ]
-            };
+            // Standard configuration without debug
+            if (isNpx) {
+                serverConfig = {
+                    "command": isWindows ? "npx.cmd" : "npx",
+                    "args": [
+                        "@wonderwhy-er/desktop-commander"
+                    ]
+                };
+            } else {
+                // For local installation, use absolute path to handle Windows properly
+                const indexPath = join(__dirname, 'dist', 'index.js');
+                serverConfig = {
+                    "command": "node",
+                    "args": [
+                        indexPath.replace(/\\/g, '\\\\') // Double escape backslashes for JSON
+                    ]
+                };
+            }
         }
 
         // Initialize mcpServers if it doesn't exist
@@ -337,7 +392,12 @@ export default async function setup() {
         await trackEvent('npx_setup_update_config');
         logToFile('Successfully added MCP server to Claude configuration!');
         logToFile(`Configuration location: ${claudeConfigPath}`);
-        logToFile('\nTo use the server:\n1. Restart Claude if it\'s currently running\n2. The server will be available as "desktop-commander" in Claude\'s MCP server list');
+        
+        if (debugMode) {
+            logToFile('\nTo use the debug server:\n1. Restart Claude if it\'s currently running\n2. The server will be available as "desktop-commander-debug" in Claude\'s MCP server list\n3. Connect your debugger to port 9229');
+        } else {
+            logToFile('\nTo use the server:\n1. Restart Claude if it\'s currently running\n2. The server will be available as "desktop-commander" in Claude\'s MCP server list');
+        }
 
         await restartClaude();
         

package/dist/tools/filesystem.js

@@ -27,16 +27,20 @@ function expandHome(filepath) {
 export async function validatePath(requestedPath) {
     // Temporarily allow all paths by just returning the resolved path
     // TODO: Implement configurable path validation
+    // Expand home directory if present
     const expandedPath = expandHome(requestedPath);
+    // Convert to absolute path
     const absolute = path.isAbsolute(expandedPath)
         ? path.resolve(expandedPath)
         : path.resolve(process.cwd(), expandedPath);
-    // Try to resolve real path for symlinks, but don't enforce restrictions
+    // Check if path exists
     try {
+        const stats = await fs.stat(absolute);
+        // If path exists, resolve any symlinks
         return await fs.realpath(absolute);
     }
     catch (error) {
-        // If can't resolve (e.g., file doesn't exist yet), return absolute path
+        // return path if it's not exist. This will be used for folder creation and many other file operations
         return absolute;
     }
     /* Original implementation commented out for future reference
@@ -135,6 +139,7 @@ export async function searchFiles(rootPath, pattern) {
             }
         }
     }
+    // if path not exist, it will throw an error
     const validPath = await validatePath(rootPath);
     await search(validPath);
     return results;

package/dist/utils.js

@@ -6,16 +6,24 @@ let posthog = null;
 // Try to load PostHog without breaking if it's not available
 try {
     // Dynamic imports to prevent crashing if dependencies aren't available
-    const { PostHog } = require('posthog-node');
-    const machineId = require('node-machine-id');
-    uniqueUserId = machineId.machineIdSync();
-    if (isTrackingEnabled) {
-        posthog = new PostHog('phc_TFQqTkCwtFGxlwkXDY3gSs7uvJJcJu8GurfXd6mV063', {
-            host: 'https://eu.i.posthog.com',
-            flushAt: 3, // send all every time
-            flushInterval: 5 // send always
+    import('posthog-node').then((posthogModule) => {
+        const PostHog = posthogModule.PostHog;
+        import('node-machine-id').then((machineIdModule) => {
+            // Access the default export from the module
+            uniqueUserId = machineIdModule.default.machineIdSync();
+            if (isTrackingEnabled) {
+                posthog = new PostHog('phc_TFQqTkCwtFGxlwkXDY3gSs7uvJJcJu8GurfXd6mV063', {
+                    host: 'https://eu.i.posthog.com',
+                    flushAt: 3, // send all every time
+                    flushInterval: 5 // send always
+                });
+            }
+        }).catch(() => {
+            // Silently fail - we don't want analytics issues to break functionality
         });
-    }
+    }).catch(() => {
+        // Silently fail - we don't want analytics issues to break functionality
+    });
 }
 catch (error) {
     //console.log('Analytics module not available - continuing without tracking');

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.1.27";
+export declare const VERSION = "0.1.29";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.1.27';
+export const VERSION = '0.1.29';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonderwhy-er/desktop-commander",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "MCP server for terminal operations and file editing",
   "license": "MIT",
   "author": "Eduards Ruzga",
@@ -27,7 +27,9 @@
     "build": "tsc && shx cp setup-claude-server.js dist/ && shx chmod +x dist/*.js",
     "watch": "tsc --watch",
     "start": "node dist/index.js",
+    "start:debug": "node --inspect-brk=9229 dist/index.js",
     "setup": "npm install && npm run build && node setup-claude-server.js",
+    "setup:debug": "npm install && npm run build && node setup-claude-server.js --debug",
     "prepare": "npm run build",
     "test": "node test/test.js",
     "test:watch": "nodemon test/test.js",
@@ -68,6 +70,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.17.24",
+    "nexe": "^5.0.0-beta.4",
     "nodemon": "^3.0.2",
     "shx": "^0.3.4",
     "typescript": "^5.3.3"