Sympathy-MCP

Instructions

Returns:
    Formatted list of all instances, or a message if none exist.

Implementation Reference

• src/sympathy_mcp/server.py:284-304 (handler)

  The MCP tool handler registered with @mcp.tool() decorator. This function calls the lifecycle implementation and formats the VM list as a formatted string output.

  @mcp.tool()
  async def vm_list() -> str:
      """List all available VMs and containers with their status (Incus).
  
      Returns:
          Formatted list of all instances, or a message if none exist.
      """
      try:
          vms = await _vm_list()
          if not vms:
              return "No VMs or containers found."
  
          lines = [f"{'Name':<20} {'Status':<12} {'Type':<18} {'IPv4':<16}"]
          lines.append("-" * 66)
          for vm in vms:
              lines.append(
                  f"{vm.name:<20} {vm.status:<12} {vm.type:<18} {vm.ipv4:<16}"
              )
          return "\n".join(lines)
      except (RuntimeError, OSError) as e:
          return f"ERROR: {e}"

• src/sympathy_mcp/lifecycle.py:211-246 (handler)

  The core implementation that runs 'incus list --format json', parses the JSON output, and extracts VM information including name, status, type, and IPv4 addresses.

  async def vm_list() -> list[VMInfo]:
      """List all VMs/containers with status.
  
      Uses `incus list --format json`.
      """
      result = await _run_incus("list", "--format", "json")
      if result.exit_code != 0:
          raise RuntimeError(
              f"Failed to list VMs: {result.stderr.strip()}"
          )
  
      try:
          instances = json.loads(result.stdout)
      except json.JSONDecodeError as e:
          raise RuntimeError(f"Failed to parse incus output: {e}")
  
      vms: list[VMInfo] = []
      for inst in instances:
          ipv4 = ""
          state = inst.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", "")
  
          vms.append(VMInfo(
              name=inst.get("name", ""),
              status=inst.get("status", "Unknown"),
              type=inst.get("type", "unknown"),
              ipv4=ipv4,
          ))
  
      return vms

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

  Dataclass schema defining the VMInfo structure with fields for name, status, type, IPv4/IPv6 addresses, architecture, and resource usage statistics.

  @dataclass
  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:34-34 (registration)

  Import statement that imports vm_list from lifecycle module as _vm_list, making the core implementation available to the MCP tool handler.

  vm_list as _vm_list,