Sympathy-MCP

Instructions

Args:
    vm: Name of the VM or container.
    snapshot: Name of the snapshot to restore.

Returns:
    Success confirmation or error message.

Implementation Reference

• src/sympathy_mcp/server.py:244-261 (handler)

  MCP tool handler that wraps the core vm_restore implementation with error handling and response formatting. Decorated with @mcp.tool() for registration.

  @mcp.tool()
  async def vm_restore(vm: str, snapshot: str) -> str:
      """Restore a VM/container to a named snapshot (Incus).
  
      Args:
          vm: Name of the VM or container.
          snapshot: Name of the snapshot to restore.
  
      Returns:
          Success confirmation or error message.
      """
      try:
          result = await _vm_restore(vm, snapshot)
          if result.exit_code == 0:
              return f"Restored {vm} to snapshot '{snapshot}'"
          return f"ERROR restoring snapshot: {result.stderr.strip()}"
      except (ValueError, RuntimeError, OSError) as e:
          return f"ERROR: {e}"

• src/sympathy_mcp/lifecycle.py:133-140 (handler)

  Core implementation of vm_restore that validates inputs and executes the incus CLI command to restore a VM to a snapshot.

  async def vm_restore(vm: str, snapshot: str) -> ExecResult:
      """Restore a VM/container to a named snapshot.
  
      Uses `incus snapshot restore <vm> <snapshot>`.
      """
      _validate_vm_name(vm)
      _validate_snapshot_name(snapshot)
      return await _run_incus("snapshot", "restore", vm, snapshot)

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

  Validation helper functions used by vm_restore to ensure VM and snapshot names are safe before executing the incus command.

  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"
          )
  
  
  def _validate_snapshot_name(name: str) -> None:
      """Validate a snapshot name."""
      if not name or not name.strip():
          raise ValueError("Snapshot name cannot be empty")
      if not re.match(r"^[a-zA-Z0-9_\-]+$", name):
          raise ValueError(
              f"Invalid snapshot name '{name}': "
              "only alphanumeric, hyphens, and underscores allowed"
          )

• src/sympathy_mcp/server.py:29-35 (registration)

  Import statement that brings the core vm_restore implementation into the server module, aliased as _vm_restore to distinguish from the MCP handler.

  from sympathy_mcp.lifecycle import (
      VMInfo,
      vm_snapshot as _vm_snapshot,
      vm_restore as _vm_restore,
      vm_status as _vm_status,
      vm_list as _vm_list,
  )