Claude Desktop Commander MCP

Instructions

                    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.
                    
                    Running on Linux (Docker). Default shell: bash.

Implementation Reference

• src/tools/improved-process-tools.ts:15-101 (handler)

  Core implementation of the start_process tool. Validates input using StartProcessArgsSchema, checks command permissions, determines shell, executes the command via terminalManager, analyzes process state for input readiness or completion, and returns PID with initial output and 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,
      };
    }
  
    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(
      parsed.data.command,
      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}`
      }],
    };
  }

• src/tools/schemas.ts:21-26 (schema)

  Zod schema defining input parameters for start_process: command (required string), timeout_ms (required number), shell (optional string), verbose_timing (optional boolean).

  export const StartProcessArgsSchema = z.object({
    command: z.string(),
    timeout_ms: z.number(),
    shell: z.string().optional(),
    verbose_timing: z.boolean().optional(),
  });

• src/server.ts:693-760 (registration)

  Tool metadata registration in list_tools handler: defines name 'start_process', detailed description, inputSchema from 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 for JSON processing  
              • 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:
              1. start_process("python3 -i") - Start Python REPL for data work
              2. start_process("node -i") - Start Node.js REPL for JSON/JS
              3. start_process("bash") - Start interactive bash shell
              4. Use interact_with_process() to send commands
              5. Use read_process_output() to get responses
              
              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:1204-1206 (registration)

  Dispatch registration in CallToolRequestHandler switch statement: routes 'start_process' tool calls to handlers.handleStartProcess(args).

  case "start_process":
      result = await handlers.handleStartProcess(args);
      break;

• src/handlers/terminal-handlers.ts:20-25 (handler)

  Thin wrapper handler that strictly parses args with StartProcessArgsSchema and delegates to the 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);
  }