@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_cluster_sdn_vnets_vnet",
+  "usageNotes": "Use this to inspect the stored configuration of a specific SDN VNet, including its zone membership, VLAN tag or VXLAN VNI, and port-isolation settings. Pass `pending=true` to see unapplied changes (e.g., after editing but before running `apply_cluster_sdn`) or `running=true` to see the configuration currently active in the dataplane. Requires `SDN.Audit` or `SDN.Allocate` on `/sdn/zones/<zone>/<vnet>`; the vnet identifier must be 2–8 alphanumeric characters starting with a letter.",
+  "examples": [
+    {
+      "summary": "Fetch stored config for a VXLAN VNet called 'vnet01', also showing any pending changes",
+      "path_params": {
+        "vnet": "vnet01"
+      },
+      "params": {
+        "pending": true
+      }
+    }
+  ],
+  "tips": [
+    "The `state` field in the response indicates lifecycle status: 'new' means created but never applied, 'changed' means edited since last apply, 'deleted' means queued for removal.",
+    "Use `pending=true` after any SDN edit to diff what will change before committing with the apply operation.",
+    "The `digest` field can be passed to update operations to enforce optimistic concurrency (prevents overwriting concurrent edits).",
+    "The `tag` field meaning depends on the zone type: it is a VLAN ID (1–4094) for VLAN/QinQ zones and a VXLAN VNI (1–16777215) for VXLAN/EVPN zones."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets",
+    "create_cluster_sdn_vnets",
+    "update_cluster_sdn_vnets_vnet",
+    "delete_cluster_sdn_vnets_vnet",
+    "apply_cluster_sdn",
+    "get_cluster_sdn_zones_zone"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_sdn_vnets_vnet_firewall",
+  "usageNotes": "Returns the firewall directory index for a specific SDN VNet, listing the available firewall sub-resources (typically 'rules' and 'ipset'). Use this as a discovery step before querying firewall rules or IP sets scoped to the VNet. SDN must be enabled in the cluster and the target VNet must already exist.",
+  "examples": [
+    {
+      "summary": "List firewall sub-resources for SDN VNet 'webapp1'",
+      "path_params": {
+        "vnet": "webapp1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "VNet identifiers are 2–8 alphanumeric characters starting with a letter; they are distinct from bridge names created on nodes.",
+    "This endpoint only lists available sub-resources (directory index); follow child links to 'rules' or 'ipset' endpoints to read or manage actual firewall entries.",
+    "SDN firewall rules at the VNet level are separate from node-level and VM-level firewall rules — changes here affect all traffic traversing the VNet."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets_vnet_firewall_rules",
+    "get_cluster_sdn_vnets_vnet_firewall_ipset",
+    "get_cluster_sdn_vnets",
+    "get_cluster_sdn_vnets_vnet"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_sdn_vnets_vnet_firewall_options",
+  "usageNotes": "Use this to read the current firewall configuration for a specific SDN vnet, including whether the firewall is enabled and the forward policy and log level in effect. Requires SDN.Audit or SDN.Allocate on the vnet's zone path, so API tokens with read-only SDN scope are sufficient. The vnet identifier must be 2–8 alphanumeric characters starting with a letter, matching the pattern used when the vnet was created.",
+  "examples": [
+    {
+      "summary": "Retrieve firewall options for the vnet 'prodvn01'",
+      "path_params": {
+        "vnet": "prodvn01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'enable' field defaults to 0 (disabled); if it is absent from the response, the firewall is off for this vnet.",
+    "A missing 'policy_forward' in the response means no explicit forward policy is set — check the zone-level firewall for inherited defaults.",
+    "Use the companion set operation to update these options; this endpoint is read-only."
+  ],
+  "relatedOperations": [
+    "set_cluster_sdn_vnets_vnet_firewall_options",
+    "get_cluster_sdn_vnets_vnet_firewall_rules",
+    "get_cluster_sdn_vnets_vnet"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_sdn_vnets_vnet_firewall_rules",
+  "usageNotes": "Returns the ordered list of firewall rules attached to a specific SDN VNet, including action, source/destination filters, protocol, port, and per-rule log level. Requires SDN.Audit or SDN.Allocate on '/sdn/zones/<zone>/<vnet>' — a cluster-level privilege, not per-node. SDN firewall must be enabled on the cluster and the vnet must already exist; querying a non-existent vnet returns a 500 error rather than an empty list.",
+  "examples": [
+    {
+      "summary": "List all firewall rules for the 'webvnet' SDN VNet",
+      "path_params": {
+        "vnet": "webvnet"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rules are returned in 'pos' order — position 0 is evaluated first; rule ordering matters for ACCEPT/DROP precedence.",
+    "Disabled rules (enable=0) are still returned in the list but are not enforced by the dataplane.",
+    "The 'vnet' identifier is 2–8 alphanumeric characters starting with a letter — confirm the exact identifier via get_cluster_sdn_vnets before calling this endpoint.",
+    "An empty array response means no rules are configured, not that the vnet is missing; a missing vnet returns an error."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets",
+    "get_cluster_sdn_vnets_vnet_firewall_rules_pos",
+    "create_cluster_sdn_vnets_vnet_firewall_rules",
+    "get_cluster_sdn_vnets_vnet_firewall"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_sdn_vnets_vnet_firewall_rules_pos",
+  "usageNotes": "Retrieves a single firewall rule for an SDN vnet by its zero-based position in the ruleset. Requires SDN.Audit or SDN.Allocate on the vnet's zone path; SDN must be enabled and the vnet must exist. Use this to inspect or verify a specific rule before modifying or deleting it — rule position is order-sensitive, so always confirm the pos index with the list endpoint first.",
+  "examples": [
+    {
+      "summary": "Fetch rule at position 0 for vnet 'prodvn1'",
+      "path_params": {
+        "vnet": "prodvn1",
+        "pos": 0
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rule positions are zero-based and shift when rules are inserted or deleted above them — re-query the list after any mutation to confirm current positions.",
+    "The 'enable' field is an integer (1 = enabled, 0 = disabled), not a boolean.",
+    "If 'ipversion' is absent in the response, it was auto-derived from source/dest and may not have been explicitly set."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets_vnet_firewall_rules",
+    "put_cluster_sdn_vnets_vnet_firewall_rules_pos",
+    "delete_cluster_sdn_vnets_vnet_firewall_rules_pos",
+    "post_cluster_sdn_vnets_vnet_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_cluster_sdn_vnets_vnet_subnets",
+  "usageNotes": "Lists all subnets defined under a specific SDN VNet. Use this to inspect the IP ranges and IPAM configuration attached to a VNet before allocating IPs or adding new subnets. Requires 'SDN.Audit' or 'SDN.Allocate' on the VNet's zone path; pass 'pending=true' to preview unapplied changes before running 'apply_cluster_sdn'.",
+  "examples": [
+    {
+      "summary": "List all subnets for the VNet 'vmbr10', including any pending (unapplied) changes",
+      "path_params": {
+        "vnet": "vmbr10"
+      },
+      "params": {
+        "pending": true
+      }
+    }
+  ],
+  "tips": [
+    "VNet identifiers are 2–8 alphanumeric characters and must start with a letter — validate before calling.",
+    "Use 'pending=true' after editing subnets to confirm your changes are queued before applying the SDN config cluster-wide.",
+    "Use 'running=true' to see what is currently active in the kernel/data-plane, which may differ from saved config if 'apply' has not been run.",
+    "Each item in the returned array includes a 'subnet' child link (CIDR-style key); follow it with get_cluster_sdn_vnets_vnet_subnets_subnet to inspect a single subnet's details."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets_vnet",
+    "create_cluster_sdn_vnets_vnet_subnets",
+    "get_cluster_sdn_vnets_vnet_subnets_subnet",
+    "update_cluster_sdn_vnets_vnet_subnets_subnet",
+    "delete_cluster_sdn_vnets_vnet_subnets_subnet",
+    "apply_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_cluster_sdn_vnets_vnet_subnets_subnet",
+  "usageNotes": "Reads the configuration of a specific SDN subnet within a vnet. Use the 'pending' flag to inspect changes that have been staged but not yet applied via 'apply', and 'running' to see what is currently active in the network stack — these can differ after a config change before reload. Requires 'SDN.Audit' or 'SDN.Allocate' on '/sdn/zones/<zone>/<vnet>'.",
+  "examples": [
+    {
+      "summary": "Read configuration for subnet 10.10.20.0/24 within vnet 'prodnet', showing pending changes",
+      "path_params": {
+        "vnet": "prodnet",
+        "subnet": "10.10.20.0-24"
+      },
+      "params": {
+        "pending": true
+      }
+    }
+  ],
+  "tips": [
+    "The subnet path param uses pve-sdn-subnet-id format — typically the CIDR with the slash replaced by a dash (e.g. 10.0.0.0/24 → 10.0.0.0-24).",
+    "If both 'pending' and 'running' are omitted, the response reflects the stored (committed) configuration, which may differ from what is live if a reload is pending.",
+    "List available subnets for a vnet first using get_cluster_sdn_vnets_vnet_subnets before calling this endpoint to confirm valid subnet IDs."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets_vnet_subnets",
+    "get_cluster_sdn_vnets_vnet",
+    "get_cluster_sdn_vnets",
+    "get_cluster_sdn_zones_zone"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_cluster_sdn_zones",
+  "usageNotes": "Use this to enumerate all SDN zones defined in the cluster before creating VNets, subnets, or diagnosing overlay networking. SDN must be enabled on the cluster (requires the 'pvesdn' package and a supported kernel). The caller needs at least 'SDN.Audit' on '/sdn/zones/<zone>' for each zone they expect to see; zones without that permission are silently omitted from the response.",
+  "examples": [
+    {
+      "summary": "List only VXLAN zones, showing any pending (not-yet-applied) config changes",
+      "path_params": {},
+      "params": {
+        "type": "vxlan",
+        "pending": true
+      }
+    }
+  ],
+  "tips": [
+    "A zone with 'state': 'changed' or 'state': 'new' has edits that have not been applied yet; run the SDN apply operation to push them to the data plane.",
+    "Use 'running': true to see what is actually active on the nodes right now, which may differ from the stored config if an apply is pending.",
+    "Filter by 'type' (e.g. 'evpn', 'vxlan', 'vlan') to reduce noise when managing a specific overlay technology.",
+    "The 'digest' field on each zone can be passed to update/delete operations to guard against concurrent modifications (optimistic locking)."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_zones_zone",
+    "get_cluster_sdn_vnets",
+    "get_cluster_sdn_controllers",
+    "get_cluster_sdn_ipams"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_cluster_sdn_zones_zone",
+  "usageNotes": "Use this to inspect the full configuration of a single SDN zone by its identifier. The `pending` flag is especially useful after making edits — it surfaces changes that have been saved but not yet applied via `applysdn`; the `running` flag shows the live kernel state. Requires `SDN.Allocate` on `/sdn/zones/{zone}`, which is typically an administrator-level privilege.",
+  "examples": [
+    {
+      "summary": "Fetch the configuration of an EVPN zone, including any unapplied pending changes",
+      "path_params": {
+        "zone": "evpnzone"
+      },
+      "params": {
+        "pending": true
+      }
+    }
+  ],
+  "tips": [
+    "Zone identifiers are 2–8 characters, start with a letter, and contain only alphanumeric characters — plan names accordingly before creation.",
+    "Most returned fields are zone-type-specific (e.g., `exitnodes`, `vrf-vxlan` are EVPN-only; `peers` is VXLAN-only; `tag` and `bridge` are QinQ/VLAN-only). Fields irrelevant to the zone type are omitted from the response.",
+    "The `state` field (`new`, `changed`, `deleted`) indicates whether the stored config differs from what is currently applied; a non-empty `pending` sub-object alongside `state: changed` means an apply cycle is needed.",
+    "The `digest` field can be passed to update operations as an optimistic-lock check to prevent overwriting concurrent changes."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_zones",
+    "put_cluster_sdn_zones_zone",
+    "delete_cluster_sdn_zones_zone",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_status",
+  "usageNotes": "Use this to get a combined view of the cluster and all its nodes in one call — each array item has a 'type' field ('cluster' or 'node') that determines which fields are populated. Requires Sys.Audit on / (root path). On a standalone (non-clustered) PVE host this endpoint still returns results but the cluster-type entry will reflect a single-node quorum.",
+  "examples": [
+    {
+      "summary": "Fetch cluster and node health for a three-node cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Check 'quorate: false' on the cluster-type entry first — if quorum is lost, no write operations will succeed cluster-wide.",
+    "The 'local: true' node entry identifies which node is serving the API response; useful when the PVE_HOST is a load-balanced VIP.",
+    "The 'level' field on node entries reflects the Proxmox subscription tier (e.g. 'c' = community, 'b' = basic, 's' = standard, 'p' = premium) — an empty string means no active subscription.",
+    "Use 'version' on the cluster-type entry to detect corosync config drift; version should be identical across all online nodes."
+  ],
+  "relatedOperations": [
+    "get_cluster_resources",
+    "get_nodes",
+    "get_cluster_ha_status_current",
+    "get_cluster_log"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_tasks",
+  "usageNotes": "Returns a list of recent tasks cluster-wide, each represented by a UPID (Unique Process ID) string that encodes the node, task type, PID, and start time. Use this to discover in-progress or recently completed async operations across all nodes without needing per-node queries. No special privilege is required beyond a valid authenticated session.",
+  "examples": [
+    {
+      "summary": "List all recent cluster-wide tasks",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each returned UPID can be decoded or passed to node-level task endpoints (e.g., GET /nodes/{node}/tasks/{upid}/status) to retrieve full status and log output.",
+    "The list is scoped to recent tasks; very old tasks may not appear — use node-level task history endpoints if you need historical data beyond the rolling window.",
+    "Because permissions are 'user: all', any authenticated API token can call this endpoint, but task log detail endpoints may enforce stricter per-task or per-node ACLs."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes",
+  "usageNotes": "Use this as the first call to discover all nodes in the cluster before making node-scoped requests. Any authenticated user or API token may call it. Offline or unreachable nodes are included in the response with status 'offline' and their resource fields (cpu, mem, uptime) omitted.",
+  "examples": [
+    {
+      "summary": "List all cluster nodes to check online/offline status",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Filter on status === 'online' before passing a node name to any node-scoped endpoint.",
+    "The 'node' field value is the exact string to use as the {node} path parameter in downstream calls.",
+    "cpu is returned as a fraction (e.g. 0.42 = 42%); convert before displaying.",
+    "mem and maxmem are raw bytes; divide by 1073741824 for GiB."
+  ],
+  "relatedOperations": [
+    "get_node_status",
+    "get_node_version",
+    "list_vms",
+    "list_containers"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node",
+  "usageNotes": "Use this endpoint to discover the top-level API sub-resources available under a specific node (e.g., qemu, lxc, storage, network, tasks). It acts as an index and is commonly called first to confirm a node name is valid and reachable before issuing node-scoped operations. No special privilege is required beyond being authenticated; any user can call this.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for node 'pve1'",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an array of objects with a 'name' field representing child resource names (e.g., 'qemu', 'lxc', 'storage') — use these as path segments for deeper node-scoped calls.",
+    "Node names must match the pve-node format exactly (lowercase, no spaces); the cluster node list from get_cluster_config_nodes or get_nodes can supply valid names.",
+    "If the node is offline or unreachable, the API may return an error or an empty index rather than a clean 404 — check cluster status first if results are unexpected."
+  ],
+  "relatedOperations": [
+    "get_nodes",
+    "get_cluster_config_nodes",
+    "get_cluster_resources"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_aplinfo",
+  "usageNotes": "Returns the list of available LXC appliance templates (from the Proxmox appliance repository) as seen by the specified node. The node must be online and able to reach the appliance info cache; if the cache is stale or missing, use the companion download operation first to refresh it. This endpoint requires no special privilege beyond a valid user session (permissions: user=all).",
+  "examples": [
+    {
+      "summary": "List all available appliance templates on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The list is sourced from the node-local appliance cache; if the list appears empty or outdated, trigger a cache refresh via POST /nodes/{node}/aplinfo (download action) before calling this endpoint.",
+    "Each returned object typically includes fields such as package, version, section, headline, architecture, and location — useful for filtering before downloading a template.",
+    "Results vary per node if nodes have different appliance repositories configured in /etc/apt/sources.list.d/ on the node."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_aplinfo",
+    "get_nodes_node_storage_content",
+    "post_nodes_node_lxc"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_apt",
+  "usageNotes": "Returns the APT sub-resource directory for a specific node, listing the available child endpoints (e.g., update, changelog, versions). Use this as a discovery call to confirm which APT operations are accessible before invoking them. The node must be online and reachable by the cluster; no special privilege is required beyond basic authenticated access.",
+  "examples": [
+    {
+      "summary": "List available APT sub-resources on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a directory index, not a package list — use get_nodes_node_apt_update to retrieve pending package updates.",
+    "Accessible to all authenticated users (permissions: user=all), so no admin token is needed for this call.",
+    "Child resource IDs returned here map directly to sub-paths under /nodes/{node}/apt/ for subsequent calls."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_update",
+    "get_nodes_node_apt_versions",
+    "get_nodes_node_apt_changelog"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_apt_changelog",
+  "usageNotes": "Use this to review the changelog of an installed or available APT package on a specific node before applying updates, helping you assess risk. The target node must be online and reachable by the API. Requires Sys.Modify on /nodes/{node}, which is a privileged permission — API tokens scoped to read-only roles will be denied.",
+  "examples": [
+    {
+      "summary": "Fetch the changelog for the proxmox-ve meta-package on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "name": "proxmox-ve",
+        "version": "8.2.2"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting 'version' returns the changelog for the currently available (candidate) version from the APT cache.",
+    "The response is a plain-text string (the raw Debian changelog), not JSON — handle it as a text blob.",
+    "Run get_nodes_node_apt_update first to refresh the package index so the returned changelog reflects the latest available version.",
+    "Package names must match the Debian naming pattern (lowercase, digits, hyphens, plus, dots, colons) — invalid names will be rejected."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_update",
+    "get_nodes_node_apt_versions",
+    "post_nodes_node_apt_update"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_apt_repositories",
+  "usageNotes": "Use this to audit the APT repository configuration on a specific node — useful before running updates, after a PVE version upgrade, or when troubleshooting package availability. Requires Sys.Audit on /nodes/{node}; the node must be online and reachable by the API. Check the 'errors' array in the response first — parse failures on malformed .list or .sources files will appear there and may silently block package operations.",
+  "examples": [
+    {
+      "summary": "Fetch APT repository info for node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'digest' field in the top-level response covers all parsed files; use it as an optimistic-concurrency token when pairing with a write operation that modifies repositories.",
+    "The 'standard-repos' array lists well-known Proxmox repositories (e.g., pve-no-subscription, enterprise) and shows whether each is enabled — a quick way to confirm subscription vs. community repo state.",
+    "Repositories with 'Enabled: false' are still parsed and returned; check the 'Enabled' field on each entry rather than assuming all returned repos are active.",
+    "The 'infos' array surfaces warnings (e.g., deprecated suite names or redundant entries) that do not prevent parsing but may cause unexpected behavior during upgrades."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_update",
+    "post_nodes_node_apt_repositories",
+    "get_nodes_node_apt_changelog",
+    "get_nodes_node_apt_versions"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_apt_update",
+  "usageNotes": "Returns the list of pending APT package updates already cached on the node — this is a read of the local apt cache, not a live network refresh. Call `post_nodes_node_apt_update` first to refresh the cache if you need current results. The caller needs `Sys.Modify` on `/nodes/{node}`, so API tokens scoped only to VM operations will be denied.",
+  "examples": [
+    {
+      "summary": "List pending updates on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Results reflect whatever apt last fetched; run `post_nodes_node_apt_update` (the POST variant) to trigger a live `apt-get update` before calling this.",
+    "Check the `Origin` field to distinguish Proxmox-specific packages (Origin: 'Proxmox') from upstream Debian packages — useful when deciding whether to delay updates pending PVE release notes.",
+    "NotifyStatus indicates the version for which PVE already sent an email/notification; if it matches Version the update is pending but the admin has already been alerted.",
+    "This endpoint is per-node — loop across all cluster nodes to get a full cluster-wide pending-update picture."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_apt_update",
+    "get_nodes_node_apt_changelog",
+    "get_nodes_node_apt_repositories",
+    "get_nodes_node_apt_versions"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_apt_versions",
+  "usageNotes": "Use this to inspect the installed and available versions of key Proxmox packages (e.g., pve-manager, proxmox-ve, qemu-server) on a specific node — useful before or after running apt upgrades to confirm version state. The node must be online and reachable by the API; the caller needs Sys.Audit on /nodes/{node}. This endpoint returns package state only for Proxmox-curated packages, not the full dpkg database.",
+  "examples": [
+    {
+      "summary": "List important package versions on node 'pve1'",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'Version' field is the candidate upgrade version from apt, while 'OldVersion' is what is currently installed — if they differ, an update is available for that package.",
+    "The 'RunningKernel' field is only populated for the 'proxmox-ve' meta-package entry; use it to confirm whether a kernel update requires a reboot to take effect.",
+    "The 'ManagerVersion' field reflects the live pve-manager API version and may differ from the installed package version if an upgrade happened without a service restart.",
+    "NotifyStatus shows the version for which an update notification was already sent — useful for suppressing duplicate alerts in automation."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_update",
+    "post_nodes_node_apt_update",
+    "get_nodes_node_apt_changelog"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_nodes_node_capabilities",
+  "usageNotes": "Returns the top-level capabilities index for a specific node, exposing available sub-resources (such as QEMU machine types, CPU models, etc.) that the node supports. This is a discovery/enumeration call — use it to find which capability sub-categories exist before querying a specific child resource. The node must be online and reachable by the PVE API; no special privileges are required beyond being an authenticated user.",
+  "examples": [
+    {
+      "summary": "List capability sub-resources available on node 'pve01'",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an array of objects with a 'name' property that maps to child API paths under /nodes/{node}/capabilities/{name} — follow those links to retrieve actual capability data.",
+    "Useful as a preflight check when building tooling that needs to conditionally support features (e.g., check if 'qemu' or 'cpu' sub-resources exist before querying machine types).",
+    "Works with API tokens (allowtoken: true) and requires no elevated permissions, making it safe to call from read-only service accounts."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_capabilities_qemu",
+    "get_nodes_node_capabilities_qemu_cpu",
+    "get_nodes_node_capabilities_qemu_machines"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_nodes_node_capabilities_qemu",
+  "usageNotes": "Returns the list of QEMU capability sub-endpoints available on a specific node, functioning as a discovery index rather than returning capability data directly. Use this to enumerate what QEMU capability categories (e.g., cpu, machines) the node exposes before querying them individually. The node must be online and reachable; no special privileges are required beyond authenticated access.",
+  "examples": [
+    {
+      "summary": "List available QEMU capability sub-endpoints on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is an index endpoint — it returns child link names, not actual capability values. Follow the returned 'name' entries to reach the real data (e.g., /nodes/{node}/capabilities/qemu/cpu).",
+    "Accessible to all authenticated users (permissions: user=all), so API tokens with any role can call it.",
+    "If the node is offline or the node name is wrong, the API returns a 500-level error rather than an empty array."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_capabilities_qemu_cpu",
+    "get_nodes_node_capabilities_qemu_machines"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_capabilities_qemu_cpu",
+  "usageNotes": "Use this endpoint to discover valid CPU model names before creating or reconfiguring a VM — the returned `name` values are the identifiers accepted by the `cpu` parameter in VM create/update calls. Custom models are visibility-filtered by the caller's Mapping.{Audit,Use,Modify} privilege on `/mapping/cpu/<name>`, so the list may vary between users. When targeting an ARM guest, pass `arch=aarch64`; omitting `arch` defaults to the host's native architecture.",
+  "examples": [
+    {
+      "summary": "List all available QEMU CPU models on node pve1 for x86_64 guests",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "arch": "x86_64"
+      }
+    }
+  ],
+  "tips": [
+    "Models with `abstract: true` (e.g. x86-64-v2, x86-64-v3) are PVE baseline profiles — they cannot be used as the `reported-model` field when defining a custom CPU type.",
+    "Custom CPU models appear with a `custom-` prefix in their `name`; these are defined via the `/cluster/mapping/cpu` API and stored cluster-wide.",
+    "Running this against any online node in the cluster is sufficient — the built-in model list is QEMU-version-dependent, so results may differ if nodes run different QEMU versions after a partial upgrade."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu",
+    "put_nodes_node_qemu_vmid_config",
+    "get_cluster_mapping_cpu",
+    "get_nodes_node_capabilities_qemu_machines"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_capabilities_qemu_cpu_flags",
+  "usageNotes": "Use this endpoint to discover which VM-specific CPU flags are available on a given node before configuring a guest's CPU options. The response includes a 'supported-on' list per flag so you can verify cluster-wide compatibility before live-migrating a VM with custom flags. Always pass 'arch=aarch64' explicitly when targeting ARM nodes — the endpoint returns an empty list for aarch64 since no VM-specific flags are currently defined for that architecture.",
+  "examples": [
+    {
+      "summary": "List available KVM CPU flags on an x86_64 node",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "accel": "kvm",
+        "arch": "x86_64"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting 'arch' defaults to the host's native architecture — always specify it explicitly in mixed-arch clusters to avoid ambiguous results.",
+    "The 'supported-on' array in each flag entry tells you which cluster nodes support that flag under the chosen acceleration type, making it useful for pre-migration compatibility checks.",
+    "Use 'accel=tcg' to check flag availability when KVM hardware virtualization is not present (e.g., nested virtualization or non-KVM hosts).",
+    "This endpoint requires no special privilege beyond a valid Proxmox session ('user: all'), so it is safe to expose to read-only API tokens."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_capabilities_qemu_cpu",
+    "get_nodes_node_capabilities_qemu_machines",
+    "get_nodes_node_capabilities_qemu"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_capabilities_qemu_machines",
+  "usageNotes": "Use this to discover which QEMU/KVM machine types (q35, i440fx) and specific versioned IDs are available on a given node before creating or migrating a VM. The `arch` parameter is only needed when targeting non-host architectures (e.g., querying aarch64 machine types on an x86_64 host). Results are node-specific — available versions vary by the QEMU package installed on that node.",
+  "examples": [
+    {
+      "summary": "List all available machine types on node pve1 (host default architecture)",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `id` field (e.g., 'q35-8.1+pve1') is the value to pass as `machine` when creating or updating a VM via qemu endpoints.",
+    "Versioned IDs with '+pveX' suffixes include Proxmox-specific patches; the `changes` field describes what those patches add.",
+    "If you omit `arch`, the API returns types for the host's native architecture — usually x86_64 on standard Proxmox nodes.",
+    "Run this per-node when planning cross-node VM migrations to confirm the destination node supports the same machine type version."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu",
+    "put_nodes_node_qemu_vmid_config",
+    "get_nodes_node_capabilities_qemu_cpu"
+  ]
+}