@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_access_users",
+  "usageNotes": "Use this to list all Proxmox VE users visible to the authenticated principal; every authenticated user always sees themselves in the result even with minimal privileges, but the full list is filtered to users where the caller holds 'User.Modify' or 'Sys.Audit' on '/access/groups' or on a group the user belongs to. Pass 'full=true' to include each user's group memberships and API tokens in the response, which is useful for auditing access or building user-management tooling. Users with a non-zero 'expire' timestamp or 'enable=false' are still returned unless you filter with the 'enabled' query param.",
+  "examples": [
+    {
+      "summary": "List all enabled users including their group and token details",
+      "path_params": {},
+      "params": {
+        "enabled": true,
+        "full": true
+      }
+    }
+  ],
+  "tips": [
+    "User IDs are always in 'name@realm' format (e.g. 'admin@pam', 'kevin@pve'); use this format when referencing users in ACL or token operations.",
+    "The 'tokens' array is only populated when 'full=true'; omitting it keeps the response lean for large user sets.",
+    "A non-zero 'tfa-locked-until' value means the user is temporarily locked out of 2FA — useful to surface in monitoring or alerting pipelines.",
+    "The 'realm-type' field distinguishes PAM, PVE, LDAP, and AD realms; filter on it client-side to scope operations to a specific auth backend."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid",
+    "post_access_users",
+    "put_access_users_userid",
+    "delete_access_users_userid",
+    "get_access_groups",
+    "get_access_roles"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_access_users_userid",
+  "usageNotes": "Use this to retrieve the full configuration of a single Proxmox VE user, including group memberships, account status, expiry, email, and any API tokens defined on the account. The caller must hold either User.Modify or Sys.Audit on the relevant user path — regular users without these privileges cannot inspect other accounts. The userid must be in name@realm format (e.g., admin@pam or jdoe@pve); realm omission will fail.",
+  "examples": [
+    {
+      "summary": "Fetch configuration for a local PVE user to check group membership and token list",
+      "path_params": {
+        "userid": "jdoe@pve"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "API tokens are returned as an object keyed by token ID; each entry includes its own expiry and privsep flag — useful for auditing whether any token has unrestricted (privsep=false) privileges.",
+    "The 'enable' field defaults to true and is omitted from the response when not explicitly set; absence means the account is active.",
+    "expire=0 means no expiration; a non-zero value is a Unix timestamp — compare against current time to determine if the account is expired.",
+    "This endpoint returns the YubiKey OTP key IDs (keys field) if configured, which is relevant for auditing 2FA enrollment."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "put_access_users_userid",
+    "post_access_users",
+    "delete_access_users_userid",
+    "get_access_users_userid_token_tokenid"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_access_users_userid_tfa",
+  "usageNotes": "Use this to check what TFA methods are configured for a specific user, both at the personal level and enforced by their realm. A user can call it for themselves; otherwise, the caller needs User.Modify or Sys.Audit on the user's group. Pass `multiple: true` to get a full array of all configured TFA types instead of just the primary one.",
+  "examples": [
+    {
+      "summary": "Retrieve TFA configuration for a specific user, requesting all entries as an array",
+      "path_params": {
+        "userid": "admin@pam"
+      },
+      "params": {
+        "multiple": true
+      }
+    }
+  ],
+  "tips": [
+    "Without `multiple`, the response returns `user` (single legacy type) and `types` (array); with `multiple: true`, the shape changes — `user` and `types` are omitted.",
+    "The `realm` field reflects TFA enforced at the realm level (oath/yubico), which users cannot bypass regardless of their personal settings.",
+    "Note the typo in the spec enum value: `recovedry` (not `recovery`) — match this exactly if filtering on type strings."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "get_access_users_userid",
+    "post_access_tfa",
+    "get_access_tfa_userid"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_users_userid_token",
+  "usageNotes": "Use this to list all API tokens associated with a given Proxmox user (e.g., before auditing expiry dates or before creating/deleting a token). Any user can list their own tokens; listing another user's tokens requires the User.Modify privilege. Note that this endpoint returns token metadata only — the actual secret value is never retrievable after initial creation.",
+  "examples": [
+    {
+      "summary": "List all API tokens for the local admin user",
+      "path_params": {
+        "userid": "admin@pam"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Token secrets are shown only once at creation time (via the create endpoint); this list endpoint cannot retrieve them.",
+    "privsep: true (the default) means the token's effective permissions are the intersection of the token's ACLs and the user's ACLs — it cannot exceed the user's own rights.",
+    "An expire value of 0 means the token never expires; check this during access audits to flag unbounded tokens.",
+    "To inspect a single token's details, use the child resource: GET /access/users/{userid}/token/{tokenid}."
+  ],
+  "relatedOperations": [
+    "post_access_users_userid_token_tokenid",
+    "get_access_users_userid_token_tokenid",
+    "delete_access_users_userid_token_tokenid",
+    "get_access_users"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_access_users_userid_token_tokenid",
+  "usageNotes": "Use this to inspect a specific API token's metadata — expiry, privilege-separation flag, and comment — without revealing the token secret itself (the secret is only returned at creation time). A user can read their own tokens; reading another user's tokens requires the User.Modify privilege on the realm or a parent path. Useful when auditing token expiration or confirming whether a token runs with full user privileges or a restricted ACL (privsep).",
+  "examples": [
+    {
+      "summary": "Read the 'automation' token for a local admin user",
+      "path_params": {
+        "userid": "admin@pam",
+        "tokenid": "automation"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The token secret is never returned by this endpoint — it is only shown once, at creation (post_access_users_userid_token_tokenid). Store it securely at that time.",
+    "privsep=true (the default) means the token's effective permissions are the intersection of its ACLs and the owner's ACLs — it cannot exceed the user's own rights.",
+    "An expire value of 0 means the token never expires; check this when auditing long-lived service accounts.",
+    "tokenid must start with a letter and may contain letters, digits, dots, hyphens, and underscores — validate before calling if building the ID programmatically."
+  ],
+  "relatedOperations": [
+    "post_access_users_userid_token_tokenid",
+    "put_access_users_userid_token_tokenid",
+    "delete_access_users_userid_token_tokenid",
+    "get_access_users_userid"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster",
+  "usageNotes": "Use this as a discovery entry point to enumerate all top-level cluster API namespaces (e.g. config, ha, log, resources, tasks). It requires no parameters and is accessible to any authenticated user or API token, making it a safe first call for capability probing. The response is an array of child resource descriptors, not cluster status data — use get_cluster_resources for live node/VM/storage state.",
+  "examples": [
+    {
+      "summary": "List all top-level cluster API namespaces",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'name' field in each returned object matches the href link relation and can be appended to /cluster/ to form the child endpoint path.",
+    "This endpoint returns structural metadata only — it does not reflect cluster health or membership. Use get_cluster_status for that.",
+    "Works on standalone (non-clustered) PVE nodes as well; the child namespaces returned are the same regardless of cluster membership."
+  ],
+  "relatedOperations": [
+    "get_cluster_status",
+    "get_cluster_resources",
+    "get_cluster_config",
+    "get_cluster_log"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_acme",
+  "usageNotes": "Returns the top-level ACME index listing available child resources (accounts, directories, plugins, TOS). Use this as a discovery call to confirm ACME support is accessible before navigating to sub-resources. No parameters are required and all authenticated users can call it.",
+  "examples": [
+    {
+      "summary": "List ACME index resources on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned array contains child resource names (e.g. 'accounts', 'directories', 'plugins', 'tos') — use these as the next path segment to drill into specific ACME configuration.",
+    "This endpoint is a directory index, not a list of ACME accounts; use get_cluster_acme_accounts to enumerate configured accounts.",
+    "API tokens are allowed, so this can be called from automation without a full user session."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_account",
+    "get_cluster_acme_accounts",
+    "get_cluster_acme_directories",
+    "get_cluster_acme_plugins",
+    "get_cluster_acme_tos"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_acme_account",
+  "usageNotes": "Lists all ACME accounts registered on the cluster, returning their names as child links. Use this before issuing certificate operations to confirm which ACME account names are available; the names returned here are the values expected by certificate-related endpoints that require an account reference. No privileges beyond basic authentication are required.",
+  "examples": [
+    {
+      "summary": "List all registered ACME accounts on the cluster",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a name-index only — each entry links to a child resource; fetch individual accounts via get_cluster_acme_account_name to retrieve full details such as directory URL and contact email.",
+    "An empty array means no ACME accounts have been configured yet; you must create one before requesting certificates.",
+    "API tokens are supported (allowtoken: true), so automation scripts can safely call this endpoint without a full user session."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_account_name",
+    "post_cluster_acme_account",
+    "put_cluster_acme_account_name",
+    "delete_cluster_acme_account_name",
+    "get_cluster_acme_directories"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_acme_account_name",
+  "usageNotes": "Use this to inspect an existing ACME account registration, including the CA directory URL, account object, and agreed terms-of-service URL. The `name` path parameter defaults to `default`, so omitting it retrieves the primary account. Requires cluster-level ACME configuration to exist; if no account has been registered under the given name, the call will return an error.",
+  "examples": [
+    {
+      "summary": "Retrieve the default ACME account details",
+      "path_params": {
+        "name": "default"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `account` field in the response is rendered as YAML and contains the contact email(s) and account status as returned by the CA.",
+    "Check the `directory` field to confirm which ACME CA (e.g., Let's Encrypt production vs. staging) the account is registered against.",
+    "The `location` field holds the account URL at the CA — useful for manual ACME API lookups or debugging renewal failures."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_account",
+    "create_cluster_acme_account",
+    "delete_cluster_acme_account_name",
+    "update_cluster_acme_account_name"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_acme_challenge_schema",
+  "usageNotes": "Call this before configuring an ACME account or DNS/HTTP challenge plugin to discover which challenge types (e.g. 'dns', 'standalone') are available on the cluster and what parameters each type requires. No authentication privilege beyond a valid user session is needed — API tokens are accepted. The response schema object per entry describes the fields required to configure that challenge type, so parse it before calling any ACME plugin create/update endpoint.",
+  "examples": [
+    {
+      "summary": "List all supported ACME challenge types and their configuration schemas",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'schema' field in each returned object is a JSON Schema describing the parameters needed to configure that challenge type — use it to validate plugin configuration before submission.",
+    "The 'id' field is what you pass as the 'type' or 'api' parameter in ACME plugin creation calls; 'name' is display-only.",
+    "This endpoint requires no special privilege and is safe to call at any time — use it for feature detection when building tooling that targets multiple PVE versions."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_plugins",
+    "create_cluster_acme_plugins",
+    "get_cluster_acme_directories",
+    "get_cluster_acme_accounts"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_cluster_acme_directories",
+  "usageNotes": "Call this before creating or updating an ACME account to discover the canonical directory URLs that Proxmox knows about (e.g. Let's Encrypt production and staging). No parameters are required and no special privilege is needed — any authenticated user or API token can call it. Use the returned 'name' values when referencing a directory in ACME account configuration.",
+  "examples": [
+    {
+      "summary": "List all known ACME directory endpoints",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned list is built into Proxmox and is not cluster-configuration-dependent — it reflects directories compiled into the pve-manager package.",
+    "Use the 'url' field directly when registering an ACME account via POST /cluster/acme/account if you need a non-default directory.",
+    "Let's Encrypt staging URL is useful for testing certificate issuance without hitting rate limits."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_accounts",
+    "create_cluster_acme_account",
+    "get_cluster_acme_plugins"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_cluster_acme_meta",
+  "usageNotes": "Use this to inspect an ACME CA directory before configuring it in Proxmox — it reveals whether an External Account Binding (EAB) is required, the Terms of Service URL, and the CAA hostnames the CA recognizes. Defaults to Let's Encrypt production; pass a different `directory` URL to query staging or a private ACME CA (e.g., ZeroSSL, Buypass). Requires Sys.Audit on any node; no ACME account needs to exist beforehand.",
+  "examples": [
+    {
+      "summary": "Query Let's Encrypt staging directory to check if EAB is required before adding the CA",
+      "path_params": {},
+      "params": {
+        "directory": "https://acme-staging-v02.api.letsencrypt.org/directory"
+      }
+    }
+  ],
+  "tips": [
+    "If externalAccountRequired is true, you must obtain EAB credentials from the CA before creating an ACME account in Proxmox.",
+    "Use the staging directory (acme-staging-v02) during initial setup to avoid Let's Encrypt rate limits.",
+    "The returned caaIdentities list tells you which hostnames to include in DNS CAA records for domain validation."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_tos",
+    "get_cluster_acme_directories",
+    "create_cluster_acme_account",
+    "get_cluster_acme_accounts"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_cluster_acme_plugins",
+  "usageNotes": "Use this to list all ACME challenge plugins configured at the cluster level — call it before creating or assigning a plugin to a domain in an ACME account. Requires the Sys.Modify privilege at the root path (/). Filter by type='dns' or type='standalone' to narrow results; omit the parameter to return all plugins regardless of type.",
+  "examples": [
+    {
+      "summary": "List only DNS challenge plugins",
+      "path_params": {},
+      "params": {
+        "type": "dns"
+      }
+    }
+  ],
+  "tips": [
+    "The 'standalone' plugin type is built-in and requires no additional API credentials; DNS plugins each reference a specific provider API (e.g., 'cf' for Cloudflare, 'hetzner' for Hetzner DNS).",
+    "The 'disable' flag on a returned plugin means it will not be used for certificate issuance even if assigned — check this field when troubleshooting ACME certificate failures.",
+    "The 'validation-delay' field (default 30 s) is critical for DNS plugins with high TTLs; if cert issuance fails with DNS propagation errors, increase this value on the plugin.",
+    "The 'nodes' field restricts which cluster nodes may use the plugin; an empty/absent value means all nodes are allowed."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_plugins_id",
+    "create_cluster_acme_plugins",
+    "update_cluster_acme_plugins_id",
+    "delete_cluster_acme_plugins_id",
+    "get_cluster_acme_accounts"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_acme_plugins_id",
+  "usageNotes": "Use this to inspect the full configuration of a specific ACME plugin instance by its config ID — useful before updating or troubleshooting certificate issuance. Requires Sys.Modify on the root path, so API tokens must carry that privilege. The 'data' field in the response is base64-encoded and contains the DNS provider credentials; decode before inspecting.",
+  "examples": [
+    {
+      "summary": "Retrieve the configuration of an ACME DNS plugin named 'cf-dns'",
+      "path_params": {
+        "id": "cf-dns"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'digest' value can be passed to update/delete operations to guard against concurrent modifications.",
+    "If 'disable' is true, the plugin will not be used for certificate renewals even if assigned to a domain.",
+    "The 'nodes' field restricts which cluster nodes can use this plugin — empty means all nodes are eligible.",
+    "validation-delay defaults to 30 seconds; increase this for DNS providers with long TTLs to avoid premature ACME validation failures."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_plugins",
+    "post_cluster_acme_plugins",
+    "put_cluster_acme_plugins_id",
+    "delete_cluster_acme_plugins_id"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_acme_tos",
+  "usageNotes": "Returns the Terms of Service URL for an ACME CA directory, useful for presenting the ToS to an operator before issuing certificates. This endpoint is deprecated — use get_cluster_acme_meta instead, which returns richer ACME CA metadata including the ToS URL. The default directory points to Let's Encrypt production; supply a different directory URL to query a staging or alternate CA.",
+  "examples": [
+    {
+      "summary": "Fetch ToS URL for Let's Encrypt production CA (default)",
+      "path_params": {},
+      "params": {
+        "directory": "https://acme-v02.api.letsencrypt.org/directory"
+      }
+    }
+  ],
+  "tips": [
+    "Omitting the directory parameter uses the Let's Encrypt production directory automatically.",
+    "For testing, supply https://acme-staging-v02.api.letsencrypt.org/directory to hit the Let's Encrypt staging CA.",
+    "Prefer /cluster/acme/meta for new integrations; this endpoint may be removed in a future Proxmox release."
+  ],
+  "relatedOperations": [
+    "get_cluster_acme_meta",
+    "get_cluster_acme_directories",
+    "get_cluster_acme_accounts"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_backup",
+  "usageNotes": "Use this to list all scheduled vzdump backup jobs defined at the cluster level, including their schedule, target storage, scope (all VMs, specific VMIDs, or pool), retention policy, and compression settings. Requires the Sys.Audit privilege on the root path ('/'). This is a read-only index — it returns job configuration objects, not backup file listings; use the storage content endpoints to enumerate actual backup archives.",
+  "examples": [
+    {
+      "summary": "List all cluster backup schedules",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'next-run' field is a UNIX timestamp — convert it to a human-readable date to quickly see when each job will fire next.",
+    "Jobs with 'enabled: false' are returned in the list but will not execute; check this field when troubleshooting missed backups.",
+    "The 'node' field, when set, restricts execution to a specific node — jobs without it run on whichever node the scheduler picks, which may vary in a cluster.",
+    "mailto and mailnotification fields are deprecated; rely on notification-mode and the PVE notification system for alerting instead.",
+    "Backup fleecing (fleecing.enabled) is VM-only and requires a separate local storage that supports thin provisioning or sparse files."
+  ],
+  "relatedOperations": [
+    "get_cluster_backup_id",
+    "create_cluster_backup",
+    "update_cluster_backup",
+    "delete_cluster_backup",
+    "get_nodes_node_storage_storage_content"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_cluster_backup_id",
+  "usageNotes": "Use this to inspect the full configuration of a specific vzdump backup job before modifying or cloning it — particularly useful for auditing retention policy (prune-backups), compression settings, and which guests are targeted. Requires Sys.Audit privilege at the root path (/). The job ID can be obtained from list_cluster_backup; the response is synchronous and returns the full job definition including the next scheduled run time.",
+  "examples": [
+    {
+      "summary": "Read a specific cluster backup job definition",
+      "path_params": {
+        "id": "backup-8d3f1a2b-4c5e"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The next-run field returns a UNIX timestamp; convert it to a readable date to confirm the schedule is active.",
+    "If enabled is absent or true and next-run is missing, the job may lack a valid schedule — check the schedule field.",
+    "The mailnotification and mailto fields are deprecated; prefer notification-mode with PVE's notification system.",
+    "A job with node set will only execute when vzdump runs on that specific node — cluster-wide jobs omit this field."
+  ],
+  "relatedOperations": [
+    "list_cluster_backup",
+    "update_cluster_backup_id",
+    "delete_cluster_backup_id",
+    "create_cluster_backup"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_cluster_backup_id_included_volumes",
+  "usageNotes": "Use this to audit which disks within a cluster backup job are actually being backed up and why — useful for verifying that no critical volumes are excluded due to misconfiguration. Requires `Sys.Audit` on `/` (cluster-wide scope), so API tokens scoped to individual nodes will not work. The response is structured as a two-level tree (guests → volumes) intended for tree-view UIs; parse `children[*].children` to programmatically check each volume's `included` and `reason` fields.",
+  "examples": [
+    {
+      "summary": "Check which volumes are included for backup job 'daily-all'",
+      "path_params": {
+        "id": "daily-all"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Guests with type 'unknown' are VMs/CTs that have been removed from the cluster but not purged from the backup job — they will appear in results but have no live configuration.",
+    "A volume with included=false will show a human-readable reason string explaining the exclusion (e.g. 'drive is marked to be excluded', 'backup disabled for this guest'); use this to distinguish intentional vs. unintentional exclusions.",
+    "This endpoint reflects the current job configuration, not historical backup results — a volume marked included=true means it is configured to be backed up on the next run, not that it was successfully backed up previously."
+  ],
+  "relatedOperations": [
+    "get_cluster_backup",
+    "get_cluster_backup_id",
+    "get_nodes_node_vzdump_defaults"
+  ]
+}

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

@@ -0,0 +1,18 @@
+{
+  "operationId": "get_cluster_backup_info",
+  "usageNotes": "Use this as a discovery call to enumerate the available sub-endpoints under /cluster/backup-info (e.g., not-backed-up). It requires no parameters and no special privileges, making it a safe first step before querying specific backup-info child resources. The response is a directory index — follow the 'subdir' values to reach actionable endpoints.",
+  "examples": [
+    {
+      "summary": "List available backup-info sub-endpoints",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values are relative paths; append them to /cluster/backup-info/ to form the full child endpoint path.",
+    "This endpoint is unauthenticated in terms of privilege checks (permissions: null), but a valid API token or ticket is still required to reach the PVE API."
+  ],
+  "relatedOperations": [
+    "get_cluster_backup_info_not_backed_up"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_backup_info_not_backed_up",
+  "usageNotes": "Use this to audit backup coverage across the entire cluster — it returns every QEMU VM and LXC container that is not included in any configured backup job. Requires the Sys.Audit privilege at the root path (/), so API tokens must carry that permission. The response is cluster-wide regardless of node; no filtering parameters are available, so post-filter client-side if you need results scoped to a specific node or type.",
+  "examples": [
+    {
+      "summary": "List all guests with no backup coverage",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "An empty array means all guests are covered — treat a non-empty result as a backup gap that needs remediation.",
+    "The 'name' field in each result is optional and may be absent for guests that have no display name set.",
+    "Cross-reference VMIDs against your backup job configurations in /cluster/backup to determine which job to add the guest to.",
+    "This endpoint reflects backup job configuration, not backup execution history — a guest appears here if it is excluded from all jobs, even if a manual backup was recently run."
+  ],
+  "relatedOperations": [
+    "get_cluster_backup",
+    "get_cluster_backup_id",
+    "create_cluster_backup"
+  ]
+}

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

@@ -0,0 +1,17 @@
+{
+  "operationId": "get_cluster_bulk_action",
+  "usageNotes": "Use this endpoint to discover the resource types available under the /cluster/bulk-action namespace; it returns a list of child resource names that can be used to construct further bulk-action requests. No parameters are required and no special privileges are needed beyond a valid API token. This is a discovery/index call — follow the 'name' values in the response to navigate to the actual bulk-action sub-resources.",
+  "examples": [
+    {
+      "summary": "List available bulk-action resource types",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response 'name' field in each returned object corresponds to the {name} href link relation — use those values to build sub-resource paths under /cluster/bulk-action/{name}.",
+    "This endpoint accepts API tokens (allowtoken: true) so a scoped read-only token is sufficient; no root or admin session required.",
+    "Because no filters or parameters are accepted, the response is always the full static list of registered bulk-action resource types for the cluster."
+  ],
+  "relatedOperations": []
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_cluster_bulk_action_guest",
+  "usageNotes": "Returns the list of available bulk-action sub-resources under /cluster/bulk-action/guest (e.g. start, stop, shutdown). Call this to discover which guest bulk-action verbs the cluster exposes before invoking a specific bulk-action endpoint. Requires no privileges — any authenticated user or API token can call it.",
+  "examples": [
+    {
+      "summary": "Discover available guest bulk-action sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an index of child links (e.g. 'start', 'stop', 'shutdown') — follow the 'name' field in each item to construct the child endpoint path.",
+    "Because this endpoint has no parameters and requires only 'user: all' privileges, it is safe to call during bootstrap or health checks to confirm the bulk-action API surface is reachable."
+  ],
+  "relatedOperations": [
+    "post_cluster_bulk_action_guest_start",
+    "post_cluster_bulk_action_guest_stop",
+    "post_cluster_bulk_action_guest_shutdown"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_ceph",
+  "usageNotes": "Returns the cluster-level Ceph API index — a list of child resource names (e.g. 'config', 'status', 'osd', 'pools') available under /cluster/ceph. Use this as a discovery call to confirm which Ceph sub-resources are exposed before drilling into them. No Ceph cluster needs to be configured for this call to succeed; it returns the static index regardless.",
+  "examples": [
+    {
+      "summary": "List available Ceph cluster sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'name' values in each item correspond to child endpoints under /cluster/ceph/{name} — use them to discover valid follow-up calls.",
+    "This endpoint requires only the 'all' permission (any authenticated user or API token can call it), making it safe for read-only monitoring tokens.",
+    "Prefer node-level /nodes/{node}/ceph/* endpoints for operational Ceph management (OSD add/remove, pool create, etc.); this cluster-level index is navigation only."
+  ],
+  "relatedOperations": [
+    "get_cluster_ceph_status",
+    "get_cluster_ceph_config",
+    "get_cluster_ceph_osd",
+    "get_cluster_ceph_pools"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_ceph_flags",
+  "usageNotes": "Use this to get a cluster-wide snapshot of all Ceph OSD flags and their current on/off state. Requires Sys.Audit on the root path — read-only tokens with that privilege are sufficient. This is the first call to make when investigating Ceph health warnings related to noout, nobackfill, or scrub suppression, since any of these flags being set will show up in ceph status as a HEALTH_WARN.",
+  "examples": [
+    {
+      "summary": "List all Ceph flags to check for any suppressed operations",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A value of true means the flag is currently set (active). For example, noout=true means OSDs will not be marked out when they go down.",
+    "The pause flag halts all Ceph client I/O; if value is true on a production cluster it warrants immediate investigation.",
+    "Flags like noout and norebalance are often intentionally set during maintenance windows — verify with your change log before clearing them.",
+    "This endpoint reflects the live cluster state; it reads from the Ceph mon quorum so at least one monitor must be reachable."
+  ],
+  "relatedOperations": [
+    "get_cluster_ceph_status",
+    "set_cluster_ceph_flag",
+    "get_cluster_ceph_flag"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_cluster_ceph_flags_flag",
+  "usageNotes": "Use this to check whether a specific Ceph OSD flag is currently set on the cluster before deciding whether to enable or clear it. Requires Sys.Audit on the root path and a running Ceph cluster; the call returns a single boolean (true = flag is active). Commonly called before maintenance windows to confirm flags like 'noout' or 'nobackfill' are set or cleared as expected.",
+  "examples": [
+    {
+      "summary": "Check if the noout flag is currently enabled",
+      "path_params": {
+        "flag": "noout"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A 'true' response means the flag is active and OSD behavior is modified — e.g., 'noout' prevents OSDs from being marked out during downtime.",
+    "This is a read-only companion to set_cluster_ceph_flags_flag; pair them to verify flag state before and after a change.",
+    "All valid flag values are enumerated in the spec; any other string will return a 400 error."
+  ],
+  "relatedOperations": [
+    "get_cluster_ceph_flags",
+    "set_cluster_ceph_flags_flag"
+  ]
+}