@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pve/enrichment/get_nodes_node_lxc_vmid_snapshot_snapname.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_snapshot_snapname",
+  "usageNotes": "Returns the list of sub-commands available under a specific LXC snapshot (typically 'config' and 'rollback'), acting as an index rather than returning snapshot data itself. Use this to confirm a named snapshot exists on the container and to discover which child operations are available before calling rollback or inspecting the snapshot config. No special privilege is required beyond basic authenticated access ('user: all').",
+  "examples": [
+    {
+      "summary": "List available sub-commands for snapshot 'before-upgrade' on CT 200",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 200,
+        "snapname": "before-upgrade"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a directory-index endpoint — it does not return snapshot metadata or timestamps; use get_nodes_node_lxc_vmid_snapshot_snapname_config for the actual snapshot configuration.",
+    "If the snapname does not exist the API returns a 500/not-found error; call get_nodes_node_lxc_vmid_snapshot first to enumerate valid snapshot names.",
+    "snapname must match the pve-configid format: alphanumeric plus hyphens/underscores, max 40 characters — spaces or special characters will be rejected."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_snapshot",
+    "get_nodes_node_lxc_vmid_snapshot_snapname_config",
+    "post_nodes_node_lxc_vmid_snapshot_snapname_rollback",
+    "delete_nodes_node_lxc_vmid_snapshot_snapname"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_lxc_vmid_snapshot_snapname_config.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_snapshot_snapname_config",
+  "usageNotes": "Retrieves the LXC container configuration that was captured at snapshot time, allowing you to inspect what CPU, memory, network, and storage settings were in effect when the snapshot was taken. Requires at least one of VM.Snapshot, VM.Snapshot.Rollback, or VM.Audit on the container's ACL path. The node hosting the container must be online and the snapshot must already exist — use the snapshot list endpoint to confirm valid snapname values before calling this.",
+  "examples": [
+    {
+      "summary": "Inspect the config captured in the 'pre-upgrade' snapshot for container 120 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 120,
+        "snapname": "pre-upgrade"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned config reflects the container state at snapshot creation, not the current running config — diff it against the live config endpoint to identify what changed since the snapshot.",
+    "snapname follows the pve-configid format: alphanumeric and hyphens only, max 40 characters; names with spaces or special characters are rejected.",
+    "This is a read-only call with no side effects and can safely be used for auditing or pre-rollback review."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_snapshot",
+    "post_nodes_node_lxc_vmid_snapshot_snapname_rollback",
+    "delete_nodes_node_lxc_vmid_snapshot_snapname",
+    "get_nodes_node_lxc_vmid_config"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_lxc_vmid_status.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_status",
+  "usageNotes": "Returns a directory index listing the available status sub-resources (e.g. 'current', 'start', 'stop', 'reboot', 'shutdown', 'suspend', 'resume') for a specific LXC container. Use this as a discovery call to enumerate which status operations are accessible before calling a specific subdir endpoint. No privileges beyond basic authentication are required.",
+  "examples": [
+    {
+      "summary": "List available status sub-resources for LXC container 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values map directly to child API paths — append them to this path to reach the actual status or control endpoints.",
+    "This endpoint is accessible to all authenticated users regardless of container ownership, making it safe to call during discovery without worrying about privilege errors.",
+    "Commonly followed by GET /nodes/{node}/lxc/{vmid}/status/current to retrieve live runtime state (CPU, memory, uptime, status)."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_status_current",
+    "post_nodes_node_lxc_vmid_status_start",
+    "post_nodes_node_lxc_vmid_status_stop",
+    "post_nodes_node_lxc_vmid_status_shutdown",
+    "post_nodes_node_lxc_vmid_status_reboot",
+    "post_nodes_node_lxc_vmid_status_suspend",
+    "post_nodes_node_lxc_vmid_status_resume"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_lxc_vmid_status_current.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_status_current",
+  "usageNotes": "Use this to poll the live runtime state of an LXC container, including CPU/memory usage, uptime, disk I/O counters, and network traffic since last start. Requires VM.Audit on /vms/{vmid} and the target node must be online; calling against a node that is down or fenced will return an error rather than cached data. Check the 'lock' field before issuing any lifecycle operations — a non-null lock (e.g. 'backup', 'migrate') means another operation is in progress and start/stop calls will be rejected.",
+  "examples": [
+    {
+      "summary": "Get current status of LXC container 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "CPU usage is returned as a fraction (e.g. 0.025 = 2.5%) — multiply by 100 to display as a percentage.",
+    "diskread/diskwrite are cumulative byte counters since the container last started, not rates; compute delta between two polls for throughput.",
+    "pressurecpu/pressureio/pressuremem fields (Linux PSI) are only present on kernels that support cgroup2 pressure stall information.",
+    "A 'template' value of true means the container is a template clone source and cannot be started directly.",
+    "The 'ha' object is always present but may be empty ({}) if the container is not managed by the HA manager."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_status_start",
+    "post_nodes_node_lxc_vmid_status_stop",
+    "post_nodes_node_lxc_vmid_status_shutdown",
+    "get_nodes_node_lxc_vmid_config",
+    "get_nodes_node_lxc"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_lxc_vmid_vncwebsocket.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_vncwebsocket",
+  "usageNotes": "This endpoint upgrades an HTTP GET request to a WebSocket connection carrying VNC traffic for an LXC container console. It must be called immediately after `post_nodes_node_lxc_vmid_vncproxy`, using the port and vncticket values returned by that call — the ticket is short-lived and single-use. The client must perform the WebSocket upgrade on the same connection; this is not a standard REST call and cannot be used with a plain HTTP client.",
+  "examples": [
+    {
+      "summary": "Open VNC WebSocket for LXC container 101 on node pve1 using ticket from a prior vncproxy call",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "port": 5900,
+        "vncticket": "PVEVNC:6543210a:AbCdEfGhIjKlMnOpQrStUvWxYz012345678901234567890123456789012345"
+      }
+    }
+  ],
+  "tips": [
+    "Always call post_nodes_node_lxc_vmid_vncproxy first — this endpoint is the second step of a two-step handshake.",
+    "The vncticket is tied to the session and expires quickly; complete the WebSocket upgrade immediately after obtaining it.",
+    "Port is always in the range 5900–5999; use the exact value returned by vncproxy, not a hardcoded default.",
+    "The caller requires VM.Console permission on /vms/{vmid}; API tokens are accepted if that privilege is granted.",
+    "noVNC and other browser-based VNC clients expect this WebSocket endpoint — pass the ticket as a query parameter, not in the Authorization header."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_vncproxy",
+    "get_nodes_node_lxc_vmid_termproxy",
+    "get_nodes_node_qemu_vmid_vncwebsocket"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_netstat.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_netstat",
+  "usageNotes": "Returns per-interface network counters (bytes in/out, packets, errors, drops) for all tap and VM network devices currently active on the node. The node must be online and reachable; results reflect kernel-level counters at the moment of the call and are not persisted. Use this for a live point-in-time traffic snapshot — for historical metrics, use the RRD-based network history endpoints instead.",
+  "examples": [
+    {
+      "summary": "Fetch live network counters for all VM/CT interfaces on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Counters are cumulative since the interface was last created or the kernel counter wrapped; subtract two readings over time to get a rate.",
+    "Only tap/veth interfaces attached to running VMs and containers appear — stopped guests produce no entries.",
+    "Counter wrap (32-bit on older kernels) can cause apparent negative deltas; handle defensively when computing rates.",
+    "For per-VM bandwidth accounting, correlate the interface name (e.g. tap101i0) back to the VMID using the guest config."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_rrddata",
+    "get_nodes_node_network",
+    "get_nodes_node_qemu_vmid_interfaces",
+    "get_nodes_node_status"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_network.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_network",
+  "usageNotes": "Use this to enumerate all network interfaces on a specific node — bridges, bonds, physical NICs, VLANs, and OVS types — useful before attaching a VM network device or diagnosing connectivity. The node must be online; the response reflects the running config parsed from /etc/network/interfaces, which may differ from a pending (not-yet-applied) config. No special privilege beyond basic cluster membership is required ('user: all').",
+  "examples": [
+    {
+      "summary": "List only Linux bridge interfaces on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "type": "bridge"
+      }
+    }
+  ],
+  "tips": [
+    "Omit the 'type' filter to get every interface in a single call; filter client-side if you need multiple types.",
+    "Check the 'active' field to distinguish interfaces that are up versus those defined but not yet applied (pending 'ifreload -a').",
+    "The 'exists' field indicates whether the interface physically exists on the OS; a false value means it is defined in config only.",
+    "Use 'any_bridge' or 'any_local_bridge' as the type filter to capture both standard Linux bridges and OVSBridges in one query."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network_iface",
+    "put_nodes_node_network_iface",
+    "post_nodes_node_network",
+    "put_nodes_node_network",
+    "delete_nodes_node_network_iface"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_network_iface.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_network_iface",
+  "usageNotes": "Use this to inspect the current configuration of a specific network interface on a Proxmox node — useful for auditing interface type (bridge, bond, VLAN, etc.) and its addressing method before making changes. Requires `Sys.Audit` on `/nodes/{node}`, so API tokens with read-only audit scope work here. Returns the persisted config from `/etc/network/interfaces`, not live runtime state, so it may differ from what `ip addr` shows if pending changes have not been applied.",
+  "examples": [
+    {
+      "summary": "Read configuration of the primary bridge interface on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "iface": "vmbr0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response reflects the on-disk network config, not live kernel state — use a system call or SSH to check runtime state if needed.",
+    "Interface name must be 2–20 characters; common names include vmbr0, bond0, eth0, ens18, vlan100.",
+    "To see all interfaces at once, use the list endpoint (GET /nodes/{node}/network) before drilling into a specific iface."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network",
+    "put_nodes_node_network_iface",
+    "delete_nodes_node_network_iface",
+    "put_nodes_node_network"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_qemu",
+  "usageNotes": "Use this to list all QEMU VMs on a specific node, including their run state, resource usage, and tags. Only VMs where the caller has VM.Audit permission on /vms/<vmid> are returned — partial lists are normal in multi-tenant clusters. Pass full=true to include live CPU/memory/disk/network stats for running VMs; omitting it returns a lighter response suitable for inventory enumeration.",
+  "examples": [
+    {
+      "summary": "List all VMs on node 'pve1' with full runtime stats",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "full": true
+      }
+    }
+  ],
+  "tips": [
+    "Results are scoped per-node; call this for each node in the cluster to build a cluster-wide VM inventory.",
+    "The 'status' field reflects the QEMU process state (stopped/running); 'qmpstatus' gives finer-grained QMP state (e.g. 'paused') for running VMs.",
+    "template=true entries are VM templates — filter these out if you only want live or startable VMs.",
+    "The 'lock' field indicates a config lock (e.g. 'migrate', 'backup', 'snapshot') — avoid config changes or migrations on locked VMs.",
+    "disk/net counters (diskread, diskwrite, netin, netout) are cumulative since guest start, not per-second rates; compute deltas between polls for throughput."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_qemu_vmid_config",
+    "get_cluster_resources"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid",
+  "usageNotes": "Returns the directory index — a list of available sub-resource names (subdirs) for a specific QEMU VM on a given node. Use this as a discovery step to determine which child endpoints (e.g., config, status, snapshot, firewall) are accessible for the VM before calling them. No privileges beyond basic authenticated access are required, but the node must be reachable and the VM must exist.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an array of objects each containing a 'subdir' string — use these values to construct child API paths like /nodes/{node}/qemu/{vmid}/{subdir}.",
+    "This endpoint is useful for programmatic discovery when the set of available subdirs may vary by PVE version or VM state.",
+    "Accessible to all authenticated users; no VM-specific privilege check is enforced on this index call itself, though child endpoints will enforce their own permissions."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_qemu_vmid_config",
+    "get_nodes_node_qemu_vmid_snapshot"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent",
+  "usageNotes": "Returns the list of QEMU Guest Agent (QGA) sub-commands available for a running VM. Use this as a discovery step before calling specific agent sub-commands (e.g., get-fsinfo, get-network-interfaces) to confirm which commands the installed QGA version supports. The VM must be running and the qemu-guest-agent service must be active inside the guest; if the agent is not running the response will be empty or the request will fail.",
+  "examples": [
+    {
+      "summary": "List available guest agent commands for VM 101 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "An empty result array means the guest agent is installed but not running, or the VM is powered off.",
+    "Child links in the response (rel: child) map directly to callable sub-endpoints under /nodes/{node}/qemu/{vmid}/agent/{name}.",
+    "Guest agent must be enabled in the VM config (agent: enabled=1) and the qemu-guest-agent package installed inside the OS."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_qemu_vmid_agent_get_fsinfo",
+    "get_nodes_node_qemu_vmid_agent_get_host_name",
+    "get_nodes_node_qemu_vmid_agent_network_get_interfaces"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_exec_status.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_exec_status",
+  "usageNotes": "Poll this endpoint after calling the exec agent action to retrieve stdout, stderr, exit code, and whether the process has finished. The PID returned by the exec call must be passed here; polling should continue until the 'exited' field is true. Requires the QEMU guest agent to be running inside the VM and the caller to hold VM.GuestAgent.Unrestricted on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Check the status of a previously executed guest command",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {
+        "pid": 4823
+      }
+    }
+  ],
+  "tips": [
+    "Output is buffered by the guest agent; very large stdout/stderr may be truncated — check 'out-truncated' and 'err-truncated' fields.",
+    "If 'exited' is false, the process is still running; repeat the poll on a short interval (e.g. 1–2 seconds) rather than assuming completion.",
+    "A non-zero 'signal' field instead of 'exitcode' indicates the process was killed by a signal or crashed abnormally.",
+    "The PID is ephemeral and scoped to the guest agent session — do not cache it across VM reboots or agent restarts."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_exec",
+    "get_nodes_node_qemu_vmid_agent"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_file_read.json

@@ -0,0 +1,32 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_file_read",
+  "usageNotes": "Reads a file from inside a running VM via the QEMU Guest Agent (qemu-guest-agent must be installed and running in the guest). The response is capped at 16 MiB; check the `truncated` field in the response — if true, use the `offset` param to page through the remainder. The caller must hold `VM.GuestAgent.FileRead` or `VM.GuestAgent.Unrestricted` on `/vms/{vmid}`.",
+  "examples": [
+    {
+      "summary": "Read /etc/hostname from a Linux VM (decoded, first 1 KB)",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {
+        "file": "/etc/hostname",
+        "count": 1024,
+        "offset": 0,
+        "decode": true
+      }
+    }
+  ],
+  "tips": [
+    "Set decode=false if you need to forward the raw base64 payload (e.g., for binary files or when the caller handles decoding itself).",
+    "Use offset + count together to paginate large files; always check `truncated: true` before assuming you have the full content.",
+    "The 16 MiB hard cap is enforced server-side regardless of the count value supplied.",
+    "Guest agent must be running — if the VM is powered off or the agent service is stopped, the call will fail with a timeout or connection error.",
+    "On Windows guests, use Windows-style paths (e.g., C:\\\\Windows\\\\System32\\\\drivers\\\\etc\\\\hosts)."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_agent_exec",
+    "get_nodes_node_qemu_vmid_agent_exec_status",
+    "post_nodes_node_qemu_vmid_agent_file_write",
+    "get_nodes_node_qemu_vmid_agent"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_fsinfo.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_fsinfo",
+  "usageNotes": "Returns filesystem mount information from inside the VM via the QEMU Guest Agent — requires the agent to be installed, running, and responsive inside the guest. Use this to inspect mount points, disk usage, and filesystem types without logging into the VM. If the agent is not running or the guest OS does not support the get-fsinfo command, the call will return an error rather than partial data.",
+  "examples": [
+    {
+      "summary": "Get filesystem info from VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The result object contains an array of filesystem entries under result.result; each entry typically includes name, mountpoint, total-bytes, used-bytes, and type.",
+    "If the VM is Windows, the QEMU Guest Agent must be the VirtIO Windows guest tools build — plain QEMU agent builds may not implement get-fsinfo.",
+    "Stale or unresponsive agent channels return a timeout error; restart the guest agent service inside the VM to recover.",
+    "Requires either VM.GuestAgent.Audit or VM.GuestAgent.Unrestricted on /vms/{vmid} — the Audit privilege is sufficient for this read-only call."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_get_osinfo",
+    "get_nodes_node_qemu_vmid_agent_get_host_name",
+    "get_nodes_node_qemu_vmid_agent_get_memory_block_info",
+    "post_nodes_node_qemu_vmid_agent"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_host_name.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_host_name",
+  "usageNotes": "Retrieves the hostname of a running QEMU VM by querying the QEMU Guest Agent (QGA) inside the guest OS. The guest agent must be installed, running, and enabled in the VM's hardware configuration — the call will fail with an error if the agent is not responsive. Use this to programmatically resolve a VM's OS-level hostname without logging into the guest.",
+  "examples": [
+    {
+      "summary": "Get the hostname of VM 101 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Requires the QEMU Guest Agent package (qemu-guest-agent) to be installed inside the guest and the 'Guest Agent' option enabled in Proxmox VM options.",
+    "The returned object has a `result` property containing the hostname string as reported by the guest OS — not the Proxmox VM name.",
+    "If the VM is stopped or the agent is unresponsive, the API returns an error; always confirm the VM is in 'running' state before calling.",
+    "Requires VM.GuestAgent.Audit OR VM.GuestAgent.Unrestricted on /vms/{vmid}; API tokens with scoped permissions must include one of these."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_get_osinfo",
+    "get_nodes_node_qemu_vmid_agent_network_get_interfaces",
+    "get_nodes_node_qemu_vmid_agent_get_time",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_memory_block_info.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_memory_block_info",
+  "usageNotes": "Retrieves memory block (DIMM/hotplug slot) information from the QEMU guest agent running inside the VM; the guest agent must be installed, running, and the VM must be in a powered-on state. The response's `result` object reflects the guest OS view of memory topology, which is useful for verifying memory hotplug operations or auditing effective RAM layout inside the guest. Requires at least the `VM.GuestAgent.Audit` permission on `/vms/{vmid}`.",
+  "examples": [
+    {
+      "summary": "Get memory block info for VM 105 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If the guest agent is not running or not installed, Proxmox will return a 500-level error rather than an empty result — ensure qemu-guest-agent is active inside the guest before calling.",
+    "The `result` object structure varies by guest OS; Linux guests typically return an array of memory block entries with online/offline state, while Windows guests may return a different schema.",
+    "Memory block info reflects the guest kernel's view, which may differ from the hypervisor's configured RAM if hotplug changes are pending a guest-side acknowledgment."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_get_memory_blocks",
+    "get_nodes_node_qemu_vmid_agent_info",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_memory_blocks.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_memory_blocks",
+  "usageNotes": "Queries the QEMU Guest Agent for the VM's current memory block configuration, including which blocks are online and their hotplug state. Requires the guest agent to be installed, running, and responsive inside the VM — the call will fail if the agent is not active. Caller must hold VM.GuestAgent.Audit or VM.GuestAgent.Unrestricted on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Retrieve memory block info from a running VM",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If the guest agent is not running, the API returns an error rather than an empty result — check agent status first with get_nodes_node_qemu_vmid_agent_info.",
+    "Memory block visibility depends on the guest OS and whether hotplug memory devices were attached; guests with no hotplug DIMMs may return an empty block list.",
+    "This is a read-only passthrough to the QEMU Guest Agent protocol command 'guest-get-memory-blocks'; no changes are made to the VM."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_info",
+    "get_nodes_node_qemu_vmid_agent_get_memory_block_info",
+    "post_nodes_node_qemu_vmid_agent_set_user_password"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_osinfo.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_osinfo",
+  "usageNotes": "Retrieves operating system information (distro, name, version, kernel, machine type) from a running VM via the QEMU Guest Agent. The Guest Agent must be installed and running inside the VM; if it is not, the call will return an error rather than an empty result. Requires either VM.GuestAgent.Audit or VM.GuestAgent.Unrestricted on the VM's path.",
+  "examples": [
+    {
+      "summary": "Get OS info from a Linux VM on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If the Guest Agent is not running, the API returns a 500-class error with a message like 'guest agent is not running'; check agent status with get_nodes_node_qemu_vmid_agent_info first.",
+    "The response is wrapped in a `result` object; actual OS fields (name, version, id, pretty-name, kernel-release, machine) are nested inside it.",
+    "Useful for automated inventory and asset classification — pair with get_nodes_node_qemu_vmid_agent_get_host_name to build a complete identity record.",
+    "VM must be in a running (started) state; suspended or stopped VMs will not have an active Guest Agent channel."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_info",
+    "get_nodes_node_qemu_vmid_agent_get_host_name",
+    "get_nodes_node_qemu_vmid_agent_get_vcpus",
+    "get_nodes_node_qemu_vmid_agent_get_memory_blocks",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_time.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_time",
+  "usageNotes": "Retrieves the current time from inside a running VM via the QEMU Guest Agent. The VM must be running and have the guest agent installed and active; the call will fail if the agent is not responding. Useful for detecting time drift between the VM and the host without logging into the guest.",
+  "examples": [
+    {
+      "summary": "Get the current guest time from VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned `result` object typically contains `localtime`, `timezone`, and `utctime` fields from the guest OS.",
+    "If the guest agent is not running, Proxmox returns a 500 error — check agent status with get_nodes_node_qemu_vmid_agent_info first.",
+    "Time drift between guest and host is common on VMs that were suspended or migrated; compare utctime against host time to detect skew.",
+    "Requires VM.GuestAgent.Audit or VM.GuestAgent.Unrestricted on /vms/{vmid} — either privilege satisfies the check."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_get_osinfo",
+    "get_nodes_node_qemu_vmid_agent_info",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_timezone.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_timezone",
+  "usageNotes": "Retrieves the timezone configured inside the guest OS via the QEMU Guest Agent. Requires the Guest Agent to be installed, running, and connected inside the VM — the call will fail if the agent is offline or the VM is not running. Useful for verifying guest timezone alignment across a fleet before scheduling maintenance windows or cron jobs.",
+  "examples": [
+    {
+      "summary": "Get the timezone of VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The QEMU Guest Agent must be installed (qemu-guest-agent package) and enabled in the VM hardware settings — check Proxmox UI under Options > QEMU Guest Agent.",
+    "The returned `result` object contains the timezone string as reported by the guest OS (e.g., 'America/Los_Angeles' on Linux, or a Windows timezone name on Windows guests).",
+    "If the guest agent is not running, the API returns a 500-level error; use get_nodes_node_qemu_vmid_agent to check agent status first."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_get_osinfo",
+    "get_nodes_node_qemu_vmid_agent_get_host_name",
+    "get_nodes_node_qemu_vmid_agent_get_time",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_users.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_users",
+  "usageNotes": "Retrieves the list of local user accounts from inside a running QEMU VM via the QEMU Guest Agent (QGA). The VM must be running and the guest agent must be installed and active; otherwise the call will fail with a timeout or agent error. Caller requires either VM.GuestAgent.Audit or VM.GuestAgent.Unrestricted on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "List local users on VM 101 hosted on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The guest agent daemon (qemu-guest-agent) must be running inside the VM; check its status with get_nodes_node_qemu_vmid_agent_info before calling.",
+    "The response wraps the raw QGA payload in a 'result' key; parse result.return to access the array of user objects (name, domain, full-name where available).",
+    "On Windows guests, domain-joined accounts appear with a domain prefix; on Linux, domain is typically empty.",
+    "If the agent is unresponsive, consider calling get_nodes_node_qemu_vmid_status_current first to confirm the VM is running."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_info",
+    "get_nodes_node_qemu_vmid_agent_get_osinfo",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

package/dist/catalog-pve/enrichment/get_nodes_node_qemu_vmid_agent_get_vcpus.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_get_vcpus",
+  "usageNotes": "Retrieves the list of vCPUs visible to the guest OS via the QEMU Guest Agent (QGA); use this to verify CPU hot-plug operations have taken effect inside the VM. The QEMU Guest Agent must be installed and running inside the guest, and the VM must be in a powered-on state, otherwise the call will fail. Requires either VM.GuestAgent.Audit or VM.GuestAgent.Unrestricted on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Get vCPU list for VM 105 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If the guest agent is not running, the API returns an error rather than an empty result — check agent status with get_nodes_node_qemu_vmid_agent_get_osinfo first.",
+    "The returned vCPU list reflects the guest OS perspective, which may differ from the host-configured vCPU count if hot-plug changes have not yet been acknowledged by the guest.",
+    "CPU online/offline state per vCPU is included in the result; useful for confirming that CPU hot-add actually brought a new vCPU online inside the guest."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_get_osinfo",
+    "get_nodes_node_qemu_vmid_agent_info",
+    "get_nodes_node_qemu_vmid_config"
+  ]
+}