wait_for_vm
Block until a VM reaches a target status like started, stopped, or paused. Ideal for orchestration to confirm VM readiness.
Instructions
Wait until a VM reaches a target status.
Useful for orchestration — start a VM then wait for it to be ready.
Args: name: VM name target_status: Status to wait for: "stopped", "started", or "paused" timeout: Seconds to wait (default: 120)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| target_status | No | started | |
| timeout | No |
Implementation Reference
- src/mcp_utm/server.py:160-162 (registration)The @mcp.tool() decorator registers 'wait_for_vm' as an MCP tool. The function delegates to applescript.wait_for_vm().
@mcp.tool() def wait_for_vm(name: str, target_status: str = "started", timeout: int = 120) -> dict: """Wait until a VM reaches a target status. - src/mcp_utm/server.py:161-172 (handler)The MCP tool handler for 'wait_for_vm': accepts name, target_status (default 'started'), and timeout (default 120s); calls utm.wait_for_vm() and returns a dict with name and status.
def wait_for_vm(name: str, target_status: str = "started", timeout: int = 120) -> dict: """Wait until a VM reaches a target status. Useful for orchestration — start a VM then wait for it to be ready. Args: name: VM name target_status: Status to wait for: "stopped", "started", or "paused" timeout: Seconds to wait (default: 120) """ status = utm.wait_for_vm(name, target_status=target_status, timeout=timeout) return {"name": name, "status": status} - src/mcp_utm/applescript.py:366-380 (helper)Core polling logic: validates inputs, then polls get_vm_status() every 2 seconds until the target status is reached or timeout expires. Raises TimeoutError on timeout.
def wait_for_vm(name: str, target_status: str = "started", timeout: int = 120) -> str: """Poll VM status until it matches target or timeout is reached.""" _validate_vm_name(name) if target_status not in _VALID_STATUSES: raise ValueError(f"Invalid target_status '{target_status}'. Must be one of: {_VALID_STATUSES}") timeout = _validate_timeout(timeout) status = get_vm_status(name) deadline = time.monotonic() + timeout while time.monotonic() < deadline: if status == target_status: return status time.sleep(2) status = get_vm_status(name) raise TimeoutError(f"VM '{name}' did not reach '{target_status}' within {timeout}s (current: {status})") - src/mcp_utm/applescript.py:21-21 (schema)Defines _VALID_STATUSES = {'stopped', 'started', 'paused', 'starting', 'stopping', 'pausing', 'resuming'} used for validation of the target_status parameter.
_VALID_STATUSES = {"stopped", "started", "paused", "starting", "stopping", "pausing", "resuming"} - src/mcp_utm/applescript.py:53-54 (helper)_validate_timeout clamps the timeout value between 1 and _MAX_TIMEOUT (600).
def _validate_timeout(timeout: int) -> int: return max(1, min(timeout, _MAX_TIMEOUT))