@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_ha_resources",
+  "usageNotes": "Use this endpoint to list all resources currently managed by the Proxmox HA manager; each entry's `sid` (service ID) is the handle used by all other HA resource operations such as get, update, migrate, and delete. Requires `Sys.Audit` on `/` — a cluster-level privilege, so API tokens scoped to a single node or resource will be denied. Filter by `type` (`vm` or `ct`) to narrow results when working with a mixed cluster.",
+  "examples": [
+    {
+      "summary": "List all HA-managed VMs (exclude containers)",
+      "path_params": {},
+      "params": {
+        "type": "vm"
+      }
+    }
+  ],
+  "tips": [
+    "The returned `sid` format is `<type>:<vmid>` (e.g. `vm:100`, `ct:201`); use it verbatim as the path segment when calling per-resource HA endpoints.",
+    "A resource appearing here does not guarantee it is currently running — check `state` and `crm_state` fields on the individual resource detail endpoint.",
+    "HA resources are cluster-wide config; this endpoint is valid against any cluster node, not just the primary."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources_sid",
+    "create_cluster_ha_resources",
+    "get_cluster_ha_status_current",
+    "get_cluster_ha_groups"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_cluster_ha_resources_sid",
+  "usageNotes": "Use this to inspect the HA configuration for a specific VM or container — its desired state, group membership, failback/rebalance settings, and retry limits. Requires Sys.Audit on the root path; no cluster node needs to be online to read the config. The returned `digest` field should be passed to any subsequent update call to prevent concurrent modification conflicts.",
+  "examples": [
+    {
+      "summary": "Fetch HA resource config for VM 105",
+      "path_params": {
+        "sid": "vm:105"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The sid can be given as a bare integer (e.g. '105') as a shortcut for VM/CT IDs — Proxmox resolves it automatically.",
+    "Check the `state` field to distinguish between operator-intended state (e.g. 'started') and temporary states set during maintenance.",
+    "Capture `digest` before calling the update endpoint to safely serialize concurrent changes.",
+    "A resource listed here is managed by the HA manager; if `state` is 'ignored', HA will not act on it even though it is registered."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources",
+    "create_cluster_ha_resources",
+    "update_cluster_ha_resources_sid",
+    "delete_cluster_ha_resources_sid",
+    "get_cluster_ha_status_current"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_ha_rules",
+  "usageNotes": "Use this to list all HA placement rules defined in the cluster, optionally filtering by rule type or the specific resource they govern. Requires Sys.Audit on the root path — available to any read-only audit token. Returns a flat list of rule identifiers; use a sibling endpoint to fetch individual rule details.",
+  "examples": [
+    {
+      "summary": "List all node-affinity rules in the cluster",
+      "path_params": {},
+      "params": {
+        "type": "node-affinity"
+      }
+    }
+  ],
+  "tips": [
+    "The 'resource' filter accepts HA resource IDs (e.g. 'vm:100') — useful when troubleshooting why a specific VM is pinned to certain nodes.",
+    "Rule identifiers returned here are child links; query /cluster/ha/rules/{rule} to retrieve the full rule configuration.",
+    "HA rules only apply to resources already registered under /cluster/ha/resources — verify resource membership there if a rule appears to have no effect."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources",
+    "get_cluster_ha_groups",
+    "get_cluster_ha_status_current"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_ha_rules_rule",
+  "usageNotes": "Use this to inspect a specific HA rule by its config ID — useful when verifying placement constraints before migrating VMs or modifying HA groups. Requires `Sys.Audit` on the root path (`/`), so API tokens must carry that privilege. The rule identifier must match the `pve-configid` format (alphanumeric, hyphens allowed, no spaces).",
+  "examples": [
+    {
+      "summary": "Read a node-affinity HA rule named 'prod-nodes'",
+      "path_params": {
+        "rule": "prod-nodes"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rule identifiers are case-sensitive and must be valid pve-configid strings — check with list_cluster_ha_rules first if unsure of the exact name.",
+    "The response type field distinguishes node-affinity rules (restrict which nodes a resource can run on) from resource-affinity rules (co-locate or separate resources); use this to understand the rule's effect before modifying HA group membership.",
+    "This endpoint is read-only and safe to call frequently for audit or monitoring purposes."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_rules",
+    "get_cluster_ha_groups_group",
+    "get_cluster_ha_resources_sid"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_ha_status",
+  "usageNotes": "Use this endpoint to discover the available sub-resources under the HA status tree (e.g., 'current' and 'manager_status'). It returns a directory listing of child endpoints, not actual HA state data — follow the child hrefs to retrieve live cluster status or manager details. No special privileges are required; any authenticated user can call this.",
+  "examples": [
+    {
+      "summary": "List HA status sub-resources on a cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a directory index — use the returned 'name' values to construct child paths like /cluster/ha/status/current for live HA state.",
+    "Pair with get_cluster_ha_status_current to retrieve the actual quorum and resource health summary.",
+    "No query parameters are accepted; the response shape is fixed."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_status_current",
+    "get_cluster_ha_status_manager_status",
+    "get_cluster_ha_resources",
+    "get_cluster_ha_groups"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_ha_status_current",
+  "usageNotes": "Use this endpoint to get a real-time snapshot of the entire HA subsystem in one call — it returns entries for quorum, the CRM master, each node's LRM, every HA-managed service, and fencing state. Requires Sys.Audit on the root path, so API tokens scoped to that privilege work fine. The response is an array of typed entries; always filter by the 'type' field ('quorum', 'master', 'lrm', 'service', 'fencing') since available properties differ per type.",
+  "examples": [
+    {
+      "summary": "Fetch current HA status for the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Check 'quorate' on the type='quorum' entry first — if false, the cluster has lost quorum and HA decisions are frozen.",
+    "The type='fencing' entry's 'armed-state' field indicates whether STONITH fencing is active ('armed'), standing by ('standby'), or in the process of disarming — 'disarmed' means fencing is off and node failures won't trigger automatic recovery.",
+    "Service entries (type='service') expose both 'request_state' (what the CRM wants) and 'crm_state' (what it observes) — a mismatch between these two indicates the manager is still reconciling.",
+    "The 'timestamp' on type='lrm' and type='master' entries is a Unix epoch; stale timestamps (many minutes behind wall-clock) can indicate a node's LRM is unresponsive even if the node appears online.",
+    "This endpoint is cluster-wide and does not require specifying a node — query it from any cluster member."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources",
+    "get_cluster_ha_groups",
+    "get_cluster_status",
+    "get_nodes"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_ha_status_manager_status",
+  "usageNotes": "Use this to get the full state of the Proxmox HA Manager, including the status of all Local Resource Managers (LRMs) on each node and the current disposition of every HA-managed service. Requires `Sys.Audit` on `/` — API tokens are supported. This endpoint returns a snapshot; poll it to detect HA failovers, quorum loss, or service relocation in progress.",
+  "examples": [
+    {
+      "summary": "Fetch full HA manager and LRM status across the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned object includes both the HA Manager (CRM) state and per-node LRM states — check both sections to distinguish a cluster-wide quorum problem from a single-node LRM issue.",
+    "HA Manager is only active on the quorum master node; if the master changes during a failover, this endpoint still returns consistent cluster-view data via the Proxmox cluster API layer.",
+    "Use alongside get_cluster_ha_status_current_status to cross-reference service-level HA states with the manager's internal view."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_status_current_status",
+    "get_cluster_ha_resources",
+    "get_cluster_ha_groups",
+    "get_cluster_status"
+  ]
+}

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

@@ -0,0 +1,19 @@
+{
+  "operationId": "get_cluster_jobs",
+  "usageNotes": "Use this endpoint to discover what job-related sub-endpoints are available under /cluster/jobs (e.g., scheduled tasks, realm-sync jobs). It is a navigation index only — it returns directory entries with 'subdir' names, not actual job data. No authentication privileges beyond a valid API token are required.",
+  "examples": [
+    {
+      "summary": "List available job sub-endpoints on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values (e.g., 'realm-sync', 'schedule') are the path segments to append to /cluster/jobs/ for actual job operations.",
+    "This is a pure discovery call with no side effects; safe to call at any time without impacting cluster state."
+  ],
+  "relatedOperations": [
+    "get_cluster_jobs_realm_sync",
+    "get_cluster_jobs_schedule"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_jobs_realm_sync",
+  "usageNotes": "Use this to audit all scheduled realm-sync jobs across the cluster — useful before adding a new job to avoid duplicates, or to confirm a job is enabled and scheduled correctly. Requires Sys.Audit on the root path ('/'); API tokens are supported. The response includes last-run and next-run timestamps (Unix epoch), so no additional calls are needed to determine job health at a glance.",
+  "examples": [
+    {
+      "summary": "List all configured realm-sync jobs",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "last-run and next-run are Unix timestamps — convert with 'date -d @<timestamp>' or equivalent to get human-readable times.",
+    "A job with enabled=false will not run on its schedule but remains configured; useful for temporarily suspending sync without deleting the job.",
+    "The remove-vanished field defaults to 'none' when not set, meaning stale users/groups are never pruned automatically — review this on each job if directory hygiene matters.",
+    "Use the returned 'id' values to target specific jobs via the per-job endpoints (read, update, delete, or run)."
+  ],
+  "relatedOperations": [
+    "get_cluster_jobs_realm_sync_{id}",
+    "post_cluster_jobs_realm_sync",
+    "post_cluster_jobs_realm_sync_{id}_run"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_jobs_realm_sync_id",
+  "usageNotes": "Use this to inspect the configuration of a specific realm-sync scheduled job by its job ID (a pve-configid string). The caller must hold Sys.Audit on the root path (/); API tokens are supported. This is a read-only call and returns immediately with the job definition object — no UPID or async behavior.",
+  "examples": [
+    {
+      "summary": "Read the definition of a realm-sync job named 'sync-ad-daily'",
+      "path_params": {
+        "id": "sync-ad-daily"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Job IDs follow the pve-configid format: alphanumeric plus hyphens/underscores, no spaces.",
+    "To discover valid job IDs, list all realm-sync jobs first with get_cluster_jobs_realm_sync.",
+    "The returned object includes the realm, schedule, sync options, and remove-vanished settings — useful for auditing before triggering a manual sync."
+  ],
+  "relatedOperations": [
+    "get_cluster_jobs_realm_sync",
+    "post_cluster_jobs_realm_sync",
+    "put_cluster_jobs_realm_sync_id",
+    "delete_cluster_jobs_realm_sync_id"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_jobs_schedule_analyze",
+  "usageNotes": "Use this endpoint to preview the next N fire times for a Proxmox systemd-style calendar schedule before assigning it to a backup job, replication job, or other cluster job — it validates the schedule string and shows exactly when it will trigger. The `schedule` parameter must conform to the `pve-calendar-event` format (e.g., `daily`, `mon..fri 02:00`, `*/2:00`); invalid strings return an error rather than a result set. No special privilege is required — all authenticated users can call it.",
+  "examples": [
+    {
+      "summary": "Preview the next 5 fire times for a weekday 2 AM backup schedule starting from now",
+      "path_params": {},
+      "params": {
+        "schedule": "mon..fri 02:00",
+        "iterations": 5
+      }
+    }
+  ],
+  "tips": [
+    "Omit `starttime` to anchor the simulation to the current server time; supply a UNIX timestamp to model future or past schedule windows.",
+    "The maximum `iterations` value is 100 — for long-horizon planning, chain multiple calls with successive `starttime` values offset from the last returned timestamp.",
+    "Use this before saving a job to confirm that an unfamiliar schedule expression fires as often as expected — the API validates the format server-side and will error on malformed strings."
+  ],
+  "relatedOperations": [
+    "get_cluster_jobs_realm_sync",
+    "get_nodes_node_vzdump_defaults",
+    "get_cluster_backup"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_log",
+  "usageNotes": "Use this to retrieve recent cluster-wide log entries (tasks, node events, and system messages aggregated across all cluster members). The caller must have the 'Sys.Syslog' privilege on '/' to see all entries — unprivileged users receive a filtered or empty result. Omit 'max' to receive the API default limit; set it explicitly when you need a larger or bounded window of recent activity.",
+  "examples": [
+    {
+      "summary": "Fetch the 50 most recent cluster log entries",
+      "path_params": {},
+      "params": {
+        "max": 50
+      }
+    }
+  ],
+  "tips": [
+    "Without 'Sys.Syslog' on '/', results may be silently filtered — always verify the token/user privilege if the response is unexpectedly empty.",
+    "This endpoint aggregates logs from all cluster nodes; it is not a substitute for per-node syslog or journald output.",
+    "The 'max' minimum is 1; there is no documented upper cap, but very large values can produce slow responses on busy clusters."
+  ],
+  "relatedOperations": [
+    "get_cluster_tasks",
+    "get_nodes_node_syslog",
+    "get_cluster_status"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_mapping",
+  "usageNotes": "Use this as a discovery call to list the available resource-mapping types (e.g., 'dir', 'pci', 'usb') supported by the cluster. No parameters are required and no special privileges are needed — any authenticated user or API token can call it. The returned array of objects each contain a 'name' field that corresponds to a child endpoint under /cluster/mapping/{name}.",
+  "examples": [
+    {
+      "summary": "List all cluster mapping resource types",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response acts as an index — each returned 'name' value is a valid path segment for deeper mapping endpoints like /cluster/mapping/dir or /cluster/mapping/pci.",
+    "This endpoint is safe to poll repeatedly; it is read-only and has no side effects.",
+    "API tokens are accepted (allowtoken: true), making this suitable for automation scripts that enumerate available resource types before querying specific mappings."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_dir",
+    "get_cluster_mapping_pci",
+    "get_cluster_mapping_usb"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_mapping_dir",
+  "usageNotes": "Use this endpoint to list all cluster-wide directory mappings, which abstract node-local directory paths behind logical IDs for use in VM/container configurations. The caller only sees entries where they hold Mapping.Modify, Mapping.Use, or Mapping.Audit on '/mapping/dir/<id>', so results are permission-filtered. Pass 'check-node' to validate that the mapping configuration is actually correct and usable on a specific node — any mismatches appear as severity-tagged diagnostics in the response.",
+  "examples": [
+    {
+      "summary": "List all directory mappings and validate them against node 'pve1'",
+      "path_params": {},
+      "params": {
+        "check-node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "The 'checks' field is absent from each item unless 'check-node' is supplied — always include it when troubleshooting VM startup failures related to directory mounts.",
+    "Results are permission-filtered per mapping ID, so an empty list may mean no mappings exist or the caller lacks any Mapping.* privilege.",
+    "Use the returned 'id' values as the identifier when calling per-mapping GET/PUT/DELETE endpoints under /cluster/mapping/dir/{id}."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_dir_id",
+    "post_cluster_mapping_dir",
+    "put_cluster_mapping_dir_id",
+    "delete_cluster_mapping_dir_id"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_mapping_dir_id",
+  "usageNotes": "Retrieves the full configuration of a single cluster-wide directory mapping by its config ID. The caller must hold at least one of Mapping.Use, Mapping.Modify, or Mapping.Audit on the specific mapping path — a token with only global admin may still fail if per-mapping ACLs are not set. Use this to inspect node-to-path overrides before attaching a directory mapping to a VM or container storage entry.",
+  "examples": [
+    {
+      "summary": "Fetch configuration for a directory mapping named 'local-backups'",
+      "path_params": {
+        "id": "local-backups"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The id must match a pve-configid — alphanumeric plus hyphens/underscores, no spaces.",
+    "Returns an object whose 'map' array contains per-node path overrides; check this when diagnosing why a mapping resolves differently on different nodes.",
+    "Listing available IDs first via get_cluster_mapping_dir (the directory index) avoids 404s from typos."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_dir",
+    "create_cluster_mapping_dir",
+    "update_cluster_mapping_dir_id",
+    "delete_cluster_mapping_dir_id"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_mapping_pci",
+  "usageNotes": "Returns all cluster-wide PCI hardware mappings visible to the authenticated user based on Mapping.Modify, Mapping.Use, or Mapping.Audit permissions. Use the optional `check-node` parameter to validate that each mapping's physical devices are present and healthy on a specific node — the response will then include per-mapping diagnostics (warnings or errors). The node named in `check-node` must be online and reachable for diagnostics to populate.",
+  "examples": [
+    {
+      "summary": "List all PCI mappings and validate them against node pve01",
+      "path_params": {},
+      "params": {
+        "check-node": "pve01"
+      }
+    }
+  ],
+  "tips": [
+    "Without `check-node`, the `checks` field is absent from every mapping entry — include it when troubleshooting VM passthrough failures.",
+    "PCI mappings are cluster-scoped abstractions; the `map` array entries describe per-node device bindings (node:path pairs), so a single logical mapping can cover multiple physical hosts.",
+    "Results are filtered per caller privileges — a restricted API token may see fewer mappings than an admin; audit with a root@pam token to see the full list."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_pci_id",
+    "create_cluster_mapping_pci",
+    "update_cluster_mapping_pci_id",
+    "delete_cluster_mapping_pci_id",
+    "get_cluster_mapping_usb"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_mapping_pci_id",
+  "usageNotes": "Retrieves the full configuration of a named PCI hardware mapping, including all node-to-device entries defined under that mapping ID. Caller must hold at least one of Mapping.Use, Mapping.Modify, or Mapping.Audit on the specific mapping path. The 'id' must match an existing pve-configid (alphanumeric/hyphen, no spaces); use list_cluster_mapping_pci to discover valid IDs first.",
+  "examples": [
+    {
+      "summary": "Fetch the configuration for a GPU passthrough mapping named 'gpu-rtx3090'",
+      "path_params": {
+        "id": "gpu-rtx3090"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned object includes per-node device entries (node name, PCI device IDs, IOMMU group, subsystem IDs) — useful for verifying multi-node consistency before live-migrating a VM that uses PCI passthrough.",
+    "Mapping IDs follow pve-configid format: lowercase letters, digits, and hyphens only; underscores are not valid.",
+    "If the caller only needs to enumerate available mappings without reading details, use list_cluster_mapping_pci instead to avoid needing per-mapping permissions."
+  ],
+  "relatedOperations": [
+    "list_cluster_mapping_pci",
+    "create_cluster_mapping_pci",
+    "update_cluster_mapping_pci_id",
+    "delete_cluster_mapping_pci_id"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_mapping_usb",
+  "usageNotes": "Use this to list all cluster-level USB hardware mappings that the caller has permission to see (Mapping.Modify, Mapping.Use, or Mapping.Audit on each entry). Pass check-node with a specific node name to validate that each mapping's physical USB device actually exists and is reachable on that node — errors are returned inline per mapping rather than as a top-level failure. Results are filtered by per-mapping permissions, so callers with restricted roles may see a partial list.",
+  "examples": [
+    {
+      "summary": "List all USB mappings and validate them against node pve1",
+      "path_params": {},
+      "params": {
+        "check-node": "pve1"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting check-node returns mappings quickly with no node-side validation; include it before attaching a mapping to a VM to confirm the USB device is present.",
+    "The 'error' array on each mapping item is only populated when check-node is supplied; an empty or absent error array means the mapping passed validation on that node.",
+    "USB mappings are cluster-wide logical names — the 'map' array entries bind each node to its physical USB vendor:product or path."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_usb_id",
+    "post_cluster_mapping_usb",
+    "put_cluster_mapping_usb_id",
+    "delete_cluster_mapping_usb_id",
+    "get_cluster_mapping_pci"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_mapping_usb_id",
+  "usageNotes": "Use this to retrieve the full definition of a named USB hardware mapping, including the list of nodes and their matched USB device entries. The caller must hold at least one of Mapping.Audit, Mapping.Use, or Mapping.Modify on the specific mapping path — cluster-level Sys.Audit does not substitute. The 'id' must be an exact pve-configid match; use list_cluster_mapping_usb to discover valid IDs if you do not already know the name.",
+  "examples": [
+    {
+      "summary": "Fetch the USB mapping definition for a YubiKey shared across cluster nodes",
+      "path_params": {
+        "id": "yubikey-shared"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "USB mappings bind a logical name to vendor/product (and optionally serial) filters per node; the returned object includes the per-node map entries, not a flat device list.",
+    "If a mapping is only partially configured (some nodes missing), the response will still succeed — check that each expected node appears in the returned map array.",
+    "API tokens may be used (allowtoken: true), making this safe to call from automation without a full user ticket."
+  ],
+  "relatedOperations": [
+    "list_cluster_mapping_usb",
+    "create_cluster_mapping_usb",
+    "update_cluster_mapping_usb",
+    "delete_cluster_mapping_usb"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_metrics",
+  "usageNotes": "Returns the list of available metrics server configurations (e.g., InfluxDB, Graphite) defined in the cluster. Use this to discover which external metric targets are configured before querying or modifying individual metric server entries. No parameters are required and no special privilege beyond cluster membership is needed.",
+  "examples": [
+    {
+      "summary": "List all configured cluster metric servers",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an index listing child resources by name — follow each child name to get full configuration details via the metrics server-specific endpoint.",
+    "An empty array means no external metric servers have been configured in the cluster yet.",
+    "This endpoint is useful as a pre-flight check before adding a new metric server to avoid duplicates."
+  ],
+  "relatedOperations": [
+    "get_cluster_metrics_server",
+    "create_cluster_metrics_server",
+    "update_cluster_metrics_server",
+    "delete_cluster_metrics_server"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_cluster_metrics_export",
+  "usageNotes": "Use this endpoint to pull raw time-series metrics for nodes, VMs, and containers across the cluster; requires Sys.Audit on /. By default it returns only the most recent sample set — pass `history: true` together with a `start-time` Unix epoch to bound the window and avoid very large payloads. When diagnosing a single node, combine `local-only: true` or `node-list` to reduce response size.",
+  "examples": [
+    {
+      "summary": "Fetch metrics for two specific nodes since a point in time",
+      "path_params": {},
+      "params": {
+        "history": true,
+        "node-list": "pve01,pve02",
+        "start-time": 1719532800
+      }
+    }
+  ],
+  "tips": [
+    "Response items are sorted by timestamp ascending; if you need only the latest snapshot, omit `history` and `start-time`.",
+    "The `id` field encodes object type and identity (e.g. 'node/pve01', 'qemu/100', 'lxc/200') — parse the prefix to filter by resource type.",
+    "Metric `type` values follow RRDtool semantics: gauge is an instantaneous value, counter/derive are cumulative (need delta calculation for rate).",
+    "Using `history: true` without `start-time` returns the full available retention window, which can be very large on active clusters."
+  ],
+  "relatedOperations": [
+    "get_cluster_metrics_server",
+    "get_nodes_node_rrddata",
+    "get_nodes_node_vms_vmid_rrddata"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_metrics_server",
+  "usageNotes": "Use this to list all metric server integrations configured on the cluster (e.g. InfluxDB, Graphite). Requires `Sys.Audit` on the root path — API tokens are supported. The `disable` flag on each entry indicates whether the plugin is currently active; a server appearing in the list does not guarantee it is receiving metrics.",
+  "examples": [
+    {
+      "summary": "List all configured metric servers on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Check the `disable` field on each result — a configured server with `disable: true` is not receiving any metrics.",
+    "Use `type` to distinguish InfluxDB vs. Graphite entries when multiple backends are configured.",
+    "Pair with the individual get/update endpoints (e.g. get_cluster_metrics_server_id) to inspect or modify a specific entry by its `id`."
+  ],
+  "relatedOperations": [
+    "get_cluster_metrics_server_id",
+    "create_cluster_metrics_server_influxdb",
+    "create_cluster_metrics_server_graphite",
+    "update_cluster_metrics_server_id",
+    "delete_cluster_metrics_server_id"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_metrics_server_id",
+  "usageNotes": "Use this to retrieve the full configuration of a specific external metrics server (e.g. InfluxDB or Graphite) registered in the cluster by its config ID. Requires Sys.Audit on the root path, so API tokens used for read-only monitoring dashboards are sufficient. The `id` must match a pve-configid value visible in the list returned by the sibling list operation; supplying an unknown id results in a 500-level error.",
+  "examples": [
+    {
+      "summary": "Read the configuration for an InfluxDB metrics server named 'influx-prod'",
+      "path_params": {
+        "id": "influx-prod"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The id must conform to pve-configid format: lowercase alphanumeric and hyphens only, no spaces.",
+    "Response includes connection details (host, port, protocol) and status flags; use it to verify before making write changes via the update endpoint.",
+    "API tokens with only Sys.Audit can call this — no need for Sys.Modify for a read."
+  ],
+  "relatedOperations": [
+    "get_cluster_metrics_server",
+    "create_cluster_metrics_server_id",
+    "update_cluster_metrics_server_id",
+    "delete_cluster_metrics_server_id"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_nextid",
+  "usageNotes": "Call this before creating a VM or container to obtain a free VMID that Proxmox will not assign to another resource. When called without a vmid, it returns the next available ID cluster-wide; when called with a specific vmid, it asserts that ID is currently unallocated (returning the same ID on success, or an error if already in use). Note that the returned ID is not reserved — a concurrent creation race is possible on busy clusters, so use it promptly.",
+  "examples": [
+    {
+      "summary": "Get the next free VMID (no preference)",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Pass a specific vmid (e.g. 200) to validate your desired ID is free before a planned deployment — useful in scripted provisioning workflows.",
+    "The returned VMID is not locked; on clusters with high VM creation frequency, call this immediately before the create request to minimize collision risk.",
+    "VMIDs below 100 are reserved by Proxmox; the minimum valid value is 100."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu",
+    "post_nodes_node_lxc",
+    "get_cluster_resources"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_cluster_notifications",
+  "usageNotes": "This is a directory-index endpoint that returns the list of child API resources under /cluster/notifications (e.g., endpoints, matchers, targets). Call it to discover which notification sub-resources are available before navigating to a specific child endpoint. No parameters are required and no special privileges are needed — any authenticated user or API token can call it.",
+  "examples": [
+    {
+      "summary": "List all notification sub-resource endpoints on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned objects contain a 'name' property that maps to the child endpoint path segment (e.g., 'endpoints', 'matchers', 'targets').",
+    "Use this as an entry point to traverse the notifications API tree — follow child links to manage notification targets or matchers."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints",
+    "get_cluster_notifications_matchers",
+    "get_cluster_notifications_targets"
+  ]
+}