@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_config_views_id",
+  "usageNotes": "Use this to inspect the full configuration of a named PDM view, including its include/exclude filter rules and layout. The caller must hold Resource.Audit on the view path; views are created and managed separately via the config/views collection endpoints. The 'id' must match the stored view name exactly — there is no fuzzy or prefix matching.",
+  "examples": [
+    {
+      "summary": "Fetch the configuration of a view named 'production-vms'",
+      "path_params": {
+        "id": "production-vms"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "View IDs follow the pattern /^(?:[A-Za-z0-9_][A-Za-z0-9._\\-]*)$/ — hyphens and dots are allowed but the first character must be alphanumeric or underscore.",
+    "The 'include-all' flag in the response means the view shows every resource unless explicitly excluded; when false, only resources matching 'include' rules appear.",
+    "Filter rules support an optional 'exact:' prefix to force literal matching rather than prefix/pattern matching on pool, tag, and remote names.",
+    "The 'layout' field is an opaque JSON-encoded string used by the PDM UI; it is safe to ignore in API consumers."
+  ],
+  "relatedOperations": [
+    "get_config_views",
+    "post_config_views",
+    "put_config_views_id",
+    "delete_config_views_id"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_nodes",
+  "usageNotes": "Exists solely for PVE API compatibility — PDM does not manage individual nodes directly, so this endpoint always returns null rather than a node list. Use cluster-level or resource-specific endpoints (e.g. Ceph cluster, auto-install) to query PDM-managed infrastructure. No privileges are required and no parameters are accepted.",
+  "examples": [
+    {
+      "summary": "Check the compatibility stub response",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns null, not an empty array — callers should guard against a null response rather than iterating the result.",
+    "This endpoint is safe to call for connectivity testing since it requires no privileges and has no side effects."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_auto_install_installations",
+    "get_config"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node",
+  "usageNotes": "Use this endpoint to retrieve the directory index for a specific PDM node, which serves as a navigation entry point listing the available sub-resources under that node. It requires no query parameters and is accessible to all authenticated users. Useful as a first call to confirm a node is reachable and to discover the resource paths it exposes.",
+  "examples": [
+    {
+      "summary": "Fetch the directory index for a node named 'pve-hetzner'",
+      "path_params": {
+        "node": "pve-hetzner"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response type is null per the schema — the practical return is a directory listing of available child endpoints rather than a data object; parse it as an array of route entries.",
+    "This endpoint is commonly used to verify node connectivity before querying guests or metrics on that node.",
+    "Token-based authentication is supported (allowtoken: true), making it safe to call from automated scripts."
+  ],
+  "relatedOperations": [
+    "get_nodes",
+    "get_nodes_node_guests",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_apt",
+  "usageNotes": "Returns the directory index of APT sub-endpoints available under a given PDM node (e.g. update, changelog, versions). Use this to discover which package-management operations are exposed for a node before calling them. No special privilege is required, but the target node must be online and reachable by PDM.",
+  "examples": [
+    {
+      "summary": "List available APT sub-endpoints for node 'pdm-node1'",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a link/directory index, not package data — follow up with sibling endpoints like get_nodes_node_apt_update or get_nodes_node_apt_versions to retrieve actionable information.",
+    "This endpoint is safe to call at any time; it is read-only and has no side effects."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_update",
+    "get_nodes_node_apt_versions",
+    "get_nodes_node_apt_changelog"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_apt_changelog",
+  "usageNotes": "Use this endpoint to inspect what changes a package update will introduce before applying it — useful for change-control review or auditing upgrade risk. The node must be reachable and the package must exist in the APT cache on that node; if no version is specified, the candidate (available-to-install) version's changelog is returned. Requires the System.Modify privilege, so API tokens scoped below that level will receive a permission error.",
+  "examples": [
+    {
+      "summary": "Fetch the changelog for the candidate version of proxmox-datacenter-manager on node pdm01",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {
+        "name": "proxmox-datacenter-manager"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting 'version' returns the changelog for the candidate (newest available) version, which is the most useful for pre-upgrade review.",
+    "The response is a plain text string (Debian-style changelog), not JSON — handle it as raw text in your client.",
+    "If the package is not in the local APT cache, the node may return an error; run an apt update equivalent first if the package was recently published."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_update",
+    "get_nodes_node_apt_versions"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_apt_repositories",
+  "usageNotes": "Use this endpoint to audit the APT repository configuration on a specific PDM node — useful before running updates or troubleshooting package availability. The response includes a top-level SHA256 digest that must be passed to any subsequent write operations to guard against concurrent modification. Check the 'errors' array first; parse failures mean the repository state is unreliable and updates should not proceed.",
+  "examples": [
+    {
+      "summary": "Retrieve APT repository list for node 'pdm1'",
+      "path_params": {
+        "node": "pdm1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The top-level 'digest' field is a concurrency guard — pass it to any repository write API to prevent overwriting concurrent changes.",
+    "The 'standard-repos' array shows whether Proxmox enterprise/no-subscription/test repos are configured and whether each is currently enabled, making it easy to spot missing or disabled official sources.",
+    "A non-empty 'errors' array means one or more /etc/apt/ files could not be parsed; treat repository state as incomplete until the errors are resolved.",
+    "The 'infos' array surfaces warnings (e.g. deprecated suite names or mixed signed/unsigned repos) even when parsing succeeds — review before applying updates."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_apt_repositories",
+    "put_nodes_node_apt_repositories",
+    "get_nodes_node_apt_update_database",
+    "get_nodes_node_apt_changelog"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_apt_update",
+  "usageNotes": "Returns the cached list of available APT package updates for the specified PDM node; this reflects the last `apt-get update` run on that node, not live repository state — call the corresponding refresh/update trigger first if you need a current snapshot. Requires only System.Audit, so API tokens scoped to read-only monitoring can use this safely. The node must be online and reachable by the PDM server.",
+  "examples": [
+    {
+      "summary": "List pending APT updates for the pdm1 node",
+      "path_params": {
+        "node": "pdm1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "An empty array response means the cached package index shows no pending updates — it does not guarantee the node is fully up to date if the index is stale.",
+    "Check the 'OldVersion' and 'Version' fields together to assess upgrade delta size before scheduling maintenance.",
+    "The 'Origin' field (e.g. 'Debian:stable', 'Proxmox') helps distinguish vendor security patches from upstream Debian updates.",
+    "Use 'localhost' as the node value when calling from a script running directly on the PDM node itself."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_apt_update"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_apt_versions",
+  "usageNotes": "Use this endpoint to check the currently installed versions of key Proxmox Backup Server packages on a given node — useful for verifying the PBS software stack before or after an `apt-upgrade` operation. The response scope is limited to packages that PDM considers important (not the full dpkg database). The node must be online and reachable by PDM; requires the System.Audit privilege.",
+  "examples": [
+    {
+      "summary": "List installed PBS package versions on node 'pbs01'",
+      "path_params": {
+        "node": "pbs01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'OldVersion' field is only present when an upgrade is available; if absent, the installed version matches 'Version'.",
+    "Use this alongside get_nodes_node_apt_update to first refresh the package index, then call this endpoint to see current vs. available versions.",
+    "Passing 'localhost' as the node name works when calling the API directly on the PDM node itself."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_update",
+    "post_nodes_node_apt_update"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_certificates",
+  "usageNotes": "Use this endpoint to retrieve the certificate directory index for a specific PDM node, which lists the certificate-related sub-resources available (e.g. custom, info). No query parameters are required and any authenticated user may call it, making it useful as a lightweight connectivity or node-readiness check before performing certificate operations. The node must be reachable by PDM; offline or unreachable nodes will return an error.",
+  "examples": [
+    {
+      "summary": "List certificate sub-resources for a PDM node",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a directory index endpoint — it enumerates sub-resources under /nodes/{node}/certificates rather than returning certificate details directly; follow up with a more specific endpoint (e.g. get_nodes_node_certificates_info) to retrieve actual certificate data.",
+    "Accessible to all authenticated users (permissions: user=all), so no special privilege is needed, but API token access is supported if you prefer token-based auth."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_certificates_info",
+    "post_nodes_node_certificates_custom",
+    "delete_nodes_node_certificates_custom"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_certificates_acme",
+  "usageNotes": "Returns the ACME certificate sub-resource directory index for a given PDM node, listing the available ACME-related endpoints under /nodes/{node}/certificates/acme. Use this as a discovery call to confirm which ACME operations are exposed for a node before attempting certificate provisioning or renewal. No special privilege is required — any authenticated user or API token can call it.",
+  "examples": [
+    {
+      "summary": "List ACME certificate sub-resources for a PDM node named 'pdm-node1'",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response type is null in the schema, meaning the payload shape is not formally described; treat the response as an opaque directory listing of child endpoints.",
+    "Use this call before invoking ACME certificate order or renewal operations to confirm the node exposes ACME support."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_certificates",
+    "get_nodes_node_certificates_acme_account",
+    "get_nodes_node_certificates_acme_certificate"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_certificates_info",
+  "usageNotes": "Use this to inspect the TLS certificates currently installed on a PDM node, including validity windows, issuer, SANs, and fingerprint. Useful for proactively checking certificate expiry before renewals or troubleshooting HTTPS trust issues. The 'node' path param accepts 'localhost' when querying the node you are directly connected to; no query params are required.",
+  "examples": [
+    {
+      "summary": "List certificate info for PDM node 'pdm-node1'",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "notafter and notbefore are UNIX epoch integers — convert with 'date -d @<value>' or JavaScript's new Date(<value>*1000) to get a human-readable timestamp.",
+    "The san array lists all Subject Alternative Names; verify the node's hostname or IP appears here if clients report certificate mismatch errors.",
+    "Use 'localhost' as the node value when calling this from a script running on the PDM node itself to avoid hardcoding the hostname."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_certificates_custom",
+    "delete_nodes_node_certificates_custom",
+    "post_nodes_node_certificates_acme_certificate"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_config",
+  "usageNotes": "Use this to read a PDM node's active configuration, including TLS cipher settings, HTTP proxy, notification email, and UI language. Requires the System.Audit privilege on the /system path — API tokens are supported. The special value 'localhost' can be used for the node name when targeting the PDM node itself; all returned fields are optional and may be absent if not configured.",
+  "examples": [
+    {
+      "summary": "Fetch configuration for the PDM node named 'pdm01'",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Use 'localhost' as the node value to target the PDM node you are directly connected to without needing its hostname.",
+    "All response fields are optional — an unconfigured node returns an empty object, which is valid.",
+    "TLS cipher fields ('ciphers-tls-1.2' and 'ciphers-tls-1.3') follow OpenSSL cipher list/ciphersuites syntax respectively; these affect the PDM API server's TLS negotiation.",
+    "Pair with the corresponding PUT/POST config endpoint to audit before making changes."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_config"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_nodes_node_dns",
+  "usageNotes": "Use this to read the current DNS resolver configuration (nameservers, search domain) for a specific PDM node. The response includes a SHA-256 digest suitable for optimistic-lock checks before issuing a write. Requires the System.Audit privilege on the node's dns path — token-based auth is supported.",
+  "examples": [
+    {
+      "summary": "Fetch DNS settings for a PDM node named 'pdm-node1'",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "dns1/dns2/dns3 and search are optional in the response — a node with minimal configuration may return only one nameserver or no search domain.",
+    "Capture the returned 'digest' value before calling a corresponding DNS write endpoint; passing a stale digest will cause the write to be rejected, preventing concurrent config clobbering.",
+    "The 'options' field surfaces any extra directives present in /etc/resolv.conf that PDM does not model explicitly (e.g. 'timeout', 'ndots')."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_dns"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_journal",
+  "usageNotes": "Use this to pull systemd journal (syslog) entries from a PDM node for diagnostics, auditing, or log review. The caller must hold the System.Audit privilege on the system/log ACL path. Pagination is cursor-based — use startcursor/endcursor from a prior response to page forward/backward; do not mix cursor and epoch parameters as they conflict.",
+  "examples": [
+    {
+      "summary": "Retrieve the last 100 journal lines from a node",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {
+        "lastentries": 100
+      }
+    }
+  ],
+  "tips": [
+    "startcursor and since are mutually exclusive — use one or the other, not both.",
+    "endcursor and until are mutually exclusive — same constraint applies.",
+    "Omitting all params returns the full journal, which can be very large on busy nodes; always scope with lastentries or a since/until epoch window.",
+    "Use 'localhost' as the node value when the API request is already targeting the local node's address.",
+    "Entries are returned as raw syslog-formatted strings; parse with standard journal tools if structured fields are needed."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_syslog",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_network",
+  "usageNotes": "Use this to enumerate all network interfaces configured on a PDM node, including their type (eth, bridge, bond, vlan, alias), IP assignments, and active/autostart state. The caller must hold the System.Audit privilege on the node's network path. Results reflect the on-disk configuration (/etc/network/interfaces) and include a digest for optimistic-lock checks when making subsequent write calls.",
+  "examples": [
+    {
+      "summary": "List all network interfaces on node 'pve1'",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'active' field reflects the live kernel state (interface UP); 'autostart' reflects whether it is set to come up at boot — these can differ if an interface was manually downed or is pending a reboot after config changes.",
+    "Bridge interfaces include a 'bridge_ports' array listing their member NICs; bond interfaces expose their member NICs via 'slaves' and the bonding mode via 'bond_mode'.",
+    "The response includes a config digest. Pass this digest to write operations (e.g., PUT /nodes/{node}/network/{iface}) to avoid overwriting concurrent changes.",
+    "Use 'localhost' as the node value when the PDM API host is itself the target node."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network_iface",
+    "put_nodes_node_network_iface",
+    "post_nodes_node_network",
+    "delete_nodes_node_network_iface",
+    "put_nodes_node_network"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_network_iface",
+  "usageNotes": "Use this to inspect the full configuration of a specific network interface on a PDM node, including IP addressing, interface type, bond/bridge membership, and active state. Requires System.Audit privilege on the specific interface path. The response reflects the on-disk /etc/network/interfaces configuration, not necessarily the live kernel state — check the 'active' field to confirm the interface is currently UP.",
+  "examples": [
+    {
+      "summary": "Read configuration for the management bridge vmbr0 on node pdm1",
+      "path_params": {
+        "node": "pdm1",
+        "iface": "vmbr0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'active' field reflects kernel UP state; 'autostart' reflects whether the interface is configured to come up at boot — both can differ after manual ifup/ifdown.",
+    "For VLAN interfaces, expect 'vlan-id' and 'vlan-raw-device' fields in the response; for bonds, expect 'bond_mode' and 'slaves'.",
+    "Interface names are capped at 15 characters (Linux IFNAMSIZ limit), which also applies to the iface path parameter.",
+    "This endpoint reads the pending configuration file. If changes have been made but not applied, the response may differ from what is currently active on the node."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_network",
+    "put_nodes_node_network_iface",
+    "post_nodes_node_network",
+    "delete_nodes_node_network_iface"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_report",
+  "usageNotes": "Returns a plain-text diagnostic report for the specified PDM node, similar to the output of `pvereport` on PVE; useful for support bundles, health checks, and auditing node configuration. Requires the `System.Audit` privilege on the `system/status` ACL path. The response is a raw string (not JSON-structured), so parse or display it as-is.",
+  "examples": [
+    {
+      "summary": "Fetch the system report for a PDM node named 'pdm01'",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Pass 'localhost' as the node value to target the PDM host you are directly connected to without knowing its registered node name.",
+    "The returned string can be large; when storing for support use, pipe it to a file rather than holding it in memory.",
+    "API tokens are accepted (allowtoken: true), so a read-only audit token with System.Audit is sufficient — no user session required."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status",
+    "get_nodes_node_syslog"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_rrddata",
+  "usageNotes": "Use this endpoint to retrieve historical performance metrics (CPU, memory, disk, network, swap, and pressure stall information) for a specific PDM node over a chosen timeframe. Both `cf` and `timeframe` are required — choose `AVERAGE` for trend analysis and `MAX` to catch spike behavior. Data points may have null/missing fields for metrics the node does not expose; always check for optional field presence before graphing.",
+  "examples": [
+    {
+      "summary": "Fetch hourly average CPU and memory metrics for the local PDM node",
+      "path_params": {
+        "node": "localhost"
+      },
+      "params": {
+        "cf": "AVERAGE",
+        "timeframe": "hour"
+      }
+    }
+  ],
+  "tips": [
+    "Use 'localhost' as the node name when querying the PDM node you are directly connected to — it is always valid regardless of the configured hostname.",
+    "AVERAGE smooths over collection intervals and is best for capacity planning; MAX reveals peak bursts that AVERAGE would hide.",
+    "The 'decade' timeframe produces very coarse data points — use it only for long-horizon trend views, not operational alerting.",
+    "metric-collection-total-time reflects PDM's own collection overhead; a rising value can indicate the node is under load or a metric source is slow.",
+    "All rate fields (disk-read, disk-write, net-in, net-out) are in bytes per second; convert before displaying as MB/s."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status",
+    "get_nodes"
+  ]
+}

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

@@ -0,0 +1,18 @@
+{
+  "operationId": "get_nodes_node_sdn",
+  "usageNotes": "Returns the SDN (Software-Defined Networking) directory index for a specific PDM node, listing available SDN sub-resources. Because it requires no privileges beyond a valid session, it is useful for probing whether SDN capabilities are exposed on a given node before issuing more specific SDN calls. The endpoint returns null per the schema, meaning it functions as a navigation anchor rather than a data payload.",
+  "examples": [
+    {
+      "summary": "List SDN sub-resources for node 'pdm1'",
+      "path_params": {
+        "node": "pdm1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns null data — treat this as a directory listing stub; actual SDN configuration is retrieved through child endpoints under /nodes/{node}/sdn/.",
+    "Accessible with any valid API token (permissions: all), so safe to call for capability discovery without elevated credentials."
+  ],
+  "relatedOperations": []
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_sdn_vnets_vnet",
+  "usageNotes": "Returns the directory index for a specific SDN VNet scoped to a given PDM node — useful as a discoverability call to confirm the VNet exists and to enumerate sub-resources available beneath it. The response type is null (an empty or minimal index object), so this endpoint is primarily a navigation/existence check rather than a data-fetch. SDN must be configured on the node and the VNet name must exactly match an existing VNet identifier.",
+  "examples": [
+    {
+      "summary": "Confirm existence and enumerate sub-resources for VNet 'vnet10' on node 'pdm01'",
+      "path_params": {
+        "node": "pdm01",
+        "vnet": "vnet10"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "VNet names in Proxmox SDN are typically short lowercase identifiers (e.g. 'vnet10', 'dmz'); use list-vnets first to get exact names.",
+    "A 404 or empty response indicates the VNet does not exist on that node or SDN is not applied — check SDN zone/subnet configuration.",
+    "This endpoint requires no special privilege beyond 'user: all', so API tokens with minimal scope can call it safely."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_vnets",
+    "get_nodes_node_sdn"
+  ]
+}

package/dist/catalog-pdm/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 look up the MAC-VRF entry for a specific EVPN vnet as seen from a node on a given remote PDM instance — useful for verifying EVPN BGP MAC/IP advertisement and nexthop reachability across sites. The `remote` query parameter is required and must identify a configured PDM remote (2–32 chars, alphanumeric with dots/dashes). The node must be reachable and the vnet must be an EVPN-type SDN object; calling against a non-EVPN vnet or an unconfigured remote will return an error.",
+  "examples": [
+    {
+      "summary": "Get the MAC-VRF entry for vnet 'vnet10' from remote 'site-b' as seen by node 'pdm1'",
+      "path_params": {
+        "node": "pdm1",
+        "vnet": "vnet10"
+      },
+      "params": {
+        "remote": "site-b"
+      }
+    }
+  ],
+  "tips": [
+    "The returned MAC address matches the locally-learned unicast MAC advertised via EVPN Type-2 routes; use the nexthop field to confirm the VTEP tunnel endpoint is correct.",
+    "If the response is empty or returns an error, verify that EVPN is enabled on the zone backing the vnet and that BGP peering with the remote is established.",
+    "The MAC pattern enforces locally-administered or universal unicast bits — multicast MACs are rejected by the schema."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_vnets_vnet_ips",
+    "get_nodes_node_sdn_zones",
+    "get_nodes_node_sdn_vnets"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_sdn_zones_zone",
+  "usageNotes": "Returns the sub-resource directory index for a specific SDN zone scoped to a PDM node — useful for discovering what child endpoints are available under a given zone. No query parameters are accepted; supply the node name and zone ID as path parameters. Accessible to all authenticated users, including API token-based access.",
+  "examples": [
+    {
+      "summary": "Fetch the directory index for SDN zone 'vlan10' on node 'pdm-node1'",
+      "path_params": {
+        "node": "pdm-node1",
+        "zone": "vlan10"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response type is null in the schema, meaning this is a directory-listing endpoint — use it to navigate available sub-resources rather than retrieve zone configuration details.",
+    "To get actual zone configuration data (type, MTU, peers, etc.), query the PDM SDN zones list endpoint at the cluster level instead of the per-node path.",
+    "Zone IDs in Proxmox SDN follow the naming constraint of alphanumeric characters with hyphens; ensure the zone value matches exactly as defined in the SDN configuration."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_zones",
+    "get_nodes_node_sdn"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_sdn_zones_zone_ip_vrf",
+  "usageNotes": "Use this to retrieve the IP-VRF route table entry for a specific EVPN SDN zone as seen from a given remote peer — useful for verifying BGP EVPN route propagation between datacenters. The zone must be of type EVPN and the remote must already be configured in PDM's SDN fabric; the node specified must be online and participating in that zone. Returns a single route object (CIDR, metric, nexthops, protocol), not a list.",
+  "examples": [
+    {
+      "summary": "Get the IP-VRF route for EVPN zone 'evpn-dc1' on node 'pve01' from remote peer 'hetzner-de'",
+      "path_params": {
+        "node": "pve01",
+        "zone": "evpn-dc1"
+      },
+      "params": {
+        "remote": "hetzner-de"
+      }
+    }
+  ],
+  "tips": [
+    "The 'remote' value must match the remote ID as configured in PDM SDN — check existing remotes via the SDN fabric API before calling this endpoint.",
+    "A missing or empty response typically means the VRF route has not been advertised yet from the remote; verify BGP session state and EVPN route-target configuration on both sides.",
+    "The returned 'protocol' field (e.g. 'bgp') indicates where the route was learned — useful for distinguishing imported EVPN routes from locally injected static routes."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_sdn_zones_zone",
+    "get_cluster_sdn_zones_zone",
+    "get_cluster_sdn_zones"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_status",
+  "usageNotes": "Use this endpoint to get a point-in-time snapshot of a PDM node's resource utilization — CPU, memory, swap, root disk, load averages, uptime, kernel version, and boot mode. The node must be reachable by the PDM cluster; calling against an offline node will fail or return stale data. Requires the System.Audit privilege on the node; API tokens are supported.",
+  "examples": [
+    {
+      "summary": "Fetch current resource status for a node named 'pbs01'",
+      "path_params": {
+        "node": "pbs01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'cpu' field is a ratio (0.0–1.0) representing usage since the last query, not a percentage — multiply by 100 for display.",
+    "Memory and disk values (memory.used, root.used, etc.) are in bytes; divide by 1073741824 for GiB.",
+    "The 'loadavg' array is ordered [1m, 5m, 15m] — the 15m value is most useful for trend alerting.",
+    "Use 'localhost' as the node name when calling from a script running on the PDM node itself.",
+    "The 'kversion' field is a legacy string; prefer 'current-kernel' for structured kernel info."
+  ],
+  "relatedOperations": [
+    "get_nodes",
+    "get_nodes_node_rrddata",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_subscription",
+  "usageNotes": "Use this to check the Proxmox Datacenter Manager subscription status on a specific node — useful for confirming whether enterprise repository access is valid before applying updates. Accessible by all authenticated users (no elevated privilege required). The `status` field is the primary signal: `active` means the key is valid; `expired`, `invalid`, or `notfound` indicate the node will fall back to the no-subscription or community repository.",
+  "examples": [
+    {
+      "summary": "Retrieve subscription status for a PDM node named 'pdm1'",
+      "path_params": {
+        "node": "pdm1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `checktime` field is a Unix timestamp; if stale (>24h), the cached status may not reflect a recently applied key.",
+    "The `key` and `serverid` fields are only returned if the caller has permission to view them — their absence does not mean no key is set.",
+    "A status of 'notfound' is the default when no subscription key has been applied; this is expected on community installations.",
+    "Use 'localhost' as the node value when querying the node you are directly connected to."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_subscription",
+    "delete_nodes_node_subscription",
+    "get_nodes_node_status"
+  ]
+}