power_off_vm

Instructions

Implementation Reference

• src/nutanix_mcp/tools/vm.py:64-84 (schema)

  Tool definition (schema) for 'power_off_vm' with vm_uuid and optional force boolean parameters.

  {
      "name": "power_off_vm",
      "description": (
          "Power off a virtual machine. Uses ACPI shutdown by default (guest-initiated)."
      ),
      "inputSchema": {
          "type": "object",
          "properties": {
              "vm_uuid": {
                  "type": "string",
                  "description": "The UUID (extId) of the virtual machine",
              },
              "force": {
                  "type": "boolean",
                  "description": "Force power off (hard shutdown) instead of ACPI guest shutdown",
                  "default": False,
              },
          },
          "required": ["vm_uuid"],
      },
  },

• src/nutanix_mcp/tools/vm.py:185-198 (handler)

  Handler function for power_off_vm. Posts to v4 API with either 'guest-shutdown' (ACPI, default) or 'power-off' (hard) action based on force parameter.

  async def handle_power_off_vm(
      client: NutanixClient, arguments: dict[str, Any]
  ) -> dict[str, Any]:
      """Power off a VM using v4 vmm API."""
      vm_uuid = arguments["vm_uuid"]
      force = arguments.get("force", False)
  
      action = "power-off" if force else "guest-shutdown"
      result = await client.v4_post(
          namespace="vmm",
          path=f"ahv/config/vms/{vm_uuid}/$actions/{action}",
          body={},
      )
      return {"status": f"{action}_initiated", "taskExtId": result.get("data", {}).get("extId")}

• src/nutanix_mcp/tools/vm.py:240-246 (registration)

  Handler dispatch table mapping 'power_off_vm' string to handle_power_off_vm function.

  VM_HANDLERS: dict[str, Any] = {
      "list_vms": handle_list_vms,
      "get_vm": handle_get_vm,
      "power_on_vm": handle_power_on_vm,
      "power_off_vm": handle_power_off_vm,
      "create_vm": handle_create_vm,
  }

• src/nutanix_mcp/server.py:35-41 (registration)

  Merged ALL_HANDLERS dict that includes VM_HANDLERS (containing power_off_vm) used by the MCP server's call_tool handler.

  ALL_HANDLERS: dict[str, Any] = {
      **VM_HANDLERS,
      **CLUSTER_HANDLERS,
      **PE_HANDLERS,
      **REPORT_HANDLERS,
      **NETWORKING_HANDLERS,
  }

• src/nutanix_mcp/client.py:134-170 (helper)

  NutanixClient.v4_post() - the low-level HTTP POST helper used by handle_power_off_vm to call the Nutanix v4 API with retry logic.

  async def v4_post(
      self,
      namespace: str,
      path: str,
      body: dict[str, Any],
      params: Optional[dict[str, str]] = None,
  ) -> dict[str, Any]:
      """POST request against v4 API."""
      client = await self._get_client()
      url = f"/{namespace}/{self.V4_VERSION}/{path}"
  
      for attempt in range(self.MAX_RETRIES + 1):
          try:
              response = await client.post(url, json=body, params=params)
          except httpx.ConnectError as e:
              raise NutanixAPIError(
                  f"Connection failed to {self.settings.host}:{self.settings.port}",
                  details=str(e),
              )
          except httpx.TimeoutException as e:
              raise NutanixAPIError(
                  f"Request timed out after {self.settings.timeout}s",
                  details=str(e),
              )
  
          if response.status_code == 429 and attempt < self.MAX_RETRIES:
              wait = self.RETRY_BACKOFF_BASE * (2 ** attempt)
              await asyncio.sleep(wait)
              continue
  
          if response.status_code >= 400:
              self._handle_error(response)
  
          return response.json()
  
      self._handle_error(response)
      return {}  # unreachable