wait_for_vm
Waits for a virtual machine to reach a specific status (stopped, started, paused) within a set timeout. Enables reliable orchestration of VM actions.
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-172 (handler)MCP tool handler for 'wait_for_vm'. Uses the @mcp.tool() decorator to register the tool. Delegates to utm.wait_for_vm() and returns dict with name and status.
@mcp.tool() 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 AppleScript helper that polls VM status until target is reached or timeout. Validates inputs, then loops calling get_vm_status every 2 seconds.
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/server.py:160-161 (registration)Tool registration via @mcp.tool() decorator on the wait_for_vm function. Makes 'wait_for_vm' available as an MCP tool.
@mcp.tool() def wait_for_vm(name: str, target_status: str = "started", timeout: int = 120) -> dict: - src/mcp_utm/server.py:160-172 (schema)Input parameters: name (str), target_status (str, default 'started'), timeout (int, default 120). Return type: dict with name and status keys.
@mcp.tool() 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}