@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_access_users_userid_token_tokenid",
+  "usageNotes": "Use this to permanently revoke an API token from a user account — for example, when rotating credentials, offboarding a user, or retiring an automation. The caller must either be the token's owner or hold User.Modify on the relevant user group. Deletion is immediate and irreversible; any service using the revoked token will lose API access instantly.",
+  "examples": [
+    {
+      "summary": "Revoke the 'automation' token for a local admin user",
+      "path_params": {
+        "userid": "admin@pam",
+        "tokenid": "automation"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the API token secret; the token cannot be recovered and any service or script using it will immediately lose API access.",
+  "tips": [
+    "Token IDs must start with a letter and contain only alphanumeric characters, dots, hyphens, or underscores.",
+    "Audit active tokens with get_access_users_userid_token_tokenid or list_access_users_userid_tokens before deleting to confirm which services depend on the token.",
+    "If rotating rather than permanently revoking, create the replacement token first so dependent services have zero-downtime transition."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid_token_tokenid",
+    "create_access_users_userid_token_tokenid",
+    "get_access_users_userid"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_acme_account_name",
+  "usageNotes": "Use this to deactivate and remove an ACME account registration from both Proxmox and the upstream CA (e.g. Let's Encrypt). The account must not be the active issuer for any certificates currently in use; deactivating it at the CA is irreversible and will prevent renewal of any certificates tied to that account. If omitted, the path param 'name' defaults to 'default', which is the standard single-account setup.",
+  "examples": [
+    {
+      "summary": "Deactivate the default ACME account",
+      "path_params": {
+        "name": "default"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Deactivates the ACME account at the CA permanently; existing certificates issued under this account can no longer be renewed once the account is gone.",
+  "tips": [
+    "The 'name' path param uses the pve-configid format (alphanumeric, no spaces); it matches the filename under /etc/pve/acme/.",
+    "Before deleting, verify no nodes or certificate profiles reference this account — check via get_cluster_acme_account_name or list_cluster_acme_account.",
+    "Returns a plain string (task result), not a UPID — this operation completes synchronously from the API perspective."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_account_name",
+    "list_cluster_acme_account",
+    "create_cluster_acme_account",
+    "update_cluster_acme_account_name"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_acme_plugins_id",
+  "usageNotes": "Use this to permanently remove an ACME plugin configuration from the cluster. Before deleting, ensure no ACME accounts or domains are referencing this plugin; removing a plugin that is still in use will prevent certificate renewals from succeeding. Requires the Sys.Modify privilege at the root path — only cluster administrators should perform this action.",
+  "examples": [
+    {
+      "summary": "Delete a Let's Encrypt DNS plugin named 'cf-dns'",
+      "path_params": {
+        "id": "cf-dns"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the named ACME plugin configuration from the cluster; any ACME accounts or certificate domains still referencing this plugin will fail to renew.",
+  "tips": [
+    "Run get_cluster_acme_plugins_id first to confirm the plugin exists and note any accounts using it.",
+    "After deletion, verify no domain entries in any node's ACME config still reference the deleted plugin ID.",
+    "Returns null on success — no UPID is issued; the operation is synchronous."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_plugins_id",
+    "get_cluster_acme_plugins",
+    "post_cluster_acme_plugins",
+    "put_cluster_acme_plugins_id"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "delete_cluster_backup_id",
+  "usageNotes": "Permanently removes a scheduled vzdump backup job definition from the cluster configuration. Requires the `Sys.Modify` privilege at the root path (`/`). This operation is synchronous and returns null — the job entry is removed immediately with no undo; any VMs or CTs that were covered by this schedule will no longer be backed up automatically.",
+  "examples": [
+    {
+      "summary": "Delete a daily backup job by its job ID",
+      "path_params": {
+        "id": "backup-695d3c8f-ab12"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the backup job definition; scheduled backups for all covered guests will cease immediately and the configuration cannot be recovered.",
+  "tips": [
+    "Retrieve the job ID first via GET /cluster/backup (list_cluster_backup) — the ID is not human-assigned and looks like a UUID-style token.",
+    "Deleting the job does NOT delete any existing backup archives already written to storage; those must be removed separately.",
+    "This call returns null on success with no confirmation step — verify the correct ID before issuing the request.",
+    "API tokens must have the `Sys.Modify` privilege granted at `/`; a token scoped only to a guest path will be denied."
+  ],
+  "relatedOperations": [
+    "list_cluster_backup",
+    "get_cluster_backup_id",
+    "create_cluster_backup",
+    "update_cluster_backup_id"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "delete_cluster_config_nodes_node",
+  "usageNotes": "Use this to remove a node from the Proxmox cluster configuration — typically after the node has already been shut down or when evicting a dead/unreachable node. The target node should be offline before removal; removing an active, healthy node without migrating its VMs/containers and storage first can leave workloads unmanageable. This operation returns null synchronously, but the underlying cluster config propagation (corosync quorum) takes effect immediately.",
+  "examples": [
+    {
+      "summary": "Remove a decommissioned node named 'pve-node3' from the cluster",
+      "path_params": {
+        "node": "pve-node3"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the node's membership from the cluster configuration; any VMs, storage mappings, or HA rules still assigned to the node become orphaned and must be manually reassigned or cleaned up.",
+  "tips": [
+    "Migrate all VMs and containers off the node before removal — orphaned guests are not automatically reassigned.",
+    "Remove the node from any HA groups and storage replication jobs before deleting it from the cluster config.",
+    "After removal, the evicted node's local corosync/pmxcfs state is not automatically wiped — reinstall or manually clean it to prevent split-brain if the node is reused.",
+    "Requires quorum: if the cluster already lacks quorum, this call may fail or produce unexpected results."
+  ],
+  "relatedOperations": [
+    "get_cluster_config_nodes",
+    "post_cluster_config_nodes",
+    "get_cluster_status",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "delete_cluster_firewall_aliases_name",
+  "usageNotes": "Permanently removes a named IP/network alias from the cluster-level firewall configuration. The alias must not be actively referenced by any firewall rules or IPSets before deletion; removing a referenced alias can silently break rule resolution. Use the `digest` parameter when scripting concurrent workflows to guard against race conditions overwriting an in-flight configuration change.",
+  "examples": [
+    {
+      "summary": "Delete the alias 'mgmt-net' from cluster firewall aliases",
+      "path_params": {
+        "name": "mgmt-net"
+      },
+      "params": {
+        "digest": "a3f5c2e1b8d047629f1e3a5c7b90d2f4e6c8a1b3"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes the named alias from the cluster firewall; any firewall rules or IPSets that reference it by name will silently lose their target, potentially allowing or blocking unintended traffic.",
+  "tips": [
+    "Fetch the current digest via GET /cluster/firewall/aliases/{name} and pass it here to prevent clobbering concurrent edits.",
+    "Search all cluster and node firewall rules for references to the alias name before deletion — Proxmox does not enforce referential integrity on aliases.",
+    "Returns null (HTTP 200) on success; no UPID is issued since this is a synchronous configuration change, not an async task."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_aliases_name",
+    "get_cluster_firewall_aliases",
+    "post_cluster_firewall_aliases",
+    "put_cluster_firewall_aliases_name"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "delete_cluster_firewall_groups_group",
+  "usageNotes": "Permanently deletes a cluster-level firewall security group. The group must have all its rules removed first — Proxmox will reject the request if the group is non-empty. Requires the Sys.Modify privilege at the root path ('/'), meaning only cluster admins can perform this action.",
+  "examples": [
+    {
+      "summary": "Delete a security group named 'web-servers'",
+      "path_params": {
+        "group": "web-servers"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the named cluster firewall security group; any firewall rules still referencing this group by name on nodes or VMs will become dangling references.",
+  "tips": [
+    "Use get_cluster_firewall_groups_group (GET /cluster/firewall/groups/{group}) to list existing rules in the group before deletion — the group must be empty.",
+    "Security group names are 2–18 characters, must start with a letter, and may only contain letters, digits, hyphens, and underscores.",
+    "This operation returns null on success; absence of an error is the confirmation.",
+    "If any VM or node firewall rule references this group, those rule entries will silently become invalid after deletion — audit usages with get_cluster_firewall_refs before deleting."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_groups",
+    "get_cluster_firewall_groups_group",
+    "post_cluster_firewall_groups",
+    "delete_cluster_firewall_groups_group_pos",
+    "get_cluster_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_cluster_firewall_groups_group_pos",
+  "usageNotes": "Use this to permanently remove a specific rule from a cluster-level firewall security group by its zero-based position index. Requires the `Sys.Modify` privilege at the root (`/`) path. Pass the `digest` parameter when scripting concurrent-safe deletions — it prevents accidental overwrites if the ruleset was modified between your read and this delete.",
+  "examples": [
+    {
+      "summary": "Delete the first rule (pos 0) from the security group 'webservers'",
+      "path_params": {
+        "group": "webservers",
+        "pos": 0
+      },
+      "params": {
+        "digest": "a3f1c2e4b5d6789012345678901234567890abcd"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the firewall rule at the specified position from the security group; all remaining rules shift up by one position and there is no undo.",
+  "tips": [
+    "Rule positions are zero-based and shift after each deletion — re-read the group's rule list before deleting multiple rules in sequence.",
+    "Omitting `pos` from the path is technically allowed by the spec but will likely target rule 0; always specify the position explicitly to avoid unintended deletions.",
+    "Use `get_cluster_firewall_groups_group` to retrieve the current ruleset and its digest before calling this endpoint.",
+    "Returns null on success; any non-null response indicates an error."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_groups_group",
+    "post_cluster_firewall_groups_group",
+    "put_cluster_firewall_groups_group_pos",
+    "get_cluster_firewall_groups_group_pos",
+    "get_cluster_firewall_groups"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_firewall_ipset_name",
+  "usageNotes": "Permanently deletes a named cluster-level firewall IPSet. By default the deletion fails if the IPSet still contains members; pass `force: true` to delete all members along with the set in one operation. Requires `Sys.Modify` on the root path — API tokens must have this privilege explicitly granted.",
+  "examples": [
+    {
+      "summary": "Delete an empty IPSet named 'trusted-mgmt'",
+      "path_params": {
+        "name": "trusted-mgmt"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the named IPSet and, when force is true, all of its member IP/CIDR entries — any firewall rules referencing this IPSet by name will break silently.",
+  "tips": [
+    "Check for firewall rules that reference the IPSet by name before deleting; Proxmox does not cascade-update rules, so orphaned references can silently open or block traffic unexpectedly.",
+    "Use `force: true` only when you have confirmed no active firewall rules depend on the set members.",
+    "IPSet names must start with a letter and may only contain letters, digits, hyphens, and underscores (2–64 chars)."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_ipsets",
+    "get_cluster_firewall_ipset_name",
+    "create_cluster_firewall_ipset",
+    "delete_cluster_firewall_ipset_name_cidr"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "delete_cluster_firewall_ipset_name_cidr",
+  "usageNotes": "Use this to remove a specific IP address or CIDR block from a cluster-level firewall IPSet. The caller must hold the Sys.Modify privilege on the root path (/). Pass the current configuration digest to guard against concurrent edits overwriting each other — omitting it skips the optimistic-lock check. This operation is synchronous and returns null on success; the firewall rule referencing this IPSet takes effect immediately after removal.",
+  "examples": [
+    {
+      "summary": "Remove a specific host IP from the 'trusted-mgmt' IPSet",
+      "path_params": {
+        "name": "trusted-mgmt",
+        "cidr": "192.168.10.50"
+      },
+      "params": {
+        "digest": "a3f1c2e9b7d04561ef238940dcb12345"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the specified IP/CIDR entry from the IPSet; any firewall rules that allowed or denied traffic based on this entry will stop matching that address immediately.",
+  "tips": [
+    "Fetch the current digest via GET /cluster/firewall/ipset/{name} before deleting to avoid optimistic-lock conflicts in automation scripts.",
+    "The 'cidr' path param accepts bare IPs (e.g. 10.0.0.1), CIDR notation (e.g. 10.0.0.0/24), or an alias name — match exactly what is stored in the IPSet.",
+    "Removing an entry from an IPSet that is actively referenced by cluster firewall rules takes effect instantly; verify no production traffic depends on the entry before deleting."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_ipset_name",
+    "create_cluster_firewall_ipset_name_cidr",
+    "update_cluster_firewall_ipset_name_cidr",
+    "delete_cluster_firewall_ipset_name",
+    "get_cluster_firewall_ipsets"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "delete_cluster_firewall_rules_pos",
+  "usageNotes": "Permanently removes a cluster-wide firewall rule at the specified zero-based position; the operation takes effect immediately and requires `Sys.Modify` on `/`. Always fetch the current rule list first to confirm the target position, since rules shift after any deletion. Pass the `digest` from the current ruleset to guard against concurrent modifications overwriting each other.",
+  "examples": [
+    {
+      "summary": "Delete the third cluster firewall rule (position 2), with digest guard",
+      "path_params": {
+        "pos": 2
+      },
+      "params": {
+        "digest": "a3f1c2e9d8b047a65f3312c8e1d4b5f6a2c9e1d3"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes the cluster firewall rule at the given position; no undo is available and all cluster nodes immediately lose the traffic control that rule provided.",
+  "tips": [
+    "Rule positions are zero-indexed and compact — deleting position 2 shifts all higher-index rules down by one.",
+    "Retrieve the current ruleset with get_cluster_firewall_rules first; its response includes the digest you should pass here.",
+    "Omitting `pos` targets position 0 (the first rule) — always supply an explicit position to avoid accidental deletions.",
+    "This endpoint returns null on success; treat a 200 with no body as confirmation."
+  ],
+  "relatedOperations": [
+    "get_cluster_firewall_rules",
+    "get_cluster_firewall_rules_pos",
+    "post_cluster_firewall_rules",
+    "put_cluster_firewall_rules_pos"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "delete_cluster_ha_groups_group",
+  "usageNotes": "Permanently removes an HA group configuration from the cluster. This endpoint is deprecated in favor of HA rules; prefer managing high-availability through the rules API for new configurations. Before deleting, ensure no HA resources are still assigned to the group, as removing a group with active members can disrupt service protection.",
+  "examples": [
+    {
+      "summary": "Delete an HA group named 'production'",
+      "path_params": {
+        "group": "production"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the HA group configuration; any HA resources still referencing this group will lose their group assignment and may fall back to default HA behavior or become unprotected.",
+  "tips": [
+    "Check for HA resources still using this group via GET /cluster/ha/resources before deleting.",
+    "This API is marked deprecated — use HA rules (/cluster/ha/rules) for managing high availability in current Proxmox versions.",
+    "Returns null on success; errors if the group does not exist or if the caller lacks Sys.Console on /."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_groups_group",
+    "get_cluster_ha_groups",
+    "create_cluster_ha_groups",
+    "update_cluster_ha_groups_group",
+    "get_cluster_ha_resources"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "delete_cluster_ha_resources_sid",
+  "usageNotes": "Removes a resource from HA management entirely — the VM or container continues to exist but will no longer be monitored or restarted by the HA manager. Requires `Sys.Console` at the root level, which is a cluster-wide privilege. Before deleting, ensure the resource is in a stable, non-migrating state; removing an HA resource while a recovery or migration is in progress may leave the cluster state inconsistent.",
+  "examples": [
+    {
+      "summary": "Remove VM 105 from HA management and purge it from any referencing rules",
+      "path_params": {
+        "sid": "vm:105"
+      },
+      "params": {
+        "purge": true
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the HA resource configuration for the specified VM or container, causing it to lose all high-availability protection (automatic restart, failover) with no recovery path short of re-adding it.",
+  "tips": [
+    "You can use the bare VM/CT ID (e.g. '105') as a shortcut instead of the full 'vm:105' form.",
+    "The default behavior (purge=true) also removes the resource from any HA group rules that reference it, which can silently delete those rules if they had no other members — audit HA groups before running if rule preservation matters.",
+    "This call returns null synchronously; there is no UPID to poll, but you should verify removal with get_cluster_ha_resources or list_cluster_ha_resources immediately after."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_resources_sid",
+    "create_cluster_ha_resources",
+    "update_cluster_ha_resources_sid",
+    "get_cluster_ha_resources",
+    "get_cluster_ha_groups"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "delete_cluster_ha_rules_rule",
+  "usageNotes": "Permanently deletes a named HA rule from the cluster configuration. The rule must already exist (use get_cluster_ha_rules or list_cluster_ha_rules to verify) and the caller must hold the Sys.Console privilege at the root path ('/'). Deletion takes effect immediately with no grace period — any resources currently matched by the rule will fall back to default HA behavior.",
+  "examples": [
+    {
+      "summary": "Delete an HA location rule named 'prefer-node1'",
+      "path_params": {
+        "rule": "prefer-node1"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "The HA rule is permanently removed from cluster configuration; any resource placement or migration preferences it enforced are immediately lost and cannot be recovered without manual recreation.",
+  "tips": [
+    "The 'rule' path param must match a valid pve-configid (alphanumeric and hyphens, no spaces).",
+    "Returns null on success — a 404-equivalent error is returned if the rule does not exist.",
+    "Changes are cluster-wide and take effect immediately; no node restart or HA manager reload is needed.",
+    "Review dependent HA groups or resources before deleting a rule to avoid unexpected migration behavior."
+  ],
+  "relatedOperations": [
+    "get_cluster_ha_rules_rule",
+    "get_cluster_ha_rules",
+    "post_cluster_ha_rules",
+    "put_cluster_ha_rules_rule"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_jobs_realm_sync_id",
+  "usageNotes": "Permanently deletes a scheduled realm-sync job by its config ID, stopping any future automatic user/group synchronization from the associated authentication realm. The operation returns null synchronously — no UPID is issued, so deletion is immediate upon a successful response. Requires Sys.Modify at the root path; this privilege is typically held only by administrators.",
+  "examples": [
+    {
+      "summary": "Delete a realm-sync job for an LDAP realm",
+      "path_params": {
+        "id": "ldap-daily-sync"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the realm-sync job definition; scheduled synchronization of users and groups from the associated realm will no longer run.",
+  "tips": [
+    "List existing realm-sync jobs first via GET /cluster/jobs/realm-sync to confirm the correct job ID before deleting.",
+    "Deleting the job does not remove users already synchronized into Proxmox — it only stops future sync runs.",
+    "The id must match the pve-configid format (alphanumeric, hyphens allowed, no spaces); an invalid id returns a 500 error, not a 404."
+  ],
+  "relatedOperations": [
+    "get_cluster_jobs_realm_sync",
+    "get_cluster_jobs_realm_sync_id",
+    "post_cluster_jobs_realm_sync",
+    "put_cluster_jobs_realm_sync_id"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_mapping_dir_id",
+  "usageNotes": "Permanently removes a cluster-wide directory mapping by its config ID; the mapping must not be actively referenced by any guest or resource pool, or the delete may be blocked. Requires the `Mapping.Modify` privilege on `/mapping/dir` — typically held by the root user or a delegated administrator role. Returns null synchronously (no UPID); the mapping is gone immediately upon success.",
+  "examples": [
+    {
+      "summary": "Delete a directory mapping named 'shared-backups'",
+      "path_params": {
+        "id": "shared-backups"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Deletes the named directory mapping from the cluster configuration permanently; any guest storage reference pointing to this mapping will become unresolvable until reconfigured.",
+  "tips": [
+    "Use list_cluster_mapping_dir (GET /cluster/mapping/dir) first to confirm the exact config ID before deleting.",
+    "Check all guest storage configurations to ensure no VM/CT is actively using this mapping before removal.",
+    "The `id` must match the `pve-configid` format: alphanumeric with hyphens and underscores, no spaces."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_dir",
+    "get_cluster_mapping_dir_id",
+    "create_cluster_mapping_dir",
+    "update_cluster_mapping_dir_id"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_mapping_pci_id",
+  "usageNotes": "Permanently removes a cluster-wide PCI hardware mapping by its config ID. Before deleting, ensure no VMs or containers reference the mapping — Proxmox does not block deletion even if the mapping is in use, which will cause affected guests to fail at next start. Requires the `Mapping.Modify` privilege on `/mapping/pci`.",
+  "examples": [
+    {
+      "summary": "Delete a GPU PCI mapping named 'gpu-quadro'",
+      "path_params": {
+        "id": "gpu-quadro"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the named PCI hardware mapping from the cluster; any VM or LXC configuration referencing this mapping by ID will fail to start until the reference is removed or the mapping is recreated.",
+  "tips": [
+    "List existing mappings first with get_cluster_mapping_pci to confirm the correct ID before deleting.",
+    "Check VM configs for references to this mapping ID (e.g., via grep on /etc/pve/qemu-server/) before removal.",
+    "Deletion is immediate and cluster-wide — there is no soft-delete or recycle bin."
+  ],
+  "relatedOperations": [
+    "get_cluster_mapping_pci",
+    "get_cluster_mapping_pci_id",
+    "create_cluster_mapping_pci",
+    "update_cluster_mapping_pci_id"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_mapping_usb_id",
+  "usageNotes": "Permanently removes a cluster-level USB hardware mapping by its config ID. Before deleting, ensure no VMs or containers reference this mapping, as removal does not automatically detach it from running guests. Requires the Mapping.Modify privilege on /mapping/usb.",
+  "examples": [
+    {
+      "summary": "Delete a USB mapping named 'usb-dongle-license'",
+      "path_params": {
+        "id": "usb-dongle-license"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the named USB hardware mapping from the cluster; any VM configurations still referencing this mapping ID will have a dangling reference and may fail to start.",
+  "tips": [
+    "Use get_cluster_mapping_usb_id to inspect the mapping and identify which nodes/VMs reference it before deleting.",
+    "The id must match a pve-configid format (alphanumeric plus hyphens/underscores, no spaces).",
+    "Deletion returns null — confirm removal by listing mappings with list_cluster_mapping_usb afterward."
+  ],
+  "relatedOperations": [
+    "list_cluster_mapping_usb",
+    "get_cluster_mapping_usb_id",
+    "create_cluster_mapping_usb",
+    "update_cluster_mapping_usb_id"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_metrics_server_id",
+  "usageNotes": "Permanently removes a metrics server (InfluxDB or Graphite) from the cluster configuration by its config ID. Requires `Sys.Modify` at the root (`/`) path — API tokens must carry this privilege explicitly. The operation returns null synchronously; there is no UPID, but the change propagates cluster-wide on the next config sync.",
+  "examples": [
+    {
+      "summary": "Remove an InfluxDB metrics server named 'influx-prod'",
+      "path_params": {
+        "id": "influx-prod"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the named metrics server entry from the cluster config; all nodes stop shipping metrics to that server immediately and the configuration cannot be recovered without re-adding it manually.",
+  "tips": [
+    "Use get_cluster_metrics_server_id to confirm the exact config ID before deleting — IDs follow the pve-configid format (alphanumeric plus hyphens, no spaces).",
+    "Deletion takes effect cluster-wide without a restart; verify in the Datacenter → Metric Server UI or via list_cluster_metrics_servers that the entry is gone.",
+    "If metrics pipelines (dashboards, alerting) depend on this server, coordinate removal with the monitoring team to avoid silent data gaps."
+  ],
+  "relatedOperations": [
+    "get_cluster_metrics_server_id",
+    "list_cluster_metrics_servers",
+    "create_cluster_metrics_server",
+    "update_cluster_metrics_server_id"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "delete_cluster_notifications_endpoints_gotify_name",
+  "usageNotes": "Permanently removes a named Gotify push-notification endpoint from the cluster notification configuration. Requires the `Mapping.Modify` privilege on `/mapping/notifications`. Any notification matchers or targets that reference this endpoint by name should be updated or removed first, as deleting the endpoint while it is referenced may leave dangling references in the notification routing config.",
+  "examples": [
+    {
+      "summary": "Delete a Gotify endpoint named 'gotify-alerts'",
+      "path_params": {
+        "name": "gotify-alerts"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the named Gotify endpoint and its configuration (URL, token, SSL settings) from the cluster; this cannot be undone and any notification matchers referencing this endpoint will no longer deliver alerts.",
+  "tips": [
+    "List existing Gotify endpoints first with GET /cluster/notifications/endpoints/gotify to confirm the exact name before deleting.",
+    "Check notification matchers (GET /cluster/notifications/matchers) for references to this endpoint name before removal to avoid silent alert delivery failures.",
+    "The endpoint name must match the pve-configid format (alphanumeric and hyphens, no spaces).",
+    "This is a cluster-wide operation — the deletion takes effect on all nodes without requiring per-node action."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_gotify",
+    "get_cluster_notifications_endpoints_gotify_name",
+    "create_cluster_notifications_endpoints_gotify",
+    "update_cluster_notifications_endpoints_gotify_name",
+    "get_cluster_notifications_matchers"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_cluster_notifications_endpoints_sendmail_name",
+  "usageNotes": "Permanently removes a named sendmail notification endpoint from the cluster. Requires the `Mapping.Modify` privilege on `/mapping/notifications`. Any notification rules or matchers that reference this endpoint by name should be updated or removed first, as the deletion does not cascade.",
+  "examples": [
+    {
+      "summary": "Delete the sendmail endpoint named 'alerts-smtp'",
+      "path_params": {
+        "name": "alerts-smtp"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the sendmail endpoint configuration; any notification rules referencing it will lose their delivery target and must be reconfigured manually.",
+  "tips": [
+    "The endpoint name must match the pve-configid format (alphanumeric, hyphens allowed, no spaces).",
+    "List existing endpoints with GET /cluster/notifications/endpoints/sendmail before deleting to confirm the correct name.",
+    "Check notification matchers and routing rules referencing this endpoint before deletion to avoid silent notification failures."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_sendmail_name",
+    "get_cluster_notifications_endpoints_sendmail",
+    "create_cluster_notifications_endpoints_sendmail",
+    "update_cluster_notifications_endpoints_sendmail_name"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "delete_cluster_notifications_endpoints_smtp_name",
+  "usageNotes": "Use this to permanently remove an SMTP notification endpoint from the cluster. Before deleting, ensure no notification rules or matchers reference this endpoint — Proxmox will reject the deletion if the endpoint is still in use by an active rule. This operation is synchronous and returns null on success; no UPID is issued.",
+  "examples": [
+    {
+      "summary": "Delete an SMTP endpoint named 'alerts-smtp'",
+      "path_params": {
+        "name": "alerts-smtp"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the SMTP endpoint configuration from the cluster; any notification rules that referenced it will stop delivering email alerts.",
+  "tips": [
+    "Check existing notification matchers and rules first (GET /cluster/notifications/matchers and /cluster/notifications/targets) to confirm nothing references this endpoint.",
+    "The 'name' must match the pve-configid format — lowercase alphanumeric and hyphens, no spaces.",
+    "Requires Mapping.Modify on /mapping/notifications; API tokens need this privilege explicitly granted."
+  ],
+  "relatedOperations": [
+    "get_cluster_notifications_endpoints_smtp_name",
+    "create_cluster_notifications_endpoints_smtp",
+    "update_cluster_notifications_endpoints_smtp_name",
+    "get_cluster_notifications_endpoints_smtp",
+    "get_cluster_notifications_matchers"
+  ]
+}