@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_certificates_acme",
+  "usageNotes": "Returns the ACME sub-resource index for a specific node, listing the available child endpoints (e.g. certificate, challenge-schema) under /nodes/{node}/certificates/acme. Use this to discover what ACME operations are supported before calling more specific endpoints. No query parameters are required and any authenticated user or API token may call it.",
+  "examples": [
+    {
+      "summary": "List ACME sub-resources for node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a navigation index (links with rel=child), not ACME certificate data itself — follow child hrefs to get certificate info or manage ACME settings.",
+    "Accessible to all authenticated users, including read-only API tokens, so no special privilege is needed.",
+    "The node must be reachable by the Proxmox cluster; if the node is offline, the API request will fail at the proxy layer."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_certificates_acme_certificate",
+    "get_nodes_node_certificates_acme_challengeschema",
+    "get_nodes_node_certificates_info"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_certificates_info",
+  "usageNotes": "Use this to inspect the TLS certificates currently installed on a Proxmox node — including the web GUI/API certificate and any ACME-managed certificates. The response includes validity timestamps (Unix epoch) and SHA-256 fingerprints useful for expiry monitoring and pinning verification. Accessible by all authenticated users (no special privilege required), but the target node must be online and reachable by the API host.",
+  "examples": [
+    {
+      "summary": "List certificates on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The notafter field is a Unix timestamp — compare against current time to detect certs expiring within your alert window (e.g. 30 days).",
+    "Multiple entries are returned when both a self-signed and an ACME/custom certificate are installed; check the filename field to distinguish them (e.g. pveproxy-ssl.pem vs pve-ssl.pem).",
+    "The fingerprint field uses colon-separated SHA-256 hex pairs — useful for comparing against what browsers or clients report for the node's HTTPS cert.",
+    "san entries confirm which hostnames/IPs the certificate covers; verify your node FQDN appears there after an ACME renewal."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_certificates_acme_certificate",
+    "delete_nodes_node_certificates_acme_certificate",
+    "post_nodes_node_certificates_custom"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_config",
+  "usageNotes": "Use this to inspect a node's local configuration including ACME certificate settings, ballooning target, Wake-on-LAN, boot delay, and location. Requires Sys.Audit on the root path — API tokens must carry that privilege. Use the optional `property` filter to retrieve a single field and avoid parsing the full object when only one setting is needed.",
+  "examples": [
+    {
+      "summary": "Fetch full node configuration for pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response includes a `digest` (SHA1 of the config file) — pass it to update operations to guard against concurrent modifications.",
+    "Use `property=acme` or `property=acmedomain0` to quickly check certificate domain assignments without fetching the full config.",
+    "ballooning-target defaults to 80 (percent); if not set, the field is absent from the response rather than returning the default explicitly.",
+    "wakeonlan and location are node-level overrides — if absent here, the datacenter-level defaults apply."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_config",
+    "get_nodes_node_status",
+    "get_cluster_config_nodes"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_disks",
+  "usageNotes": "Returns the list of disk-related sub-resource endpoints available under the specified node (e.g., list, smart, initgpt, wipedisk). Use this to discover what disk operations are supported before calling a specific sub-endpoint. Requires the node to be online; the response is a directory index, not actual disk data.",
+  "examples": [
+    {
+      "summary": "List available disk sub-resources on node 'pve1'",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a directory index only — to get actual disk inventory, call get_nodes_node_disks_list instead.",
+    "All authenticated users can call this endpoint; no elevated privilege is required.",
+    "The returned 'name' values in each object correspond to child API paths you can call next (e.g., 'list', 'smart', 'initgpt', 'wipedisk', 'directory', 'zfs', 'lvm', 'lvmthin')."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_list",
+    "get_nodes_node_disks_smart",
+    "get_nodes_node_disks_directory",
+    "get_nodes_node_disks_zfs",
+    "get_nodes_node_disks_lvm",
+    "get_nodes_node_disks_lvmthin"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_disks_directory",
+  "usageNotes": "Lists all PVE-managed directory storage mounts on the specified node, including their device, mount path, filesystem type, and mount options. Requires the node to be online and the caller to hold Sys.Audit on the root path. Use this to audit which block devices are mounted as directory-backed storage before adding, removing, or troubleshooting storage configurations.",
+  "examples": [
+    {
+      "summary": "List all directory storages on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each entry's 'unitfile' field points to the systemd mount unit managing the mount — useful for diagnosing mount failures via 'systemctl status'.",
+    "Results reflect only PVE-managed directory mounts, not all mounts on the host; system mounts (/, /boot, etc.) are excluded.",
+    "Cross-reference 'device' values with 'get_nodes_node_disks_list' to map directory mounts back to their physical or logical disk."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_list",
+    "post_nodes_node_disks_directory",
+    "delete_nodes_node_disks_directory_name",
+    "get_nodes_node_storage"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "get_nodes_node_disks_list",
+  "usageNotes": "Use this to inventory physical and virtual block devices visible to a specific node — useful before adding disks to Ceph, ZFS, or LVM storage. SMART health data is queried per disk by default, which can slow the response on nodes with many drives; pass skipsmart=true for faster enumeration when health status is not needed. Requires Sys.Audit on / or on /nodes/{node}.",
+  "examples": [
+    {
+      "summary": "List all unused disks on node pve1, skipping SMART checks for speed",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "type": "unused",
+        "skipsmart": true
+      }
+    }
+  ],
+  "tips": [
+    "Set type=unused to quickly find unpartitioned disks eligible for new storage pools or Ceph OSDs.",
+    "Set type=journal_disks to find disks designated as Ceph journal/WAL/DB devices.",
+    "include-partitions=true is needed to see individual partitions alongside whole disks; partition entries include a 'parent' field pointing to the containing disk.",
+    "The 'osdid' and 'osdid-list' fields identify Ceph OSDs residing on that disk — a non-negative osdid means the disk is already claimed by Ceph.",
+    "SMART health is returned in the 'health' field (e.g. PASSED, FAILED); absent or empty health usually means the disk type does not support SMART."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_smart",
+    "get_nodes_node_disks_zfs",
+    "post_nodes_node_disks_zfs",
+    "get_nodes_node_disks_lvmthin",
+    "get_nodes_node_ceph_osd"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_disks_lvm",
+  "usageNotes": "Use this to inventory LVM Volume Groups on a specific node, including each VG's underlying physical volumes and their free/total byte counts. Requires `Sys.Audit` on `/` — API tokens must carry that privilege. The node must be online; the call fails if the node is unreachable from the API host.",
+  "examples": [
+    {
+      "summary": "List all LVM Volume Groups on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a tree: top-level `children` are VGs, and each VG optionally has its own `children` array of PVs with per-PV free/size bytes.",
+    "Sizes are in bytes — divide by 1073741824 for GiB.",
+    "A VG named `pve` is the default Proxmox VG created by the installer; avoid modifying it unless you know the LV layout.",
+    "Use the free/size values here to determine whether a VG has enough headroom before creating a new LV-backed storage via `post_nodes_node_disks_lvmthin`."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_lvmthin",
+    "post_nodes_node_disks_lvm",
+    "get_nodes_node_disks_list",
+    "get_nodes_node_storage"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_disks_lvmthin",
+  "usageNotes": "Use this to inventory all LVM thin pools on a specific node before creating or resizing a thin-provisioned storage pool in Proxmox. Requires the Sys.Audit privilege at the root path (/). The node must be online; the call targets the local LVM subsystem of that node and will fail if the node is unreachable.",
+  "examples": [
+    {
+      "summary": "List all LVM thin pools on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each result includes both lv (thin pool LV name) and vg (volume group), which together form the storage identifier used when adding LVM-thin storage via the datacenter storage config (e.g. vg/lv).",
+    "Monitor metadata_used vs metadata_size — if metadata fills up, the thin pool will stop accepting writes even if data space remains.",
+    "lv_size and used are in bytes; divide by 1073741824 for GiB display."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_lvm",
+    "get_nodes_node_disks_list",
+    "get_storage",
+    "post_nodes_node_disks_lvmthin"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_disks_smart",
+  "usageNotes": "Use this endpoint to inspect the SMART health and attribute data for a specific block device on a PVE node. The node must be online and reachable, and the caller must hold `Sys.Audit` on `/`. Set `healthonly: true` for a lightweight pass/fail check; omit it to retrieve the full attribute table and raw smartctl text, which is useful for diagnosing early-warning reallocated sectors or pending uncorrectable errors.",
+  "examples": [
+    {
+      "summary": "Get full SMART data for an NVMe drive on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "disk": "/dev/nvme0",
+        "healthonly": false
+      }
+    }
+  ],
+  "tips": [
+    "The disk path must match the pattern ^/dev/[a-zA-Z0-9\\/]+$ — use get_nodes_node_disks_list first to enumerate valid device paths for the node.",
+    "When healthonly is true the response only contains the `health` field (e.g. 'PASSED' or 'FAILED'), which is faster and suitable for automated health checks.",
+    "SMART data is read directly from the device at request time; for NVMe drives the `type` field in the response will reflect the NVMe protocol rather than ATA.",
+    "This endpoint is read-only and has no side effects on the disk or running VMs."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_list",
+    "get_nodes_node_disks_initgpt",
+    "get_nodes_node_hardware"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_disks_zfs",
+  "usageNotes": "Use this to list all ZFS zpools on a specific node, including their health status, allocated/free space, fragmentation, and deduplication ratio. The target node must be online and have ZFS kernel modules loaded; nodes without any zpools return an empty array. Requires the Sys.Audit privilege at the root path — a read-only audit token is sufficient.",
+  "examples": [
+    {
+      "summary": "List all zpools on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'health' field mirrors 'zpool status' output: ONLINE, DEGRADED, FAULTED, OFFLINE, UNAVAIL, or REMOVED — anything other than ONLINE warrants immediate investigation.",
+    "alloc, free, and size values are in bytes; divide by 1073741824 for GiB.",
+    "A high frag percentage (>50%) on a pool can indicate performance degradation; consider scrubbing or expanding the pool.",
+    "dedup ratio of 1.00 means deduplication is off or not saving space — enabling dedup has significant RAM overhead (roughly 5 GB RAM per 1 TB of deduplicated data).",
+    "This endpoint lists zpools only, not individual datasets or zvols — use the ZFS dataset APIs for deeper inspection."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_disks_zfs_name",
+    "post_nodes_node_disks_zfs",
+    "delete_nodes_node_disks_zfs_name",
+    "get_nodes_node_disks_list",
+    "get_nodes_node_storage"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_disks_zfs_name",
+  "usageNotes": "Use this to inspect a specific ZFS pool's health on a given node — including its vdev layout, per-vdev read/write/checksum error counters, overall pool state (ONLINE/DEGRADED/FAULTED), and the last scrub result. Requires the Sys.Audit privilege at the root path; API tokens are supported. The node must be online and ZFS must be loaded — pools on offline or unreachable nodes will return an error, not empty data.",
+  "examples": [
+    {
+      "summary": "Get details for the 'rpool' ZFS pool on node 'pve1'",
+      "path_params": {
+        "node": "pve1",
+        "name": "rpool"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'children' array is nested: top-level entries represent vdev groups (e.g. 'mirror-0', 'cache', 'spares'), and their children are the individual member disks.",
+    "Non-zero 'cksum', 'read', or 'write' counters on a vdev child indicate I/O errors — a pool in ONLINE state can still have silent errors accumulating.",
+    "The 'scan' field contains the last scrub timestamp and result; an empty or missing value means no scrub has ever completed.",
+    "The optional 'action' field surfaces ZFS's own recommended remediation step (e.g. 'resilver in progress', 'replace the disk') — useful to surface directly in alerts.",
+    "Use list_nodes_node_disks_zfs to enumerate all pool names on a node before calling this endpoint."
+  ],
+  "relatedOperations": [
+    "list_nodes_node_disks_zfs",
+    "create_nodes_node_disks_zfs",
+    "delete_nodes_node_disks_zfs_name",
+    "get_nodes_node_disks_list"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_dns",
+  "usageNotes": "Use this to inspect the DNS resolver configuration (up to three nameservers and the search domain) currently active on a specific node's /etc/resolv.conf. The target node must be online and reachable by the API; the caller needs Sys.Audit on /nodes/{node}. All returned fields are optional — a node with minimal config may return only a subset.",
+  "examples": [
+    {
+      "summary": "Read DNS settings from node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "All response fields (dns1, dns2, dns3, search) are optional; check for their presence before using them.",
+    "To update DNS settings, use the corresponding PUT endpoint (update_nodes_node_dns).",
+    "In a cluster, each node stores its own /etc/resolv.conf — query each node individually if you need a cluster-wide view."
+  ],
+  "relatedOperations": [
+    "update_nodes_node_dns",
+    "get_nodes_node_network",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_firewall",
+  "usageNotes": "Returns the list of available sub-resources under a node's firewall namespace (e.g., rules, options, log, refs). Use this as a discovery call to confirm which firewall sub-paths are exposed for a given node before querying them individually. Accessible to all authenticated users; no special privilege is required.",
+  "examples": [
+    {
+      "summary": "List firewall sub-resources for node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a directory index — each item's 'name' field corresponds to a child endpoint (e.g., 'rules', 'options', 'log', 'refs').",
+    "Use this call to verify the node is reachable and the firewall API surface is available before making write calls to sub-endpoints."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_firewall_options",
+    "get_nodes_node_firewall_rules",
+    "get_nodes_node_firewall_log",
+    "get_nodes_node_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_firewall_log",
+  "usageNotes": "Use this endpoint to read the node-level firewall log (iptables/nftables kernel log entries) for a specific Proxmox node. Requires the `Sys.Syslog` privilege on `/nodes/{node}`, so API tokens scoped below that path will be denied. Use `since`/`until` (UNIX epoch) to narrow the time window; without them the full log is returned, which can be large on busy nodes.",
+  "examples": [
+    {
+      "summary": "Fetch the last 50 firewall log entries from node pve1 since a recent timestamp",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "limit": 50,
+        "since": 1719532800
+      }
+    }
+  ],
+  "tips": [
+    "Results are an array of objects with `n` (line number) and `t` (raw log text); parse `t` for IP, port, and action fields.",
+    "Use `start` + `limit` together for pagination through large log windows.",
+    "This endpoint reads the node firewall log only — for VM/CT firewall logs use the equivalent endpoint under `/nodes/{node}/qemu/{vmid}/firewall/log` or `/nodes/{node}/lxc/{vmid}/firewall/log`.",
+    "Log entries only appear if the firewall LOG rule action is configured; if the firewall is enabled but no LOG rules exist, the log will be empty."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_firewall_rules",
+    "get_nodes_node_firewall_options",
+    "get_cluster_firewall_log"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_firewall_options",
+  "usageNotes": "Returns the host-level firewall configuration for a specific node, including whether the firewall is enabled, log verbosity for in/out/forwarded traffic, conntrack settings, and DDoS mitigations (synflood, SMURFS, TCP-flag filters). Requires Sys.Audit on /nodes/{node} — readable by API tokens with that privilege. Use this before modifying node firewall options to capture the current state and avoid blind overwrites.",
+  "examples": [
+    {
+      "summary": "Read firewall options for node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "enable defaults to 1 (on) — an absent field in the response means the default is in effect, not that the option is unset.",
+    "nftables is a tech preview flag; enabling it changes the firewall backend and may affect existing iptables rules.",
+    "nf_conntrack_max defaults to 262144; on busy nodes with many VMs/CTs, a low conntrack limit causes dropped connections — check this when troubleshooting intermittent packet loss.",
+    "log_level_in/out/forward all default to 'nolog'; setting them to 'info' or 'debug' generates high syslog volume on active nodes."
+  ],
+  "relatedOperations": [
+    "set_nodes_node_firewall_options",
+    "get_nodes_node_firewall_rules",
+    "get_cluster_firewall_options"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_firewall_rules",
+  "usageNotes": "Returns the ordered list of host-level firewall rules for a specific node (not VM/CT rules). Rules are returned in positional order; the `pos` field is the zero-based index used by rule-specific endpoints. Requires `Sys.Audit` on `/nodes/{node}` — API tokens must have this privilege explicitly granted.",
+  "examples": [
+    {
+      "summary": "List all firewall rules on node pve01",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each returned object's `pos` value is the handle for GET/PUT/DELETE on /nodes/{node}/firewall/rules/{pos}.",
+    "Rules with `enable: 0` are present in the list but inactive; check this field before assuming a rule is enforced.",
+    "An `action` that does not match ACCEPT/DROP/REJECT is a security group reference — it will not have src/dest/port fields of its own.",
+    "This endpoint covers only the node host firewall chain. VM and container rules live under /nodes/{node}/qemu/{vmid}/firewall/rules and /nodes/{node}/lxc/{vmid}/firewall/rules respectively.",
+    "The node firewall must be enabled at the node level (not just cluster level) for these rules to be active; verify with get_nodes_node_firewall_options."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_firewall_rules_pos",
+    "post_nodes_node_firewall_rules",
+    "put_nodes_node_firewall_rules_pos",
+    "delete_nodes_node_firewall_rules_pos",
+    "get_nodes_node_firewall_options",
+    "get_cluster_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_firewall_rules_pos",
+  "usageNotes": "Use this to inspect a single node-level firewall rule by its zero-based position in the ruleset. Requires `Sys.Audit` on `/nodes/{node}`. Because rules are position-indexed, pair this with the rule list endpoint first to identify the target `pos` before fetching details.",
+  "examples": [
+    {
+      "summary": "Fetch the first rule on node pve1 to inspect its action and source filter",
+      "path_params": {
+        "node": "pve1",
+        "pos": 0
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rule positions are zero-based and shift whenever rules are inserted or deleted — always re-query the list after any write operation to get current positions.",
+    "The `pos` path param is marked optional in the spec but functionally required; omitting it will cause an API error.",
+    "Check the `enable` field (0 or 1) to confirm whether the rule is currently active before troubleshooting connectivity."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_firewall_rules",
+    "put_nodes_node_firewall_rules_pos",
+    "delete_nodes_node_firewall_rules_pos",
+    "post_nodes_node_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_hardware",
+  "usageNotes": "Returns a list of hardware category types (e.g. 'pci', 'usb') available for inspection on the specified node — use this as a discovery step before querying a specific hardware subcategory. The node must be online and reachable by the cluster; the endpoint is accessible to all authenticated users with no privilege restrictions. No query parameters exist; the only input is the node name.",
+  "examples": [
+    {
+      "summary": "List available hardware categories on node 'pve1'",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a navigation index — each returned 'type' value corresponds to a child endpoint under /nodes/{node}/hardware/{type} (e.g. /nodes/pve1/hardware/pci).",
+    "Typical types include 'pci' and 'usb'; the exact list depends on what the Proxmox version exposes for the node.",
+    "This endpoint is safe to poll frequently; it is read-only and carries no performance impact."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_hardware_pci",
+    "get_nodes_node_hardware_usb"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_hardware_pci",
+  "usageNotes": "Use this endpoint to enumerate all PCI devices physically present on a node — essential before configuring PCI passthrough (PCIe PT) or mediated device (mdev) assignments for VMs. The node must be online and reachable; the caller needs either Sys.Audit or Sys.Modify at the root path. Bridge, memory controller, and processor-class devices are filtered out by default; pass a custom pci-class-blacklist (or an empty string) if you need those classes included.",
+  "examples": [
+    {
+      "summary": "List all PCI devices on node 'pve1' with full vendor/device names",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "verbose": true
+      }
+    }
+  ],
+  "tips": [
+    "An iommugroup value of -1 means IOMMU is not active or the device is not grouped — passthrough will not work without IOMMU enabled in BIOS and the kernel (intel_iommu=on / amd_iommu=on).",
+    "Devices with mdev: true support mediated-device (vGPU) slicing, not just full passthrough — check this field before deciding on a passthrough strategy.",
+    "Set verbose: false for a quick ID-only list when scripting; use verbose: true (the default) when you need vendor/device names for documentation or VM config.",
+    "To include normally-filtered classes (e.g., bridges), pass pci-class-blacklist as an empty string or omit the classes you want visible."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_hardware_pci_pciid",
+    "get_nodes_node_hardware_pci_pciid_mdev",
+    "post_nodes_node_qemu_vmid_config",
+    "put_nodes_node_qemu_vmid_config"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_hardware_pci_pci_id_or_mapping",
+  "usageNotes": "Returns the list of available sub-methods (child endpoints) for a specific PCI device or PCI mapping on a node — useful as a discovery step before calling device-info or mdev sub-endpoints. The path parameter accepts either a PCI address in the form `[domain:]bus:slot.function` (e.g. `0000:00:02.0` or `00:02.0`) or a named mapping identifier (e.g. `gpu-mapping`). The node must be reachable; this endpoint does not validate that the device is currently in use by a VM.",
+  "examples": [
+    {
+      "summary": "List available sub-methods for a GPU at PCI address 0000:01:00.0 on pve1",
+      "path_params": {
+        "node": "pve1",
+        "pci-id-or-mapping": "0000:01:00.0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Use the short form (bus:slot.function, e.g. '01:00.0') when the domain is 0000 — Proxmox accepts both.",
+    "Named mapping identifiers must start with a letter and contain only letters, digits, hyphens, or underscores.",
+    "Child methods typically include 'mdev' (for mediated device types) and device info — call those sub-endpoints after discovering them here.",
+    "Accessible by all authenticated users (no node-level privilege required), so safe to call for discovery without elevated tokens."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_hardware_pci",
+    "get_nodes_node_hardware_pci_pci_id_or_mapping_mdev",
+    "get_nodes_node_hardware_pci_pci_id_or_mapping_reports"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_hardware_pci_pci_id_or_mapping_mdev",
+  "usageNotes": "Use this to discover which mediated device (mdev) types a PCI device supports before assigning one to a VM — required for GPU partitioning workflows (e.g. NVIDIA vGPU, Intel GVT-g). The node must be online and the host kernel/driver must already expose mdev types via sysfs; if no mdev types are registered the response will be an empty array. Requires Sys.Audit or Sys.Modify at the root level.",
+  "examples": [
+    {
+      "summary": "List mdev types for an NVIDIA GPU at PCI address 0000:01:00.0 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "pci-id-or-mapping": "0000:01:00.0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'available' field in each returned item shows remaining free instances — a value of 0 means every slot of that mdev type is already allocated to a VM.",
+    "You can pass either a raw PCI address (e.g. 0000:01:00.0) or a Proxmox PCI mapping name (e.g. gpu-nvidia) as pci-id-or-mapping.",
+    "If the driver does not register mdev support in sysfs, this endpoint returns an empty array rather than an error — verify the correct vGPU driver is installed and loaded on the node.",
+    "Use get_nodes_node_hardware_pci to enumerate available PCI devices on the node before calling this endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_hardware_pci",
+    "get_nodes_node_hardware_pci_pciid"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_hardware_usb",
+  "usageNotes": "Use this endpoint to enumerate all USB devices physically connected to a specific cluster node — useful before configuring USB passthrough to a VM or LXC container. The node must be online and reachable, and the caller requires the Sys.Modify privilege at the root path (/). The response includes bus/device numbers, vendor/product IDs, speed, and optional serial numbers that are needed when adding a usb device to a VM config.",
+  "examples": [
+    {
+      "summary": "List all USB devices on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Use vendid and prodid from the response when configuring USB passthrough by vendor/product ID (usb: host=vendid:prodid) — this is more stable than bus/device numbers which can change on reboot.",
+    "If serial is present, prefer it for unique device identification when multiple identical USB devices are attached to the same node.",
+    "The usbpath field (when present) allows port-based passthrough (usb: host=bus-port) — useful when you need a specific physical port regardless of which device is plugged in."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_hardware_pci",
+    "get_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_config"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_nodes_node_hosts",
+  "usageNotes": "Use this to read the raw content of /etc/hosts on a specific PVE node, useful for auditing static hostname mappings or capturing the current digest before issuing an update. The returned digest should be passed to the corresponding write operation to prevent concurrent modification conflicts. Requires Sys.Audit privilege at the root path.",
+  "examples": [
+    {
+      "summary": "Fetch /etc/hosts content from node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Capture the 'digest' field from the response and pass it to the update endpoint to guard against race conditions when multiple operators may edit hosts concurrently.",
+    "Each node maintains its own /etc/hosts — run this per-node to audit cluster-wide hostname resolution rather than assuming all nodes are in sync.",
+    "Static entries here affect name resolution for guests and host services on that node; verify entries are consistent with your DNS infrastructure."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_hosts"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_journal",
+  "usageNotes": "Reads the systemd journal (journald) for a specific cluster node, returning an array of log line strings. Requires the `Sys.Syslog` privilege on `/nodes/{node}`, so API tokens must be granted that privilege explicitly. Use cursor-based pagination (`startcursor`/`endcursor`) for efficient incremental reads; time-range filters (`since`/`until`) accept UNIX epoch integers — note that `since` conflicts with `startcursor` and `until` conflicts with `endcursor`, so only one pagination strategy can be used per request.",
+  "examples": [
+    {
+      "summary": "Fetch the last 100 journal entries from node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "lastentries": 100
+      }
+    }
+  ],
+  "tips": [
+    "Use `lastentries` for a quick tail-style view; omit all filters to retrieve the full journal (can be very large on busy nodes).",
+    "Cursor values are opaque strings returned in prior responses; store them to implement reliable forward pagination without duplicates.",
+    "Time-range (`since`/`until`) and cursor (`startcursor`/`endcursor`) filters are mutually exclusive pairs — mixing them will result in an API error.",
+    "The node must be online and reachable by the Proxmox API; offline nodes will return an error rather than cached logs."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_syslog",
+    "get_nodes_node_status",
+    "get_nodes_node_tasks"
+  ]
+}