@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_notifications_endpoints",
+  "usageNotes": "Use this to discover all configured notification endpoint types available in the cluster (e.g. gotify, sendmail, smtp, webhook). No parameters are required and no special privilege is needed beyond a valid API token. This is typically the first call when building a notification workflow — use the returned name values as child identifiers to drill into specific endpoint configurations.",
+  "examples": [
+    {
+      "summary": "List all notification endpoint types on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an index of endpoint type categories (e.g. 'gotify', 'sendmail', 'smtp', 'webhook') — not individual configured endpoints; follow child links (the 'name' field) to enumerate instances.",
+    "Accessible by all authenticated users, including unprivileged API tokens, making it safe to use in read-only automation."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_gotify",
+    "get_cluster_notifications_endpoints_sendmail",
+    "get_cluster_notifications_endpoints_smtp",
+    "get_cluster_notifications_endpoints_webhook",
+    "get_cluster_notifications_matchers"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_notifications_endpoints_gotify",
+  "usageNotes": "Use this to list all Gotify push-notification endpoints configured at the cluster level. The caller must hold the `Mapping.Audit` privilege on `/mapping/notifications`; API tokens are supported. Each returned entry includes the endpoint name (used as the identifier in notification matchers), the target server URL, enabled/disabled state, and whether the entry is user-created or built-in.",
+  "examples": [
+    {
+      "summary": "List all Gotify endpoints in the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `name` field (format: pve-configid) is the stable identifier used when referencing this endpoint in notification matchers or rules — note it down for use with related create/update/delete operations.",
+    "Entries with `disable: true` exist in config but will not receive notifications; check this field when troubleshooting missing alerts.",
+    "The `origin` field distinguishes user-created endpoints from built-in or modified-built-in ones; built-in endpoints cannot be deleted."
+  ],
+  "relatedOperations": [
+    "create_cluster_notifications_endpoints_gotify",
+    "get_cluster_notifications_endpoints_gotify_name",
+    "update_cluster_notifications_endpoints_gotify_name",
+    "delete_cluster_notifications_endpoints_gotify_name",
+    "get_cluster_notifications_matchers"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_notifications_endpoints_gotify_name",
+  "usageNotes": "Use this to retrieve the current configuration of a specific Gotify push notification endpoint by name, including its server URL, enabled/disabled state, and optional comment. Requires either Mapping.Modify or Mapping.Audit privilege on /mapping/notifications. The response includes a digest field — capture it before calling an update operation to guard against concurrent configuration changes.",
+  "examples": [
+    {
+      "summary": "Fetch the 'gotify-alerts' endpoint configuration",
+      "path_params": {
+        "name": "gotify-alerts"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'digest' value should be passed to the corresponding update operation to prevent overwriting concurrent changes.",
+    "If 'disable' is absent from the response, the endpoint is enabled (default is false/not disabled).",
+    "Endpoint names follow the pve-configid format: alphanumeric and hyphens, no spaces or special characters."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_gotify",
+    "create_cluster_notifications_endpoints_gotify",
+    "update_cluster_notifications_endpoints_gotify_name",
+    "delete_cluster_notifications_endpoints_gotify_name"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_notifications_endpoints_sendmail",
+  "usageNotes": "Returns all sendmail notification endpoints configured at the cluster level, including both user-created and built-in entries. Requires either Mapping.Modify or Mapping.Audit on /mapping/notifications — read-only audit access is sufficient. Use this to inventory available sendmail targets before creating or updating notification matchers.",
+  "examples": [
+    {
+      "summary": "List all sendmail endpoints to find active recipient targets",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'origin' field distinguishes user-created endpoints from Proxmox built-ins (builtin) and user-modified built-ins (modified-builtin) — only user-created entries can be freely deleted.",
+    "An endpoint with 'disable: true' will silently drop notifications; check this field when troubleshooting missing alerts.",
+    "Recipients can be specified as raw email addresses (mailto) or PVE user IDs (mailto-user); both fields may be populated simultaneously on a single endpoint.",
+    "This endpoint covers only sendmail-type endpoints; use the sibling gotify, smtp, or webhook list endpoints for other notification channels."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_sendmail_name",
+    "create_cluster_notifications_endpoints_sendmail",
+    "update_cluster_notifications_endpoints_sendmail_name",
+    "delete_cluster_notifications_endpoints_sendmail_name",
+    "get_cluster_notifications_matchers"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_notifications_endpoints_sendmail_name",
+  "usageNotes": "Use this to inspect the configuration of a specific sendmail notification endpoint by its config ID (name). The response includes the digest field, which you should pass to update operations to prevent concurrent modification conflicts. Requires either Mapping.Modify or Mapping.Audit privilege on /mapping/notifications.",
+  "examples": [
+    {
+      "summary": "Retrieve the 'default-mail' sendmail endpoint configuration",
+      "path_params": {
+        "name": "default-mail"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'digest' value should be supplied to update/delete calls to guard against concurrent config changes.",
+    "Recipients can be specified as direct email addresses (mailto) or as PVE user IDs (mailto-user); both fields may be present simultaneously.",
+    "If 'disable' is true in the response, this endpoint is configured but will not actually send notifications until re-enabled.",
+    "The 'from-address' field is optional; if absent, Proxmox uses the system's default MTA sender address."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_sendmail",
+    "create_cluster_notifications_endpoints_sendmail",
+    "update_cluster_notifications_endpoints_sendmail_name",
+    "delete_cluster_notifications_endpoints_sendmail_name"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_notifications_endpoints_smtp",
+  "usageNotes": "Use this to enumerate all configured SMTP notification endpoints in the cluster, including their delivery settings, recipient lists, and enabled/disabled state. Requires either Mapping.Modify or Mapping.Audit privilege on /mapping/notifications. Note that passwords are not returned by this endpoint — only configuration metadata is exposed.",
+  "examples": [
+    {
+      "summary": "List all SMTP endpoints to review configured mail delivery targets",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'origin' field distinguishes user-created endpoints from Proxmox built-ins ('builtin') and built-ins that have been modified ('modified-builtin').",
+    "A disabled endpoint (disable: true) will appear in the list but silently drops notifications — check this field when troubleshooting missing alerts.",
+    "Default encryption mode is 'tls' (port 465); if your SMTP relay requires STARTTLS use 'starttls' (port 587).",
+    "Recipients can be specified as raw email addresses (mailto) or as PVE user IDs (mailto-user), which resolve to the user's configured email address."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_smtp_name",
+    "create_cluster_notifications_endpoints_smtp",
+    "update_cluster_notifications_endpoints_smtp_name",
+    "delete_cluster_notifications_endpoints_smtp_name",
+    "get_cluster_notifications_matchers"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_notifications_endpoints_smtp_name",
+  "usageNotes": "Use this to inspect the configuration of a specific SMTP notification endpoint by its config ID — useful before updating it or verifying delivery settings. Requires either Mapping.Modify or Mapping.Audit on /mapping/notifications; note that SMTP credentials (password) are never returned, only the username. The response includes a 'digest' field that should be passed to any subsequent update call to guard against concurrent modifications.",
+  "examples": [
+    {
+      "summary": "Fetch the 'mail-alerts' SMTP endpoint configuration",
+      "path_params": {
+        "name": "mail-alerts"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'digest' in the response is a config-file hash — pass it to the corresponding update operation to prevent overwriting concurrent changes.",
+    "If 'disable' is true in the response, notifications will not be sent through this endpoint even if it is referenced by active notification rules.",
+    "SMTP passwords are write-only in Proxmox; this endpoint will never reveal them — verify authentication by testing the endpoint via the UI or a separate test notification.",
+    "Default TLS mode is 'tls' (implicit TLS, port 465); if the server requires STARTTLS, confirm 'mode' is 'starttls' and 'port' is 587."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_smtp",
+    "create_cluster_notifications_endpoints_smtp",
+    "update_cluster_notifications_endpoints_smtp_name",
+    "delete_cluster_notifications_endpoints_smtp_name"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_notifications_endpoints_webhook",
+  "usageNotes": "Returns all webhook notification endpoints configured cluster-wide. Use this to audit outbound HTTP targets before creating or modifying notification matchers. Requires 'Mapping.Audit' on '/mapping/notifications'; header and secret values are base64-encoded in the response, so decode before display.",
+  "examples": [
+    {
+      "summary": "List all webhook endpoints to audit configured targets",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'secret' field values are returned base64-encoded; decode with atob() or base64 -d before comparing.",
+    "Check the 'disable' field — disabled endpoints silently drop notifications even when referenced by an active matcher.",
+    "The 'origin' field distinguishes user-created endpoints from built-in or modified-builtin ones; built-in endpoints cannot be deleted.",
+    "Use the 'name' field values here as references when calling get/update/delete operations on individual webhook endpoints."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_webhook_name",
+    "create_cluster_notifications_endpoints_webhook",
+    "update_cluster_notifications_endpoints_webhook_name",
+    "delete_cluster_notifications_endpoints_webhook_name",
+    "get_cluster_notifications_matchers"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_cluster_notifications_endpoints_webhook_name",
+  "usageNotes": "Use this to inspect the current configuration of a named webhook notification endpoint, including its URL, HTTP method, headers, and whether it is enabled. Requires either Mapping.Modify or Mapping.Audit privilege on /mapping/notifications. The response includes a digest field — capture it when you intend to follow up with an update, to guard against concurrent modifications.",
+  "examples": [
+    {
+      "summary": "Retrieve the configuration for a webhook endpoint named 'alerts-slack'",
+      "path_params": {
+        "name": "alerts-slack"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'secret' field in the response contains base64-encoded secret values (e.g., HMAC signing keys); treat the output as sensitive.",
+    "The 'header' array entries use the format name=<name>,value=<base64 of value> — decode before displaying to users.",
+    "Use the returned 'digest' value as input to the update endpoint to prevent lost-update races in concurrent environments.",
+    "A 'disable: true' in the response means notifications are silently dropped for this endpoint even if it is otherwise correctly configured."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_webhook",
+    "create_cluster_notifications_endpoints_webhook",
+    "update_cluster_notifications_endpoints_webhook_name",
+    "delete_cluster_notifications_endpoints_webhook_name",
+    "get_cluster_notifications_matchers"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_notifications_matcher_field_values",
+  "usageNotes": "Call this before creating or updating a notification matcher to discover which metadata fields (e.g. severity, type, service) and their allowed values are recognized by the cluster. The response is purely informational — no params are accepted and results reflect what the cluster currently knows based on its configured services and event sources. Requires either Mapping.Modify or Mapping.Audit on /mapping/notifications.",
+  "examples": [
+    {
+      "summary": "List all known matcher field values for use in a new notification matcher",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'comment' field is optional and provides human-readable context for a value — check it when a value's meaning is ambiguous.",
+    "Use the returned 'field' and 'value' strings verbatim when configuring match-criteria in notification matchers via create_cluster_notifications_matcher or update_cluster_notifications_matcher.",
+    "Results are cluster-scoped and reflect dynamically discovered values — re-query after adding new notification endpoints or storage services to pick up newly registered field values."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_matchers",
+    "create_cluster_notifications_matcher",
+    "update_cluster_notifications_matcher",
+    "get_cluster_notifications_matcher_fields"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_cluster_notifications_matcher_fields",
+  "usageNotes": "Call this before creating or editing a notification matcher to discover which metadata field names are valid for match conditions (e.g. 'type', 'severity', 'hostname'). Requires Mapping.Modify or Mapping.Audit on /mapping/notifications. Takes no parameters and returns the full list of supported fields cluster-wide.",
+  "examples": [
+    {
+      "summary": "List all available notification matcher field names",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Use the returned field names as the 'field' value when constructing matcher rules via create_cluster_notifications_matcher or update_cluster_notifications_matcher.",
+    "The response only contains field names, not their allowed values — use get_cluster_notifications_matcher_field_values to enumerate valid values for a specific field."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_matchers",
+    "create_cluster_notifications_matcher",
+    "update_cluster_notifications_matcher"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_notifications_matchers",
+  "usageNotes": "Use this to retrieve all notification matchers configured at the cluster level, which control which notification targets receive alerts based on severity, field conditions, calendar windows, and other criteria. Requires at least Mapping.Use, Mapping.Audit, or Mapping.Modify on /mapping/notifications. Matchers with 'disable: true' are still returned in the list but will not route notifications at runtime.",
+  "examples": [
+    {
+      "summary": "List all cluster notification matchers",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'origin' field distinguishes user-created matchers from PVE built-ins ('builtin') and built-ins that have been customized ('modified-builtin') — useful for auditing drift from defaults.",
+    "match-field entries use the format (regex|exact):<field>=<value>, e.g. 'exact:type=vzdump' to target only backup notifications.",
+    "When 'mode' is 'all' (default), every specified match condition must be satisfied; use 'any' if any single condition being true should trigger the matcher.",
+    "Matchers reference targets by their pve-configid name; cross-check against get_cluster_notifications_targets to confirm referenced targets still exist."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_matcher",
+    "create_cluster_notifications_matcher",
+    "update_cluster_notifications_matcher",
+    "delete_cluster_notifications_matcher",
+    "get_cluster_notifications_targets",
+    "get_cluster_notifications_endpoints_sendmail"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_cluster_notifications_matchers_name",
+  "usageNotes": "Retrieves the full configuration of a single notification matcher by its config ID, including all match criteria (severity, field, calendar), target endpoints, mode, and the current digest. Use the returned digest when calling the corresponding update operation to guard against concurrent modifications. Requires either Mapping.Modify or Mapping.Audit on /mapping/notifications.",
+  "examples": [
+    {
+      "summary": "Fetch the 'critical-alerts' matcher to inspect its severity filters and targets",
+      "path_params": {
+        "name": "critical-alerts"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The digest field in the response is a concurrency token — pass it to the update endpoint to prevent overwriting changes made by another session.",
+    "If 'disable' is absent or false, the matcher is active and will route matching notifications to the listed targets.",
+    "The 'mode' field (default: 'all') controls whether ALL match conditions must be satisfied or ANY one is sufficient — verify this when debugging unexpected notification routing.",
+    "match-field entries follow the format (regex|exact):<field>=<value>; inspect this carefully when troubleshooting field-based filtering."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_matchers",
+    "create_cluster_notifications_matchers",
+    "update_cluster_notifications_matchers_name",
+    "delete_cluster_notifications_matchers_name",
+    "get_cluster_notifications_targets"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_notifications_targets",
+  "usageNotes": "Use this endpoint to enumerate all notification targets configured on the cluster before creating or updating a notification matcher or routing rule. The caller must hold at least one of Mapping.Modify, Mapping.Audit, or Mapping.Use on /mapping/notifications. Results include both built-in targets (e.g., the default sendmail target) and user-created ones; check the 'origin' and 'disable' fields to avoid referencing a disabled or unmodifiable built-in.",
+  "examples": [
+    {
+      "summary": "List all notification targets to find available sendmail and webhook endpoints",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "origin='builtin' targets cannot be deleted; origin='modified-builtin' means a built-in was customized by the user.",
+    "A target with disable=true will silently drop notifications — filter these out before assigning to a matcher.",
+    "The 'name' field uses pve-configid format (alphanumeric + hyphens, no spaces), which is required when referencing targets in notification matchers."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_matchers",
+    "get_cluster_notifications_endpoints_sendmail",
+    "get_cluster_notifications_endpoints_gotify",
+    "get_cluster_notifications_endpoints_smtp",
+    "get_cluster_notifications_endpoints_webhook"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_options",
+  "usageNotes": "Use this to read datacenter-wide settings such as keyboard layout, HTTP proxy, email address, migration network, console type, and HA/bandwidth defaults. Requires the `Sys.Audit` privilege on `/`; without it, the response is silently filtered and only a subset of options is returned. No parameters are required — the endpoint always returns the current cluster configuration object.",
+  "examples": [
+    {
+      "summary": "Fetch all datacenter options for the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response shape varies by privilege level — a token scoped below `Sys.Audit` on `/` will receive a reduced object without warning.",
+    "Pair with `update_cluster_options` (PUT /cluster/options) when you need to read-then-modify a specific setting.",
+    "Useful as a pre-flight check to confirm migration network, HA settings, or email relay before making cluster-wide changes."
+  ],
+  "relatedOperations": [
+    "update_cluster_options",
+    "get_cluster_status",
+    "get_cluster_config"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_qemu",
+  "usageNotes": "Returns a cluster-wide index of all QEMU VM entries across all nodes; useful as a quick inventory check without targeting a specific node. No parameters are required and any authenticated user may call it, but results reflect only VMs visible to the caller's permission set. Does not include LXC containers — use the equivalent cluster/lxc endpoint for those.",
+  "examples": [
+    {
+      "summary": "List all QEMU VMs across the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns VM metadata (name, VMID, node, status) but not full config details — follow up with get_nodes_node_qemu_vmid_config per VM for config specifics.",
+    "Useful for finding which node a given VMID lives on before issuing node-scoped operations.",
+    "Returned list is an array of child link objects; the 'name' field corresponds to the VMID."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_qemu_vmid_config",
+    "get_cluster_resources"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_qemu_cpu_flags",
+  "usageNotes": "Use this to discover which CPU flags are available cluster-wide and which specific nodes support each flag under a given acceleration mode (KVM or TCG). This is the correct pre-flight call before enabling CPU flags in a VM's hardware config — consult `supported-on` to avoid scheduling a VM on a node that lacks the required flag. Note that aarch64 always returns an empty list; this endpoint is only meaningful for x86_64 workloads.",
+  "examples": [
+    {
+      "summary": "List all KVM-accelerated CPU flags for x86_64, showing which cluster nodes support each",
+      "path_params": {},
+      "params": {
+        "accel": "kvm",
+        "arch": "x86_64"
+      }
+    }
+  ],
+  "tips": [
+    "The `supported-on` field in each returned item is a list of node names — if it is absent or empty for a flag, no node in the cluster supports it under the chosen acceleration type.",
+    "When using TCG (software emulation), more flags may appear available than with KVM, but performance will differ significantly; always prefer KVM for production VMs.",
+    "Pair with CPU type enumeration (e.g., get_cluster_qemu_cpu) to understand which flags are already bundled into a chosen CPU model before adding individual flag overrides."
+  ],
+  "relatedOperations": [
+    "get_cluster_qemu_cpu",
+    "get_node_qemu_config",
+    "put_node_qemu_config"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_qemu_custom_cpu_models",
+  "usageNotes": "Use this to discover which custom CPU model definitions are available cluster-wide before assigning a 'custom-*' cputype to a VM. Results are visibility-filtered by the caller's permissions on '/mapping/cpu/<name>', so an unprivileged token may see fewer entries than a root-equivalent user. Custom CPU model names are always prefixed with 'custom-' (e.g. 'custom-secure-baseline'); if no custom models have been defined the response will be an empty array.",
+  "examples": [
+    {
+      "summary": "List all custom CPU models visible to the current API token",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'digest' field in each returned entry can be passed to update/delete operations to prevent concurrent modification races.",
+    "The 'reported-model' field controls what the guest OS sees (e.g. 'Skylake-Server'), while 'cputype' is the internal Proxmox reference name; they are independent.",
+    "If the list is unexpectedly empty, verify the API token has at least 'Mapping.Audit' on '/mapping/cpu/' — without it, no entries will be returned even if models exist.",
+    "Setting 'hidden: true' on a custom model suppresses the KVM hypervisor signature, which can help with anti-VM software in Windows guests."
+  ],
+  "relatedOperations": [
+    "get_cluster_qemu_custom_cpu_models_cputype",
+    "create_cluster_qemu_custom_cpu_models",
+    "update_cluster_qemu_custom_cpu_models_cputype",
+    "delete_cluster_qemu_custom_cpu_models_cputype"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_qemu_custom_cpu_models_cputype",
+  "usageNotes": "Use this to inspect the full definition of a specific custom CPU model before assigning it to a VM — confirming its reported-model, enabled/disabled flags, and any phys-bits or level overrides. The caller must hold Mapping.Audit, Mapping.Use, or Mapping.Modify on the path /mapping/cpu/{cputype}. The 'custom-' prefix in the cputype path segment is optional; the API normalises both forms.",
+  "examples": [
+    {
+      "summary": "Retrieve details for a custom CPU model named 'custom-secure-epyc'",
+      "path_params": {
+        "cputype": "custom-secure-epyc"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Custom CPU model names are defined cluster-wide in /etc/pve/cpu-models.conf; verify the model exists there before querying.",
+    "The returned 'digest' field can be passed to modification calls to guard against concurrent edits.",
+    "Using 'phys-bits: host' in a custom model breaks live migration between hosts with different physical address bit widths — check this field before migrating VMs that use the model.",
+    "If the response 'hidden' flag is true, the guest OS will not detect it is running inside KVM, which is useful for software that refuses to run in virtual environments."
+  ],
+  "relatedOperations": [
+    "get_cluster_qemu_custom_cpu_models",
+    "post_cluster_qemu_custom_cpu_models",
+    "put_cluster_qemu_custom_cpu_models_cputype",
+    "delete_cluster_qemu_custom_cpu_models_cputype"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_cluster_replication",
+  "usageNotes": "Returns all cluster-wide replication jobs the calling user has VM.Audit permission to see; jobs for VMs the caller cannot audit are silently omitted, so an empty result does not necessarily mean no jobs exist. Each job ID follows the pattern '<VMID>-<JOBNUM>' (e.g. '100-0') and links to a specific target node. Use this as a starting point before creating, modifying, or troubleshooting replication schedules — it requires no parameters and is safe to call at any time.",
+  "examples": [
+    {
+      "summary": "List all replication jobs visible to the current user",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Jobs with 'remove_job' set ('local' or 'full') are already marked for deletion — they will disappear after their next scheduled run completes cleanup.",
+    "The 'source' field is populated internally to detect VM migrations (guest stolen from another node); it is not user-settable.",
+    "The default schedule '*/15' means every 15 minutes; check the 'schedule' field to understand replication frequency before making bandwidth assumptions.",
+    "A job with 'disable: true' will not run but still appears in this list — filter client-side if you only want active jobs.",
+    "Rate is expressed in megabytes per second (not megabits); a value of 10 means 10 MB/s."
+  ],
+  "relatedOperations": [
+    "get_cluster_replication_id",
+    "create_cluster_replication",
+    "update_cluster_replication_id",
+    "delete_cluster_replication_id",
+    "get_nodes_node_replication",
+    "get_nodes_node_replication_id_log",
+    "get_nodes_node_replication_id_status"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_replication_id",
+  "usageNotes": "Use this to inspect the configuration of a specific replication job by its composite ID (e.g. '100-0' for VM 100, job number 0). Requires VM.Audit on the guest's /vms/<vmid> path — API tokens are supported. The response includes the digest field, which should be passed to any subsequent update call to prevent concurrent modification conflicts.",
+  "examples": [
+    {
+      "summary": "Read the configuration of replication job 0 for VM 100",
+      "path_params": {
+        "id": "100-0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'digest' in the response is a configuration fingerprint — pass it to update/delete calls to guard against race conditions.",
+    "If 'remove_job' is set ('local' or 'full'), the job is already queued for self-deletion and may disappear after the next replication run.",
+    "A 'disable': true flag means the job exists but is not running; it will not replicate until re-enabled.",
+    "The 'source' field is internal bookkeeping used by Proxmox to detect guest migrations; do not rely on it for topology decisions."
+  ],
+  "relatedOperations": [
+    "get_cluster_replication",
+    "put_cluster_replication_id",
+    "delete_cluster_replication_id",
+    "get_nodes_node_replication_id_status"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_cluster_resources",
+  "usageNotes": "Use this as the primary cluster-wide inventory call — it returns all nodes, VMs (qemu), containers (lxc), storage pools, and SDN entities in a single request with live utilization metrics. Omit the 'type' filter to get the full picture, or supply it to narrow results when you only care about one resource class. CPU and memory values are live stats, so offline or paused guests may return null/zero for those fields.",
+  "examples": [
+    {
+      "summary": "List all running VMs cluster-wide to check CPU and memory utilization",
+      "path_params": {},
+      "params": {
+        "type": "vm"
+      }
+    }
+  ],
+  "tips": [
+    "The 'id' field follows the pattern '<type>/<name-or-vmid>' (e.g., 'qemu/100', 'node/pve1', 'storage/local-lvm') — use it to build subsequent per-resource API calls.",
+    "Response type enum includes 'qemu' and 'lxc' even though the query param only accepts 'vm'; filtering by type='vm' returns both qemu and lxc entries.",
+    "The 'status' field values are resource-specific: nodes return 'online'/'offline', guests return 'running'/'stopped'/'paused', storage returns 'available'/'unavailable'.",
+    "Guests that are templates have template=true and will show status='stopped' with zero utilization — filter them out when building capacity reports.",
+    "This endpoint requires no special privilege beyond being authenticated (permissions: user='all'), so API tokens with minimal scope can call it safely."
+  ],
+  "relatedOperations": [
+    "get_nodes",
+    "get_node_status",
+    "get_cluster_status",
+    "get_node_qemu",
+    "get_node_lxc"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_sdn",
+  "usageNotes": "Use this to enumerate the top-level SDN API sub-resources available on the cluster (e.g. vnets, zones, controllers, ipams). It is a directory index only — it returns child resource IDs, not SDN configuration data itself. Requires the SDN.Audit privilege on /sdn; SDN must be enabled in the cluster (datacenter configuration) for child resources to be present.",
+  "examples": [
+    {
+      "summary": "List SDN sub-resource categories available on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If the returned array is empty or SDN child routes are missing, verify that SDN is enabled in Datacenter > Options > SDN.",
+    "This endpoint is a navigation index — follow the returned 'id' values as path segments to reach actual SDN objects (e.g. GET /cluster/sdn/vnets, /cluster/sdn/zones).",
+    "API tokens are supported; ensure the token has SDN.Audit on /sdn."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets",
+    "get_cluster_sdn_zones",
+    "get_cluster_sdn_controllers",
+    "get_cluster_sdn_ipams"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_cluster_sdn_controllers",
+  "usageNotes": "Use this to enumerate all SDN routing controllers (BGP, EVPN, IS-IS, Faucet) configured in the cluster. Pass 'pending: true' to preview staged changes that have not yet been applied via 'apply', or 'running: true' to see only what is currently active on the data plane. Requires 'SDN.Audit' or 'SDN.Allocate' on each controller path — callers without either privilege on a controller will simply not see that entry in the response.",
+  "examples": [
+    {
+      "summary": "List only EVPN controllers with pending (unapplied) changes visible",
+      "path_params": {},
+      "params": {
+        "type": "evpn",
+        "pending": true
+      }
+    }
+  ],
+  "tips": [
+    "A 'state' field of 'changed' or 'new' on a returned controller means the config has been saved but not yet applied — run the SDN apply operation to push it to the data plane.",
+    "Omitting both 'pending' and 'running' returns the stored config; it may differ from what is actually running if changes were made but not applied.",
+    "The 'digest' field on each controller can be used as an optimistic-lock value when updating or deleting a specific controller.",
+    "Filter by 'type' to scope results when you only care about, e.g., BGP controllers in a mixed SDN deployment."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_controllers_controller",
+    "create_cluster_sdn_controllers",
+    "update_cluster_sdn_controllers_controller",
+    "delete_cluster_sdn_controllers_controller",
+    "get_cluster_sdn",
+    "apply_cluster_sdn"
+  ]
+}