---
gsd_state_version: 1.0
milestone: v1.1
milestone_name: Installation Ease-of-Use
current_phase: 11
status: unknown
last_updated: "2026-03-25T02:37:59.977Z"
progress:
  total_phases: 2
  completed_phases: 0
  total_plans: 2
  completed_plans: 1
---

# Project State: vmcluster-mcp

**Last updated:** 2026-03-24
**Current phase:** 11
**Milestone:** v1.1 Installation Ease-of-Use

---

## Current Position

Phase: 11 (pypi-packaging) — EXECUTING
Plan: 2 of 2

## Key Context

All `libvirt-python` calls must be dispatched through a single `ThreadPoolExecutor(max_workers=1)` in `libvirt_client.py`. The `@structured_tool_handler` catch-all decorator must wrap every tool registration. External snapshot revert requires destroy-all-nodes-first discipline. Fault registry persists to disk with atomic tmp-rename writes.

v1.1 focus: installation ease-of-use only. No changes to MCP tool behavior. Phase 11 = PyPI packaging hygiene. Phase 12 = `vmcluster-mcp setup` CLI wizard.

---

## Decisions Log

| Date | Decision | Rationale |
|------|----------|-----------|
| 2026-03-22 | Single `ThreadPoolExecutor(max_workers=1)` for all libvirt calls | Thread-unsafe C library |
| 2026-03-22 | `@structured_tool_handler` catch-all defined in Phase 1 | All tools must be wrapped from creation |
| 2026-03-22 | Destroy-all-before-revert for `snapshot_revert` | No atomic multi-domain revert in libvirt |
| 2026-03-22 | Atomic artifact registry writes (write-tmp + os.replace) | Prevents registry corruption on crash |
| 2026-03-23 | Lazy inline imports in `node_crash` | Avoids circular import at module load time |
| 2026-03-25 | Version set to 1.0.0 for PyPI-ready packaging | Package is production-ready; v1.1 is distribution, not new features |
| 2026-03-25 | main() wraps mcp.run() in __main__.py | pip-installed console script shim requires callable; module-level mcp.run() doesn't work |

---

## Accumulated Context

### Architecture Notes

- `server.py` is a pure routing/serialization layer — no domain logic
- `ToolResult[T]` wraps every tool response; `success`, `error`, `data` fields
- v1.1 adds a CLI entry point (`vmcluster-mcp setup`) — separate from the MCP stdio server path

### Blockers/Concerns

None.

---

## Project Reference

See: .planning/PROJECT.md (updated 2026-03-24)

**Core value:** Agents can provision and reset realistic multi-node VM clusters end-to-end without requiring human intervention.
**Current focus:** Phase 11 — pypi-packaging

---
*State initialized: 2026-03-22 | v1.1 roadmap set: 2026-03-24*
