Desktop Commander MCP

Instructions

Implementation Reference

• src/tools/improved-process-tools.ts:379-647 (handler)

  Core handler function that executes the interact_with_process tool logic: parses args, sends input to process PID, waits for prompt/response with smart detection, handles virtual Node sessions, returns formatted output with state info.
  export async function interactWithProcess(args: unknown): Promise<ServerResult> { const parsed = InteractWithProcessArgsSchema.safeParse(args); if (!parsed.success) { capture('server_interact_with_process_failed', { error: 'Invalid arguments' }); return { content: [{ type: "text", text: `Error: Invalid arguments for interact_with_process: ${parsed.error}` }], isError: true, }; } const { pid, input, timeout_ms = 8000, wait_for_prompt = true, verbose_timing = false } = parsed.data; // Get config for output line limit const config = await configManager.getConfig(); const maxOutputLines = config.fileReadLineLimit ?? 1000; // Check if this is a virtual Node session (node:local) if (virtualNodeSessions.has(pid)) { const session = virtualNodeSessions.get(pid)!; capture('server_interact_with_process_node_fallback', { pid: pid, inputLength: input.length }); // Execute code via temp file approach // Respect per-call timeout if provided, otherwise use session default const effectiveTimeout = timeout_ms ?? session.timeout_ms; return executeNodeCode(input, effectiveTimeout); } // Timing telemetry const startTime = Date.now(); let firstOutputTime: number | undefined; let lastOutputTime: number | undefined; const outputEvents: any[] = []; let exitReason: 'early_exit_quick_pattern' | 'early_exit_periodic_check' | 'process_finished' | 'timeout' | 'no_wait' = 'timeout'; try { capture('server_interact_with_process', { pid: pid, inputLength: input.length }); // Capture output snapshot BEFORE sending input // This handles REPLs where output is appended to the prompt line const outputSnapshot = terminalManager.captureOutputSnapshot(pid); const success = terminalManager.sendInputToProcess(pid, input); if (!success) { return { content: [{ type: "text", text: `Error: Failed to send input to process ${pid}. The process may have exited or doesn't accept input.` }], isError: true, }; } // If not waiting for response, return immediately if (!wait_for_prompt) { exitReason = 'no_wait'; let timingMessage = ''; if (verbose_timing) { const endTime = Date.now(); const timingInfo = { startTime, endTime, totalDurationMs: endTime - startTime, exitReason, firstOutputTime, lastOutputTime, timeToFirstOutputMs: undefined, outputEvents: undefined }; timingMessage = formatTimingInfo(timingInfo); } return { content: [{ type: "text", text: `✅ Input sent to process ${pid}. Use read_process_output to get the response.${timingMessage}` }], }; } // Smart waiting with immediate and periodic detection let output = ""; let processState: ProcessState | undefined; let earlyExit = false; // Quick prompt patterns for immediate detection const quickPromptPatterns = />>>\s*$|>\s*$|\$\s*$|#\s*$/; const waitForResponse = (): Promise<void> => { return new Promise((resolve) => { let resolved = false; let attempts = 0; const pollIntervalMs = 50; // Poll every 50ms for faster response const maxAttempts = Math.ceil(timeout_ms / pollIntervalMs); let interval: NodeJS.Timeout | null = null; let lastOutputLength = 0; // Track output length to detect new output let resolveOnce = () => { if (resolved) return; resolved = true; if (interval) clearInterval(interval); resolve(); }; // Fast-polling check - check every 50ms for quick responses interval = setInterval(() => { if (resolved) return; // Use snapshot-based reading to handle REPL prompt line appending const newOutput = outputSnapshot ? terminalManager.getOutputSinceSnapshot(pid, outputSnapshot) : terminalManager.getNewOutput(pid); if (newOutput && newOutput.length > lastOutputLength) { const now = Date.now(); if (!firstOutputTime) firstOutputTime = now; lastOutputTime = now; if (verbose_timing) { outputEvents.push({ timestamp: now, deltaMs: now - startTime, source: 'periodic_poll', length: newOutput.length - lastOutputLength, snippet: newOutput.slice(lastOutputLength, lastOutputLength + 50).replace(/\n/g, '\\n') }); } output = newOutput; // Replace with full output since snapshot lastOutputLength = newOutput.length; // Analyze current state processState = analyzeProcessState(output, pid); // Exit early if we detect the process is waiting for input if (processState.isWaitingForInput) { earlyExit = true; exitReason = 'early_exit_periodic_check'; if (verbose_timing && outputEvents.length > 0) { outputEvents[outputEvents.length - 1].matchedPattern = 'periodic_check'; } resolveOnce(); return; } // Also exit if process finished if (processState.isFinished) { exitReason = 'process_finished'; resolveOnce(); return; } } attempts++; if (attempts >= maxAttempts) { exitReason = 'timeout'; resolveOnce(); } }, pollIntervalMs); }); }; await waitForResponse(); // Clean and format output let cleanOutput = cleanProcessOutput(output, input); const timeoutReached = !earlyExit && !processState?.isFinished && !processState?.isWaitingForInput; // Apply output line limit to prevent context overflow let truncationMessage = ''; const outputLines = cleanOutput.split('\n'); if (outputLines.length > maxOutputLines) { const truncatedLines = outputLines.slice(0, maxOutputLines); cleanOutput = truncatedLines.join('\n'); const remainingLines = outputLines.length - maxOutputLines; truncationMessage = `\n\n⚠️ Output truncated: showing ${maxOutputLines} of ${outputLines.length} lines (${remainingLines} hidden). Use read_process_output with offset/length for full output.`; } // Determine final state if (!processState) { processState = analyzeProcessState(output, pid); } let statusMessage = ''; if (processState.isWaitingForInput) { statusMessage = `\n🔄 ${formatProcessStateMessage(processState, pid)}`; } else if (processState.isFinished) { statusMessage = `\n✅ ${formatProcessStateMessage(processState, pid)}`; } else if (timeoutReached) { statusMessage = '\n⏱️ Response may be incomplete (timeout reached)'; } // Add timing information if requested let timingMessage = ''; if (verbose_timing) { const endTime = Date.now(); const timingInfo = { startTime, endTime, totalDurationMs: endTime - startTime, exitReason, firstOutputTime, lastOutputTime, timeToFirstOutputMs: firstOutputTime ? firstOutputTime - startTime : undefined, outputEvents: outputEvents.length > 0 ? outputEvents : undefined }; timingMessage = formatTimingInfo(timingInfo); } if (cleanOutput.trim().length === 0 && !timeoutReached) { return { content: [{ type: "text", text: `✅ Input executed in process ${pid}.\n📭 (No output produced)${statusMessage}${timingMessage}` }], }; } // Format response with better structure and consistent emojis let responseText = `✅ Input executed in process ${pid}`; if (cleanOutput && cleanOutput.trim().length > 0) { responseText += `:\n\n📤 Output:\n${cleanOutput}`; } else { responseText += `.\n📭 (No output produced)`; } if (statusMessage) { responseText += `\n\n${statusMessage}`; } if (truncationMessage) { responseText += truncationMessage; } if (timingMessage) { responseText += timingMessage; } return { content: [{ type: "text", text: responseText }], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); capture('server_interact_with_process_error', { error: errorMessage }); return { content: [{ type: "text", text: `Error interacting with process: ${errorMessage}` }], isError: true, }; } }
• src/server.ts:1250-1252 (registration)

  In the MCP call_tool request handler switch, dispatches 'interact_with_process' calls to the specific handler function.
  case "interact_with_process": result = await handlers.handleInteractWithProcess(args); break;
• src/server.ts:842-907 (registration)

  Tool registration in list_tools handler: defines name, description, input schema (from InteractWithProcessArgsSchema), and annotations for the interact_with_process tool.
  name: "interact_with_process", description: ` Send input to a running process and automatically receive the response. CRITICAL: THIS IS THE PRIMARY TOOL FOR ALL LOCAL FILE ANALYSIS For ANY local file analysis (CSV, JSON, data processing), ALWAYS use this instead of the analysis tool. The analysis tool CANNOT access local files and WILL FAIL - use processes for ALL file-based work. FILE ANALYSIS PRIORITY ORDER (MANDATORY): 1. ALWAYS FIRST: Use this tool (start_process + interact_with_process) for local data analysis 2. ALTERNATIVE: Use command-line tools (cut, awk, grep) for quick processing 3. NEVER EVER: Use analysis tool for local file access (IT WILL FAIL) REQUIRED INTERACTIVE WORKFLOW FOR FILE ANALYSIS: 1. Start REPL: start_process("python3 -i") 2. Load libraries: interact_with_process(pid, "import pandas as pd, numpy as np") 3. Read file: interact_with_process(pid, "df = pd.read_csv('/absolute/path/file.csv')") 4. Analyze: interact_with_process(pid, "print(df.describe())") 5. Continue: interact_with_process(pid, "df.groupby('column').size()") BINARY FILE PROCESSING WORKFLOWS: Use appropriate Python libraries (PyPDF2, pandas, docx2txt, etc.) or command-line tools for binary file analysis. SMART DETECTION: - Automatically waits for REPL prompt (>>>, >, etc.) - Detects errors and completion states - Early exit prevents timeout delays - Clean output formatting (removes prompts) SUPPORTED REPLs: - Python: python3 -i (RECOMMENDED for data analysis) - Node.js: node -i - R: R - Julia: julia - Shell: bash, zsh - Database: mysql, postgres PARAMETERS: - pid: Process ID from start_process - input: Code/command to execute - timeout_ms: Max wait (default: 8000ms) - wait_for_prompt: Auto-wait for response (default: true) - verbose_timing: Enable detailed performance telemetry (default: false) Returns execution result with status indicators. 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_finished, timeout, no_wait) - 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 slow interactions and optimize detection patterns. ALWAYS USE FOR: CSV analysis, JSON processing, file statistics, data visualization prep, ANY local file work NEVER USE ANALYSIS TOOL FOR: Local file access (it cannot read files from disk and WILL FAIL) ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(InteractWithProcessArgsSchema), annotations: { title: "Send Input to Process", readOnlyHint: false, destructiveHint: true, openWorldHint: true, }, },
• src/tools/schemas.ts:146-152 (schema)

  Zod schema defining input parameters for interact_with_process: pid (number), input (string), optional timeout_ms, wait_for_prompt, verbose_timing.
  export const InteractWithProcessArgsSchema = z.object({ pid: z.number(), input: z.string(), timeout_ms: z.number().optional(), wait_for_prompt: z.boolean().optional(), verbose_timing: z.boolean().optional(), });
• src/handlers/terminal-handlers.ts:35-40 (handler)

  Thin MCP handler wrapper that forwards args directly to the core interactWithProcess function (note: does not parse schema here).
  /** * Handle interact_with_process command (improved send_input) */ export async function handleInteractWithProcess(args: unknown): Promise<ServerResult> { return interactWithProcess(args); }