get_vm_ip

Instructions

Implementation Reference

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

  MCP tool handler that registers 'get_vm_ip' as a tool and delegates to the AppleScript utility function.

  @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/applescript.py:387-414 (helper)

  Helper function that reads the VM's MAC address from UTM config, then polls the ARP table to discover the IP address. Handles zero-stripped MAC formats and raises TimeoutError if not found within the 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/applescript.py:107-122 (schema)

  The VMConfig dataclass carries the MAC address used by get_vm_ip to search the ARP table.

  @dataclass
  class VMConfig:
      name: str
      memory: int  # MiB
      cpu_cores: int
      mac_address: str
      network_mode: str
  
      def to_dict(self) -> dict:
          return {
              "name": self.name,
              "memory": self.memory,
              "cpu_cores": self.cpu_cores,
              "mac_address": self.mac_address,
              "network_mode": self.network_mode,
          }

• src/mcp_utm/server.py:10-14 (registration)

  The FastMCP instance 'mcp' and the @mcp.tool() decorator register get_vm_ip as an MCP tool in line 74.

  from mcp.server.fastmcp import FastMCP
  
  from . import applescript as utm
  
  mcp = FastMCP("utm")