vm_status

Instructions

Returns state (running/stopped), IP address, resource usage,
and available snapshots.

Args:
    vm: Name of the VM or container.

Returns:
    Formatted status information or error message.

Implementation Reference

• src/sympathy_mcp/lifecycle.py:143-208 (handler)

  The core implementation of vm_status that queries Incus CLI to get VM status information. Validates the VM name, runs 'incus list <vm> --format json', parses the JSON response, extracts network addresses, snapshots, and resource usage, then returns a VMInfo object.

  async def vm_status(vm: str) -> VMInfo:
      """Get detailed status of a VM/container.
  
      Uses `incus list <vm> --format json` for structured data.
      """
      _validate_vm_name(vm)
  
      result = await _run_incus("list", vm, "--format", "json")
      if result.exit_code != 0:
          raise RuntimeError(
              f"Failed to get status for {vm}: {result.stderr.strip()}"
          )
  
      try:
          instances = json.loads(result.stdout)
      except json.JSONDecodeError as e:
          raise RuntimeError(f"Failed to parse incus output: {e}")
  
      if not instances:
          raise RuntimeError(f"VM/container '{vm}' not found")
  
      # Find exact match (incus list does prefix matching)
      instance = None
      for inst in instances:
          if inst.get("name") == vm:
              instance = inst
              break
  
      if instance is None:
          raise RuntimeError(f"VM/container '{vm}' not found")
  
      # Extract network info
      ipv4 = ""
      ipv6 = ""
      state = instance.get("state", {})
      networks = state.get("network", {})
      for iface_name, iface in networks.items():
          if iface_name == "lo":
              continue
          for addr in iface.get("addresses", []):
              if addr.get("family") == "inet" and addr.get("scope") == "global":
                  ipv4 = ipv4 or addr.get("address", "")
              elif addr.get("family") == "inet6" and addr.get("scope") == "global":
                  ipv6 = ipv6 or addr.get("address", "")
  
      # Extract snapshots
      snapshot_names = []
      for snap in instance.get("snapshots", []) or []:
          if isinstance(snap, dict):
              snapshot_names.append(snap.get("name", ""))
          elif isinstance(snap, str):
              snapshot_names.append(snap)
  
      return VMInfo(
          name=instance.get("name", vm),
          status=instance.get("status", "Unknown"),
          type=instance.get("type", "unknown"),
          architecture=instance.get("architecture", ""),
          ipv4=ipv4,
          ipv6=ipv6,
          pid=state.get("pid", 0),
          processes=state.get("processes", 0),
          memory_usage=state.get("memory", {}).get("usage", 0),
          cpu_usage=state.get("cpu", {}).get("usage", 0),
          snapshots=snapshot_names,
      )

• src/sympathy_mcp/server.py:264-281 (registration)

  MCP tool registration for vm_status. Uses the @mcp.tool() decorator to expose the function as an MCP tool, wraps the underlying _vm_status implementation, catches exceptions, and formats the VMInfo object into a human-readable string.

  @mcp.tool()
  async def vm_status(vm: str) -> str:
      """Get the status of a VM/container (Incus).
  
      Returns state (running/stopped), IP address, resource usage,
      and available snapshots.
  
      Args:
          vm: Name of the VM or container.
  
      Returns:
          Formatted status information or error message.
      """
      try:
          info = await _vm_status(vm)
          return _format_vm_info(info)
      except (ValueError, RuntimeError, OSError) as e:
          return f"ERROR: {e}"

• src/sympathy_mcp/lifecycle.py:31-45 (schema)

  VMInfo dataclass defining the schema for VM status information. Includes fields for name, status, type, IP addresses, architecture, PID, processes, memory usage, CPU usage, and snapshots list.

  class VMInfo:
      """Status information for a single VM/container."""
  
      name: str
      status: str  # Running, Stopped, etc.
      type: str  # container or virtual-machine
      ipv4: str = ""
      ipv6: str = ""
      architecture: str = ""
      pid: int = 0
      processes: int = 0
      memory_usage: int = 0
      cpu_usage: int = 0
      snapshots: list[str] = field(default_factory=list)

• src/sympathy_mcp/server.py:69-94 (helper)

  Helper function that formats a VMInfo object into a human-readable string for the MCP tool response. Converts memory usage to MB, CPU time to seconds, and formats all fields with labels.

  def _format_vm_info(info: VMInfo) -> str:
      """Format VMInfo as a readable string."""
      lines = [
          f"Name: {info.name}",
          f"Status: {info.status}",
          f"Type: {info.type}",
      ]
      if info.architecture:
          lines.append(f"Architecture: {info.architecture}")
      if info.ipv4:
          lines.append(f"IPv4: {info.ipv4}")
      if info.ipv6:
          lines.append(f"IPv6: {info.ipv6}")
      if info.pid:
          lines.append(f"PID: {info.pid}")
      if info.processes:
          lines.append(f"Processes: {info.processes}")
      if info.memory_usage:
          mb = info.memory_usage / (1024 * 1024)
          lines.append(f"Memory: {mb:.1f} MB")
      if info.cpu_usage:
          secs = info.cpu_usage / 1_000_000_000
          lines.append(f"CPU Time: {secs:.2f}s")
      if info.snapshots:
          lines.append(f"Snapshots: {', '.join(info.snapshots)}")
      return "\n".join(lines)

• src/sympathy_mcp/lifecycle.py:54-62 (helper)

  Validation helper that ensures VM/container names are safe and valid. Checks that the name is not empty and matches the regex pattern requiring it to start with a letter and contain only alphanumeric characters and hyphens.

  def _validate_vm_name(name: str) -> None:
      """Validate that a VM/container name is safe."""
      if not name or not name.strip():
          raise ValueError("VM name cannot be empty")
      if not _VALID_NAME.match(name):
          raise ValueError(
              f"Invalid VM name '{name}': must start with a letter, "
              "contain only alphanumeric characters and hyphens"
          )