feat(kubevirt): Add basic VM management toolset

[lyarwood]

Summary

This PR introduces an initial KubeVirt toolset for the kubernetes-mcp-server, enabling AI agents to create and manage virtual machines through MCP tools.

New Tools

vm_create

Creates VirtualMachines with intelligent parameter handling:

• Workload resolution: Accepts OS names (fedora, ubuntu, rhel) or full container disk URLs
• Automatic resource selection: Resolves preferences and instance types from size/performance hints
• Flexible configuration: Supports explicit instancetype specification or automatic selection
• Autostart option: Optional parameter to create running VMs (runStrategy: Always)

Example:

{
  "name": "vm_create",
  "arguments": {
    "namespace": "my-namespace",
    "name": "my-vm",
    "workload": "fedora",
    "size": "large",
    "performance": "compute-optimized"
  }
}

vm_start

Starts halted VirtualMachines by changing runStrategy to Always.

vm_stop

Stops running VirtualMachines by changing runStrategy to Halted.

vm_troubleshoot

Provides comprehensive diagnostic guidance for broken VMs:

• Step-by-step troubleshooting instructions
• Common issues and solutions
• Checks for VirtualMachine, VirtualMachineInstance, DataVolumes, virt-launcher pods, and events

Key Features

• Single-call VM creation: No multi-stage plan/execute workflow
• Intelligent defaults: Automatic resolution of container disk images, preferences, and instance types
• Complete lifecycle management: Create → Start → Stop → Troubleshoot
• Idempotent operations: Tools can be called multiple times safely
• Non-destructive: Provides safe alternatives to delete/recreate patterns

Testing Results

Validated using the gevals (Generative AI Evaluations) framework across 5 different AI agents/models with 6 tasks each:

Version	Success Rate	Notes
Without toolset (baseline)	23.3% (7/30)	Generic Kubernetes tools only
Original toolset (vm_create + vm_troubleshoot)	93.3% (28/30)	300% improvement
Improved toolset (+ vm_start/stop)	100% (30/30)	Perfect reliability

Agent Performance (Improved Toolset)

Agent	Success Rate	Improvement from Baseline
Claude Code	100% (6/6)	+100%
Gemini	100% (6/6)	+500%
gemini-2.0-flash	100% (6/6)	+500%
gemini-2.5-pro	100% (6/6)	+200%
Granite 3.3 8B	100% (6/6)	∞ (from 0%)

Key Achievement: The toolset enables even smaller models like Granite 3.3 8B (which failed all tasks without specialized tools) to achieve perfect success rates.

Design Principles

1. Single-purpose tools: Each tool has one clear responsibility
2. Intelligent parameter handling: Flexible inputs with smart defaults
3. Abstraction of complexity: Hides KubeVirt API details from agents
4. Complete domain coverage: No gaps forcing inappropriate tool usage
5. Error recovery support: Multiple valid approaches enable graceful fallback

Implementation Details

• Location: pkg/toolsets/kubevirt/
• Structure:
  • vm/create/ - VM creation with template rendering
  • vm/start/ - Non-destructive VM startup
  • vm/stop/ - Non-destructive VM shutdown
  • vm/troubleshoot/ - Diagnostic guidance generation
• Dependencies: Uses Kubernetes dynamic client for VirtualMachine resources
• Testing: Comprehensive unit tests and integration tests via gevals

---

A set of gevals test result/report documents is available outside of this PR under pkg/toolsets/kubevirt/tests/results/ setting out how gevals has been used to first introduce and then improve the new toolset.

[Cali0707]

it would be nice if gevals included /cost and /context data allowing us to assert against it potentially.

@lyarwood +1 from my side on that being nice, the reason we haven't been able to add it there is that we use claude code in the non-interactive setup in gevals, and we haven't been able to figure out how to get that information in the non interactive setup. If you have any ideas, let me know and/or open a PR!

[codingben]

Good work Lee. Please consider creating a single VM package with tool.go that will have all VM's actions in one single place, it would help to avoid duplications and will be much better in terms of readablity and maintainability.

[codingben]

Thanks Lee.

Just an opinion: For the beginning I see too many folders and scripts to achieve a few VM's actions via MCP tooling. I'd ask the project's maintainers opinion about this, eventually this repository's codebase can be very huge.

[lyarwood]

Thanks Lee.

Just an opinion: For the beginning I see too many folders and scripts to achieve a few VM's actions via MCP tooling. I'd ask the project's maintainers opinion about this, eventually this repository's codebase can be very huge.

Assuming you are talking about the test directory, I agree it is indeed pretty large at the moment but I've already spoken to folks about improvements to the gevals framework that would help reduce that. I plan on working on introducing builtin agent support and configurable models for the openai-agent this week but until that is merged we will need to carry the extra scripts and config for now.