Repository navigation
Local MCP server for Hyper-V on Windows: VM inventory, lifecycle, checkpoints, PowerShell Direct, synthetic input, serial/KD debugging, and a driver lab loop — for one allowlisted set of VMs.
Alpha. The binaries are unsigned (no certificate is configured for this repository), so SmartScreen will warn on first run. Every artifact here is built by the tagged commit; nothing is hand-assembled.
What v0.3 adds
A dashboard that is a thin client of the service. The tkinter window is replaced by a WebView2 page over the same service the AI talks to through MCP, so both see one state and one event bus. No business rule lives in JavaScript: every action is a service call, and a contract test keeps the UI and the MCP tools from drifting apart. It opens no network port — the bridge is pywebview's own JS↔Python channel.
- Wave 1 — fleet and activity. VM list with level badges, live event feed from AI and human together, and a non-modal approval queue that no longer freezes the window.
- Wave 2 — workspace. Interactive console (click and type mapped 1:1 onto the thumbnail's guest coordinates, paste box for OOBE, Ctrl+Alt+Del) and checkpoints, with the baseline marked and blocked from deletion.
- Wave 3 — files. Two panes, host (confined to the configured roots) and guest: list, create folder, copy both ways, rename, delete. Upload takes
Copy-VMFileover the VMBus when the guest's Guest Service Interface is enabled and falls back to the PowerShell Direct session otherwise; the reply says which path carried it. SHA-256 is verified at the destination on both paths. - Wave 4 — lab and debugger. Package staging,
lab_plan→lab_apply, receipts compared across runs, KD attach over serial or KDNET, and crash triage that opens with!analyze -valready formatted. - Wave 5 — advanced. Multi-VM matrix, run recording, transport health, symbol resolution indicator.
Guest credentials now live in the Windows Credential Manager (DPAPI, per user) instead of environment variables, with the environment kept as the documented fallback. Secrets never reach a tool argument, a result, an event, an audit record, or the browser.
A release pipeline that runs. The Inno Setup installer, the PyInstaller bundle of four programs and the wheel are built on a tag. This is the first release they exist for.
Install
- Installer — download
HyperVConsoleMCP-Setup-0.3.0.exebelow. It installs per user and asks for no elevation. - winget — the manifests in
packaging/winget/are ready but no PR tomicrosoft/winget-pkgshas been opened, sowinget install maiconzeraxd.HyperVConsoleMCPdoes not work yet. - From source —
pip install hyperv_console_mcp-0.3.0-py3-none-any.whl.
What is not claimed
Not validated against a live VM in this release: the dashboard page inside WebView2 against a real service, the Copy-VMFile upload against a real guest, and the "open in Hyper-V Manager / VMConnect" buttons. The installer has never been run on a clean machine. The bundled build is unsigned, winget validate has not been run, and no winget PR exists. docs/PROJECT.md records the rest, including what has been exercised live on the test guest.
No driver, mapper or guest payload is bundled by this project. In the lab profile lab_run executes only a package the operator staged. It does not provide or automate loading unsigned kernel code, whether through a vulnerable driver or any other bypass of Driver Signature Enforcement.