@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "delete_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+  "usageNotes": "Use this to remove a specific IP address, network CIDR, or alias from a named IPSet on a VM's firewall. The operation returns null synchronously — no UPID is issued — so changes take effect immediately without polling. The caller must hold the VM.Config.Network privilege on /vms/{vmid}, and the target IPSet must already exist; deleting the last entry from an IPSet does not auto-delete the IPSet itself.",
+  "examples": [
+    {
+      "summary": "Remove 10.10.20.0/24 from the 'trusted-mgmt' IPSet on VM 105",
+      "path_params": {
+        "node": "pve-htz-01",
+        "vmid": 105,
+        "name": "trusted-mgmt",
+        "cidr": "10.10.20.0/24"
+      },
+      "params": {
+        "digest": "a3f1c2e9b84d76f0a1c3e5b2d4f6a8c0e2b4d6f8"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the specified IP/CIDR entry from the IPSet; any firewall rules that relied on this entry to permit or deny traffic will immediately stop matching it, potentially exposing or blocking access without further warning.",
+  "tips": [
+    "Pass the 'digest' query parameter (obtained from the IPSet GET response) to guard against concurrent edits overwriting each other.",
+    "If you need to remove all entries from an IPSet before deleting the set itself, enumerate entries first via the corresponding GET endpoint and delete them one by one.",
+    "The 'cidr' path segment must exactly match the stored value (e.g., '10.0.0.1' and '10.0.0.1/32' are treated as distinct entries).",
+    "Aliases (e.g., '+datacenter') are valid 'cidr' values when the IPorCIDRorAlias format is used — match the alias name exactly as stored."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_ipset_name",
+    "post_nodes_node_qemu_vmid_firewall_ipset_name",
+    "get_nodes_node_qemu_vmid_firewall_ipset",
+    "delete_nodes_node_qemu_vmid_firewall_ipset_name"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "delete_nodes_node_qemu_vmid_firewall_rules_pos",
+  "usageNotes": "Permanently removes a single firewall rule from a VM's rule list by its zero-based position index; all rules below the deleted position shift up by one. Requires VM.Config.Network on the VM. Always read the current rule list first to confirm the correct position, and pass the digest returned by the GET to guard against concurrent edits.",
+  "examples": [
+    {
+      "summary": "Delete the second firewall rule (index 1) from VM 101 on node pve01, using a digest to prevent race conditions",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101,
+        "pos": 1
+      },
+      "params": {
+        "digest": "a3f2c1d0e9b84765"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes the firewall rule at the specified position; the deletion is immediate and irreversible, and any traffic previously matched by that rule will no longer be filtered.",
+  "tips": [
+    "Position (pos) is zero-based and shifts after every deletion — re-query the rule list if deleting multiple rules in sequence.",
+    "Omitting digest is allowed but risky in multi-admin environments; fetch the current list's digest first to use optimistic locking.",
+    "The API returns null on success; a non-null error body or HTTP 4xx/5xx indicates the rule was not deleted."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "get_nodes_node_qemu_vmid_firewall_rules_pos",
+    "post_nodes_node_qemu_vmid_firewall_rules",
+    "put_nodes_node_qemu_vmid_firewall_rules_pos"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "delete_nodes_node_qemu_vmid_snapshot_snapname",
+  "usageNotes": "Permanently deletes a named QEMU VM snapshot and its associated disk delta layers; requires `VM.Snapshot` privilege on `/vms/{vmid}`. The operation is asynchronous — the return value is a task UPID that should be polled to confirm completion before assuming the snapshot is gone. Use `force: true` only as a last resort when disk snapshot removal is failing but you still need the config entry cleared.",
+  "examples": [
+    {
+      "summary": "Delete the 'pre-update' snapshot from VM 102 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 102,
+        "snapname": "pre-update"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the named snapshot and its disk delta data; the VM state captured at that point-in-time cannot be recovered after deletion.",
+  "tips": [
+    "The returned UPID string can be passed to the task status endpoint (GET /nodes/{node}/tasks/{upid}/status) to poll for completion.",
+    "Deleting a snapshot while the VM is running is supported but may take longer as disk merging occurs live.",
+    "Child snapshots that depend on the deleted snapshot's disk delta will be rebased automatically by Proxmox — verify snapshot tree integrity afterward.",
+    "Avoid using `force` in production; it can leave orphaned disk data on storage backends that support external snapshots (e.g., Ceph RBD)."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_snapshot",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "post_nodes_node_qemu_vmid_snapshot_snapname_rollback",
+    "get_nodes_node_qemu_vmid_snapshot_snapname_config"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "delete_nodes_node_storage_storage_content_volume",
+  "usageNotes": "Use to permanently remove a disk image, ISO, snippet, or backup file from a storage pool. The node hosting the storage must be online. Returns a task UPID (string) when the deletion is asynchronous, or null if the optional `delay` parameter is set and the task completes within that window.",
+  "examples": [
+    {
+      "summary": "Delete a VM disk image from local-lvm storage on pve1",
+      "path_params": {
+        "node": "pve1",
+        "storage": "local-lvm",
+        "volume": "local-lvm:vm-101-disk-0"
+      },
+      "params": {
+        "delay": 10
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes the volume data from the storage backend with no built-in recovery path — the disk image, ISO, or backup file is irrecoverably lost.",
+  "tips": [
+    "The `storage` path param is marked optional in the spec — Proxmox can infer it from the volume ID, but providing it explicitly avoids ambiguity across shared storage.",
+    "If the volume is still referenced by a VM config, detach it first (update the VM hardware config) or Proxmox may reject the delete.",
+    "Use `delay` (1–30 s) to get a synchronous-style response for small volumes; omit it for large volumes to avoid timeouts and poll the returned UPID via the tasks API instead.",
+    "Requires 'Datastore.Allocate' on the storage, or 'Datastore.AllocateSpace' + 'VM.Backup' for backup volumes — verify privileges before calling in automated workflows."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_content",
+    "get_nodes_node_storage_storage_content_volume",
+    "post_nodes_node_storage_storage_content",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "delete_nodes_node_storage_storage_prunebackups",
+  "usageNotes": "Use this to enforce backup retention policy on a storage target — it deletes backup files that fall outside the configured keep-* thresholds. Only backups following the standard Proxmox naming scheme (vzdump archives) are evaluated; any non-standard files are ignored. If no prune-backups override is supplied, the retention rules from the storage configuration are used, so verify the storage config before running this in production.",
+  "examples": [
+    {
+      "summary": "Prune backups for a single VM (ID 101) on local backup storage, keeping only the last 3 backups",
+      "path_params": {
+        "node": "pve01",
+        "storage": "local"
+      },
+      "params": {
+        "vmid": 101,
+        "type": "qemu",
+        "prune-backups": "keep-last=3"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes backup files from storage that do not satisfy the retention policy; deleted backups cannot be recovered.",
+  "tips": [
+    "Run GET /nodes/{node}/storage/{storage}/prunebackups first (dry-run) to preview which backups would be removed before committing the DELETE.",
+    "Omitting 'vmid' and 'type' prunes backups for ALL guests on the storage — scope carefully in mixed environments.",
+    "The 'prune-backups' override only applies to this single call; it does not permanently change the storage retention configuration.",
+    "Requires 'Datastore.Allocate' on the storage path; if scoped to a specific VMID, 'Datastore.AllocateSpace' + 'VM.Backup' on that VM are sufficient.",
+    "The operation returns a string (task UPID) — poll /nodes/{node}/tasks/{upid}/status to confirm completion before assuming backups are gone."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_storage_storage_prunebackups",
+    "get_nodes_node_storage_storage_content",
+    "delete_nodes_node_storage_storage_content_volume"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "delete_nodes_node_subscription",
+  "usageNotes": "Removes the Proxmox VE subscription key registered on the specified node. Once deleted, the node loses enterprise repository access and support entitlements until a new key is applied via PUT /nodes/{node}/subscription. Requires Sys.Modify on /nodes/{node}; the operation returns null synchronously (no UPID — it is not async).",
+  "examples": [
+    {
+      "summary": "Remove the subscription key from node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the subscription key from the node, immediately revoking access to the enterprise apt repository and any associated support contract entitlements until a valid key is re-applied.",
+  "tips": [
+    "This call returns null on success — no response body to parse.",
+    "After deletion, the node will fall back to the no-subscription or test repository; update /etc/apt/sources.list.d/pve-enterprise.list accordingly to avoid failed apt updates.",
+    "To replace a key rather than simply remove it, use PUT /nodes/{node}/subscription with the new key directly — you do not need to DELETE first.",
+    "In a cluster, the subscription key is per-node; you must call this endpoint once per node if cleaning up across the cluster."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_subscription",
+    "put_nodes_node_subscription"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "delete_nodes_node_tasks_upid",
+  "usageNotes": "Use this to forcibly stop a running or queued task on a specific cluster node — for example, a hung migration, backup, or vzdump job. The UPID (Unique Process ID) must be obtained from a prior task-listing call; the target node must be online and reachable. Non-owner callers require 'Sys.Modify' on '/nodes/<node>'; task owners can stop their own tasks without that privilege.",
+  "examples": [
+    {
+      "summary": "Stop a hung vzdump backup task on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "upid": "UPID:pve1:00004A2B:012C3D4E:67890ABC:vzdump:101:root@pam:"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Forcibly terminates the running task process, which may leave in-progress operations (backups, migrations, snapshots) in an incomplete or inconsistent state.",
+  "tips": [
+    "Retrieve the UPID first via get_nodes_node_tasks (the active-task list) or the finished-task log — it is not guessable.",
+    "Check task status with get_nodes_node_tasks_upid_status before stopping; the task may have already completed.",
+    "Stopping a live migration mid-flight will keep the VM on the source node but may leave lock files; check /var/run/lock/qemu-server/ if the VM shows as locked afterward.",
+    "Returns null on success — poll the task status endpoint to confirm the process has actually exited."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_pools",
+  "usageNotes": "Permanently deletes a resource pool from the cluster. The pool must be empty — all VMs, containers, and storage entries must be removed from the pool before deletion will succeed. Requires the Pool.Allocate privilege on /pool/{poolid}.",
+  "examples": [
+    {
+      "summary": "Delete an empty pool named 'dev-team'",
+      "path_params": {},
+      "params": {
+        "poolid": "dev-team"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently removes the pool definition from the cluster; this action cannot be undone and any ACL entries scoped to /pool/{poolid} are also deleted.",
+  "tips": [
+    "The API returns null on success — absence of error is the confirmation.",
+    "Remove all member resources (VMs, CTs, storage) via update_pools before attempting deletion; a non-empty pool returns a 400 error.",
+    "Pool-scoped permission grants (user ACLs on /pool/{poolid}) are automatically cleaned up when the pool is deleted."
+  ],
+  "relatedOperations": [
+    "get_pools",
+    "get_pools_poolid",
+    "create_pools",
+    "update_pools"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_pools_poolid",
+  "usageNotes": "Deletes a resource pool by poolid using the legacy path-param form; prefer 'DELETE /pools/?poolid={poolid}' for environments with nested pool support. The pool must be empty — remove all member VMs, CTs, and storage entries before calling. Requires the Pool.Allocate privilege on /pool/{poolid}.",
+  "examples": [
+    {
+      "summary": "Delete an empty pool named 'dev-team'",
+      "path_params": {
+        "poolid": "dev-team"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the pool object and its ACL entries; any access-control rules scoped to this pool are lost and cannot be recovered.",
+  "tips": [
+    "This endpoint is marked deprecated — use DELETE /pools with poolid as a query parameter when nested pools are in use.",
+    "If the pool still has members the API returns an error; use GET /pools/{poolid} to list and remove members first.",
+    "Returns null on success — no task UPID is issued, so the deletion is synchronous."
+  ],
+  "relatedOperations": [
+    "get_pools_poolid",
+    "put_pools_poolid",
+    "post_pools",
+    "delete_pools"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "delete_storage_storage",
+  "usageNotes": "Removes a storage definition from the cluster-wide storage configuration. This is a synchronous operation — it returns null immediately, not a task UPID. It only deletes the configuration entry; any data on the underlying storage (disks, datasets, directories) is left untouched. Requires the Datastore.Allocate privilege on the /storage path.",
+  "examples": [
+    {
+      "summary": "Delete an NFS storage definition named 'nfs-backup'",
+      "path_params": {
+        "storage": "nfs-backup"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the named storage pool from the Proxmox cluster configuration; any VMs or backups referencing this storage ID will lose access to their configured paths until the storage is re-added.",
+  "tips": [
+    "Verify no VMs or CT have disks, backups, or ISOs referencing this storage ID before deleting — Proxmox does not block removal even if resources are still assigned.",
+    "The operation is cluster-wide; removing the storage here removes it from all nodes that share the cluster config.",
+    "If you need to temporarily disable a storage pool without losing the config, use the update endpoint to set 'disable: 1' instead."
+  ],
+  "relatedOperations": [
+    "get_storage_storage",
+    "put_storage_storage",
+    "get_storage",
+    "post_storage"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_access",
+  "usageNotes": "Returns the list of available subdirectories under the /access endpoint, functioning as a discovery index for the access and authentication subsystem. No privileges are required — any authenticated user or API token can call it. Useful as a sanity check that the API is reachable and to enumerate supported auth sub-resources before drilling into specific endpoints like /access/users or /access/roles.",
+  "examples": [
+    {
+      "summary": "List all access subdirectories",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values map directly to child endpoints (e.g., 'users', 'groups', 'roles', 'acl', 'domains', 'ticket') — use them to discover what's available without hardcoding paths.",
+    "Because this endpoint requires no special privilege, it is safe to use as a lightweight connectivity/health probe against the PVE API."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "get_access_groups",
+    "get_access_roles",
+    "get_access_acl",
+    "get_access_domains"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_access_acl",
+  "usageNotes": "Use this endpoint to audit which users, groups, and API tokens have been granted roles across the Proxmox resource tree (nodes, VMs, storage, pools, etc.). The returned list is automatically filtered to paths where the caller has permission to modify permissions, so a restricted token may see a partial view. No parameters are required; the full ACL is returned in one call.",
+  "examples": [
+    {
+      "summary": "Retrieve all ACL entries visible to the authenticated caller",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each entry includes a 'path' (e.g. '/', '/nodes/pve1', '/vms/100'), 'type' (user/group/token), 'ugid' (the subject identifier), 'roleid', and optional 'propagate' flag.",
+    "propagate=true (the default) means the role cascades to child paths; set it to false on a parent path to grant access only at that exact level.",
+    "API tokens are listed with type='token' and ugid in 'USER@REALM!TOKENID' format — useful for auditing which tokens have cluster-wide roles.",
+    "To see the full ACL regardless of your own privileges, you must authenticate as a Proxmox admin (root@pam or a user with Sys.Modify on '/')."
+  ],
+  "relatedOperations": [
+    "update_access_acl",
+    "get_access_users",
+    "get_access_groups",
+    "get_access_roles"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_access_domains",
+  "usageNotes": "Use this to enumerate all configured authentication realms (e.g., 'pve', 'pam', LDAP/AD, OpenID) available on the cluster. No authentication is required — Proxmox intentionally exposes this endpoint publicly so login UIs can populate the realm dropdown before a user authenticates. Results include the realm ID, type, optional comment, and whether a legacy TFA provider (yubico or oath) is configured.",
+  "examples": [
+    {
+      "summary": "List all authentication domains on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'tfa' field only appears for realms using the older yubico/oath TFA providers; modern TOTP/WebAuthn TFA configured via the user TFA API will not show here.",
+    "Realm names returned here are the values to pass as the 'realm' parameter when authenticating via POST /access/ticket.",
+    "The built-in 'pam' (Linux PAM) and 'pve' (Proxmox internal) realms are always present."
+  ],
+  "relatedOperations": [
+    "create_access_ticket",
+    "get_access_domain",
+    "create_access_domain",
+    "update_access_domain",
+    "delete_access_domain"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_access_domains_realm",
+  "usageNotes": "Use this to inspect the full configuration of a specific authentication realm (LDAP, AD, PAM, PVE, OpenID, etc.) by its realm ID. Requires either the Realm.Allocate or Sys.Audit privilege on /access/realm. Returned fields vary by realm type (e.g. LDAP returns server/base_dn fields; OpenID returns issuer-url/client-id).",
+  "examples": [
+    {
+      "summary": "Fetch configuration for the built-in 'pam' realm",
+      "path_params": {
+        "realm": "pam"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Common realm IDs: 'pam' (Linux PAM), 'pve' (Proxmox built-in), or whatever was set at realm creation time.",
+    "Realm IDs are case-sensitive and max 32 characters; use list_access_domains to enumerate available realms before calling this.",
+    "API tokens are allowed (allowtoken: true), so service accounts can read realm config without interactive credentials."
+  ],
+  "relatedOperations": [
+    "list_access_domains",
+    "create_access_domains",
+    "update_access_domains_realm",
+    "delete_access_domains_realm"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_access_groups",
+  "usageNotes": "Use this to enumerate all Proxmox VE access groups visible to the authenticated token or user. Results are automatically filtered by privilege — only groups where the caller holds 'User.Modify', 'Sys.Audit', or 'Group.Allocate' on /access/groups/<group> are returned, so an empty list does not mean no groups exist. No parameters are required; this is a lightweight read suitable for populating dropdowns or validating group names before assignment.",
+  "examples": [
+    {
+      "summary": "List all access groups visible to the current token",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'users' field in each returned object is a comma-separated list in pve-userid-list format (e.g. 'alice@pam,bob@pve'); it may be absent if the group has no members.",
+    "A non-admin token will silently see only the groups it has privilege on — always validate with a Sys.Audit-capable token when auditing the full group roster.",
+    "Use the returned 'groupid' values directly with create_access_group_role_mapping or delete_access_group to act on a specific group."
+  ],
+  "relatedOperations": [
+    "get_access_group",
+    "create_access_group",
+    "delete_access_group",
+    "get_access_acl"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_access_groups_groupid",
+  "usageNotes": "Use this to retrieve the member list and optional comment for a specific Proxmox access group. The caller must hold either Sys.Audit or Group.Allocate on /access/groups. The group must already exist; a non-existent groupid returns an error, not an empty result.",
+  "examples": [
+    {
+      "summary": "Fetch membership of the 'admins' group",
+      "path_params": {
+        "groupid": "admins"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The members array contains full user IDs in name@realm format (e.g. jdoe@pve); iterate it to build audit reports or compare expected vs. actual group membership.",
+    "API tokens are allowed (allowtoken: true), so automation scripts can read group data without interactive credentials.",
+    "Group IDs are case-sensitive and follow the pve-groupid format; use list_access_groups first if unsure of exact casing."
+  ],
+  "relatedOperations": [
+    "get_access_groups",
+    "post_access_groups",
+    "put_access_groups_groupid",
+    "delete_access_groups_groupid"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_access_openid",
+  "usageNotes": "Returns the list of available sub-resources under the /access/openid path (e.g., 'login', 'callback', 'auth-url'). Use this as a discovery call to confirm which OpenID Connect endpoints are exposed by the cluster before calling them. No authentication is required beyond a valid API token, and no parameters are needed.",
+  "examples": [
+    {
+      "summary": "List available OpenID Connect sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values are the relative child paths — append them to /access/openid/ to construct the full endpoint URLs.",
+    "This is a directory index only; it does not initiate or validate any OpenID Connect flow."
+  ],
+  "relatedOperations": [
+    "get_access_openid_login",
+    "get_access_openid_callback",
+    "get_access_openid_auth_url"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_access_permissions",
+  "usageNotes": "Use this to audit what privileges a specific user or API token actually has in effect across the cluster — useful for troubleshooting access denials or verifying least-privilege configurations. Omitting both `userid` and `path` returns the full privilege tree for the currently authenticated caller. To inspect another user's permissions, your token or user must hold `Sys.Audit` on `/access`; without it, you can only query yourself or tokens you own.",
+  "examples": [
+    {
+      "summary": "Fetch all effective permissions for a specific API token scoped to a single path",
+      "path_params": {},
+      "params": {
+        "userid": "kevin@pve!monitoring",
+        "path": "/nodes/pve01"
+      }
+    }
+  ],
+  "tips": [
+    "Omit `path` to get the full permission tree; supply it to narrow the response to one ACL path (faster for targeted checks).",
+    "The response maps each path to a privilege object where values are booleans indicating whether the privilege propagates to children.",
+    "API tokens always have permissions that are the intersection of their owner's permissions and any explicit token ACLs — effective permissions may be narrower than the owner's.",
+    "This endpoint is safe to call frequently; it is read-only and does not alter any cluster state."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "get_access_roles",
+    "get_access_acl",
+    "get_access_token"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_access_roles",
+  "usageNotes": "Use this to enumerate all roles defined in the cluster, including built-in roles (marked with special: true) and any custom roles created by administrators. Accessible by all authenticated users, so no elevated privilege is required. The returned privs field is a comma-separated list of privileges assigned to each role, useful for auditing permission scope before assigning a role to a user or group.",
+  "examples": [
+    {
+      "summary": "List all roles in the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Built-in roles (Administrator, PVEVMAdmin, PVEAuditor, etc.) have special: true and cannot be deleted or modified.",
+    "Custom roles have special: false or omit the field; these can be managed via create/update/delete role endpoints.",
+    "Cross-reference roleid values here with ACL entries from get_access_acl to understand effective permissions for a user or path."
+  ],
+  "relatedOperations": [
+    "get_access_acl",
+    "get_access_users",
+    "get_access_groups"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_roles_roleid",
+  "usageNotes": "Use this to inspect the exact privilege set granted by a specific role before assigning it to a user or token — useful for auditing custom roles or verifying built-in roles like PVEVMUser or PVEAdmin. The roleid must match an existing role exactly (case-sensitive); built-in roles use the PVE prefix convention (e.g., PVEAdmin, PVEVMUser). All authenticated users including API tokens can call this endpoint regardless of privilege level.",
+  "examples": [
+    {
+      "summary": "Inspect the built-in PVEVMUser role to see which VM privileges it grants",
+      "path_params": {
+        "roleid": "PVEVMUser"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Only privileges set to true are returned in the response; unset privileges are omitted entirely rather than returned as false.",
+    "Built-in roles (prefixed with PVE) cannot be modified; use list_access_roles (GET /access/roles) to enumerate all available roles before fetching a specific one.",
+    "API tokens with restricted privileges can still call this endpoint — permissions are 'user: all', meaning any authenticated session qualifies."
+  ],
+  "relatedOperations": [
+    "get_access_roles",
+    "post_access_roles",
+    "put_access_roles_roleid",
+    "delete_access_roles_roleid",
+    "get_access_acl"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_access_tfa",
+  "usageNotes": "Use this to audit TFA enrollment across all users in the cluster — useful for compliance checks or onboarding reviews. Unprivileged users only receive their own entry; the full list requires Sys.Audit or equivalent realm-admin privilege. The response also surfaces lockout state (tfa-locked-until, totp-locked), making it useful for diagnosing why a user cannot complete login.",
+  "examples": [
+    {
+      "summary": "List all TFA configurations as an admin token",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "An empty 'entries' array for a user means they have no TFA methods registered — not that TFA is disabled globally.",
+    "Check 'tfa-locked-until' (unix timestamp) and 'totp-locked' on a user's record before resetting credentials; a lockout may clear on its own.",
+    "TFA type 'recovery' indicates one-time recovery codes; if this is the only entry for a user, they have no active second factor.",
+    "u2f is legacy — users with only u2f entries should migrate to webauthn."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "post_access_tfa_userid",
+    "delete_access_tfa_userid_id",
+    "get_access_users"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_tfa_userid",
+  "usageNotes": "Use this to audit or inspect all TFA entries registered for a specific Proxmox user. A user can read their own TFA entries without elevated privileges; reading another user's entries requires User.Modify or Sys.Audit on the root path. Each entry includes the type (totp, webauthn, u2f, recovery, yubico) and whether it is currently enabled, making it useful for verifying MFA posture before disabling or rotating credentials.",
+  "examples": [
+    {
+      "summary": "List all TFA entries for a local admin user",
+      "path_params": {
+        "userid": "admin@pam"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "An empty array means the user has no TFA configured — treat this as a security gap for privileged accounts.",
+    "The 'enable' field defaults to true; a disabled entry (enable: false) still exists but will not be challenged at login.",
+    "Recovery entries (type: 'recovery') are one-time-use codes — their presence in the list does not indicate how many remain.",
+    "API tokens are allowed (allowtoken: true), so this endpoint can be called from automation without an interactive session."
+  ],
+  "relatedOperations": [
+    "post_access_tfa_userid",
+    "put_access_tfa_userid_id",
+    "delete_access_tfa_userid_id",
+    "get_access_users"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_tfa_userid_id",
+  "usageNotes": "Use this to inspect a specific TFA entry for a user — useful for verifying the type (totp, webauthn, yubico, etc.), enabled state, and creation time before deciding to update or delete it. Requires either the requesting user to be looking up their own entry, or the caller to hold User.Modify or Sys.Audit on the user's realm. The TFA entry ID is not human-readable; retrieve it first via the list endpoint (get_access_tfa_userid).",
+  "examples": [
+    {
+      "summary": "Fetch a specific TOTP entry for a PVE admin user",
+      "path_params": {
+        "userid": "admin@pve",
+        "id": "totp-7f3a1c2d4e5b6a8f"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "TFA entry IDs are opaque strings — always list first with get_access_tfa_userid to get the correct ID.",
+    "The 'enable' field defaults to true; a missing field in the response means the entry is active.",
+    "Recovery codes are returned as type 'recovery' — avoid exposing these in logs or automation output.",
+    "API tokens can call this endpoint (allowtoken: true), making it safe for read-only automation."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "put_access_tfa_userid_id",
+    "delete_access_tfa_userid_id"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_access_ticket",
+  "usageNotes": "This is a dummy/stub endpoint that returns null and carries no payload; its sole purpose is to serve as a discoverable login-page hint for API clients and UI formatters that need to identify the authentication endpoint. No credentials or authentication are required (world-accessible). Prefer the POST /access/ticket endpoint when you actually need to create an authentication ticket.",
+  "examples": [
+    {
+      "summary": "Probe the ticket endpoint for login-page discovery",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns null — do not use this to validate credentials or check auth state; it will always succeed with an empty response regardless of whether the caller is authenticated.",
+    "The companion POST /access/ticket (create_access_ticket) is the real authentication endpoint that issues PVEAuthCookie + CSRFPreventionToken.",
+    "Useful in health-check or API-discovery scripts to confirm the PVE API is reachable without needing any credentials."
+  ],
+  "relatedOperations": [
+    "create_access_ticket",
+    "delete_access_ticket"
+  ]
+}