get_serial_port
Get the serial port address (ptty path or TCP address/port) of a UTM VM for direct console access without SSH.
Instructions
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
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
Implementation Reference
- src/mcp_utm/applescript.py:330-359 (handler)Core implementation of get_serial_port: validates VM name, executes AppleScript to query UTM for the first serial port's interface/address/port, and returns structured dict with available flag.
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/applescript.py:353-359 (schema)Return value schema: available (bool), id (int), interface (string: 'ptty' or 'tcp'), address (string: path or IP), port (int).
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:147-157 (registration)MCP tool registration using @mcp.tool() decorator on get_serial_port function, which delegates to applescript.get_serial_port.
@mcp.tool() 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:33-36 (helper)_validate_vm_name helper used to sanitize the VM name input before AppleScript execution.
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 - src/mcp_utm/applescript.py:77-82 (helper)_parse_int helper used to parse integer values from AppleScript output (used for serial port id and port number).
def _parse_int(value: str) -> int: """Parse an integer from AppleScript output, handling floats.""" try: return int(float(value)) except (ValueError, TypeError): return 0