clone_vm

Instructions

Implementation Reference

• src/mcp_utm/server.py:31-46 (handler)

  MCP tool handler for clone_vm — registers the tool with FastMCP and delegates to applescript.clone_vm

  @mcp.tool()
  def clone_vm(
      template: str,
      name: str,
      randomize_mac: bool = True,
  ) -> dict:
      """Clone a UTM template VM with a unique random MAC address.
  
      Args:
          template: Name of the template VM to clone
          name: Name for the new VM
          randomize_mac: Assign a random MAC so clones get unique IPs (default: True)
      """
      config = utm.clone_vm(template, name, randomize_mac=randomize_mac)
      return {"cloned": True, **config.to_dict()}

• src/mcp_utm/applescript.py:215-246 (helper)

  Core AppleScript implementation — duplicates the VM template via osascript, optionally randomizes MAC, and returns the new VM config

  def clone_vm(template_name: str, new_name: str, randomize_mac: bool = True) -> VMConfig:
      """Clone a VM, optionally assigning a random MAC address.
  
      Uses AppleScript ``duplicate`` + ``update configuration`` so UTM's
      in-memory state is updated (unlike raw plist edits).
      """
      _validate_vm_name(template_name)
      _validate_vm_name(new_name)
      new_mac = generate_mac() if randomize_mac else ""
  
      if new_mac:
          script = f'''
          tell application "UTM"
              set tmpl to virtual machine named "{_esc(template_name)}"
              duplicate tmpl with properties {{configuration:{{name:"{_esc(new_name)}"}}}}
              set vm to virtual machine named "{_esc(new_name)}"
              set conf to configuration of vm
              set nic to item 1 of (network interfaces of conf)
              set address of nic to "{_esc(new_mac)}"
              update configuration of vm with conf
          end tell
          '''
      else:
          script = f'''
          tell application "UTM"
              set tmpl to virtual machine named "{_esc(template_name)}"
              duplicate tmpl with properties {{configuration:{{name:"{_esc(new_name)}"}}}}
          end tell
          '''
      _run(script, timeout=600)
  
      return get_vm_config(new_name)

• src/mcp_utm/server.py:31-46 (registration)

  Registration via @mcp.tool() decorator — registers clone_vm as an MCP tool on the FastMCP server

  @mcp.tool()
  def clone_vm(
      template: str,
      name: str,
      randomize_mac: bool = True,
  ) -> dict:
      """Clone a UTM template VM with a unique random MAC address.
  
      Args:
          template: Name of the template VM to clone
          name: Name for the new VM
          randomize_mac: Assign a random MAC so clones get unique IPs (default: True)
      """
      config = utm.clone_vm(template, name, randomize_mac=randomize_mac)
      return {"cloned": True, **config.to_dict()}

• src/mcp_utm/applescript.py:85-89 (helper)

  MAC address generator helper — produces random locally-administered unicast MACs for cloned VMs

  def generate_mac() -> str:
      """Generate a random locally-administered unicast MAC address."""
      octets = [random.randint(0, 255) for _ in range(6)]
      octets[0] = (octets[0] & 0xFC) | 0x02  # locally administered, unicast
      return ":".join(f"{b:02x}" for b in octets)

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

  Input validation helper — ensures VM names contain only safe characters to prevent AppleScript injection

  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