@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_storage_storage_identity",
+  "usageNotes": "Use this to confirm which storage plugin type backs a named storage and retrieve its internal identifier, which is plugin-dependent (e.g., a pool name for ZFS/LVM, a share path for NFS/CIFS). Requires either Datastore.Audit or Datastore.AllocateSpace on the /storage/{storage} ACL path. The target node must be online and have the storage mounted/accessible.",
+  "examples": [
+    {
+      "summary": "Get identity info for an NFS storage on pve1",
+      "path_params": {
+        "node": "pve1",
+        "storage": "nfs-backup"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'id' field format varies by plugin: ZFS returns the pool/dataset name, LVM returns the VG name, PBS returns the datastore name, NFS/CIFS return the share path.",
+    "Use this endpoint to validate that a storage ID maps to the expected backend before automating provisioning or backup jobs against it.",
+    "If the storage is not available on the specified node, the API will return an error even if it is defined cluster-wide — check node-specific storage availability first."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage",
+    "get_nodes_node_storage_storage_status",
+    "get_storage"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_storage_storage_import_metadata",
+  "usageNotes": "Call this before importing a foreign guest (e.g., an ESXi VM exported as OVA/OVF) to retrieve the recommended create-args, disk map, and network interface map that should be passed to the VM/CT create endpoint. The volume must already be present on the target storage and readable by the caller; check the returned 'warnings' array before proceeding, as issues like 'guest-is-running' or 'ova-needs-extracting' require remediation before the import will succeed cleanly. Currently only ESXi-sourced volumes ('source': 'esxi') producing VM guests ('type': 'vm') are recognised.",
+  "examples": [
+    {
+      "summary": "Fetch import metadata for an ESXi OVA uploaded to local storage on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "storage": "local"
+      },
+      "params": {
+        "volume": "local:import/my-esxi-vm.ova"
+      }
+    }
+  ],
+  "tips": [
+    "Pass the returned 'create-args' object directly as parameters to the VM create endpoint (POST /nodes/{node}/qemu) to pre-populate CPU, memory, and firmware settings derived from the source guest.",
+    "The 'disks' map uses keys like 'scsi0' or 'ide0' and values in 'storeid:path' format — iterate this map to attach each disk when calling the create endpoint.",
+    "Review every entry in 'warnings' before importing; 'ova-needs-extracting' means you must unpack the OVA first, and 'efi-state-lost' means EFI NVRAM variables will not carry over.",
+    "The endpoint is read-only and safe to call multiple times — it does not alter the volume or trigger any background task."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu",
+    "get_nodes_node_storage_storage_content",
+    "post_nodes_node_storage_storage_upload"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_storage_storage_prunebackups",
+  "usageNotes": "Use this endpoint to preview which backups would be kept or removed if a prune operation were run against a storage target — without actually deleting anything. Supply the same retention policy (via `prune-backups`) that you plan to pass to the actual DELETE prune call to ensure the preview matches the real outcome. Note that the result is a snapshot in time; backups added or removed between this preview and the subsequent prune call may produce different results.",
+  "examples": [
+    {
+      "summary": "Preview prune results for VM 101 on local backup storage, keeping the last 3 backups and 1 per week",
+      "path_params": {
+        "node": "pve01",
+        "storage": "backups"
+      },
+      "params": {
+        "vmid": 101,
+        "type": "qemu",
+        "prune-backups": "keep-last=3,keep-weekly=1"
+      }
+    }
+  ],
+  "tips": [
+    "Backups marked 'protected' or with non-standard naming are never removed — they will appear in the response with mark='protected' or mark='renamed' regardless of the retention policy.",
+    "If you omit `prune-backups`, the preview uses the retention policy already configured on the storage itself, which is the most common use case when validating existing policy.",
+    "Filter by `type` (qemu or lxc) to scope the preview to one guest type when a storage holds mixed backup sets.",
+    "The caller needs either Datastore.Audit or Datastore.AllocateSpace on /storage/{storage} — API tokens are supported."
+  ],
+  "relatedOperations": [
+    "delete_nodes_node_storage_storage_prunebackups",
+    "get_nodes_node_storage_storage_content",
+    "get_storage"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_storage_storage_rrd",
+  "usageNotes": "Use this to retrieve historical storage performance graphs (returned as a PNG file path) for a specific storage pool on a node. Requires either Datastore.Audit or Datastore.AllocateSpace on the /storage/{storage} path. The response contains a filename pointing to the generated PNG — not the image bytes directly — so the caller must fetch that file separately if the image is needed.",
+  "examples": [
+    {
+      "summary": "Fetch a daily average disk usage graph for the local-zfs storage on pve1",
+      "path_params": {
+        "node": "pve1",
+        "storage": "local-zfs"
+      },
+      "params": {
+        "ds": "used",
+        "timeframe": "day",
+        "cf": "AVERAGE"
+      }
+    }
+  ],
+  "tips": [
+    "Common datasources for storage RRD include 'used' and 'total' — check the storage's rrddata endpoint to discover what datasources are available for a given pool.",
+    "Use cf=MAX instead of AVERAGE to surface peak usage spikes that averages would mask.",
+    "The returned filename is a server-side path to the PNG; it is not returned as base64 or a URL — use a subsequent file fetch if you need the image bytes.",
+    "This endpoint is read-only and safe to poll frequently for dashboarding; it does not modify any state."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_rrddata",
+    "get_nodes_node_storage_storage_status"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_storage_storage_rrddata",
+  "usageNotes": "Use this to retrieve historical RRD time-series statistics (disk usage, I/O throughput, etc.) for a specific storage pool on a given node. The node must be online and the caller needs either Datastore.Audit or Datastore.AllocateSpace on the storage path. The returned array of objects has no guaranteed fixed schema — field availability depends on the storage type and what Proxmox has been collecting.",
+  "examples": [
+    {
+      "summary": "Fetch last 24 hours of storage RRD data for local-lvm on pve1, using AVERAGE consolidation",
+      "path_params": {
+        "node": "pve1",
+        "storage": "local-lvm"
+      },
+      "params": {
+        "timeframe": "day",
+        "cf": "AVERAGE"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting 'cf' lets Proxmox choose its default; supply 'MAX' when you want to catch peak usage spikes rather than averages.",
+    "RRD data is pre-aggregated — shorter timeframes give finer resolution (hour = minute-level points), longer ones are coarser.",
+    "If the storage is currently unmounted or unavailable, the API may return an empty array or an error rather than historical data.",
+    "Use 'week' or 'month' timeframes for trend analysis; use 'hour' or 'day' for recent incident investigation."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_status",
+    "get_nodes_node_storage_storage_content",
+    "get_nodes_node_rrddata"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_storage_storage_status",
+  "usageNotes": "Use this to check whether a specific storage backend is reachable and how much capacity remains on a given node. The `active` field indicates live connectivity — a storage may be `enabled` in config but `active: false` if the node cannot currently reach it (e.g. NFS mount down, Ceph degraded). Requires `Datastore.Audit` or `Datastore.AllocateSpace` on `/storage/{storage}`.",
+  "examples": [
+    {
+      "summary": "Check status and free space of local-lvm storage on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "storage": "local-lvm"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If `active` is false but `enabled` is true, the storage is configured but currently unreachable from that node — check mounts, network, or Ceph health.",
+    "Capacity fields (`avail`, `used`, `total`) are in bytes and may be absent if the storage is inactive.",
+    "For cluster-wide capacity across all nodes, call the storage list endpoint instead; this endpoint is scoped to a single node's view."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage",
+    "get_storage",
+    "get_nodes_node_storage_storage_content"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_subscription",
+  "usageNotes": "Use this to check the Proxmox VE subscription status and key details for a specific cluster node — useful for validating license compliance, confirming a subscription is active before relying on enterprise repository access, or auditing expiration dates. The `status` field is the primary signal: `active` means the node has a valid subscription; `expired`, `invalid`, or `notfound` means enterprise features and repos may be unavailable. The `key` and `serverid` fields are only returned if the caller has sufficient privilege to view them.",
+  "examples": [
+    {
+      "summary": "Check subscription status on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `level` field encodes the subscription tier (e.g. 'c' = Community/free, 'b' = Basic, 's' = Standard, 'p' = Premium) — use it to determine what enterprise features are licensed.",
+    "A `status` of `notfound` typically means no subscription key has been applied to this node via the Proxmox web UI or `pvesubscription set` CLI.",
+    "`checktime` is a Unix timestamp of the last online validation; if it is very stale, the node may not have been able to reach the Proxmox subscription servers.",
+    "This endpoint is node-scoped — in a cluster you must query each node individually to get a full picture of subscription coverage."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_subscription",
+    "put_nodes_node_subscription",
+    "delete_nodes_node_subscription"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_syslog",
+  "usageNotes": "Use this endpoint to read the system journal/syslog of a specific cluster node for troubleshooting services, boot issues, or auditing activity. Requires the Sys.Syslog privilege on /nodes/{node}; API tokens must also have that privilege explicitly granted. Results are paginated via start/limit — omitting both returns the full log, which can be very large on busy nodes.",
+  "examples": [
+    {
+      "summary": "Fetch the last 100 syslog lines from pve01 for the pve-cluster service since June 1",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "service": "pve-cluster",
+        "since": "2026-06-01",
+        "limit": 100,
+        "start": 0
+      }
+    }
+  ],
+  "tips": [
+    "The 'since' and 'until' patterns accept date-only (YYYY-MM-DD) or datetime with optional seconds (YYYY-MM-DD HH:MM or YYYY-MM-DD HH:MM:SS).",
+    "Use 'start' + 'limit' together for pagination; 'n' in each returned object is the absolute line number and can anchor the next page's 'start' value.",
+    "The 'service' filter maps to systemd unit names (e.g. 'pve-cluster', 'pvedaemon', 'qemu-server'); omit it to see all journal entries.",
+    "Output can be extremely large on nodes with many VMs or active services — always set a reasonable 'limit' in production use."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks",
+    "get_nodes_node_journal",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "get_nodes_node_tasks",
+  "usageNotes": "Use this endpoint to list finished (archived) or currently active tasks on a specific node — useful for auditing recent operations, confirming async task completion, or troubleshooting failures. By default it returns up to 50 archived tasks; set `source` to `active` to poll running tasks, or `all` to see both. Without `Sys.Audit` on `/nodes/{node}`, the response is silently scoped to only the authenticated user's own tasks.",
+  "examples": [
+    {
+      "summary": "List the last 20 failed tasks on node pve1 in the past 24 hours",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "errors": true,
+        "limit": 20,
+        "since": 1751155200,
+        "source": "archive"
+      }
+    }
+  ],
+  "tips": [
+    "Use `typefilter` with values like `vzdump`, `qmstart`, `qmstop`, or `vzmigrate` to narrow results to a specific operation class.",
+    "The `upid` field in each result is the Proxmox Unique Process ID — pass it to `get_nodes_node_tasks_upid_status` to fetch the final exit status of a specific task.",
+    "Pagination is offset-based: use `start` + `limit` together to page through large task histories.",
+    "Active tasks (`source=active`) may not yet have an `endtime` or `status` in the response — check those fields for null before assuming completion.",
+    "The `since`/`until` params accept Unix epoch integers; compute them from wall-clock time before calling this endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log",
+    "delete_nodes_node_tasks_upid"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_tasks_upid",
+  "usageNotes": "Returns the list of available sub-resources (child endpoints) for a specific task UPID on a node — essentially an index of what you can query about that task (e.g., status, log). The UPID must belong to the specified node; cross-node lookups will fail. Accessible by all authenticated users, so no special privilege is required beyond a valid API token.",
+  "examples": [
+    {
+      "summary": "List sub-resources for a known migration task UPID",
+      "path_params": {
+        "node": "pve01",
+        "upid": "UPID:pve01:00001A2B:012C3D4E:67890ABC:qmigrate:101:root@pam:"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The UPID format is colon-delimited and encodes node, PID, start time, task type, and user — obtain it from task-list endpoints like get_nodes_node_tasks.",
+    "The child links returned (e.g., 'status', 'log') are the actionable sub-endpoints; follow them to retrieve task output or wait-poll for completion.",
+    "This endpoint is a directory listing, not the task result itself — use get_nodes_node_tasks_upid_status for the actual task state."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log",
+    "delete_nodes_node_tasks_upid"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_tasks_upid_log",
+  "usageNotes": "Use this endpoint to inspect the output of any async Proxmox task identified by its UPID — useful after operations like migrations, backups, or snapshot creation that return a UPID instead of a direct result. Non-owners of the task require 'Sys.Audit' on '/nodes/<node>'; task owners can read their own logs without that privilege. The log is paginated via 'start' and 'limit'; use 'download: true' to retrieve the full raw log file in one request, but note that 'download' cannot be combined with 'start' or 'limit'.",
+  "examples": [
+    {
+      "summary": "Read the first 100 lines of a backup task log on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "upid": "UPID:pve1:00001A2B:0A1B2C3D:67890ABC:vzdump:101:root@pam:"
+      },
+      "params": {
+        "start": 0,
+        "limit": 100
+      }
+    }
+  ],
+  "tips": [
+    "The default 'limit' is 50 lines — always pass an explicit 'limit' when you expect verbose output (e.g., migrations or backup runs) to avoid truncated results.",
+    "Use 'start' + 'limit' together to page through large logs: increment 'start' by 'limit' on each request until fewer lines than 'limit' are returned.",
+    "The 'download' flag returns the raw log file (useful for archival or offline analysis) but is mutually exclusive with 'start' and 'limit'.",
+    "UPIDs are node-scoped — always query the same node that issued the task; cross-node UPID lookups will fail.",
+    "The last log line typically contains 'TASK OK' or 'TASK ERROR', making it a quick way to confirm task success without parsing the full output."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status",
+    "delete_nodes_node_tasks_upid"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_tasks_upid_status",
+  "usageNotes": "Use this endpoint to poll the completion state of any async Proxmox operation (VM start, backup, migration, etc.) after receiving its UPID. The target node must be online and reachable; the UPID is node-scoped, so always query the node that originated the task. Non-owners need 'Sys.Audit' on '/nodes/<node>'; task owners can read their own status without that privilege.",
+  "examples": [
+    {
+      "summary": "Check the status of a VM backup task on pve1",
+      "path_params": {
+        "node": "pve1",
+        "upid": "UPID:pve1:00001A2B:0012D4E5:67A3F100:vzdump:101:root@pam:"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "When 'status' is 'stopped', check 'exitstatus' — 'OK' means success; any other value (e.g. 'ERROR') means the task failed.",
+    "Poll this endpoint on a short interval (2–5 s) after triggering long-running operations like backups, migrations, or snapshot creation rather than assuming instant completion.",
+    "The UPID encodes the originating node; querying a different node for a UPID it did not create will return a 404 or error — always use the node from the UPID string itself."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_log",
+    "get_nodes_node_tasks",
+    "delete_nodes_node_tasks_upid"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_nodes_node_time",
+  "usageNotes": "Use this to verify a node's system clock and configured timezone — useful before scheduling time-sensitive operations or diagnosing certificate/authentication failures caused by clock skew. Requires Sys.Audit on /nodes/{node}; the node must be online and reachable by the API. Returns both UTC epoch (time) and local-time epoch (localtime), so compare them to confirm the timezone offset is correct.",
+  "examples": [
+    {
+      "summary": "Read the current time and timezone from node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'time' field is UTC epoch and 'localtime' is the same instant expressed in the node's configured timezone — subtract them to derive the UTC offset in seconds.",
+    "Clock drift beyond a few seconds will cause TLS certificate validation errors and Proxmox cluster quorum issues; if time looks wrong, check NTP status with post_nodes_node_time or inspect chrony/timesyncd on the node directly.",
+    "This endpoint is read-only and safe to poll frequently for monitoring purposes."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_time"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_version",
+  "usageNotes": "Use this endpoint to confirm the exact PVE release and pve-manager package version running on a specific node — useful before applying updates, validating cluster homogeneity, or troubleshooting API compatibility. The node must be online and reachable; calling it against an offline node will return a connection error. Any authenticated user or API token is permitted ('user: all'), so no elevated privilege is required.",
+  "examples": [
+    {
+      "summary": "Fetch version info from a node named 'pve01'",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Compare the 'version' field across all cluster nodes to detect version drift after a rolling upgrade.",
+    "The 'repoid' (short git commit hash) pinpoints the exact build when reporting bugs to the Proxmox community.",
+    "This endpoint is available even when the node is in maintenance mode, making it a lightweight liveness probe."
+  ],
+  "relatedOperations": [
+    "get_version",
+    "get_nodes_node_status",
+    "get_cluster_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_vncwebsocket",
+  "usageNotes": "Use this as the second step in the node shell VNC flow: first call the node's 'vncshell' endpoint to obtain a port (5900–5999) and a short-lived vncticket, then use those values here to upgrade the HTTP connection to a WebSocket carrying VNC traffic. The vncticket expires quickly, so the WebSocket upgrade must happen promptly after the vncshell call. The caller must hold Sys.Console on /nodes/{node}.",
+  "examples": [
+    {
+      "summary": "Open VNC WebSocket to node shell using port and ticket from a prior vncshell call",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "port": 5900,
+        "vncticket": "PVEVNC:6501234A::abcdef1234567890abcdef1234567890"
+      }
+    }
+  ],
+  "tips": [
+    "This endpoint is intended to be called as an HTTP Upgrade (WebSocket handshake), not a plain REST GET — standard REST clients will not establish a useful connection.",
+    "The port value must exactly match what was returned by the preceding vncshell call; ports are single-use and bound to the ticket.",
+    "vnctickets are time-limited (typically ~2 minutes); do not cache them for later reuse.",
+    "API tokens are allowed (allowtoken: true), but the vncticket itself is the second authentication factor required by the permission check."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_vncshell",
+    "post_nodes_node_termproxy"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_vzdump_defaults",
+  "usageNotes": "Use this endpoint to inspect the node-level vzdump backup defaults before triggering or scheduling a backup job — it reveals the effective compression, mode, retention, and storage settings that will apply if not explicitly overridden. Optionally pass a storage ID to see storage-specific defaults (some fields like notes-template and protected are only returned when a storage is provided). A caller needs at least Datastore.Audit or Datastore.AllocateSpace on the target storage; Sys.Audit on the node is required to see node-scoped settings like the hook script path.",
+  "examples": [
+    {
+      "summary": "Retrieve vzdump defaults for node pve1 scoped to local-zfs storage",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "storage": "local-zfs"
+      }
+    }
+  ],
+  "tips": [
+    "If no storage is passed, the response reflects global node defaults; storage-specific fields (notes-template, protected) will be absent.",
+    "The mailto and mailnotification fields are deprecated — prefer notification-mode set to 'notification-system' with configured PVE notification targets.",
+    "Default compress is '0' (none) and default mode is 'snapshot'; confirm these match your backup policy before scheduling jobs.",
+    "prune-backups defaults to 'keep-all=1', meaning backups are never pruned unless explicitly overridden — check this if storage space is a concern."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_vzdump",
+    "get_nodes_node_vzdump_extractconfig",
+    "get_cluster_backup"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_vzdump_extractconfig",
+  "usageNotes": "Use this to retrieve the guest configuration (VM or CT) embedded inside a vzdump backup archive without restoring it — useful for inspecting what a backup contains before a restore or for auditing historical configs. The `volume` parameter must be a valid storage volume identifier accessible from the specified node (e.g., a backup stored on that node's configured backup storage). The caller needs 'VM.Backup' on the guest and 'Datastore.AllocateSpace' on the backup storage, so API tokens scoped to a single guest may be sufficient.",
+  "examples": [
+    {
+      "summary": "Extract the config from a CT backup stored on local backup storage",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "volume": "local:backup/vzdump-lxc-101-2024_06_01-03_00_01.tar.zst"
+      }
+    }
+  ],
+  "tips": [
+    "The returned string is the raw config file content (e.g., `/etc/pve/lxc/101.conf` for containers, `/etc/pve/qemu-server/101.conf` for VMs) — parse it as key=value pairs.",
+    "Volume identifiers follow the pattern `<storage>:<path>` or `<storage>:backup/<filename>`; check your storage browser or list backups via the storage API to get exact volume strings.",
+    "This is a read-only, synchronous call — it returns the config string directly with no UPID or polling needed.",
+    "Useful as a pre-restore sanity check: compare the backed-up config against the current running config before committing to a full restore."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_content",
+    "post_nodes_node_vzdump_defaults",
+    "post_nodes_node_qemu_vmid_mtunnelwebsocket"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pools",
+  "usageNotes": "Use this endpoint to list all resource pools visible to the authenticated user, or to retrieve the members (VMs, containers, and storage) of a specific pool by passing a poolid. When poolid is omitted the response contains only poolid and comment fields — member details are only returned when querying a specific pool. Results are scoped to pools where the caller holds Pool.Audit on /pool/<poolid>.",
+  "examples": [
+    {
+      "summary": "Get full member list for the 'dev-team' pool, filtered to VMs only",
+      "path_params": {},
+      "params": {
+        "poolid": "dev-team",
+        "type": "qemu"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting poolid returns a flat index (poolid + comment only); include poolid to get the members array with node, type, and vmid details.",
+    "The type filter (qemu, lxc, storage) only takes effect when poolid is also supplied — it filters the members array, not the pool list.",
+    "API tokens are supported (allowtoken: true), making this safe for read-only automation and monitoring scripts."
+  ],
+  "relatedOperations": [
+    "create_pool",
+    "get_pool",
+    "update_pool",
+    "delete_pool"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pools_poolid",
+  "usageNotes": "Use this endpoint to retrieve the members and optional comment for a flat (non-nested) resource pool. This path is deprecated — Proxmox recommends using GET /pools/?poolid={poolid} instead, particularly if your environment uses nested pools. Requires Pool.Audit permission on /pool/{poolid}; optionally filter the member list by type (qemu, lxc, or storage) to reduce response size.",
+  "examples": [
+    {
+      "summary": "Fetch all members of the 'prod-vms' pool",
+      "path_params": {
+        "poolid": "prod-vms"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This endpoint is marked deprecated; prefer GET /pools/?poolid={poolid} for future-proof usage and nested pool support.",
+    "Use the 'type' query param to limit results to only VMs (qemu), containers (lxc), or storage — useful when you only need one resource class.",
+    "The members array includes 'node' and 'id' fields that can be used directly to construct follow-up VM or storage API calls.",
+    "openvz appears in the response type enum for legacy compatibility but is not used in current Proxmox VE versions."
+  ],
+  "relatedOperations": [
+    "get_pools",
+    "post_pools",
+    "put_pools_poolid",
+    "delete_pools_poolid"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_storage",
+  "usageNotes": "Returns the cluster-wide storage configuration index — all storage definitions visible to the authenticated user based on Datastore.Audit or Datastore.AllocateSpace permissions. Use this to enumerate available storage backends before querying node-level storage status or allocating disk resources. This is a cluster-level endpoint and does not reflect per-node availability or current usage; use get_node_storage for that.",
+  "examples": [
+    {
+      "summary": "List all NFS storage backends across the cluster",
+      "path_params": {},
+      "params": {
+        "type": "nfs"
+      }
+    }
+  ],
+  "tips": [
+    "Omit the 'type' filter to get all storage definitions in one call — useful for building a full inventory of what backends are configured.",
+    "The response reflects storage configuration, not real-time availability; a storage may be listed here but offline on a specific node.",
+    "PBS (Proxmox Backup Server) storage entries returned here represent configured backup repositories, not general-purpose datastores.",
+    "Results are permission-filtered — users without Datastore.Audit or Datastore.AllocateSpace on a storage will not see it in the list."
+  ],
+  "relatedOperations": [
+    "get_node_storage",
+    "get_node_storage_content",
+    "get_storage_config"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_storage_storage",
+  "usageNotes": "Use this to retrieve the full configuration of a specific storage pool by its ID — including type, content flags, path/server details, and enabled state. The caller must hold `Datastore.Allocate` on `/storage/{storage}`, which is typically restricted to administrators. This operates on the cluster-level storage config, not a per-node view, so the result is authoritative regardless of which node you query.",
+  "examples": [
+    {
+      "summary": "Read configuration for a local ZFS storage pool",
+      "path_params": {
+        "storage": "tank-vms"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned object shape varies by storage type (e.g., `dir`, `zfspool`, `nfs`, `cifs`, `rbd`) — type-specific fields are only present for the matching backend.",
+    "To list all storage IDs available on the cluster before querying a specific one, call `get_storage` first.",
+    "This endpoint reads the cluster config (`/etc/pve/storage.cfg`), not live mount/availability status — use node-level storage queries to check if a storage is currently active on a specific node."
+  ],
+  "relatedOperations": [
+    "get_storage",
+    "put_storage_storage",
+    "delete_storage_storage",
+    "get_nodes_node_storage",
+    "get_nodes_node_storage_storage_status"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_version",
+  "usageNotes": "Use this as a lightweight connectivity and version check — it requires no privileges beyond being authenticated (permission 'user: all'), so it is safe to call at startup or in health checks. The response also includes the datacenter's default console viewer setting, which can inform how console links are presented. No node parameter is needed; this reflects the API node you are connected to.",
+  "examples": [
+    {
+      "summary": "Check PVE version on connection startup",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'version' field is the full pve-manager Debian package version (e.g. '8.2.2'), while 'release' is just the x.y point release (e.g. '8.2') — use 'version' for precise build comparisons.",
+    "repoid is the short git SHA of the pve-manager build; useful for confirming a specific patch is present or filing bug reports.",
+    "This endpoint works with API tokens (allowtoken: true) and requires no specific privilege, making it ideal for token-based health checks without granting elevated access.",
+    "The 'console' field reflects the datacenter-wide default and is optional in the response — do not assume it is always present."
+  ],
+  "relatedOperations": [
+    "get_cluster_status",
+    "get_nodes",
+    "get_nodes_node_version"
+  ]
+}