get_vm_ip

Instructions

Implementation Reference

• src/mcp_utm/applescript.py:387-414 (handler)

  Core implementation: polls ARP table for the VM's MAC address to discover its IP. Reads MAC from UTM config, handles stripped leading zeros in ARP output, retries every 2s up to timeout.

  def get_vm_ip(name: str, timeout: int = 60) -> tuple[str, str]:
      """Discover VM IP via ARP table by reading its MAC from UTM config.
  
      Returns (ip_address, mac_address) tuple.
      """
      _validate_vm_name(name)
      timeout = _validate_timeout(timeout)
      config = get_vm_config(name)
      mac = config.mac_address.lower()
      if not mac:
          raise RuntimeError(f"No MAC address found for VM '{name}'")
  
      # ARP output may strip leading zeros from MAC octets (e.g. 0e → e).
      mac_stripped = ":".join(p.lstrip("0") or "0" for p in mac.split(":"))
  
      deadline = time.monotonic() + timeout
      while time.monotonic() < deadline:
          result = subprocess.run(["arp", "-a"], capture_output=True, text=True)
          for line in result.stdout.split("\n"):
              line_lower = line.lower()
              if mac in line_lower or mac_stripped in line_lower:
                  start = line.find("(")
                  end = line.find(")")
                  if start != -1 and end != -1:
                      return line[start + 1 : end], config.mac_address
          time.sleep(2)
  
      raise TimeoutError(f"IP not found for VM '{name}' (MAC: {mac}) after {timeout}s")

• src/mcp_utm/server.py:74-86 (handler)

  MCP tool handler: wraps the AppleScript get_vm_ip function, returns name/ip/mac_address dict.

  @mcp.tool()
  def get_vm_ip(name: str, timeout: int = 60) -> dict:
      """Discover the IP address of a running VM via ARP.
  
      Polls the ARP table for the VM's MAC address. Works for Apple VF
      (macOS) VMs on the 192.168.64.0/24 subnet and bridged QEMU VMs.
  
      Args:
          name: VM name
          timeout: Seconds to wait for ARP discovery (default: 60)
      """
      ip, mac = utm.get_vm_ip(name, timeout=timeout)
      return {"name": name, "ip": ip, "mac_address": mac}

• src/mcp_utm/server.py:74-75 (registration)

  Tool registered via @mcp.tool() decorator on the get_vm_ip function.

  @mcp.tool()
  def get_vm_ip(name: str, timeout: int = 60) -> dict:

• src/mcp_utm/applescript.py:53-54 (helper)

  Helper: _validate_timeout clamps timeout between 1 and 600 seconds, used inside get_vm_ip.

  def _validate_timeout(timeout: int) -> int:
      return max(1, min(timeout, _MAX_TIMEOUT))

• src/mcp_utm/applescript.py:33-36 (helper)

  Helper: _validate_vm_name validates VM name format, called at the start of get_vm_ip.

  def _validate_vm_name(name: str) -> str:
      if not name or not _VM_NAME_RE.match(name):
          raise ValueError(f"Invalid VM name: {name!r} — only word characters, spaces, hyphens, and dots allowed")
      return name