MCP4Modal Sandbox

Instructions

Implementation Reference

• src/mcp4modal_sandbox/backend/mcp_server.py:284-317 (handler)

  The core handler function that retrieves the Modal sandbox by ID, verifies it is running, executes the command using modal_sandbox.exec.aio(), captures stdout, stderr, returncode and execution time, and returns a SandboxExecuteResponse.
  async def execute_command( self, sandbox_id: str, command: List[str], timeout_seconds: int = 30 ) -> SandboxExecuteResponse: # Get sandbox from Modal using from_id modal_sandbox = await modal.Sandbox.from_id.aio(sandbox_id) # Check if sandbox is running before executing command sandbox_status = await modal_sandbox.poll.aio() if sandbox_status is not None: raise ToolError(f"Sandbox {sandbox_id} is not running") start_time = time() result = await modal_sandbox.exec.aio(*command, timeout=timeout_seconds) await result.wait.aio() execution_time = time() - start_time # Get output from the sandbox stdout = result.stdout.read() if result.stdout else "" stderr = result.stderr.read() if result.stderr else "" returncode = result.returncode logger.info(f"Executed command in sandbox {sandbox_id}: {' '.join(command)}") return SandboxExecuteResponse( stdout=stdout, stderr=stderr, returncode=returncode, execution_time=execution_time )
• src/mcp4modal_sandbox/backend/mcp_server.py:116-120 (registration)

  Registers the execute_command tool with the FastMCP app, specifying the name, description from ToolDescriptions, and binding the handler method.
  mcp_app.tool( name="execute_command", description=ToolDescriptions.EXECUTE_COMMAND, )(self.execute_command)
• src/mcp4modal_sandbox/backend/response_schema.py:26-31 (schema)

  Pydantic model defining the output schema for the execute_command tool response, including stdout, stderr, returncode, and execution_time.
  class SandboxExecuteResponse(BaseModel): stdout: str stderr: str returncode: int execution_time: float
• src/mcp4modal_sandbox/backend/tool_descriptions.py:94-121 (schema)

  Tool description string used in registration, which includes detailed parameter descriptions serving as informal input schema documentation.
  EXECUTE_COMMAND = """ Executes a command in a specified Modal sandbox environment. Parameters: - sandbox_id: The unique identifier of the sandbox to run the command in - command: The shell command to execute (e.g. "python script.py", "ls -la", etc.) - working_dir: Optional working directory to execute the command from - timeout: Optional timeout in seconds for command execution Returns a SandboxExecuteResponse containing: - stdout: Standard output from the command execution - stderr: Standard error output from the command execution - returncode: Exit code of the command (0 typically indicates success) - execution_time: Time taken to execute the command in seconds This tool is useful for: - Running arbitrary commands in isolated sandbox environments - Testing scripts and programs in clean environments - Executing programs with specific dependencies - Debugging environment-specific issues - Running automated tests in isolation The tool will: 1. Verify the sandbox exists and is running 2. Execute the specified command in that sandbox 3. Capture all output and timing information 4. Return detailed execution results """