list_vms

Instructions

Implementation Reference

• src/nutanix_mcp/tools/vm.py:126-157 (handler)

  The async handler function that executes the 'list_vms' tool logic. Calls client.v4_list_all with namespace='vmm' and path='ahv/config/vms', then normalizes the response into a list of VMs with name, extId, powerState, vCPU count, memory, and cluster info.

  async def handle_list_vms(
      client: NutanixClient, arguments: dict[str, Any]
  ) -> dict[str, Any]:
      """List VMs using v4 vmm API."""
      filter_expr = arguments.get("filter")
      limit = arguments.get("limit")
  
      result = await client.v4_list_all(
          namespace="vmm",
          path="ahv/config/vms",
          filter=filter_expr,
          max_results=limit,
      )
  
      # Normalize response
      vms = result.get("data", [])
      metadata = result.get("metadata", {})
      return {
          "count": len(vms),
          "truncated": metadata.get("truncated", False),
          "vms": [
              {
                  "name": vm.get("name"),
                  "extId": vm.get("extId"),
                  "powerState": vm.get("powerState"),
                  "numVcpus": vm.get("numSockets", 0) * vm.get("numCoresPerSocket", 0),
                  "memorySizeMb": vm.get("memorySizeBytes", 0) // (1024 * 1024),
                  "cluster": vm.get("cluster", {}).get("extId"),
              }
              for vm in vms
          ],
      }

• src/nutanix_mcp/tools/vm.py:9-32 (schema)

  The tool definition/schema for 'list_vms' in the VM_TOOLS list. Defines input parameters: 'filter' (optional OData string) and 'limit' (optional integer).

  VM_TOOLS: list[dict] = [
      {
          "name": "list_vms",
          "description": (
              "List virtual machines on Nutanix. Returns VM names, UUIDs, power states, "
              "and resource allocation. Supports OData filtering."
          ),
          "inputSchema": {
              "type": "object",
              "properties": {
                  "filter": {
                      "type": "string",
                      "description": (
                          "OData filter expression. Examples: "
                          "\"name eq 'my-vm'\", \"powerState eq 'ON'\""
                      ),
                  },
                  "limit": {
                      "type": "integer",
                      "description": "Maximum number of VMs to return. Omit to retrieve all (auto-paginates).",
                  },
              },
          },
      },

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

  The handler dispatch table that maps the string 'list_vms' to the handle_list_vms function.

  VM_HANDLERS: dict[str, Any] = {
      "list_vms": handle_list_vms,

• src/nutanix_mcp/server.py:64-76 (registration)

  The MCP server's call_tool handler that looks up the tool name in ALL_HANDLERS (which includes VM_HANDLERS) and dispatches to the matching handler function.

  @server.call_tool()
  async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
      """Execute a tool and return the result."""
      handler = ALL_HANDLERS.get(name)
      if not handler:
          return [TextContent(
              type="text",
              text=f"Error: Unknown tool '{name}'",
          )]
  
      try:
          result = await handler(client, arguments or {})
          return [TextContent(type="text", text=json.dumps(result, indent=2))]

• src/nutanix_mcp/tools/__init__.py:10-12 (registration)

  The get_all_tools() function that aggregates VM_TOOLS (containing the 'list_vms' tool definition) with other tool definitions for registration with the MCP server.

  def get_all_tools() -> list[dict]:
      """Return all registered tool definitions."""
      return VM_TOOLS + CLUSTER_TOOLS + PE_TOOLS + REPORT_TOOLS + NETWORKING_TOOLS