Desktop Commander MCP

Instructions

Implementation Reference

• src/server.ts:727-799 (registration)

  Tool registration in listToolsRequestHandler: defines name 'start_process', description, input schema (StartProcessArgsSchema), and annotations.
  { name: "start_process", description: ` Start a new terminal process with intelligent state detection. PRIMARY TOOL FOR FILE ANALYSIS AND DATA PROCESSING This is the ONLY correct tool for analyzing local files (CSV, JSON, logs, etc.). The analysis tool CANNOT access local files and WILL FAIL - always use processes for file-based work. CRITICAL RULE: For ANY local file work, ALWAYS use this tool + interact_with_process, NEVER use analysis/REPL tool. ${OS_GUIDANCE} REQUIRED WORKFLOW FOR LOCAL FILES: 1. start_process("python3 -i") - Start Python REPL for data analysis 2. interact_with_process(pid, "import pandas as pd, numpy as np") 3. interact_with_process(pid, "df = pd.read_csv('/absolute/path/file.csv')") 4. interact_with_process(pid, "print(df.describe())") 5. Continue analysis with pandas, matplotlib, seaborn, etc. COMMON FILE ANALYSIS PATTERNS: • start_process("python3 -i") → Python REPL for data analysis (RECOMMENDED) • start_process("node -i") → Node.js REPL for JSON processing • start_process("node:local") → Node.js on MCP server (stateless, ES imports, all code in one call) • start_process("cut -d',' -f1 file.csv | sort | uniq -c") → Quick CSV analysis • start_process("wc -l /path/file.csv") → Line counting • start_process("head -10 /path/file.csv") → File preview BINARY FILE SUPPORT: For PDF, Excel, Word, archives, databases, and other binary formats, use process tools with appropriate libraries or command-line utilities. INTERACTIVE PROCESSES FOR DATA ANALYSIS: For code/calculations, use in this priority order: 1. start_process("python3 -i") - Python REPL (preferred) 2. start_process("node -i") - Node.js REPL (when Python unavailable) 3. start_process("node:local") - Node.js fallback (when node -i fails) 4. Use interact_with_process() to send commands 5. Use read_process_output() to get responses When Python is unavailable, prefer Node.js over shell for calculations. Node.js: Always use ES import syntax (import x from 'y'), not require(). SMART DETECTION: - Detects REPL prompts (>>>, >, $, etc.) - Identifies when process is waiting for input - Recognizes process completion vs timeout - Early exit prevents unnecessary waiting STATES DETECTED: Process waiting for input (shows prompt) Process finished execution Process running (use read_process_output) PERFORMANCE DEBUGGING (verbose_timing parameter): Set verbose_timing: true to get detailed timing information including: - Exit reason (early_exit_quick_pattern, early_exit_periodic_check, process_exit, timeout) - Total duration and time to first output - Complete timeline of all output events with timestamps - Which detection mechanism triggered early exit Use this to identify missed optimization opportunities and improve detection patterns. ALWAYS USE FOR: Local file analysis, CSV processing, data exploration, system commands NEVER USE ANALYSIS TOOL FOR: Local file access (analysis tool is browser-only and WILL FAIL) ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(StartProcessArgsSchema), annotations: { title: "Start Terminal Process", readOnlyHint: false, destructiveHint: true, openWorldHint: true, }, },
• src/server.ts:1243-1244 (registration)

  Dispatch in CallToolRequestHandler: routes 'start_process' calls to handleStartProcess handler.
  result = await handlers.handleStartProcess(args); break;
• src/handlers/terminal-handlers.ts:19-25 (handler)

  MCP tool handler for 'start_process': validates args with schema and delegates to core startProcess implementation.
  /** * Handle start_process command (improved execute_command) */ export async function handleStartProcess(args: unknown): Promise<ServerResult> { const parsed = StartProcessArgsSchema.parse(args); return startProcess(parsed); }
• src/tools/schemas.ts:21-26 (schema)

  Zod schema defining input parameters for start_process tool: command, timeout_ms, optional shell and verbose_timing.
  export const StartProcessArgsSchema = z.object({ command: z.string(), timeout_ms: z.number(), shell: z.string().optional(), verbose_timing: z.boolean().optional(), });
• src/tools/improved-process-tools.ts:97-208 (handler)

  Core implementation of process starting logic: validates args, checks command allowance, executes via terminalManager, analyzes state, returns PID and initial output with status.
  export async function startProcess(args: unknown): Promise<ServerResult> { const parsed = StartProcessArgsSchema.safeParse(args); if (!parsed.success) { capture('server_start_process_failed'); return { content: [{ type: "text", text: `Error: Invalid arguments for start_process: ${parsed.error}` }], isError: true, }; } try { const commands = commandManager.extractCommands(parsed.data.command).join(', '); capture('server_start_process', { command: commandManager.getBaseCommand(parsed.data.command), commands: commands }); } catch (error) { capture('server_start_process', { command: commandManager.getBaseCommand(parsed.data.command) }); } const isAllowed = await commandManager.validateCommand(parsed.data.command); if (!isAllowed) { return { content: [{ type: "text", text: `Error: Command not allowed: ${parsed.data.command}` }], isError: true, }; } const commandToRun = parsed.data.command; // Handle node:local - runs Node.js code directly on MCP server if (commandToRun.trim() === 'node:local') { const virtualPid = virtualPidCounter--; virtualNodeSessions.set(virtualPid, { timeout_ms: parsed.data.timeout_ms || 30000 }); return { content: [{ type: "text", text: `Node.js session started with PID ${virtualPid} (MCP server execution) IMPORTANT: Each interact_with_process call runs as a FRESH script. State is NOT preserved between calls. Include ALL code in ONE call: - imports, file reading, processing, and output together. Available libraries: - ExcelJS for Excel files: import ExcelJS from 'exceljs' - All Node.js built-ins: fs, path, http, crypto, etc. 🔄 Ready for code - send complete self-contained script via interact_with_process.` }], }; } let shellUsed: string | undefined = parsed.data.shell; if (!shellUsed) { const config = await configManager.getConfig(); if (config.defaultShell) { shellUsed = config.defaultShell; } else { const isWindows = os.platform() === 'win32'; if (isWindows && process.env.COMSPEC) { shellUsed = process.env.COMSPEC; } else if (!isWindows && process.env.SHELL) { shellUsed = process.env.SHELL; } else { shellUsed = isWindows ? 'cmd.exe' : '/bin/sh'; } } } const result = await terminalManager.executeCommand( commandToRun, parsed.data.timeout_ms, shellUsed, parsed.data.verbose_timing || false ); if (result.pid === -1) { return { content: [{ type: "text", text: result.output }], isError: true, }; } // Analyze the process state to detect if it's waiting for input const processState = analyzeProcessState(result.output, result.pid); let statusMessage = ''; if (processState.isWaitingForInput) { statusMessage = `\n🔄 ${formatProcessStateMessage(processState, result.pid)}`; } else if (processState.isFinished) { statusMessage = `\n✅ ${formatProcessStateMessage(processState, result.pid)}`; } else if (result.isBlocked) { statusMessage = '\n⏳ Process is running. Use read_process_output to get more output.'; } // Add timing information if requested let timingMessage = ''; if (result.timingInfo) { timingMessage = formatTimingInfo(result.timingInfo); } return { content: [{ type: "text", text: `Process started with PID ${result.pid} (shell: ${shellUsed})\nInitial output:\n${result.output}${statusMessage}${timingMessage}` }], }; }