Desktop Commander MCP

Instructions

Implementation Reference

• src/tools/execute.ts:5-28 (handler)

  The primary MCP tool handler function for 'execute_command'. Parses input arguments using the schema, validates the command against allowed commands, executes the command using terminalManager, and returns structured content with PID and initial output.
  export async function executeCommand(args: unknown) { const parsed = ExecuteCommandArgsSchema.safeParse(args); if (!parsed.success) { throw new Error(`Invalid arguments for execute_command: ${parsed.error}`); } if (!commandManager.validateCommand(parsed.data.command)) { throw new Error(`Command not allowed: ${parsed.data.command}`); } const result = await terminalManager.executeCommand( parsed.data.command, parsed.data.timeout_ms ); return { content: [{ type: "text", text: `Command started with PID ${result.pid}\nInitial output:\n${result.output}${ result.isBlocked ? '\nCommand is still running. Use read_output to get more output.' : '' }` }], }; }
• src/tools/schemas.ts:4-7 (schema)

  Zod schema defining the input parameters for the execute_command tool: required 'command' string and optional 'timeout_ms' number.
  export const ExecuteCommandArgsSchema = z.object({ command: z.string(), timeout_ms: z.number().optional(), });
• src/server.ts:60-65 (registration)

  Registration of the execute_command tool in the listTools response, specifying name, description, and input schema.
  { name: "execute_command", description: "Execute a terminal command with timeout. Command will continue running in background if it doesn't complete within timeout.", inputSchema: zodToJsonSchema(ExecuteCommandArgsSchema), },
• src/server.ts:216-219 (registration)

  Tool dispatch logic in the CallToolRequest handler: parses arguments and invokes the executeCommand handler function.
  case "execute_command": { const parsed = ExecuteCommandArgsSchema.parse(args); return executeCommand(parsed); }
• src/terminal-manager.ts:17-84 (helper)

  Supporting utility in TerminalManager class that performs the actual command execution using Node.js child_process.spawn, handles stdout/stderr capture, timeout enforcement, process exit handling, and session management.
  async executeCommand(command: string, timeoutMs: number = DEFAULT_COMMAND_TIMEOUT): Promise<CommandExecutionResult> { const process = spawn(command, [], { shell: true }); let output = ''; // Ensure process.pid is defined before proceeding if (!process.pid) { throw new Error('Failed to get process ID'); } const session: TerminalSession = { pid: process.pid, process, lastOutput: '', isBlocked: false, startTime: new Date() }; this.sessions.set(process.pid, session); return new Promise((resolve) => { process.stdout.on('data', (data) => { const text = data.toString(); output += text; session.lastOutput += text; }); process.stderr.on('data', (data) => { const text = data.toString(); output += text; session.lastOutput += text; }); setTimeout(() => { session.isBlocked = true; resolve({ pid: process.pid!, output, isBlocked: true }); }, timeoutMs); process.on('exit', (code) => { if (process.pid) { // Store completed session before removing active session this.completedSessions.set(process.pid, { pid: process.pid, output: output + session.lastOutput, // Combine all output exitCode: code, startTime: session.startTime, endTime: new Date() }); // Keep only last 100 completed sessions if (this.completedSessions.size > 100) { const oldestKey = Array.from(this.completedSessions.keys())[0]; this.completedSessions.delete(oldestKey); } this.sessions.delete(process.pid); } resolve({ pid: process.pid!, output, isBlocked: false }); }); }); }