clone_vm

Instructions

Implementation Reference

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

  MCP tool handler for 'clone_vm' — decorated with @mcp.tool(), delegates to utm.clone_vm() and returns the cloned VM config as a dict.

  @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-247 (handler)

  Core implementation of clone_vm — validates names, generates optional random MAC, builds AppleScript for UTM duplicate + optional MAC update, runs it via osascript, 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/applescript.py:85-89 (helper)

  generate_mac() — helper that creates a locally-administered unicast MAC address used when randomize_mac=True.

  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:107-122 (schema)

  VMConfig dataclass — return type for clone_vm; contains name, memory, cpu_cores, mac_address, network_mode with to_dict() serialization.

  @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:1-14 (registration)

  MCP server registration — line 12 imports applescript as utm, line 14 creates FastMCP('utm') which the @mcp.tool() decorator on clone_vm registers against.

  """MCP server exposing UTM virtual machine management via AppleScript.
  
  Tools for listing, cloning, configuring, and controlling UTM VMs.
  Provides proper MAC address randomization for Apple VF clones via
  the AppleScript ``update configuration`` API.
  """
  
  from __future__ import annotations
  
  from mcp.server.fastmcp import FastMCP
  
  from . import applescript as utm
  
  mcp = FastMCP("utm")