@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_lxc_vmid_pending.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pve_remotes_remote_lxc_vmid_pending",
+  "usageNotes": "Use this to retrieve pending (unapplied) configuration changes for an LXC container on a remote PVE cluster — changes that have been queued but not yet activated, typically requiring a container restart to take effect. The caller needs Resource.Audit privilege on the remote's guest resource. If the container's node is not specified, PDM resolves it automatically; supply the node parameter to skip that lookup or to disambiguate when the same VMID exists on multiple nodes.",
+  "examples": [
+    {
+      "summary": "Get pending config for LXC 201 on remote 'pve-hetzner', auto-resolved node",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 201
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A non-empty response means the container has staged config changes that differ from its running config — a restart is usually required to apply them.",
+    "If the container is actively running, pending changes will not be visible in the current/active config; always check this endpoint before and after making config edits.",
+    "Supplying the node query parameter avoids an extra cluster lookup and is slightly faster on large PVE clusters.",
+    "Returns null per spec when no pending changes exist — treat a null/empty response as 'no pending changes', not an error."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc_vmid_config",
+    "get_pve_remotes_remote_lxc",
+    "get_pve_remotes_remote_lxc_vmid_status_current"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_lxc_vmid_rrddata.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_pve_remotes_remote_lxc_vmid_rrddata",
+  "usageNotes": "Use this endpoint to retrieve historical performance metrics (CPU, memory, disk I/O, network, uptime) for a specific LXC container managed by a PDM remote. The caller must hold `Resource.Audit` on the remote/guest path; the LXC must be known to the PDM remote (it need not be running, but the remote PVE node must be reachable). Use `AVERAGE` for trend graphs and `MAX` for peak-usage analysis — the two consolidation functions can return noticeably different values for bursty workloads.",
+  "examples": [
+    {
+      "summary": "Fetch last 24-hour average stats for LXC 101 on remote 'hetzner-pve'",
+      "path_params": {
+        "remote": "hetzner-pve",
+        "vmid": 101
+      },
+      "params": {
+        "cf": "AVERAGE",
+        "timeframe": "day"
+      }
+    }
+  ],
+  "tips": [
+    "Both `cf` and `timeframe` are required; omitting either returns a 400 error.",
+    "RRD data points that fall in periods when the container was stopped will have most fields absent (optional fields omitted) — the `time` field is always present.",
+    "The `cpu-current` value is a fraction (0.0–1.0 per core) not a percentage; multiply by 100 × `cpu-max` for a human-readable % of total capacity.",
+    "Longer timeframes (week, month, year, decade) use coarser RRD resolution, so individual spikes visible in `hour` or `day` may be smoothed out.",
+    "The remote name must match the PDM-registered remote ID exactly (case-sensitive, 2–32 chars, alphanumeric/dot/dash/underscore)."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_rrddata",
+    "get_pve_remotes_remote_node_rrddata",
+    "get_pve_remotes_remote_lxc_vmid_status_current"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_lxc_vmid_snapshot.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_pve_remotes_remote_lxc_vmid_snapshot",
+  "usageNotes": "Use this to list all snapshots for a specific LXC container on a remote PVE node managed by PDM. The response always includes a synthetic 'current' entry representing the live container state, so filter it out when you only want committed snapshots. The optional 'node' query param is useful when the remote cluster has multiple nodes and the container may be running on a specific one.",
+  "examples": [
+    {
+      "summary": "List all snapshots for LXC 101 on the 'prod-hetzner' remote",
+      "path_params": {
+        "remote": "prod-hetzner",
+        "vmid": 101
+      },
+      "params": {
+        "node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "The 'current' snapshot in the results is not a real snapshot — it represents the live running state of the container and has no snaptime.",
+    "snaptime values are Unix timestamps; convert them to ISO 8601 for human-readable output.",
+    "The 'parent' field is absent on root snapshots and on 'current'; check for its presence before traversing snapshot chains.",
+    "Requires Resource.Audit privilege on the {remote}/{vmid} ACL path — read-only API tokens scoped to that resource are sufficient."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_qemu_vmid_snapshot",
+    "get_pve_remotes_remote_lxc_vmid_snapshot_snapname_config",
+    "get_pve_remotes_remote_lxc_vmid_status_current"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_lxc_vmid_status.json

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_pve_remotes_remote_lxc_vmid_status",
+  "usageNotes": "Use this to poll real-time runtime state (CPU, memory, disk I/O, network counters, uptime, and PSI pressure metrics) for a specific LXC container on a remote PVE cluster. The remote must already be registered in PDM and the caller needs Resource.Audit on the remote/guest path. Omit the optional 'node' query parameter to let PDM locate the container automatically; supply it only when you know the exact node and want to enforce a placement assertion.",
+  "examples": [
+    {
+      "summary": "Get live status of LXC container 112 on remote 'pve-hetzner', auto-resolving the node",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "vmid": 112
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "cpu is a float ratio (0.0–1.0 × cpus), not a percentage — multiply by 100 to display as %.",
+    "disk I/O counters (diskread, diskwrite) reset to 0 on container restart; compare deltas between polls, not absolute values.",
+    "PSI pressure fields (pressurecpusome, pressureiosome, etc.) are only populated when cgroup v2 is active on the PVE host; they will be absent on older kernels.",
+    "A non-empty 'lock' field means the container is mid-operation (backup, migration, snapshot) — avoid issuing state-change calls while locked.",
+    "status will be 'stopped' for templates (template: true); runtime metrics like cpu/mem/uptime will be absent in that case."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_lxc",
+    "get_pve_remotes_remote_lxc_vmid_config",
+    "post_pve_remotes_remote_lxc_vmid_status_start",
+    "post_pve_remotes_remote_lxc_vmid_status_stop",
+    "get_pve_remotes_remote_nodes"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes",
+  "usageNotes": "Use this to enumerate all nodes in a PVE remote managed by PDM, including their live status, CPU/memory utilization, and uptime. The remote must already be registered in PDM and the caller must hold Resource.Audit on the remote resource. Node-level metrics (cpu, mem, maxcpu, maxmem, uptime) are optional fields and may be absent if a node is offline or unreachable.",
+  "examples": [
+    {
+      "summary": "List all nodes for a registered PVE remote named 'pve-hetzner'",
+      "path_params": {
+        "remote": "pve-hetzner"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Check the 'status' field on each returned node before acting on it — only 'online' nodes will have valid cpu/mem metrics.",
+    "The 'ssl_fingerprint' field can be used to verify node identity if you need to cross-check TLS trust.",
+    "Remote name must match the PDM-registered ID exactly (2–32 chars, alphanumeric/dot/dash/underscore, no leading dot or dash)."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes",
+    "get_pve_remotes_remote_version",
+    "get_pve_nodes_node_status"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node",
+  "usageNotes": "Returns the API directory index for a specific node under a PDM-registered PVE remote — use it to discover which child endpoints are available for that node (e.g. guests, storage, tasks). Both the remote name and the node name must already exist in PDM; the node name matches the Proxmox cluster node name (not a hostname). The response type is null in the schema because PDM returns a list of child endpoint descriptors rather than structured node data.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for node 'pve1' on remote 'hetzner-prod'",
+      "path_params": {
+        "remote": "hetzner-prod",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The node name must match exactly as registered in the PVE cluster — check get_pve_remotes_remote_nodes for valid node names under a remote.",
+    "This is a directory index; the useful data lives in child endpoints (guests, tasks, etc.), not in this response itself.",
+    "API tokens are accepted (allowtoken: true), so service-account tokens with minimal scope work fine for this read-only call."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes",
+    "get_pve_remotes"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_apt.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_apt",
+  "usageNotes": "Returns the directory index of APT sub-endpoints available for a specific node on a managed PVE remote, acting as a discovery call before invoking child operations such as package listing or update checks. No query parameters are required, but the remote must be registered in PDM and the target node must be reachable. The response schema is typed as null in the current PDM spec, so treat the response as a navigation index rather than actionable data.",
+  "examples": [
+    {
+      "summary": "List APT sub-endpoints for node 'pve1' on the remote named 'hetzner-pve'",
+      "path_params": {
+        "remote": "hetzner-pve",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Use this endpoint to confirm which APT child routes are exposed before calling update/upgrade operations on the node.",
+    "If the call returns an error, verify the remote is online and healthy in PDM before troubleshooting node-level connectivity.",
+    "Token-based auth (allowtoken: true) is supported, making this safe to call from automation without a full user session."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_apt_update",
+    "get_pve_remotes_remote_nodes_node_apt_versions",
+    "get_pve_remotes_remote_nodes_node"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_apt_changelog.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_apt_changelog",
+  "usageNotes": "Use this to inspect the Debian/apt changelog for a package on a remote PVE node before deciding whether to apply an update — useful for reviewing what changes are included in a pending upgrade. The `name` query parameter is required and must match the exact Debian package name; omit `version` to retrieve the changelog for the currently available candidate version. The remote must be reachable and the calling user must hold `Resource.Modify` on the remote/node/system path.",
+  "examples": [
+    {
+      "summary": "Fetch the changelog for the pve-manager package at its candidate version on a remote node",
+      "path_params": {
+        "remote": "hetzner-pve1",
+        "node": "pve1"
+      },
+      "params": {
+        "name": "pve-manager"
+      }
+    }
+  ],
+  "tips": [
+    "If you need the changelog for a specific installed version rather than the candidate, supply the `version` query parameter (e.g., the version string shown by `apt-cache show`).",
+    "Returns a plain-text string — the full Debian changelog — so expect a multi-line block of text, not a structured object.",
+    "The remote ID must satisfy the pattern ^(?:[A-Za-z0-9_][A-Za-z0-9._\\-]*)$ with a length of 2–32 characters; double-check the remote name if you receive a validation error."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_apt_update",
+    "get_pve_remotes_remote_nodes_node_apt_versions",
+    "post_pve_remotes_remote_nodes_node_apt_upgrade"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_apt_repositories.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_apt_repositories",
+  "usageNotes": "Use this endpoint to inspect the APT repository configuration on a specific node of a PVE remote — useful for verifying that enterprise/community repos are correctly configured and no-subscription repos are present before running updates. The caller must hold Resource.Audit privilege on the remote's node system path; the target node must be online and reachable by PDM. Note that the spec declares returns as null, so consumers should treat any meaningful payload as implementation-defined.",
+  "examples": [
+    {
+      "summary": "List APT repositories on node 'pve01' of the 'hetzner-pve' remote",
+      "path_params": {
+        "remote": "hetzner-pve",
+        "node": "pve01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'node' path param accepts 'localhost' as a special value when PDM itself is a PVE node.",
+    "Cross-reference results with update-related endpoints to confirm repo hygiene before scheduling apt upgrades.",
+    "No query parameters are accepted; all inputs are path-only."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_apt_update",
+    "get_pve_remotes_remote_nodes_node_apt_changelog"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_apt_update.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_apt_update",
+  "usageNotes": "Use this to check whether a remote PVE node has pending APT package updates before scheduling maintenance — useful for patch audits across managed remotes. The response reflects the last cached apt cache state on the node; run an apt update on the node first if you need current data. Requires Resource.Modify on the remote/node/system path, so API tokens scoped below that level will be rejected.",
+  "examples": [
+    {
+      "summary": "List pending APT updates for node pve1 on remote hetzner-de",
+      "path_params": {
+        "remote": "hetzner-de",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The Version field is the candidate version; OldVersion is what is currently installed — diff them to gauge update severity.",
+    "An empty array means no updates are pending (or the apt cache is stale); trigger an apt-get update on the node if the list looks unexpectedly empty.",
+    "Cross-reference Origin field against 'Proxmox' to distinguish PVE-specific packages from upstream Debian packages."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_apt_changelog",
+    "post_pve_remotes_remote_nodes_node_apt_update"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_config.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_config",
+  "usageNotes": "Retrieves the configuration for a specific node within a registered PVE remote in Proxmox Datacenter Manager. Use this to inspect per-node settings (e.g., address, fingerprint, capabilities) for a remote cluster node. Requires the Resource.Audit privilege on the remote/node ACL path; the remote must already be registered in PDM.",
+  "examples": [
+    {
+      "summary": "Fetch config for node 'pve1' on the remote named 'hetzner-cluster'",
+      "path_params": {
+        "remote": "hetzner-cluster",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'node' path param accepts 'localhost' as a special value to reference the local node of the remote.",
+    "Returns null (empty body) per the spec — the actual node config data is embedded in the HTTP response payload; check for a non-error status code rather than parsing a typed return value.",
+    "Remote IDs must be 2–32 characters and match [A-Za-z0-9_][A-Za-z0-9._-]* — avoid spaces or special characters when registering remotes."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes",
+    "get_pve_remotes_remote_config",
+    "get_pve_remotes"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_firewall.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_firewall",
+  "usageNotes": "Returns the firewall directory index for a specific node on a PDM-managed PVE remote — use this to discover which firewall sub-resources (rules, options, refs, etc.) are available before drilling into them. The remote must be reachable by PDM and the node must exist within that remote cluster. Accessible to all authenticated users; no elevated privilege required.",
+  "examples": [
+    {
+      "summary": "List firewall sub-resources for node pve1 on remote prod-cluster",
+      "path_params": {
+        "remote": "prod-cluster",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a directory index endpoint — it lists available firewall sub-endpoints, not actual firewall rules or settings.",
+    "Use the returned sub-resource names to construct subsequent calls (e.g., rules, options, refs) against the same remote/node path.",
+    "If the remote is offline or the node name is invalid, PDM will return an error rather than an empty list."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_firewall_rules",
+    "get_pve_remotes_remote_nodes_node_firewall_options",
+    "get_pve_remotes_remote_nodes_node_firewall_refs",
+    "get_pve_remotes_remote_nodes_node"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_firewall_options.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_firewall_options",
+  "usageNotes": "Use this to audit or baseline the host-level firewall configuration for a specific node managed by a PDM remote — particularly useful before making changes via the corresponding PUT endpoint. Requires Resource.Audit on the remote resource; the node must be reachable through PDM. All returned fields are optional with documented defaults, so absent fields should be interpreted as their default values (e.g., firewall enabled, all log levels nolog).",
+  "examples": [
+    {
+      "summary": "Fetch firewall options for node 'pve1' on the remote 'hetzner-de'",
+      "path_params": {
+        "remote": "hetzner-de",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "All fields in the response are optional — a missing field means the node is using the compiled-in default (e.g., enable=true, nftables=false).",
+    "Check 'enable' first: if false, all firewall rules on the node are inactive regardless of other settings.",
+    "nftables support is marked as tech preview; treat its presence cautiously in production environments.",
+    "nf_conntrack_max defaults to 262144; high-traffic nodes may need this tuned upward to avoid dropped connections.",
+    "Use this endpoint to diff configurations across nodes in a cluster to detect configuration drift."
+  ],
+  "relatedOperations": [
+    "set_pve_remotes_remote_nodes_node_firewall_options",
+    "get_pve_remotes_remote_nodes_node_firewall_rules",
+    "get_pve_remotes_remote_nodes_node_firewall_log"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_firewall_rules.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_firewall_rules",
+  "usageNotes": "Use this to audit or display the ordered host-level firewall ruleset for a specific node on a registered PDM remote. The node must be reachable by PDM and the caller requires Resource.Audit on the remote resource path. Rules are returned in positional order (pos field), which determines evaluation sequence — position matters for ACCEPT/DROP/REJECT precedence.",
+  "examples": [
+    {
+      "summary": "List all firewall rules on node pve1 of the prod-cluster remote",
+      "path_params": {
+        "remote": "prod-cluster",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'pos' field is the rule's zero-based position in the chain; rules are evaluated top-down, so a DROP at pos 0 will block traffic before any ACCEPT lower in the list.",
+    "Disabled rules (enable=0) are listed but not evaluated by the firewall — check this field when troubleshooting unexpected traffic behavior.",
+    "The 'action' field may hold a security group name instead of ACCEPT/DROP/REJECT, indicating a group reference rather than a terminal rule.",
+    "Use 'localhost' as the node value to target the PDM host itself if it is also a PVE node."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_firewall_options",
+    "get_pve_remotes_remote_nodes_node_firewall_log",
+    "get_pve_remotes_remote_firewall_rules"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_firewall_status.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_firewall_status",
+  "usageNotes": "Use this to audit the firewall posture of a specific PVE node managed by PDM, including both the node-level firewall and the per-guest (VM/LXC) firewall state in a single call. The response distinguishes between rules that are present ('all') and rules that are active ('active'), so a guest with rules but firewall disabled will show enabled=false with a non-zero 'all' count. Requires Resource.Audit on the remote; no query parameters are needed.",
+  "examples": [
+    {
+      "summary": "Check firewall status for node 'pve1' on remote 'hetzner-de'",
+      "path_params": {
+        "remote": "hetzner-de",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A guest's 'status' property is optional — if the guest has no firewall rules configured at all, that key may be absent from the response.",
+    "The node-level 'status' block reflects the host firewall (nftables/iptables chain), while each entry in 'guests' reflects the per-VM or per-CT firewall independently.",
+    "Use 'active' vs 'all' to detect misconfiguration: if 'all' > 0 but 'enabled' is false, rules exist but the firewall is off.",
+    "The 'kind' field in each guest entry ('qemu' or 'lxc') lets you filter results by guest type without a separate lookup."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_firewall_rules",
+    "get_pve_remotes_remote_nodes_node_qemu_vmid_firewall_status",
+    "get_pve_remotes_remote_nodes_node_lxc_vmid_firewall_status",
+    "get_pve_remotes_remote"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_network.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_network",
+  "usageNotes": "Use this to inspect the network interface configuration of a specific node on a managed PVE remote — useful before provisioning VMs, validating bridge availability, or auditing SDN topology. The target node must be reachable by PDM and the caller needs Resource.Audit on the remote/node path. Use the 'interface-type' filter (e.g. 'bridge' or 'any_bridge') to narrow results when you only care about VM-facing bridges rather than the full interface list.",
+  "examples": [
+    {
+      "summary": "List all bridge interfaces on a PVE node to find available VM bridges",
+      "path_params": {
+        "remote": "pve-hetzner",
+        "node": "pve1"
+      },
+      "params": {
+        "interface-type": "bridge"
+      }
+    }
+  ],
+  "tips": [
+    "The 'active' field reflects runtime state; 'exists' reflects whether the interface is physically present. An interface can exist but be inactive.",
+    "SDN-managed interfaces appear when 'interface-type' is set to 'include_sdn' or 'vnet' — omit the filter to see all types including SDN.",
+    "Results reflect the current on-disk /etc/network/interfaces config plus runtime state; pending unapplied changes may differ from what this returns.",
+    "Use 'any_bridge' to include both standard Linux bridges and OVS bridges in a single filtered call."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node",
+    "get_pve_remotes_remote_nodes_node_network_iface"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_rrddata.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_rrddata",
+  "usageNotes": "Use this to retrieve time-series performance metrics (CPU, memory, disk, swap, network) for a specific node on a PDM-managed PVE remote. Both `cf` and `timeframe` are required — choose `AVERAGE` for trend analysis and `MAX` to surface peak utilization spikes. The caller must hold the `Resource.Audit` privilege on the remote/node resource path in PDM.",
+  "examples": [
+    {
+      "summary": "Fetch hourly average CPU and memory stats for a node named 'pve1' on the remote 'hetzner-de'",
+      "path_params": {
+        "remote": "hetzner-de",
+        "node": "pve1"
+      },
+      "params": {
+        "cf": "AVERAGE",
+        "timeframe": "hour"
+      }
+    }
+  ],
+  "tips": [
+    "All numeric metric fields are optional in each data point; gaps occur when the node was unreachable or data was not yet recorded for that RRD slot.",
+    "Use `timeframe=decade` only when you need long-term capacity planning; resolution is very coarse and individual spikes are invisible.",
+    "The `cpu-max` field represents the number of logical CPU cores, not a utilization percentage — divide `cpu-current` by `cpu-max` to get a 0–1 utilization ratio.",
+    "Disk and memory values are in bytes; convert appropriately before displaying to end users.",
+    "The `node` path parameter accepts the literal string 'localhost' to refer to the PDM host itself if it is also a PVE node."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_status",
+    "get_pve_remotes_remote_nodes",
+    "get_pve_remotes_remote_nodes_node_tasks"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_sdn.json

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_sdn",
+  "usageNotes": "Use this endpoint to retrieve the SDN (Software Defined Networking) directory index for a specific node on a registered PVE remote, listing available SDN sub-resources such as zones, vnets, or related objects. The target remote must be reachable by PDM and the node must be online; PDM proxies the request to the PVE cluster's SDN API. No query parameters are accepted — this is a pure index/navigation endpoint whose primary purpose is to enumerate available SDN child paths.",
+  "examples": [
+    {
+      "summary": "List SDN resources for node 'pve1' on remote 'hetzner-prod'",
+      "path_params": {
+        "remote": "hetzner-prod",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a directory-index endpoint; the actual SDN data (zones, vnets, subnets) is returned by child paths beneath /sdn/.",
+    "The 'permissions: user all' policy means any authenticated PDM user can call this — no special SDN privilege is required for the index itself.",
+    "If SDN is not configured on the target PVE cluster, this endpoint may return an empty array or a minimal index rather than an error."
+  ],
+  "relatedOperations": []
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_sdn_vnets_vnet.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_sdn_vnets_vnet",
+  "usageNotes": "Returns the directory index for a specific VNet under a remote PVE node's SDN configuration, serving as a navigation endpoint to discover available sub-resources for that VNet. Because the return type is null, this endpoint is used for resource discovery rather than fetching VNet configuration data — actual VNet properties are retrieved via child endpoints. The remote and node must both be reachable from PDM at call time.",
+  "examples": [
+    {
+      "summary": "Inspect available sub-resources for VNet 'vnet10' on node 'pve1' of remote 'hetzner-prod'",
+      "path_params": {
+        "remote": "hetzner-prod",
+        "node": "pve1",
+        "vnet": "vnet10"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "VNet names in Proxmox SDN are lowercase alphanumeric and up to 8 characters (e.g., 'vnet10', 'dmz').",
+    "This endpoint returns a directory listing (null body), not VNet config — use child paths discovered here to read actual SDN VNet details.",
+    "Open permissions ('user: all') mean any authenticated PDM token can call this; no special SDN privilege is required."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_sdn_vnets",
+    "get_pve_remotes_remote_nodes_node_sdn"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_sdn_vnets_vnet_mac_vrf.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_sdn_vnets_vnet_mac_vrf",
+  "usageNotes": "Retrieves the MAC-VRF (MAC Virtual Routing and Forwarding) table entry for a specific EVPN-backed VNet as seen by a given node on a remote PVE cluster. Use this to inspect the EVPN control-plane state — specifically which IP and nexthop are associated with a learned MAC address — when troubleshooting L2/L3 EVPN reachability across fabric nodes. The VNet must be backed by an EVPN zone; calling this against a plain VXLAN or VLAN zone will yield no meaningful result.",
+  "examples": [
+    {
+      "summary": "Fetch the MAC-VRF entry for VNet 'vnet10' on node 'pve01' of remote cluster 'dc-west'",
+      "path_params": {
+        "remote": "dc-west",
+        "node": "pve01",
+        "vnet": "vnet10"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'mac' field uses a locally-administered address pattern (second nibble in [02468ace]); this is normal for EVPN-generated MAC entries.",
+    "The 'nexthop' IP is the VTEP address of the remote node advertising the route — cross-reference it against node tunnel IPs to identify which physical host owns the endpoint.",
+    "If the response returns an empty or missing 'ip' field, the MAC was learned at L2 only (no ARP/ND snooping entry yet).",
+    "Use 'localhost' as the node value when targeting the PDM host's local PVE node without knowing its hostname."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_sdn_vnets_vnet",
+    "get_pve_remotes_remote_nodes_node_sdn_vnets",
+    "get_pve_remotes_remote_nodes_node_sdn"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_sdn_zones_zone.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_sdn_zones_zone",
+  "usageNotes": "Returns the API directory index for a specific SDN zone on a given node of a PDM-managed PVE remote — useful for discovering what sub-resources or actions are available under that zone path. Because this is a directory index with a null return body, it is most valuable as an exploration step before calling zone-specific child endpoints. The remote must be reachable and the node must be online; `user: all` permissions means any authenticated PDM user can call it.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for SDN zone 'vlan10' on node 'pve1' of remote 'hetzner-pve'",
+      "path_params": {
+        "remote": "hetzner-pve",
+        "node": "pve1",
+        "zone": "vlan10"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This endpoint is a directory index — the meaningful data lives in child endpoints beneath this path, not in the response body itself.",
+    "Zone names are case-sensitive and must match the SDN zone ID as configured in PVE (e.g., 'vlan10', not 'VLAN10').",
+    "If the remote or node is offline, PDM will return a connectivity error rather than a 403 — verify remote health first."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_sdn_zones",
+    "get_pve_remotes_remote_nodes_node_sdn"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_sdn_zones_zone_ip_vrf.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_sdn_zones_zone_ip_vrf",
+  "usageNotes": "Use this to inspect the IP-VRF routing entry that Proxmox SDN has programmed for an EVPN zone on a specific remote node — useful for verifying that BGP EVPN route advertisement is correct after zone or VNet changes. The target zone must be of type EVPN; calling this against a non-EVPN zone will return an error. The returned route shows where VRF traffic is being forwarded (nexthops) and which protocol installed it (typically BGP).",
+  "examples": [
+    {
+      "summary": "Retrieve the IP-VRF route entry for EVPN zone 'evpn-prod' on node 'pve1' of remote 'hetzner-de'",
+      "path_params": {
+        "remote": "hetzner-de",
+        "node": "pve1",
+        "zone": "evpn-prod"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'protocol' field indicates how the VRF route was learned — a value other than 'bgp' may indicate an EVPN control-plane issue.",
+    "An empty or missing nexthops array suggests the VRF interface is not up or BGP peering for this zone has not converged.",
+    "Cross-reference with SDN zone apply status to confirm the zone config has been pushed to FRR before interpreting results."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node_sdn_zones_zone",
+    "get_pve_remotes_remote_nodes_node_sdn_zones",
+    "get_pve_remotes_remote_nodes_node_sdn"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_pve_remotes_remote_nodes_node_status.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pve_remotes_remote_nodes_node_status",
+  "usageNotes": "Use this endpoint to retrieve live system status for a specific node on a PDM-managed PVE remote, including CPU usage, memory, root filesystem, load averages, kernel info, and boot mode. The remote must be registered in PDM and the target node must be reachable; if the node is offline or the remote is unreachable, the call will fail or return stale data. Requires the 'Resource.Audit' privilege on the remote/node path.",
+  "examples": [
+    {
+      "summary": "Get current status for node 'pve1' on the remote named 'hetzner-vps'",
+      "path_params": {
+        "remote": "hetzner-vps",
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'cpu' field is a fractional value (0.0–1.0); multiply by 100 for percentage.",
+    "The 'loadavg' array contains three string-encoded floats for 1-, 5-, and 15-minute load averages.",
+    "Check 'boot-info.mode' to confirm whether a node booted via EFI or legacy BIOS — useful after hardware changes or migrations.",
+    "Memory 'available' is optional and may be absent on older PVE versions; prefer 'free' as a fallback."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_nodes_node",
+    "get_pve_remotes_remote_nodes",
+    "get_pve_remotes_remote"
+  ]
+}