@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_scan_zfs",
+  "usageNotes": "Use this to discover ZFS pools that already exist on a node's local disks before adding them as Proxmox storage. The node must be online and have ZFS kernel modules loaded; pools that are not imported will not appear in the results. Requires Datastore.Allocate on /storage, so API tokens used for storage provisioning workflows will have the necessary privilege.",
+  "examples": [
+    {
+      "summary": "List all ZFS pools available on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Only imported (active) ZFS pools are returned — unimported pools or pools on offline disks will not appear.",
+    "Run this before calling the storage-create endpoint to confirm the pool name exists and is spelled correctly.",
+    "If no pools are returned but you expect some, verify ZFS is loaded on the node: `zpool list` via SSH will confirm the local view."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_scan_iscsi",
+    "get_nodes_node_scan_lvm",
+    "get_nodes_node_scan_lvmthin",
+    "get_nodes_node_scan_nfs",
+    "get_storage"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_sdn",
+  "usageNotes": "Returns the list of SDN sub-resources available under a specific node (e.g., zones, vnets, interfaces). Use this as an index/discovery call before drilling into node-level SDN configuration — the returned items act as child links. Accessible to all authenticated users; no special privilege is required.",
+  "examples": [
+    {
+      "summary": "List SDN sub-resources on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an array of child link objects; follow each item's 'name' field to traverse deeper into SDN configuration (zones, vnets, etc.).",
+    "This endpoint is node-scoped — SDN policy is cluster-wide but some state is queried per-node; run against the node where you need to inspect local SDN status.",
+    "Use the cluster-level SDN endpoints (/cluster/sdn) to manage SDN configuration; this endpoint is read-only discovery only."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn",
+    "get_cluster_sdn_zones",
+    "get_cluster_sdn_vnets"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_sdn_fabrics_fabric",
+  "usageNotes": "Returns the directory index of available sub-resources (subdirectories) for a specific SDN fabric on a given node — useful for discovering what status or configuration endpoints are available under that fabric. Requires SDN.Audit permission on /sdn/fabrics/{fabric}; the fabric must already exist and the node must be online. This is a navigation endpoint, not a status endpoint — follow the returned 'subdir' links to fetch actual fabric data.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for SDN fabric 'vxlan01' on node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "fabric": "vxlan01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The fabric ID must be 2–8 alphanumeric characters with internal hyphens allowed (e.g. 'vx01', 'evpn-dc'); single-character IDs are rejected.",
+    "The response is a directory index — each object contains a 'subdir' field pointing to a child resource. Use those paths to retrieve actual fabric status or peer information.",
+    "SDN fabric support requires the Proxmox SDN plugin to be configured; if no fabrics exist, this endpoint will return 404."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_fabrics",
+    "get_cluster_sdn_fabrics",
+    "get_cluster_sdn_fabrics_fabric"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_sdn_fabrics_fabric_interfaces",
+  "usageNotes": "Use this to inspect which network interfaces on a specific node are participating in an SDN fabric and what their current link state and topology role are. The caller needs SDN.Audit permission on /sdn/fabrics/{fabric}; the target node must be online and the fabric must already exist. Results are node-local — run the same call against each cluster node to get a full fabric-wide picture.",
+  "examples": [
+    {
+      "summary": "List all interfaces on node 'pve1' that belong to the fabric 'evpn01'",
+      "path_params": {
+        "node": "pve1",
+        "fabric": "evpn01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "fabric id must be 2–8 alphanumeric characters and cannot start or end with a hyphen.",
+    "The 'type' field distinguishes Point-to-Point underlay links from Broadcast segments — useful when diagnosing OSPF/BGP neighborship issues.",
+    "An interface in 'down' state while the fabric is otherwise healthy usually indicates a physical or VLAN misconfiguration on that specific node.",
+    "This endpoint is node-scoped; iterate over all nodes in the cluster to build a complete interface-to-fabric map."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_fabrics_fabric",
+    "get_sdn_fabrics",
+    "get_nodes_node_network"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_sdn_fabrics_fabric_neighbors",
+  "usageNotes": "Use this to inspect the live BGP/EVPN neighbor table for a specific SDN fabric as seen from a given node. Results are sourced from FRR in real time, so the node must be online and FRR must be running for the call to succeed. Requires SDN.Audit permission on the fabric path; read-only, no cluster-wide quorum needed.",
+  "examples": [
+    {
+      "summary": "List all BGP neighbors for fabric 'evpn01' as seen from node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "fabric": "evpn01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Neighbor status strings (e.g. 'Established', 'Active', 'Idle') come directly from FRR's JSON output — consult FRR BGP docs for meaning.",
+    "Uptime is formatted by FRR (e.g. '8h24m12s') and resets on BGP session flap; a short uptime relative to fabric age indicates a recent peering drop.",
+    "If the fabric has no configured peers the response is an empty array, not an error.",
+    "Each node in the cluster may report a different neighbor view; poll all nodes when diagnosing asymmetric routing or split-brain."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_fabrics_fabric",
+    "get_nodes_node_sdn_fabrics",
+    "get_cluster_sdn_fabrics",
+    "get_cluster_sdn_fabrics_fabric"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_sdn_fabrics_fabric_routes",
+  "usageNotes": "Returns the live routing table for a specific SDN fabric as seen from the given node, including each route's CIDR block and its nexthop list. Requires the SDN.Audit privilege on the fabric path; the target node must be online and the SDN fabric must already exist. Use this to verify route propagation and nexthop reachability after fabric or peer configuration changes.",
+  "examples": [
+    {
+      "summary": "List all routes for fabric 'evpn01' as seen from node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "fabric": "evpn01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'via' array may contain multiple nexthops if ECMP is in use; an empty array typically means the route is locally originated.",
+    "Run this on different nodes to detect asymmetric or missing route propagation across the fabric.",
+    "Fabric IDs are 2–8 alphanumeric characters with optional interior hyphens; check your fabric name against the pattern before calling."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_fabrics_fabric",
+    "get_cluster_sdn_fabrics",
+    "get_nodes_node_sdn"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_sdn_vnets_vnet",
+  "usageNotes": "Returns the list of available subdirectory endpoints (e.g. 'firewall') under a specific SDN VNet on a node — this is a navigation/index endpoint, not a data endpoint. Use it to discover which sub-resources are accessible for a given VNet before drilling into them. Requires 'SDN.Audit' on '/sdn/zones/<zone>/<vnet>'; the VNet name must be 2–8 alphanumeric characters starting with a letter.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for SDN VNet 'vnet01' on node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "vnet": "vnet01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an array of objects with a 'subdir' field (e.g. 'firewall') — use these values to construct further API calls under this VNet.",
+    "VNet names are case-sensitive and must match the exact identifier used when the VNet was created in the SDN configuration.",
+    "SDN must be configured and applied at the cluster level before VNet sub-resources are reachable via individual nodes."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_vnets",
+    "get_cluster_sdn_vnets_vnet",
+    "get_nodes_node_sdn"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_sdn_vnets_vnet_mac_vrf",
+  "usageNotes": "Use this endpoint to inspect the MAC VRF routing table for a specific VNet on an EVPN zone — it returns every MAC-IP binding that the queried node either self-originates or has learned via BGP from remote VTEPs. The VNet must belong to an EVPN-type SDN zone; calling it against a VXLAN or simple zone will yield no meaningful results. The caller requires SDN.Audit permission on the specific zone/vnet path, and the target node must be online and have the SDN configuration applied.",
+  "examples": [
+    {
+      "summary": "Retrieve MAC VRF entries for VNet 'prod01' from node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "vnet": "prod01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Results are node-scoped: the same VNet queried from different nodes may show different BGP-learned entries depending on each node's EVPN peering state.",
+    "An empty array is normal when no VMs are active on the VNet or BGP sessions have not yet converged.",
+    "The 'nexthop' field is the VTEP IP of the remote node that advertised the route — useful for tracing which physical host owns a given MAC.",
+    "SDN configuration must have been applied (via pvesh POST /cluster/sdn/vnets/{vnet}/apply or the Proxmox UI) before this endpoint reflects current state."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_vnets",
+    "get_nodes_node_sdn_vnets_vnet",
+    "get_cluster_sdn_vnets",
+    "get_cluster_sdn_vnets_vnet"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_sdn_zones",
+  "usageNotes": "Use this endpoint to check the operational status of all SDN zones as seen from a specific cluster node. The response reflects node-local zone state, so a zone showing 'error' on one node may be fine on others — always query the affected node directly when diagnosing SDN issues. Requires 'SDN.Audit' privilege on the SDN zone objects; results are filtered to only zones the caller can audit.",
+  "examples": [
+    {
+      "summary": "List all SDN zone statuses on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Zone status 'pending' means SDN config has been saved in the cluster database but not yet applied to this node — run 'pvesh set /cluster/sdn' or reload SDN to push the config.",
+    "Zone status 'error' is node-specific; check /var/log/syslog on that node for OVS or FRR errors.",
+    "Zone IDs are 2–8 alphanumeric characters and are returned in the 'zone' field — use these as path parameters for zone-specific endpoints."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_zones",
+    "get_nodes_node_sdn",
+    "get_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_sdn_zones_zone",
+  "usageNotes": "Returns the available sub-resource directories for a specific SDN zone as seen from a given node — effectively a navigation index rather than zone configuration detail. Use this to discover what sub-endpoints (e.g. 'content') are available under a zone before drilling deeper. Requires SDN.Audit on the zone path; the target node must be online.",
+  "examples": [
+    {
+      "summary": "List sub-resource directories for SDN zone 'vlan10' on node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "zone": "vlan10"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Zone names are 2–8 characters, must start with a letter, and contain only alphanumerics — no hyphens or underscores.",
+    "The response is a directory index (array of subdir strings), not zone configuration; use the cluster-level SDN zone endpoints to read or modify zone settings.",
+    "Call this first to know which child endpoints exist before making follow-up requests against a zone on a specific node."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_zones",
+    "get_cluster_sdn_zones_zone",
+    "get_cluster_sdn_zones"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_sdn_zones_zone_bridges",
+  "usageNotes": "Use this to inspect the realized SDN state on a specific node — it reflects what Linux bridges and VNETs are actually instantiated on that node's kernel, which may differ from the cluster-level SDN config if `apply` has not been run. Requires SDN.Audit privilege on /sdn/zones/{zone}. Pass the literal string \"localnetwork\" as the zone to enumerate bridges that are part of the node's local network zone.",
+  "examples": [
+    {
+      "summary": "List all bridges for the 'prod' SDN zone on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "zone": "prod"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response reflects the live kernel bridge state on the target node — run sdn apply if the output does not match your SDN zone configuration.",
+    "Each bridge entry maps to a VNET within the zone; the 'ports' array shows which guest interfaces and VMIDs are currently attached.",
+    "The 'primary_vlan' and 'vlans' fields on ports are only populated for VLAN-aware (vlan_filtering) bridges.",
+    "Query each node individually — SDN zones can span multiple nodes but this endpoint only reports the state on the node specified in the path."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_zones",
+    "get_cluster_sdn_zones_zone",
+    "get_cluster_sdn_vnets",
+    "get_nodes_node_network"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_sdn_zones_zone_content",
+  "usageNotes": "Use this to list all VNets (virtual networks) provisioned within a specific SDN zone on a given node, along with each VNet's runtime status and any status detail message. The querying node must be online and have the SDN subsystem active; results reflect that node's local view of the zone, so query the node that is expected to be running the zone's bridges. Requires SDN.Audit privilege on /sdn/zones/{zone}.",
+  "examples": [
+    {
+      "summary": "List VNets in the 'prod01' SDN zone as seen from node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "zone": "prod01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Zone names are 2–8 characters and must match [a-zA-Z][a-zA-Z0-9]*[a-zA-Z0-9]; verify the zone identifier against /cluster/sdn/zones before calling.",
+    "The 'status' and 'statusmsg' fields are optional in each returned item; a missing status typically means the VNet has not yet been applied/deployed on that node.",
+    "SDN changes must be applied (via the SDN apply operation) before new VNets appear with an 'ok' status here."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_zones",
+    "get_cluster_sdn_vnets",
+    "get_nodes_node_sdn_zones",
+    "get_nodes_node_sdn"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_sdn_zones_zone_ip_vrf",
+  "usageNotes": "Use this to inspect the VRF (Virtual Routing and Forwarding) route table for a specific EVPN zone as seen by a given node — useful for verifying BGP-learned routes and inter-zone reachability during SDN troubleshooting. Requires the zone to be of type EVPN and the queried node to be online with SDN applied. Note that /32 host routes for guests local to the queried node are intentionally excluded from results, as those are handled directly via the vnet bridge.",
+  "examples": [
+    {
+      "summary": "Fetch VRF route table for EVPN zone 'evpn-prod' on node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "zone": "evpn-prod"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Results only reflect routes in the VRF routing table — not the full Linux routing table or guest ARP entries.",
+    "If the response is empty, the zone may not be applied on the node yet or BGP peering may not be established.",
+    "The 'protocol' field (e.g. 'bgp') indicates how the route was learned — useful for confirming EVPN control-plane convergence.",
+    "Run this on multiple nodes and compare results to detect asymmetric routing or BGP advertisement issues across the fabric."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_zones",
+    "get_cluster_sdn_zones_zone",
+    "get_nodes_node_sdn_zones_zone_content"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_services",
+  "usageNotes": "Use this to get the current systemd status of all Proxmox-managed services on a specific node (e.g., pveproxy, pvedaemon, pvestatd, corosync). The node must be online and reachable by the API; calling against an offline node will fail. Requires Sys.Audit on /nodes/{node} — read-only, safe to call at any time for health checks or pre-maintenance validation.",
+  "examples": [
+    {
+      "summary": "List all service states on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Check 'active-state' (systemd ActiveState) for high-level health: 'active' is healthy, 'failed' needs attention.",
+    "Check 'state' (systemd SubState) for finer detail — 'running' is normal for long-lived services, 'exited' is normal for oneshot units that completed successfully.",
+    "Check 'unit-state' (UnitFileState) to distinguish services that are 'disabled' vs 'masked' — masked services cannot be started even manually.",
+    "Use this endpoint before performing maintenance (e.g., node shutdown, cluster operations) to confirm all critical services like corosync and pveproxy are running.",
+    "The 'service' field is the canonical systemd unit name to pass to service-specific endpoints (start, stop, restart, reload, state)."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_services_service_state",
+    "post_nodes_node_services_service_start",
+    "post_nodes_node_services_service_stop",
+    "post_nodes_node_services_service_restart",
+    "post_nodes_node_services_service_reload"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_services_service",
+  "usageNotes": "Returns the list of available sub-command directories (e.g. 'state', 'start', 'stop', 'restart', 'reload') for a specific system service on a given node. Use this as a discovery step before calling service action endpoints — the returned 'subdir' values tell you which operations are valid for that service. Requires Sys.Audit on the node; the node must be online and reachable by the PVE API.",
+  "examples": [
+    {
+      "summary": "List available sub-commands for the pveproxy service on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "service": "pveproxy"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values directly map to child API paths: e.g. a 'state' subdir corresponds to GET /nodes/{node}/services/{service}/state.",
+    "Not all services expose the same set of subdirs — always discover before assuming a sub-command like 'reload' exists for a given service.",
+    "Service names are an enum; submitting an unlisted service name will result in a 400 error rather than a graceful empty response."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_services",
+    "get_nodes_node_services_service_state",
+    "post_nodes_node_services_service_start",
+    "post_nodes_node_services_service_stop",
+    "post_nodes_node_services_service_restart",
+    "post_nodes_node_services_service_reload"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_services_service_state",
+  "usageNotes": "Use this to check the live runtime state of a specific PVE-managed system service on a given node — useful for health checks, troubleshooting, or pre-flight validation before restarting or reconfiguring a service. The node must be online and reachable; requires Sys.Audit on /nodes/{node}. Returns three distinct systemd state dimensions (active-state, state/SubState, unit-state) which together give a full picture: a service can be enabled (unit-state) but not currently running (active-state=inactive).",
+  "examples": [
+    {
+      "summary": "Check whether pveproxy is running on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "service": "pveproxy"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "active-state is the high-level systemd ActiveState (e.g. 'active', 'failed'); state is the finer-grained SubState (e.g. 'running', 'dead') — check both when diagnosing failures.",
+    "unit-state reflects whether the service is enabled to start at boot ('enabled'), disabled, or masked — a service can be running but 'disabled' if it was started manually.",
+    "Poll this endpoint after issuing a service restart (post_nodes_node_services_service_restart) to confirm the state transitions from 'activating' to 'active'.",
+    "The 'corosync' and 'pve-cluster' services are cluster-critical — if either shows active-state='failed', expect degraded quorum or HA instability across all nodes."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_services",
+    "post_nodes_node_services_service_restart",
+    "post_nodes_node_services_service_start",
+    "post_nodes_node_services_service_stop",
+    "post_nodes_node_services_service_reload"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_status",
+  "usageNotes": "Use this to get a real-time health snapshot of a specific cluster node, including CPU usage, memory, root filesystem, load averages, kernel version, and boot mode. The node must be online and reachable by the cluster; if the node is offline, the API will return an error rather than stale data. Requires Sys.Audit on /nodes/{node}.",
+  "examples": [
+    {
+      "summary": "Get status of cluster node 'pve1'",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "cpu is a float between 0 and 1 (e.g., 0.42 = 42% utilization) — multiply by 100 for a percentage display.",
+    "memory.available is the kernel-reported available memory (includes reclaimable caches), which is typically larger than memory.free; prefer available for headroom estimates.",
+    "loadavg returns three strings for 1-, 5-, and 15-minute averages — parse as floats before comparing to cpuinfo.cpus to gauge saturation.",
+    "boot-info.secureboot is only present when boot-info.mode is 'efi'; absence of the field implies legacy-BIOS or secure boot not detected.",
+    "rootfs reflects the root partition only (/); storage pools like local-lvm or ZFS datasets are not included here — use storage status endpoints for those."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_rrddata",
+    "get_nodes_node_network",
+    "get_nodes",
+    "get_cluster_resources"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_storage",
+  "usageNotes": "Use this endpoint to list all datastores visible to a specific node along with their live capacity metrics (total, used, available bytes). The node must be online — offline nodes return no storage status. Results are filtered by the caller's permissions: only storages where the caller holds 'Datastore.Audit' or 'Datastore.AllocateSpace' on '/storage/<storage>' will appear.",
+  "examples": [
+    {
+      "summary": "List only ISO-capable, enabled storages on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "content": "iso",
+        "enabled": true
+      }
+    }
+  ],
+  "tips": [
+    "The 'active' field in each result indicates whether the storage is currently reachable/mounted, which can differ from 'enabled' (config-level toggle).",
+    "Use the 'target' param when planning a VM migration: it restricts results to shared storages accessible by both the source node and the target node.",
+    "Set 'format=true' to get the list of supported disk image formats (qcow2, raw, vmdk, subvol) — useful before provisioning a new VM disk.",
+    "Capacity fields (avail, used, total) may be absent for storage types that do not report usage (e.g. some directory stores or external backends that are unreachable)."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_status",
+    "get_nodes_node_storage_storage_content",
+    "get_storage",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_storage_storage",
+  "usageNotes": "Returns the list of sub-resource directories available under a specific storage pool on a given node — this is a directory index, not a content listing. Use it to discover which child endpoints (e.g. 'content', 'status', 'rrd') are reachable for the storage before drilling deeper. Requires either Datastore.Audit or Datastore.AllocateSpace on /storage/{storage}; the node must be online and the storage must be configured and accessible on that node.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for the 'local-zfs' storage on node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "storage": "local-zfs"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values are the child path segments — append them to this path to reach endpoints like /nodes/{node}/storage/{storage}/content or /nodes/{node}/storage/{storage}/status.",
+    "If the storage is disabled or not mounted on the target node, the API will return an error even if the storage ID is valid in the cluster config.",
+    "Shared storages (e.g. NFS, Ceph) may return the same subdirs from any node that has them mounted, but per-node storages (e.g. local, local-lvm) only exist on their own node."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage",
+    "get_nodes_node_storage_storage_content",
+    "get_nodes_node_storage_storage_status",
+    "get_nodes_node_storage_storage_rrd",
+    "get_nodes_node_storage_storage_rrddata"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "get_nodes_node_storage_storage_content",
+  "usageNotes": "Use this to list volumes on a specific storage pool — disk images, ISO files, container templates, or backups — scoped to a single node. The target node must be online and the storage must be accessible from that node; content visible on one node may differ for shared storages depending on scan state. Narrow results with the `content` filter (e.g. `images`, `iso`, `backup`, `vztmpl`) or the `vmid` filter to avoid iterating large pools.",
+  "examples": [
+    {
+      "summary": "List all backup volumes on local-zfs storage for VM 101",
+      "path_params": {
+        "node": "pve01",
+        "storage": "local-zfs"
+      },
+      "params": {
+        "content": "images",
+        "vmid": 101
+      }
+    }
+  ],
+  "tips": [
+    "The `size` field is exact only when the storage plugin supports it; fall back to `approximate-size` for storages like PBS or thin-provisioned LVM.",
+    "For PBS storages, check the `verification.state` field to confirm the backup is verified — unverified backups may not restore cleanly.",
+    "The `protected` flag is returned for backup volumes and prevents deletion via the API until removed.",
+    "Use `content=iso` against an ISO-class storage to enumerate installable images before creating a VM.",
+    "volid values returned here are the correct identifiers to pass to volume-level operations (upload, delete, restore)."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_status",
+    "get_nodes_node_storage",
+    "post_nodes_node_storage_storage_content",
+    "delete_nodes_node_storage_storage_content_volume"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_storage_storage_content_volume",
+  "usageNotes": "Use this to inspect metadata for a specific volume on a storage backend — format, on-disk path, allocated size, and protection status for backups. The `volume` path param accepts the full volume identifier (e.g. `local:100/vm-100-disk-0.qcow2`) or a bare volume name; the `storage` path param is technically marked optional in the spec but should be included when the volume ID is ambiguous. The calling user or API token only needs read access to the volume, so this is safe for auditing or pre-flight checks before clone/move operations.",
+  "examples": [
+    {
+      "summary": "Inspect a VM disk image on local-lvm storage",
+      "path_params": {
+        "node": "pve01",
+        "storage": "local-lvm",
+        "volume": "vm-100-disk-0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `used` field is often 0 or unreliable — most storage plugins do not report actual used space; rely on `size` instead.",
+    "The `protected` field is only populated for backup volumes (vzdump/PBS); it will be absent for disk images.",
+    "Volume identifiers in Proxmox typically follow the pattern `<storage>:<vmid>/<filename>` or `<storage>:vm-<vmid>-<name>` depending on the storage type; pass the full volid if you obtained it from the content list endpoint.",
+    "This endpoint targets a specific node — if the storage is shared (e.g. Ceph, NFS), any node that has the storage mounted can serve the request, but the node must be online."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_content",
+    "post_nodes_node_storage_storage_content",
+    "delete_nodes_node_storage_storage_content_volume",
+    "post_nodes_node_storage_storage_content_volume"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_storage_storage_file_restore_download",
+  "usageNotes": "Use this endpoint to extract and download a specific file or directory from a PBS backup snapshot without fully restoring the VM or container. The `filepath` parameter must be base64-encoded; pass `tar=true` to receive directories as a `.tar.zst` archive instead of the default `.zip`. Only PBS-backed storage volumes are supported — backups on other storage types will be rejected.",
+  "examples": [
+    {
+      "summary": "Download a single config file from a PBS VM backup as a zip",
+      "path_params": {
+        "node": "pve01",
+        "storage": "pbs-main"
+      },
+      "params": {
+        "volume": "backup/vm/101/2024-06-01T02:00:00Z",
+        "filepath": "L2V0Yy9uZ2lueC9uZ2lueC5jb25m",
+        "tar": false
+      }
+    }
+  ],
+  "tips": [
+    "Base64-encode the full absolute path (e.g. /etc/nginx/nginx.conf) before passing it as `filepath`.",
+    "Set `tar=true` when downloading a directory — zip output for large directories can be slower to stream.",
+    "The response streams binary archive data directly; pipe or save it immediately rather than buffering the full body in memory.",
+    "Requires the calling user or API token to have Datastore.Read (or equivalent) on the PBS storage — verify permissions on the PBS side, not just the PVE side."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_file_restore_list",
+    "post_nodes_node_storage_storage_file_restore_list"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_storage_storage_file_restore_list",
+  "usageNotes": "Use this to browse the directory tree inside a PBS backup snapshot before restoring individual files. The `filepath` parameter must be base64-encoded; pass `/` (literal slash, not encoded) to start at the root of the archive. Currently limited to Proxmox Backup Server (PBS) snapshots — other backup types are not supported.",
+  "examples": [
+    {
+      "summary": "List root-level entries inside a PBS VM backup snapshot",
+      "path_params": {
+        "node": "pve01",
+        "storage": "pbs-main"
+      },
+      "params": {
+        "volume": "vm/101/2024-06-15T02:00:00Z",
+        "filepath": "/"
+      }
+    }
+  ],
+  "tips": [
+    "Leaf entries (leaf: true) are files; non-leaf entries are directories — recurse into them with another call using the returned `filepath` value.",
+    "The `filepath` values in the response are already base64-encoded and can be passed directly as `filepath` in the next request without re-encoding.",
+    "mtime and size are optional and may be absent for directory entries.",
+    "This endpoint only works when the target node is online and can reach the PBS datastore; ensure the storage is mounted before calling."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_file_restore_download",
+    "get_nodes_node_storage_storage_content",
+    "get_nodes_node_storage_storage_status"
+  ]
+}