@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_snapshot",
+  "usageNotes": "Creates a point-in-time snapshot of a QEMU VM; the operation is asynchronous and returns a UPID task string that must be polled via the tasks API to confirm completion. The VM can be running or stopped — if running, set vmstate to true to also capture RAM state (required for a fully live, restorable snapshot; omitting it saves disk space but loses in-memory state). The caller must hold VM.Snapshot permission on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Snapshot a running VM with RAM state before a risky change",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105
+      },
+      "params": {
+        "snapname": "pre-update-2026-06-29",
+        "description": "Pre-patch snapshot before kernel upgrade",
+        "vmstate": true
+      }
+    }
+  ],
+  "tips": [
+    "snapname must match the pve-configid format: alphanumeric plus hyphens/underscores, max 40 chars — do not use dots or spaces.",
+    "vmstate snapshots are significantly larger (VM RAM size added to snapshot) and take longer to create and restore.",
+    "Poll the returned UPID with get_nodes_node_tasks_upid_status to detect failures; the POST returns immediately even if the snapshot job is still running.",
+    "Snapshots are stored inline with the VM disk on the same storage — ensure the datastore has enough free space before snapshotting, especially with vmstate enabled.",
+    "The reserved snapshot name 'current' is used internally by Proxmox to represent the live state; do not use it as a snapname."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_snapshot",
+    "post_nodes_node_qemu_vmid_snapshot_snapname_rollback",
+    "delete_nodes_node_qemu_vmid_snapshot_snapname",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_snapshot_snapname_rollback",
+  "usageNotes": "Rolls back a QEMU VM's disk and configuration state to the named snapshot; the VM must be powered off before rolling back (unless the snapshot includes RAM state, in which case it restores live memory as well). Returns a UPID task string — poll the task API to confirm completion before acting on the VM. All changes made to the VM after the snapshot was taken are permanently discarded.",
+  "examples": [
+    {
+      "summary": "Roll back VM 105 to a pre-patch snapshot and start it automatically afterward",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105,
+        "snapname": "pre_patch_2026_06"
+      },
+      "params": {
+        "start": true
+      }
+    }
+  ],
+  "destructiveReason": "All disk writes and configuration changes made after the snapshot was taken are permanently lost upon rollback.",
+  "tips": [
+    "Shut the VM down before rolling back a disk-only snapshot; Proxmox will refuse or produce inconsistent state if the VM is running without RAM included in the snapshot.",
+    "If the snapshot includes RAM state, the VM resumes in memory as it was at snapshot time — set start=false to prevent an automatic resume if you need to inspect config first.",
+    "The returned UPID can be polled via GET /nodes/{node}/tasks/{upid}/status to detect failure before assuming the rollback succeeded.",
+    "Requires either VM.Snapshot or VM.Snapshot.Rollback privilege on /vms/{vmid} — prefer the narrower VM.Snapshot.Rollback role for accounts that should only roll back, not create snapshots."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_snapshot",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "delete_nodes_node_qemu_vmid_snapshot_snapname",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_spiceproxy",
+  "usageNotes": "Use this to obtain a SPICE connection ticket for a running QEMU VM; the returned object (host, password, tls-port, type, proxy) is passed directly to a SPICE client such as `remote-viewer`. The VM must be in a running state on the target node, and the caller needs `VM.Console` on `/vms/{vmid}`. Optionally pass the `proxy` field to override which cluster node the SPICE client should tunnel through — defaulting to the VM's current host is usually correct for direct access, but specifying the API node address improves reliability behind NAT.",
+  "examples": [
+    {
+      "summary": "Get SPICE config for VM 105 on node pve1, using the API node as the proxy",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {
+        "proxy": "192.168.1.10"
+      }
+    }
+  ],
+  "tips": [
+    "The returned `password` is a one-time ticket valid for a short window — launch the SPICE client immediately after receiving it.",
+    "Pass the entire response object to `remote-viewer` via a .vv file or stdin; all required fields (host, tls-port, type, proxy, password) are included in the response.",
+    "Every Proxmox node runs `spiceproxy`, so any node in the cluster can serve as the proxy — pick the one closest to your client or the one you're already using for API calls.",
+    "SPICE requires the VM to have a SPICE display device configured (type: spice in the display options); VMs using VNC will not respond here.",
+    "API tokens are supported (`allowtoken: true`), so this call can be made from automation without a full user session."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_vncproxy",
+    "post_nodes_node_qemu_vmid_termproxy"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_status_reboot",
+  "usageNotes": "Use this to perform a clean reboot of a running QEMU VM — it shuts the guest down gracefully then starts it again, which also applies any pending configuration changes (e.g. CPU/memory adjustments that require a restart). The call is asynchronous and returns a UPID string; poll the task status endpoint to confirm completion. The VM must be in a running state and the caller needs VM.PowerMgmt on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Reboot VM 101 on node pve1 with a 60-second shutdown timeout",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "timeout": 60
+      }
+    }
+  ],
+  "destructiveReason": "The VM's running services are interrupted during the shutdown-and-start cycle, causing a brief outage for any workloads hosted on the guest.",
+  "tips": [
+    "Omitting 'timeout' lets Proxmox use its default shutdown wait; set an explicit value if the guest is known to be slow to shut down.",
+    "This endpoint applies pending hardware changes (CPU sockets, RAM, etc.) that a simple reset would not — prefer it over a stop+start sequence for config rollouts.",
+    "The returned UPID can be passed to GET /nodes/{node}/tasks/{upid}/status to watch progress.",
+    "If the guest OS ignores ACPI shutdown signals (e.g. no guest agent, misconfigured), the shutdown may hang until the timeout expires and Proxmox force-stops the VM."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_status_shutdown",
+    "post_nodes_node_qemu_vmid_status_start",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_status_reset",
+  "usageNotes": "Sends a hard reset signal to a running QEMU VM — equivalent to pressing the physical reset button — bypassing a clean shutdown and risking filesystem corruption or data loss on the guest. Use only when the VM is unresponsive and a graceful reboot via the guest OS or QEMU agent is not possible. Returns a task UPID string; poll the node task log to confirm completion.",
+  "examples": [
+    {
+      "summary": "Force-reset a frozen VM (VMID 105) on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Issues an immediate hard reset to the VM without flushing guest disk buffers, which can corrupt filesystems or lose in-flight writes on the guest.",
+  "tips": [
+    "Prefer sending a reboot command via the QEMU guest agent (post_nodes_node_qemu_vmid_agent) before resorting to a hard reset.",
+    "The skiplock parameter is root-only; do not pass it from API tokens unless running as root.",
+    "The returned UPID can be queried with get_nodes_node_tasks_upid_status to confirm the reset completed."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_status_reboot",
+    "post_nodes_node_qemu_vmid_status_shutdown",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "post_nodes_node_qemu_vmid_agent",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_status_resume",
+  "usageNotes": "Resumes a suspended (paused) QEMU VM on the specified node; the VM must already be in a paused state — calling this on a running or stopped VM has no effect. Requires VM.PowerMgmt on the VM's ACL path and returns a task UPID string representing the async resume job. The node must be online and the VM must reside on that node; resuming a VM that holds a cluster-level lock will fail unless skiplock is set (root only).",
+  "examples": [
+    {
+      "summary": "Resume a paused VM (VMID 105) on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned UPID can be polled via GET /nodes/{node}/tasks/{upid}/status to confirm the VM has fully resumed.",
+    "If the VM was suspended to disk (hibernate) rather than paused in memory, use the start endpoint instead — this endpoint only handles in-memory (SIGCONT) pauses.",
+    "nocheck bypasses some internal state validation and is intended for recovery scenarios; prefer omitting it under normal operations.",
+    "skiplock is a root-only escape hatch; use it only when a stuck lock is preventing a legitimate resume after confirming no conflicting operation is actually running."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_status_suspend",
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_status_start",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_status_shutdown",
+  "usageNotes": "Sends an ACPI power-button signal to the VM's guest OS, triggering a graceful shutdown — prefer this over stop/reset when the guest supports ACPI. Returns a task UPID string; poll the task API to confirm completion. If the guest OS is unresponsive or has no ACPI support, the shutdown will hang until timeout; use forceStop=true to guarantee termination or fall back to post_nodes_node_qemu_vmid_status_stop.",
+  "examples": [
+    {
+      "summary": "Gracefully shut down VM 105 on node pve1, forcing stop after 60 seconds if the guest does not respond",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {
+        "timeout": 60,
+        "forceStop": true
+      }
+    }
+  ],
+  "destructiveReason": "Shuts down the running VM, interrupting all guest workloads and making the VM unavailable until it is started again.",
+  "tips": [
+    "The returned string is a UPID (Proxmox Unique Process ID); use get_nodes_node_tasks_upid_status to poll until status is 'stopped'.",
+    "forceStop=true is equivalent to a hard power-off if the guest does not shut down within the timeout window — use it when you need a guaranteed stop.",
+    "keepActive=true leaves storage volumes attached after shutdown, which is useful before live migrations or volume inspection but leaves resources locked.",
+    "skiplock is root-only; avoid unless recovering from a stuck migration or backup lock.",
+    "ACPI shutdown depends on the guest having ACPI drivers (all modern Linux/Windows do) and the qemu-guest-agent is NOT required for this operation."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_status_start",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "post_nodes_node_qemu_vmid_status_reboot",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_status_start",
+  "usageNotes": "Boots a stopped or suspended QEMU VM on the specified node; requires VM.PowerMgmt on /vms/{vmid}. Returns a task UPID string — poll the task status endpoint to confirm the VM reached the running state before taking dependent actions. The target node must be online and the VM must not be locked (use skiplock only as root in emergencies).",
+  "examples": [
+    {
+      "summary": "Start VM 105 on node pve1 with default settings",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned UPID can be passed to GET /nodes/{node}/tasks/{upid}/status to poll for completion before assuming the VM is fully booted.",
+    "Default timeout scales with VM memory (max(30, GiB of RAM)) — for large-memory VMs, callers should not treat a slow response as a failure without checking the task status.",
+    "migratedfrom, migration_network, migration_type, nets-host-mtu, and with-conntrack-state are internal migration parameters set by the cluster during live migration; do not supply them for normal boots.",
+    "skiplock bypasses advisory locks but is restricted to root — prefer resolving the lock via its source operation rather than forcing it.",
+    "If the VM was previously suspended to disk (state saved), it will restore from the saved state rather than performing a cold boot."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_status_stop",
+    "post_nodes_node_qemu_vmid_status_shutdown",
+    "post_nodes_node_qemu_vmid_status_reset",
+    "post_nodes_node_qemu_vmid_status_suspend",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_status_stop",
+  "usageNotes": "Issues an immediate hard stop of a QEMU VM by terminating the qemu process — equivalent to a power cut; use only when the guest OS is unresponsive or a graceful shutdown (post_nodes_node_qemu_vmid_status_shutdown) has failed. The call is asynchronous and returns a task UPID; poll the task endpoint to confirm completion. Requires VM.PowerMgmt on /vms/{vmid}; the node must be online and reachable.",
+  "examples": [
+    {
+      "summary": "Force-stop a hung VM (ID 105) on node pve1, overriding any in-progress shutdown task",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {
+        "overrule-shutdown": true,
+        "timeout": 30
+      }
+    }
+  ],
+  "destructiveReason": "Terminates the QEMU process without flushing disk write buffers or notifying the guest OS, which can corrupt in-flight I/O and leave the VM's filesystem in an inconsistent state.",
+  "tips": [
+    "Prefer post_nodes_node_qemu_vmid_status_shutdown for any VM whose guest OS is still responsive — it triggers a clean ACPI shutdown.",
+    "Set overrule-shutdown: true when a previous qmshutdown task is stuck; otherwise the stop may be blocked waiting for it to finish.",
+    "keepActive: true prevents Proxmox from deactivating storage volumes after the stop — useful during live migration teardown or when another process needs the volumes to remain mounted.",
+    "skiplock is root-only and should be treated as a last resort; holding locks usually signals another operation is in progress.",
+    "The returned UPID can be polled via GET /nodes/{node}/tasks/{upid}/status to confirm the stop completed before starting dependent operations."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_status_shutdown",
+    "post_nodes_node_qemu_vmid_status_reset",
+    "post_nodes_node_qemu_vmid_status_start",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_status_suspend",
+  "usageNotes": "Suspends a running QEMU VM, either to RAM (default, VM remains in memory and resumes instantly) or to disk via todisk=true (state written to storage, VM fully powers off and resumes on next start). Returns an async task UPID — poll the task status endpoint to confirm completion before assuming the VM is suspended. Suspending to disk requires additional privileges (VM.Config.Disk on the VM and Datastore.AllocateSpace on the target storage); if statestorage is omitted, Proxmox selects the default storage, which must support VM state snapshots.",
+  "examples": [
+    {
+      "summary": "Suspend VM 105 to disk on node pve1, storing state on local-lvm",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {
+        "todisk": true,
+        "statestorage": "local-lvm"
+      }
+    }
+  ],
+  "destructiveReason": "Suspending to RAM pauses all VM CPU/IO activity (service interruption); suspending to disk fully powers down the VM, making its services unavailable until it is manually started again.",
+  "tips": [
+    "RAM suspend (todisk omitted or false) keeps VM memory allocated on the node — do not migrate or stop the node while VMs are in RAM-suspend state or their state will be lost.",
+    "Use todisk=true for long-term hibernation or maintenance windows where the node itself may be rebooted.",
+    "The returned UPID string can be passed to GET /nodes/{node}/tasks/{upid}/status to monitor suspend progress.",
+    "skiplock is root-only; avoid using it unless a stuck lock is confirmed — forcibly skipping a lock on an actively-used VM risks data corruption."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_status_resume",
+    "post_nodes_node_qemu_vmid_status_start",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_template",
+  "usageNotes": "Converts an existing QEMU VM into a template, marking all its disks as base images so linked clones can be created from it. The VM must be stopped before calling this endpoint — converting a running VM is not allowed. Returns a task UPID; poll the task status to confirm completion before attempting to clone from the template.",
+  "examples": [
+    {
+      "summary": "Convert VM 200 to a full template on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The VM must be powered off before conversion; the API will reject the request if it is running.",
+    "Once converted to a template, the VM can no longer be started directly — only cloned.",
+    "Omit the 'disk' body parameter to convert all disks to base images in one call; specify a single disk slot (e.g. 'scsi0') only when you need a partial conversion.",
+    "Linked clones (fast, thin-provisioned) require the source disk to be a base image, which this operation produces.",
+    "The operation is irreversible via the API — you cannot demote a template back to a regular VM without manual intervention in the Proxmox UI or config files."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_clone",
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_termproxy",
+  "usageNotes": "Use this to open a terminal proxy session to a running QEMU VM from the web UI or a terminal client; the caller must hold VM.Console on the target VM. Returns a ticket, port, and UPID — pass the ticket to the noVNC/xterm.js WebSocket handshake to authenticate the session. If the VM has a configured serial device and you need a serial console rather than the QEMU display, supply the 'serial' parameter (e.g. 'serial0').",
+  "examples": [
+    {
+      "summary": "Open a standard terminal proxy session to VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'ticket' is short-lived; use it immediately to establish the WebSocket connection.",
+    "Omit 'serial' to connect to the QEMU display console (default); specify 'serial0'–'serial3' only when the VM uses a serial-based console (e.g. headless Linux with console=ttyS0).",
+    "The 'upid' in the response can be polled via GET /nodes/{node}/tasks/{upid}/status if you need to confirm the proxy process started successfully.",
+    "This endpoint requires the VM to be running; calling it against a stopped VM will return an error."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_vncproxy",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_qemu_vmid_vncproxy",
+  "usageNotes": "Use this to open a VNC console session to a running QEMU VM — the response returns a one-time ticket, port, and TLS cert that a VNC client (or the Proxmox noVNC web client) uses to connect. The caller must hold the VM.Console privilege on the VM. The VM must be in a running state on the specified node; calling this against a stopped or migrating VM will fail.",
+  "examples": [
+    {
+      "summary": "Open a VNC proxy session for VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "websocket": true
+      }
+    }
+  ],
+  "tips": [
+    "The returned ticket is short-lived — use it immediately to establish the VNC connection before it expires.",
+    "Set websocket: true when your client will upgrade to WebSocket transport; this is required for the serial-terminal path but harmless for standard VGA console access.",
+    "The generate-password param is deprecated and ignored; do not pass it in new code.",
+    "Use the returned cert fingerprint to validate the TLS connection and avoid MITM on the VNC channel.",
+    "If you need the SPICE protocol instead of VNC, use the sibling spiceproxy endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_spiceproxy",
+    "post_nodes_node_qemu_vmid_termproxy"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_replication_id_schedule_now",
+  "usageNotes": "Use this to immediately trigger a replication job rather than waiting for its next scheduled run — useful after a config change, manual failover prep, or to verify replication is healthy on demand. The node specified must be the source node for the job, and the caller needs VM.Replicate on the guest's /vms/<vmid> path. Returns a task UPID string; poll the node's task log to confirm completion.",
+  "examples": [
+    {
+      "summary": "Force-run replication job 100-0 immediately on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "id": "100-0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The id format is '<VMID>-<JOBNUM>' (e.g. '100-0'); VMID must be 3–9 digits starting with 1–9.",
+    "The returned UPID can be passed to GET /nodes/{node}/tasks/{upid}/status to track replication progress.",
+    "If the job is already running, Proxmox will reject the request — check task status before calling.",
+    "Replication must be enabled and the target storage reachable; a paused or error-state job will still attempt to run when scheduled this way."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_replication",
+    "get_nodes_node_replication_id",
+    "get_nodes_node_replication_id_log",
+    "get_nodes_node_replication_id_status",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_services_service_reload",
+  "usageNotes": "Use this to apply configuration changes to a running service without a full stop/start cycle; Proxmox will automatically fall back to a restart if the service does not support live reload. Requires the `Sys.Modify` privilege on `/nodes/{node}`, so API tokens must carry that permission. The return value is a task UPID — poll the task log to confirm completion.",
+  "examples": [
+    {
+      "summary": "Reload the Proxmox proxy (pveproxy) on node pve01 to pick up a certificate change",
+      "path_params": {
+        "node": "pve01",
+        "service": "pveproxy"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "For services that do not natively support SIGHUP-based reload (e.g. corosync), Proxmox will silently fall back to a full restart — treat reload as a best-effort graceful operation.",
+    "pveproxy reload is the recommended way to activate a newly installed TLS certificate without dropping active API sessions unnecessarily.",
+    "Reloading pvedaemon or pve-cluster during active migrations or HA operations may cause brief task interruptions; prefer a maintenance window.",
+    "The returned UPID can be tracked with GET /nodes/{node}/tasks/{upid}/status."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_services_service_restart",
+    "post_nodes_node_services_service_start",
+    "post_nodes_node_services_service_stop",
+    "get_nodes_node_services_service_state",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_services_service_restart",
+  "usageNotes": "Performs a hard stop-then-start of the specified Proxmox system service on the target node; prefer the reload endpoint when the service supports it to minimize downtime. The caller must hold Sys.Modify on /nodes/{node}. Restarting critical cluster services such as pve-cluster, corosync, or pvedaemon will briefly interrupt cluster communication and API availability — use with care in production.",
+  "examples": [
+    {
+      "summary": "Restart the PVE proxy (web UI / API listener) on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "service": "pveproxy"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Use the reload endpoint instead of restart for pveproxy and pvedaemon when you only need to apply a config change — reload avoids a full service stop.",
+    "Restarting corosync or pve-cluster can trigger quorum re-evaluation; ensure a majority of cluster nodes are online before doing so.",
+    "Restarting sshd will drop active SSH sessions to the node, including the one issuing the call if run interactively.",
+    "The returns type is a UPID string — poll the node tasks endpoint to confirm the restart completed successfully."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_services_service_reload",
+    "post_nodes_node_services_service_start",
+    "post_nodes_node_services_service_stop",
+    "get_nodes_node_services_service_state",
+    "get_nodes_node_services"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_services_service_start",
+  "usageNotes": "Use this to start a stopped or failed system service on a specific PVE node; the target node must be online and reachable by the cluster. Requires Sys.Modify on /nodes/{node}. Returns a task UPID string — poll the task endpoint to confirm the service reached the running state.",
+  "examples": [
+    {
+      "summary": "Start the pveproxy service on node pve1 (e.g. after manual stop or crash)",
+      "path_params": {
+        "node": "pve1",
+        "service": "pveproxy"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The return value is a UPID task string; use get_nodes_node_tasks_upid_status to poll completion.",
+    "Starting corosync or pve-cluster on a node that is already joined may cause quorum disruption — verify cluster health first.",
+    "If pvedaemon or pveproxy is the target, be aware that in-flight API connections may drop briefly during the restart window.",
+    "sshd is included in the enum; starting it via the API requires an already-working API connection — useful for re-enabling SSH after an accidental stop.",
+    "Not all services support start if their dependencies are missing (e.g. corosync requires a valid cluster.conf)."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_services_service_stop",
+    "post_nodes_node_services_service_restart",
+    "get_nodes_node_services_service_state",
+    "get_nodes_node_services",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_services_service_stop",
+  "usageNotes": "Stops a named system service on a specific cluster node; requires `Sys.Modify` on `/nodes/{node}`. Stopping critical services like `pvedaemon`, `pve-cluster`, `corosync`, or `sshd` will disrupt cluster communication, API access, or remote connectivity on that node — only use when the node can be recovered via console. The return value is a UPID string for the resulting task, which can be polled with the task status endpoint.",
+  "examples": [
+    {
+      "summary": "Stop the PVE firewall service on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "service": "pve-firewall"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Immediately stops the target system service on the node, which can interrupt active connections, cluster coordination, or VM/container operations depending on which service is stopped.",
+  "tips": [
+    "Stopping `corosync` or `pve-cluster` on a multi-node cluster will cause quorum loss or split-brain — coordinate with other nodes first.",
+    "Stopping `sshd` or `pveproxy` will cut off remote shell and web UI access; ensure console (IPMI/KVM) access is available before doing so.",
+    "Use the sibling `restart` endpoint instead of stop+start when you only need to reload a service config change.",
+    "The returned UPID can be tracked via GET /nodes/{node}/tasks/{upid}/status to confirm the service has fully stopped."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_services_service_start",
+    "post_nodes_node_services_service_restart",
+    "post_nodes_node_services_service_reload",
+    "get_nodes_node_services_service_state",
+    "get_nodes_node_services"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_spiceshell",
+  "usageNotes": "Creates a SPICE shell session on a specific node, returning connection parameters (host, tls-port, password, proxy, type) that can be passed directly to the 'remote-viewer' application for an interactive terminal. Requires the 'Sys.Console' privilege on '/nodes/{node}'; commands other than 'login' (e.g., 'upgrade', 'ceph_install') additionally require 'root@pam' authentication. Specify the 'proxy' parameter as the hostname used to reach the API so SPICE traffic is routed through a reachable node.",
+  "examples": [
+    {
+      "summary": "Open a SPICE login shell on node pve1, routing through the same node as SPICE proxy",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "cmd": "login",
+        "proxy": "pve1.example.com"
+      }
+    }
+  ],
+  "tips": [
+    "Pass the returned object directly to 'remote-viewer' (e.g., via a .vv connection file) — the password is single-use and short-lived.",
+    "The 'proxy' field defaults to the node running the request; set it explicitly to whatever hostname your client can actually reach to avoid SPICE connection failures in multi-node clusters.",
+    "The 'cmd-opts' field accepts null-terminated strings for passing extra arguments to built-in commands like 'upgrade' or 'ceph_install'.",
+    "SPICE requires the 'spiceproxy' service to be running on the target node (enabled by default on PVE nodes)."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_termproxy",
+    "get_nodes_node_vncshell",
+    "post_nodes_node_vncshell"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_startall",
+  "usageNotes": "Triggers a bulk start of all VMs and containers on the specified node; by default only guests with onboot=1 are started unless force=true is passed. The operation is asynchronous — the return value is a task UPID that must be polled via GET /nodes/{node}/tasks/{upid}/status to confirm completion. Requires VM.PowerMgmt on / or on each individual /vms/<ID> if the vms parameter is used.",
+  "examples": [
+    {
+      "summary": "Start all onboot-enabled VMs on pve1, limiting to 4 concurrent start tasks",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "max-workers": 4
+      }
+    }
+  ],
+  "tips": [
+    "Omit 'vms' to target all eligible guests on the node; supply a comma-separated VMID list (e.g. '100,101,105') to limit scope.",
+    "Set force=true during post-maintenance boot when some guests intentionally have onboot=0 but still need to come up.",
+    "max-workers defaults to the datacenter.cfg setting or CPU threads capped at 8; lower it on resource-constrained nodes to avoid boot storms.",
+    "Poll the returned UPID against GET /nodes/{node}/tasks/{upid}/status to detect failures for individual guests — the bulk task succeeds even if some guests fail to start."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_stopall",
+    "post_nodes_node_migrateall",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_status",
+  "usageNotes": "Use to reboot or gracefully shut down a Proxmox VE node. The caller must hold Sys.PowerMgmt on /nodes/{node}; API tokens work if that privilege is granted. The call returns null synchronously — the node begins the command immediately, so any running VMs or containers should be stopped or migrated first to avoid data loss.",
+  "examples": [
+    {
+      "summary": "Reboot a node after a kernel update",
+      "path_params": {
+        "node": "pve-hetzner-01"
+      },
+      "params": {
+        "command": "reboot"
+      }
+    }
+  ],
+  "tips": [
+    "Shut down or live-migrate all VMs and containers before issuing 'shutdown' to prevent ungraceful guest termination.",
+    "Use GET /nodes/{node}/status first to confirm the node is online and not already in a degraded state.",
+    "In a cluster, ensure quorum will be maintained after the node goes offline — avoid rebooting more than (N-1)/2 nodes simultaneously.",
+    "There is no UPID returned; poll GET /nodes/{node}/status or watch cluster logs to confirm the node comes back online after a reboot."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status",
+    "post_nodes_node_migrateall",
+    "get_nodes_node_tasks"
+  ]
+}