hyper-v-mcp-rs

The problem

Hyper-V is driven through a PowerShell module with hundreds of cmdlets. Anything that wants to automate it, a test harness, a lab controller, an agent, ends up shelling out and parsing text. The cmdlets also need an elevated, persistent PowerShell process, which is exactly the kind of thing that hangs, dies, or leaks.

hyper-v-mcp-rs puts a Rust process in front. Every cmdlet in the module is exposed as a typed MCP tool, named hyperv_<verb>_<noun>, with input and output schemas derived from Rust structs and surfaced to the host as JSON Schema. Inventory, network topology, and host information are read-only resources.

Architecture

The binary runs on tokio with a hand-written rmcp server handler and a tool registry collected at link time. Beneath it is a PowerShell sidecar, embedded into the binary with include_str! so nothing is written to disk. On first use the sidecar checks that it is elevated, reports ready, and then runs a persistent runspace loop, executing cmdlets and returning JSON.

The Rust side supervises the sidecar. If it crashes, hangs, or exceeds the per-call timeout, it is killed and restarted, and any pending calls fail with a structured error rather than a stuck process. Transport is stdio only: JSON-RPC in from the host, JSON-RPC out to the child.

Guest control

PowerShell Direct runs commands and moves files inside a running VM over VMBus, with no network connectivity required. Credentials resolve in a fixed order: explicit username and password in the call, a VM-specific entry in a DPAPI-encrypted store, a default credential from the config file, and otherwise an error naming the tool that registers one. The default is meant for a known base image with a fixed local administrator, from which agent-created VMs derive.

Requirements

Windows with Hyper-V enabled, administrative privileges (the server exits if it is not elevated), and PowerShell 5.1 or later.

Status

Shipped. The tool surface tracks the Hyper-V module cmdlet for cmdlet.