get_serial_port

Instructions

Implementation Reference

• src/mcp_utm/applescript.py:330-359 (handler)

  The actual implementation of get_serial_port. It runs an AppleScript to fetch the first serial port's interface, address (ptty path or TCP), and port from UTM via osascript, returning a dict with availability, id, interface, address, and port.

  def get_serial_port(name: str) -> dict:
      """Get the first serial port's interface and address (ptty path or TCP info)."""
      _validate_vm_name(name)
      script = f'''
      tell application "UTM"
          set vm to virtual machine named "{_esc(name)}"
          set ports to serial ports of vm
          if (count of ports) > 0 then
              set p to item 1 of ports
              set pId to id of p
              set pIface to interface of p as text
              set pAddr to address of p
              set pPort to port of p
              return pId & "||" & pIface & "||" & pAddr & "||" & pPort
          else
              return "none"
          end if
      end tell
      '''
      raw = _run(script)
      if raw == "none":
          return {"available": False}
      parts = raw.split("||")
      return {
          "available": True,
          "id": _parse_int(parts[0]) if len(parts) > 0 else 0,
          "interface": parts[1] if len(parts) > 1 else "",
          "address": parts[2] if len(parts) > 2 else "",
          "port": _parse_int(parts[3]) if len(parts) > 3 else 0,
      }

• src/mcp_utm/server.py:148-157 (handler)

  The MCP tool definition for get_serial_port. Decorated with @mcp.tool(), it delegates to utm.get_serial_port(name) (the applescript module).

  def get_serial_port(name: str) -> dict:
      """Get the serial port address of a VM.
  
      Returns the ptty path (for Apple VF) or TCP address/port (for QEMU)
      that can be used for direct console access without SSH.
  
      Args:
          name: VM name
      """
      return utm.get_serial_port(name)

• src/mcp_utm/server.py:148-157 (registration)

  Registration of the get_serial_port tool via the @mcp.tool() decorator on the get_serial_port function in server.py.

  def get_serial_port(name: str) -> dict:
      """Get the serial port address of a VM.
  
      Returns the ptty path (for Apple VF) or TCP address/port (for QEMU)
      that can be used for direct console access without SSH.
  
      Args:
          name: VM name
      """
      return utm.get_serial_port(name)

• src/mcp_utm/applescript.py:353-359 (schema)

  Return schema: dict with 'available' (bool), 'id' (int), 'interface' (str), 'address' (str), 'port' (int). Input is a single 'name' (str) parameter.

  return {
      "available": True,
      "id": _parse_int(parts[0]) if len(parts) > 0 else 0,
      "interface": parts[1] if len(parts) > 1 else "",
      "address": parts[2] if len(parts) > 2 else "",
      "port": _parse_int(parts[3]) if len(parts) > 3 else 0,
  }

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

  _parse_int helper used by get_serial_port to parse AppleScript integer/float values from the split result.

  def _parse_int(value: str) -> int: