mcp-wsl-exec

Instructions

Implementation Reference

• src/index.ts:324-395 (registration)

  Complete MCP tool registration for 'execute_command', defining name, description, input schema, annotations, and the handler function that manages execution with safety checks.
  // execute_command tool - potentially destructive this.server.tool( { name: 'execute_command', description: 'Execute a command in WSL (use read-only tools when possible)', schema: v.object({ command: v.pipe( v.string(), v.description('Command to execute'), ), working_dir: v.optional( v.pipe( v.string(), v.description('Working directory'), ), ), timeout: v.optional( v.pipe( v.number(), v.description('Timeout (ms)'), ), ), }), annotations: { readOnlyHint: false, destructiveHint: true, }, }, async ({ command, working_dir, timeout }) => { try { const result = await this.execute_wsl_command( command, working_dir, timeout, ); if (result.requires_confirmation) { return { content: [ { type: 'text' as const, text: result.stderr, }, ], }; } return { content: [ { type: 'text' as const, text: this.format_output(result), }, ], }; } catch (error) { return { content: [ { type: 'text' as const, text: `Error executing command: ${ error instanceof Error ? error.message : String(error) }`, }, ], isError: true, }; } }, );
• src/command-executor.ts:60-119 (handler)

  Low-level handler in CommandExecutor class that performs the actual command execution: sanitizes inputs, spawns WSL process, captures output, handles timeout and errors.
  public async execute_command( command: string, working_dir?: string, timeout?: number, ): Promise<CommandResponse> { return new Promise((resolve, reject) => { const sanitized_command = this.sanitize_command(command); const validated_dir = this.validate_working_dir(working_dir); const validated_timeout = this.validate_timeout(timeout); const cd_command = validated_dir ? `cd "${validated_dir}" && ` : ''; const full_command = `${cd_command}${sanitized_command}`; const wsl_process = spawn(wsl_config.executable, [ '--exec', wsl_config.shell, '-c', full_command, ]); let stdout = ''; let stderr = ''; wsl_process.stdout.on('data', (data) => { stdout += data.toString(); }); wsl_process.stderr.on('data', (data) => { stderr += data.toString(); }); let timeout_id: NodeJS.Timeout | undefined; if (validated_timeout) { timeout_id = setTimeout(() => { wsl_process.kill(); reject(new CommandTimeoutError(validated_timeout)); }, validated_timeout); } wsl_process.on('close', (code) => { if (timeout_id) { clearTimeout(timeout_id); } resolve({ stdout, stderr, exit_code: code, command: sanitized_command, working_dir: validated_dir, }); }); wsl_process.on('error', (error) => { if (timeout_id) { clearTimeout(timeout_id); } reject(error); }); }); }
• src/types.ts:1-8 (schema)

  Type definition for CommandResponse, used as the return type for command execution results.
  export interface CommandResponse { stdout: string; stderr: string; exit_code: number | null; command: string; requires_confirmation?: boolean; error?: string; working_dir?: string;
• src/command-executor.ts:52-58 (helper)

  Helper method to detect potentially dangerous commands requiring confirmation.
  public is_dangerous_command(command: string): boolean { return dangerous_commands.some( (dangerous) => command.toLowerCase().includes(dangerous.toLowerCase()) || command.match(new RegExp(`\\b${dangerous}\\b`, 'i')), ); }
• src/index.ts:329-346 (schema)

  Valibot input schema defining parameters for the execute_command tool.
  schema: v.object({ command: v.pipe( v.string(), v.description('Command to execute'), ), working_dir: v.optional( v.pipe( v.string(), v.description('Working directory'), ), ), timeout: v.optional( v.pipe( v.number(), v.description('Timeout (ms)'), ), ), }),