execute_command
Executes terminal commands on your computer with a specified timeout, allowing commands to run in the background if not completed within the set time.
Instructions
Execute a terminal command with timeout. Command will continue running in background if it doesn't complete within timeout.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | ||
| timeout_ms | No |
Implementation Reference
- src/tools/execute.ts:5-28 (handler)The primary handler function for the 'execute_command' MCP tool. It validates input arguments using the schema, checks if the command is allowed, executes the command via the terminal manager, and returns a formatted response with initial output and session information.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 arguments for the 'execute_command' tool: 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)Tool registration in the ListTools response, defining the name, description, and input schema for 'execute_command'.{ 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/terminal-manager.ts:17-84 (helper)Core helper method in TerminalManager that spawns the shell process, handles stdout/stderr, manages timeouts and sessions, and provides the execution result. Called by the main handler.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 }); }); }); }
- src/server.ts:216-219 (registration)Dispatch handler in the CallToolRequest switch statement that parses arguments and delegates to the executeCommand handler.case "execute_command": { const parsed = ExecuteCommandArgsSchema.parse(args); return executeCommand(parsed); }