@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_cluster_ceph_metadata",
+  "usageNotes": "Use this endpoint to get a cluster-wide snapshot of all running Ceph service metadata (MON, MGR, MDS, OSD) including version strings, bind addresses, memory usage, and PVE service state. Requires Sys.Audit or Datastore.Audit on the root path; Ceph must be configured on the cluster or the response will be empty. Use scope=versions for a lightweight version-only check across nodes, and scope=all (default) when you need full daemon-level detail for health diagnostics or upgrade pre-checks.",
+  "examples": [
+    {
+      "summary": "Fetch full Ceph daemon metadata across the cluster to verify all services are on the same release before an upgrade",
+      "path_params": {},
+      "params": {
+        "scope": "all"
+      }
+    }
+  ],
+  "tips": [
+    "scope=versions is significantly lighter than scope=all — prefer it when you only need to confirm version consistency across nodes.",
+    "OSD entries are returned as an array (not a keyed object like MON/MGR/MDS); iterate by the 'id' field to correlate with osdmap data.",
+    "The 'node' key in the response reflects the Ceph binary version installed per PVE node, which may differ from the running daemon version if a package was upgraded but the service not yet restarted.",
+    "mem_swap_kb > 0 on any daemon is a red flag worth surfacing — Ceph daemons swapping under memory pressure cause significant latency."
+  ],
+  "relatedOperations": [
+    "get_cluster_ceph_status",
+    "get_cluster_ceph_flags",
+    "get_node_ceph_osd",
+    "get_node_ceph_mon",
+    "get_node_ceph_mgr"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_ceph_status",
+  "usageNotes": "Use this endpoint to get a high-level health summary of the Ceph cluster — overall health status, IOPS, throughput, and pool/OSD counts — without targeting a specific node. Requires Sys.Audit or Datastore.Audit on the root path. The cluster must have Ceph configured; calling this on a cluster with no Ceph deployment will return an error.",
+  "examples": [
+    {
+      "summary": "Fetch Ceph cluster health and performance overview",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned object includes a 'health' sub-object with a 'status' field — values are HEALTH_OK, HEALTH_WARN, or HEALTH_ERR.",
+    "Check 'pgmap' fields (bytes_used, bytes_avail, num_pgs) for storage utilization and PG state counts.",
+    "This is a cluster-level call, not node-level — no node parameter is needed; any cluster member can serve it.",
+    "For per-OSD or per-pool detail, follow up with get_nodes_ceph_osd or get_nodes_ceph_pools on a specific node."
+  ],
+  "relatedOperations": [
+    "get_cluster_ceph_flags",
+    "get_nodes_ceph_status",
+    "get_nodes_ceph_osd",
+    "get_nodes_ceph_pools",
+    "get_nodes_ceph_mon"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_cluster_config",
+  "usageNotes": "Use this endpoint to discover the available sub-resources under `/cluster/config` (e.g., nodes, totem, join). It is a directory index with no parameters and requires `Sys.Audit` on the root path, so it is readable by any monitoring token with that privilege. Useful as a starting point before calling deeper cluster configuration endpoints.",
+  "examples": [
+    {
+      "summary": "List available cluster config sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned array contains objects with a `name` field identifying each child resource; follow those names to construct sub-paths like /cluster/config/nodes or /cluster/config/totem.",
+    "This endpoint is safe to poll frequently — it is a read-only directory index with no side effects."
+  ],
+  "relatedOperations": [
+    "get_cluster_config_nodes",
+    "get_cluster_config_totem",
+    "get_cluster_config_join"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_config_apiversion",
+  "usageNotes": "Call this before initiating a cluster join workflow to confirm the target node supports the join API version your client expects. Requires Sys.Audit on / — available to API tokens. Currently always returns 1; check for values greater than your minimum supported version before proceeding.",
+  "examples": [
+    {
+      "summary": "Check the cluster join API version before adding a new node",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "No parameters required — the endpoint is a simple capability probe.",
+    "Use this as a pre-flight check in node-join automation to guard against version mismatches.",
+    "The returned integer is the API version, not the Proxmox VE release version."
+  ],
+  "relatedOperations": [
+    "get_cluster_config",
+    "post_cluster_config_join",
+    "get_cluster_config_join"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_config_join",
+  "usageNotes": "Use this before adding a new node to an existing Proxmox VE cluster — it returns the corosync link addresses, certificate fingerprints, and totem configuration that the joining node needs. Requires Sys.Audit on the root path; run it against an already-clustered node, not the node being joined. The returned `pve_fp` values must be passed verbatim to the join request to establish mutual trust.",
+  "examples": [
+    {
+      "summary": "Fetch join info from the default (connected) node",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Omit the `node` param to get info for whichever node you are connected to — the most common usage.",
+    "Use `pve_fp` from each entry in `nodelist` to verify TLS fingerprints before trusting cluster traffic.",
+    "The `totem` object reflects the live corosync totem settings; compare it against your target node's corosync.conf to catch link-count mismatches before attempting a join.",
+    "This endpoint is read-only and safe to call repeatedly — use it to audit cluster membership or confirm a node came back after maintenance."
+  ],
+  "relatedOperations": [
+    "post_cluster_config_join",
+    "get_cluster_config_nodes",
+    "get_cluster_status"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_config_nodes",
+  "usageNotes": "Returns the list of node names participating in the Corosync cluster quorum as defined in the cluster configuration. Use this to enumerate cluster members before targeting node-specific operations. Note that this reflects the configured node list, not live membership — a node may be listed here but currently offline.",
+  "examples": [
+    {
+      "summary": "List all Corosync cluster nodes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This endpoint reads the static cluster config (/etc/pve/corosync.conf), not real-time quorum state — use the cluster status endpoint to check which nodes are actually online.",
+    "Requires Sys.Audit on the root path; API tokens with that privilege work without additional scoping.",
+    "Each returned 'node' value matches the node name used in other node-scoped paths (e.g., /nodes/{node}/...)."
+  ],
+  "relatedOperations": [
+    "get_cluster_status",
+    "get_nodes",
+    "get_cluster_config"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_config_qdevice",
+  "usageNotes": "Returns the current status of the cluster QDevice (quorum device), which is a lightweight tie-breaker service used to provide quorum in two-node Proxmox clusters. Call this to verify whether the QDevice is reachable and vote-contributing before maintenance or node reboots. Requires the QDevice to have been previously configured via corosync; the response will be minimal or error-like if no QDevice is configured.",
+  "examples": [
+    {
+      "summary": "Check QDevice status on a two-node cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A two-node cluster without a QDevice has no quorum majority — losing one node brings the whole cluster down. This endpoint lets you confirm the QDevice is actively contributing a vote before taking a node offline.",
+    "If the cluster was never configured with a QDevice, this endpoint typically returns an empty object or a state indicating 'not configured' rather than an error.",
+    "The QDevice process runs on an external lightweight host (e.g., a small VPS or Pi); confirm that host is reachable at the network level if this call returns a degraded state."
+  ],
+  "relatedOperations": [
+    "get_cluster_config_nodes",
+    "get_cluster_status",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_config_totem",
+  "usageNotes": "Returns the active Corosync totem protocol settings for the cluster, including transport, crypto cipher/hash, token/join/consensus timers, and interface bindings. Useful when diagnosing cluster communication problems or verifying that totem parameters match expectations after a config change. Requires Sys.Audit on / — a read-only API token with that privilege is sufficient.",
+  "examples": [
+    {
+      "summary": "Retrieve current Corosync totem settings",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Totem settings are written to /etc/pve/corosync.conf — this endpoint reflects what Corosync is currently configured with, not necessarily what is live in memory if the daemon has not reloaded.",
+    "Key fields to watch: 'token' (ms before a node is declared dead, default 3000), 'crypto_cipher' and 'crypto_hash' (should be non-none in production clusters), and 'transport' (udpu for unicast, knet for Proxmox 7.1+).",
+    "If the returned object is empty or missing expected keys, the cluster config may not yet be fully initialized — confirm with get_cluster_status first."
+  ],
+  "relatedOperations": [
+    "get_cluster_config",
+    "get_cluster_status",
+    "get_cluster_config_nodes",
+    "get_cluster_config_join"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_firewall",
+  "usageNotes": "Returns the directory index of the cluster-level firewall API, listing available child endpoints (e.g. rules, groups, options, refs). Use this as a discovery call to confirm which firewall sub-resources are accessible on the cluster before querying them individually. No parameters are required and no special privilege beyond cluster membership is needed.",
+  "examples": [
+    {
+      "summary": "List available cluster firewall sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned array contains child resource names (e.g. 'rules', 'groups', 'options', 'refs') that map directly to sub-paths under /cluster/firewall/.",
+    "This endpoint is purely navigational — use child endpoints to read or modify actual firewall rules and settings.",
+    "Accessible with API tokens (allowtoken: true), making it safe to include in read-only monitoring or discovery scripts."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_options",
+    "get_cluster_firewall_rules",
+    "get_cluster_firewall_groups",
+    "get_cluster_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_firewall_aliases",
+  "usageNotes": "Returns all named IP/CIDR aliases defined at the cluster firewall level. Aliases are reusable labels (e.g. 'mgmt-net') that can be referenced in cluster or node firewall rules instead of hardcoding CIDRs. Requires Sys.Audit on the root path ('/'); API tokens are supported.",
+  "examples": [
+    {
+      "summary": "List all cluster firewall aliases",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each alias object includes a 'digest' field — pass it to update/delete calls to prevent concurrent-modification conflicts.",
+    "These aliases are cluster-scoped; node- or VM-level aliases are fetched via their respective firewall alias endpoints.",
+    "An empty array is a valid response when no aliases have been created yet."
+  ],
+  "relatedOperations": [
+    "create_cluster_firewall_alias",
+    "get_cluster_firewall_alias",
+    "update_cluster_firewall_alias",
+    "delete_cluster_firewall_alias",
+    "get_cluster_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_firewall_aliases_name",
+  "usageNotes": "Use this to retrieve the IP address or CIDR definition of a specific cluster-level firewall alias by its name. The alias name must start with a letter and match the pattern [A-Za-z][A-Za-z0-9\\-\\_]+. Requires Sys.Audit privilege at the root path; API tokens are supported.",
+  "examples": [
+    {
+      "summary": "Fetch the definition of a firewall alias named 'WebServers'",
+      "path_params": {
+        "name": "WebServers"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Alias names are case-sensitive; 'webservers' and 'WebServers' are distinct entries.",
+    "Cluster-level aliases (this endpoint) are available to all nodes; node-level aliases live under /nodes/{node}/firewall/aliases/{name}.",
+    "Use list_cluster_firewall_aliases (GET /cluster/firewall/aliases) to discover valid alias names before calling this endpoint."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_aliases",
+    "post_cluster_firewall_aliases",
+    "put_cluster_firewall_aliases_name",
+    "delete_cluster_firewall_aliases_name"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_firewall_groups",
+  "usageNotes": "Use this to enumerate all cluster-level firewall security groups before creating rules that reference them by name. Accessible to every authenticated user (privilege 'all'), so no special role is required. Each item in the response includes a digest that can be passed to write operations to guard against concurrent edits.",
+  "examples": [
+    {
+      "summary": "List all cluster firewall security groups",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Security group names are 2–18 characters, starting with a letter, and may contain letters, digits, hyphens, and underscores.",
+    "Use the returned 'digest' value when calling create/update/delete group operations to prevent race conditions from concurrent modifications.",
+    "Groups listed here are cluster-wide; node- or VM-level firewall rule sets are managed through separate endpoints."
+  ],
+  "relatedOperations": [
+    "create_cluster_firewall_group",
+    "get_cluster_firewall_group_rules",
+    "delete_cluster_firewall_group"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_cluster_firewall_groups_group",
+  "usageNotes": "Use this to inspect the ordered ruleset of a specific cluster-level security group before modifying or auditing firewall policy. The group name must already exist (use list_cluster_firewall_groups to verify); the name is case-sensitive and follows the pattern [A-Za-z][A-Za-z0-9\\-\\_]+. Rules are returned in positional order (pos field); disabled rules (enable: 0) are included in the list and must be filtered client-side if only active rules are needed.",
+  "examples": [
+    {
+      "summary": "List all rules in the 'web-tier' security group",
+      "path_params": {
+        "group": "web-tier"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The pos field is the rule's index (0-based or 1-based depending on PVE version) and is used as the child link for fetching or modifying individual rules.",
+    "Rules with enable=0 are still returned; check this field before assuming all returned rules are active.",
+    "Security groups referenced inside another group's rules appear as action values (not ACCEPT/DROP/REJECT), so you may see nested group names in the action field.",
+    "Requires Sys.Audit privilege on the root path (/); API tokens must have this privilege explicitly granted."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_groups",
+    "post_cluster_firewall_groups_group",
+    "put_cluster_firewall_groups_group_pos",
+    "delete_cluster_firewall_groups_group_pos",
+    "get_cluster_firewall_groups_group_pos"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_cluster_firewall_groups_group_pos",
+  "usageNotes": "Use this endpoint to inspect a single firewall rule within a cluster-level security group by its zero-based position index. Requires the Sys.Audit privilege on the root path ('/'). The `pos` path parameter is listed as optional in the spec but is required in practice to retrieve a specific rule — omitting it returns position 0.",
+  "examples": [
+    {
+      "summary": "Fetch rule at position 2 from the 'web-servers' security group",
+      "path_params": {
+        "group": "web-servers",
+        "pos": 2
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rule positions are zero-based; the first rule in a group is at pos=0.",
+    "The 'enable' field in the response is an integer flag (1=enabled, 0=disabled), not a boolean.",
+    "Security group names must be 2–18 characters, start with a letter, and contain only letters, digits, hyphens, or underscores.",
+    "To discover all rules in a group first, use list_cluster_firewall_groups_group (GET /cluster/firewall/groups/{group}) before targeting a specific position."
+  ],
+  "relatedOperations": [
+    "list_cluster_firewall_groups_group",
+    "create_cluster_firewall_groups_group_pos",
+    "update_cluster_firewall_groups_group_pos",
+    "delete_cluster_firewall_groups_group_pos",
+    "list_cluster_firewall_groups"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_firewall_ipset",
+  "usageNotes": "Use this to list all named IP sets defined in the cluster-level firewall configuration. Requires the Sys.Audit privilege on the root path (/). IP set names returned here are used as references in firewall rules via the '+setname' syntax, so enumerate them before creating or auditing firewall rules.",
+  "examples": [
+    {
+      "summary": "List all cluster firewall IP sets",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The digest field in each returned item can be passed to write operations to guard against concurrent modifications.",
+    "IP set names follow the pattern [A-Za-z][A-Za-z0-9\\-\\_]+ — they must start with a letter and be at least 2 characters.",
+    "This endpoint lists cluster-level IP sets only; node or VM/CT firewall IP sets are managed under their respective paths."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_ipset_name",
+    "create_cluster_firewall_ipset",
+    "delete_cluster_firewall_ipset_name",
+    "get_cluster_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_firewall_ipset_name",
+  "usageNotes": "Use this to inspect the CIDR entries inside a specific cluster-level firewall IPSet by name. Requires Sys.Audit on the root path (/). Each entry includes a cidr, optional comment, a digest (useful for passing to update/delete calls to guard against concurrent edits), and an optional nomatch flag that negates the entry (i.e., excludes that CIDR from the set).",
+  "examples": [
+    {
+      "summary": "List all CIDRs in an IPSet named 'trusted-mgmt'",
+      "path_params": {
+        "name": "trusted-mgmt"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The nomatch field, when true, means the CIDR is excluded from the set rather than included — useful for carving exceptions out of a broader range.",
+    "Capture the digest from each entry before calling an update or delete; passing it back prevents overwriting concurrent changes.",
+    "IPSet names must start with a letter and contain only letters, digits, hyphens, and underscores (2–64 chars)."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_ipsets",
+    "create_cluster_firewall_ipset_name",
+    "update_cluster_firewall_ipset_name_cidr",
+    "delete_cluster_firewall_ipset_name_cidr",
+    "delete_cluster_firewall_ipset_name"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_cluster_firewall_ipset_name_cidr",
+  "usageNotes": "Use this to retrieve the comment and any properties attached to a specific IP or CIDR entry within a named cluster-level IPSet. The IPSet must already exist and the CIDR must be a current member — use list_cluster_firewall_ipset_name to enumerate entries first. Requires Sys.Audit on '/' and supports API tokens.",
+  "examples": [
+    {
+      "summary": "Read a specific CIDR entry from the 'trusted-mgmt' IPSet",
+      "path_params": {
+        "name": "trusted-mgmt",
+        "cidr": "10.10.0.0/24"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'cidr' path param accepts a plain IP (e.g. 192.168.1.5), a CIDR (e.g. 10.0.0.0/8), or a defined alias — the format is IPorCIDRorAlias.",
+    "IPSet names must start with a letter and be 2–64 characters; the API will 404 if the name or CIDR does not exist.",
+    "This endpoint operates at the cluster firewall level — it has no node equivalent; node-level IPSets use a separate /nodes/{node}/firewall path.",
+    "The returned object typically includes 'cidr', 'nomatch' (boolean negation flag), and an optional 'comment' field."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_ipsets",
+    "get_cluster_firewall_ipset_name",
+    "create_cluster_firewall_ipset_name_cidr",
+    "update_cluster_firewall_ipset_name_cidr",
+    "delete_cluster_firewall_ipset_name_cidr"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_firewall_macros",
+  "usageNotes": "Use this to retrieve the full list of built-in Proxmox firewall macro names and their descriptions before writing firewall rules that reference a macro in the 'macro' field. No authentication privilege is required beyond a valid login — any API token or user can call this. The list is static and cluster-wide; it reflects macros baked into the Proxmox firewall engine, not custom rules.",
+  "examples": [
+    {
+      "summary": "List all available firewall macros to find the correct name before creating a rule",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Macro names are case-sensitive when used in firewall rules (e.g., 'SSH' not 'ssh').",
+    "This endpoint returns no pagination — the full macro list is always returned in a single response.",
+    "Use the 'descr' field to understand what traffic a macro covers before applying it to a rule."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_rules",
+    "create_cluster_firewall_rule",
+    "get_nodes_node_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_firewall_options",
+  "usageNotes": "Use this to read the current cluster-wide firewall configuration before making changes or auditing security posture. Requires Sys.Audit on / — available to API tokens with that privilege. A response showing 'enable': 0 means the firewall is globally disabled regardless of any node- or VM-level rules.",
+  "examples": [
+    {
+      "summary": "Read current cluster firewall options",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If 'enable' is 0 (or absent, since default is 0), all firewall rules across the cluster are inactive — node and VM rules do nothing until this is set to 1.",
+    "ebtables defaults to enabled (1); disabling it removes layer-2 bridging rules cluster-wide, which can expose VM traffic on the same bridge.",
+    "log_ratelimit is returned as a formatted string (e.g., '1,burst=5,rate=1/second'); parse it carefully if evaluating log volume.",
+    "policy_in/policy_out/policy_forward may be absent from the response if they have never been explicitly set — treat absence as no default-drop safety net."
+  ],
+  "relatedOperations": [
+    "set_cluster_firewall_options",
+    "get_cluster_firewall_groups",
+    "get_cluster_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_firewall_refs",
+  "usageNotes": "Use this endpoint to discover the valid IPSet and Alias names that can be placed in the source/dest fields of cluster firewall rules. Call it before constructing or validating a firewall rule to confirm a reference name exists at cluster scope. Requires Sys.Audit on the root path; filter by the optional `type` param to narrow results to either aliases or IPSets.",
+  "examples": [
+    {
+      "summary": "List only IPSet references available for use in cluster firewall rules",
+      "path_params": {},
+      "params": {
+        "type": "ipset"
+      }
+    }
+  ],
+  "tips": [
+    "Omit the `type` param to return both aliases and IPSets in a single call.",
+    "The `ref` field in each result is the exact token to use in a firewall rule's source or dest property (e.g., `+ipset-name` or `dc/alias-name`).",
+    "This endpoint only surfaces cluster-scope references; node- or VM-level aliases/IPSets defined elsewhere will not appear here."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_aliases",
+    "get_cluster_firewall_ipsets",
+    "get_cluster_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_firewall_rules",
+  "usageNotes": "Returns the ordered list of firewall rules defined at the cluster level — rules that apply across all nodes and VMs unless overridden at a lower scope. Requires the Sys.Audit privilege on the root path (/). Rules are returned in positional order (pos field); the pos value is what you pass to rule-specific endpoints when reading, updating, or deleting a single rule.",
+  "examples": [
+    {
+      "summary": "List all cluster-level firewall rules",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'pos' field in each returned rule is the 1-based index used by sibling endpoints (get/update/delete a single rule). Rules are evaluated top-down; lower pos = higher priority.",
+    "A rule's 'enable' field is an integer flag (1 = enabled, 0 = disabled) — disabled rules remain in the list but are not enforced.",
+    "The 'action' field may be ACCEPT, DROP, REJECT, or a security group name — check the type field ('in'/'out'/'group') to distinguish firewall rules from group references.",
+    "Cluster-level rules apply globally; node-level and VM/CT-level rules can override or supplement them. Use this endpoint to audit the base policy before troubleshooting connectivity."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_rule",
+    "create_cluster_firewall_rule",
+    "update_cluster_firewall_rule",
+    "delete_cluster_firewall_rule",
+    "get_cluster_firewall_groups",
+    "get_cluster_firewall_options"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_firewall_rules_pos",
+  "usageNotes": "Retrieves a single cluster-level firewall rule by its zero-based position index. Use this after listing rules (get_cluster_firewall_rules) to inspect a specific rule's full details before editing or deleting it. Requires Sys.Audit on the root path ('/'); the pos parameter is optional — omitting it returns rule at position 0.",
+  "examples": [
+    {
+      "summary": "Fetch the third cluster firewall rule (index 2)",
+      "path_params": {
+        "pos": 2
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rule positions are zero-based and shift when rules are inserted or deleted — always re-list before referencing a position in a subsequent write operation.",
+    "The 'action' field may be an ACCEPT/DROP/REJECT keyword or the name of a security group when the rule type is 'group'.",
+    "The 'enable' field is an integer (1 = enabled, 0 = disabled), not a boolean.",
+    "ipversion is derived automatically from source/dest addresses and is informational; you cannot set it directly."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_rules",
+    "put_cluster_firewall_rules_pos",
+    "delete_cluster_firewall_rules_pos",
+    "post_cluster_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_cluster_ha",
+  "usageNotes": "Returns the top-level HA directory index listing the available HA sub-resources (e.g. groups, resources, status). Use this as a discovery call to enumerate the HA namespace before drilling into specific sub-endpoints. Requires Sys.Audit on / — typically granted to cluster admins.",
+  "examples": [
+    {
+      "summary": "List available HA sub-resources on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'id' values correspond directly to child API paths under /cluster/ha (e.g. 'groups', 'resources', 'status').",
+    "HA is only meaningful when the cluster has at least two nodes and quorum is healthy; the directory index itself will succeed regardless of quorum state."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_groups",
+    "get_cluster_ha_resources",
+    "get_cluster_ha_status"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_ha_groups",
+  "usageNotes": "Returns the list of configured HA groups on the cluster. This endpoint is deprecated in favor of HA rules but remains useful for auditing legacy HA group assignments. Requires the Sys.Audit privilege at the root path (/); no parameters are accepted — the response is always the full group list.",
+  "examples": [
+    {
+      "summary": "List all HA groups on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response includes only the group identifier (name); fetch individual group details with the sibling get_cluster_ha_groups_{group} endpoint.",
+    "This endpoint is marked deprecated by Proxmox — prefer HA rules (get_cluster_ha_rules) for new automation.",
+    "API tokens are supported (allowtoken: true), making this safe to call from read-only monitoring tokens."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_rules",
+    "get_cluster_ha_resources",
+    "get_cluster_ha_status_current"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_ha_groups_group",
+  "usageNotes": "Retrieves the configuration of a specific HA group by its identifier, including member nodes and group options. Note that HA groups are deprecated in favor of HA rules in recent Proxmox versions — prefer the HA rules API for new configurations. Requires the Sys.Audit privilege on the root path.",
+  "examples": [
+    {
+      "summary": "Fetch configuration for the HA group named 'prod-ha'",
+      "path_params": {
+        "group": "prod-ha"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The group identifier must match the pve-configid format: alphanumeric with hyphens/underscores, no spaces.",
+    "This endpoint is marked deprecated — check /cluster/ha/rules equivalents for forward-compatible HA management.",
+    "Returns an empty object schema in the spec; actual response includes fields like 'nodes', 'nofailback', 'restricted', and 'comment'."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_groups",
+    "get_cluster_ha_status_current",
+    "get_cluster_ha_resources_sid"
+  ]
+}