@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pdm/enrichment/get_ceph_clusters_cluster_osd_tree.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_ceph_clusters_cluster_osd_tree",
+  "usageNotes": "Use this endpoint to retrieve the CRUSH tree structure for a Ceph cluster managed by PDM, which shows how OSDs are organized into buckets (hosts, racks, zones) and their weights. The `cluster` path parameter must be the cluster's FSID (UUID-like identifier), not a display name. This is a read-only operation accessible to all authenticated users.",
+  "examples": [
+    {
+      "summary": "Fetch the OSD tree for a specific Ceph cluster by FSID",
+      "path_params": {
+        "cluster": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The cluster FSID can be obtained from list-clusters or get-cluster endpoints — it is the UUID that Ceph uses internally, not a human-readable name.",
+    "The returned CRUSH tree reflects OSD placement, replication domains, and weights, which are useful for verifying failure domain configuration before making storage policy changes.",
+    "An empty or malformed tree may indicate the cluster is not fully initialized or PDM has lost connectivity to it."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters_cluster",
+    "get_ceph_clusters_cluster_osds",
+    "get_ceph_clusters"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_ceph_clusters_cluster_pools.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_ceph_clusters_cluster_pools",
+  "usageNotes": "Use this to enumerate all Ceph pools in a managed cluster and inspect their replication settings, PG counts, and current usage. The `cluster` path parameter must be the Ceph FSID (not a friendly name), which can be retrieved from `get_ceph_clusters`. Usage statistics (`bytes_used`, `percent_used`) are optional and will be absent if the cluster has not yet reported them.",
+  "examples": [
+    {
+      "summary": "List all pools in a Ceph cluster by FSID",
+      "path_params": {
+        "cluster": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `cluster` value is the Ceph FSID (UUID format), not a human-readable cluster name — use get_ceph_clusters to look it up first.",
+    "Pool type 'unknown' means PDM does not recognise the pool type; treat those pools as read-only/opaque.",
+    "When pg_autoscale_mode is 'on', the live pg_num may drift from pg_num_final as the autoscaler adjusts — compare both fields to detect in-progress scaling.",
+    "application_metadata keys (e.g. 'rbd', 'cephfs', 'rgw') indicate which Ceph service is using the pool; pools with no application tag are unassigned."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_ceph_clusters_cluster",
+    "get_ceph_clusters_cluster_osds"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_ceph_clusters_cluster_status.json

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_ceph_clusters_cluster_status",
+  "usageNotes": "Use this endpoint to retrieve the current health and status of a Ceph cluster managed by PDM — equivalent to running `ceph status` on the cluster. The `cluster` path parameter must be the Ceph cluster's FSID (not a human-readable name), which can be obtained from the cluster listing endpoint. Use `max-age` to control cache staleness: omitting it or passing `0` forces a live fetch, while a positive value allows PDM to serve a recently cached result, reducing load on the Ceph monitors.",
+  "examples": [
+    {
+      "summary": "Fetch live Ceph cluster status by FSID",
+      "path_params": {
+        "cluster": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {
+        "max-age": 30
+      }
+    }
+  ],
+  "tips": [
+    "The cluster identifier is a UUID-format FSID, not a cluster name — use the cluster listing endpoint first if you only know the human-readable name.",
+    "Pass `max-age=0` (or omit the parameter) when you need guaranteed fresh data, such as right after a topology change or OSD failure.",
+    "A non-empty `health.checks` object in the response indicates degraded or warning conditions that warrant investigation.",
+    "This endpoint is accessible to all authenticated users (`permissions.user: all`), so no elevated privilege is needed."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_ceph_clusters_cluster_health",
+    "get_ceph_clusters_cluster_osds",
+    "get_ceph_clusters_cluster_nodes"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_ceph_clusters_cluster_summary.json

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_ceph_clusters_cluster_summary",
+  "usageNotes": "Use this to get a typed, dashboard-ready snapshot of a Ceph cluster's health, capacity, OSD/MON/MGR/PG counts, and client I/O rates — the cluster must already be registered in PDM and at least one member must be reachable for the enriched fields (fullest-pool, version) to be populated. Most data is served from PDM's cache; pass `max-age` to control staleness tolerance, and expect `fullest-pool` / `version` to be absent if no live member read succeeds.",
+  "examples": [
+    {
+      "summary": "Fetch a fresh Ceph cluster summary, accepting cache up to 30 seconds old",
+      "path_params": {
+        "cluster": "b3e2a1f0-4c5d-4e6f-8a7b-9c0d1e2f3a4b"
+      },
+      "params": {
+        "max-age": 30
+      }
+    }
+  ],
+  "tips": [
+    "The `cluster` path param is the Ceph fsid (UUID format) — find it via the cluster list endpoint, not the cluster's display name.",
+    "Check `version-mixed: true` during rolling upgrades; a mixed-version cluster may show degraded performance or unexpected warnings.",
+    "If `checks` is non-empty, inspect each entry's `code` (e.g. OSD_DOWN, POOL_NEAR_FULL) to triage alerts without shelling into a Ceph node.",
+    "Use `fullest-pool` + `fullest-pool-used` together — cluster-wide `bytes-avail` can look healthy while a single pool is near capacity and blocking writes.",
+    "A missing `version` field means no live member read succeeded; the cached health/capacity figures are still returned from PDM's internal cache."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_ceph_clusters_cluster",
+    "get_ceph_clusters_cluster_osds",
+    "get_ceph_clusters_cluster_pools",
+    "get_ceph_clusters_cluster_health"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config.json

@@ -0,0 +1,19 @@
+{
+  "operationId": "get_config",
+  "usageNotes": "Use this to enumerate the top-level configuration sub-resources exposed by the PDM API; it acts as a directory index rather than returning configuration values directly. The response is a list of available sub-endpoints under /config, not a settings payload. No special privilege beyond a valid API token is required.",
+  "examples": [
+    {
+      "summary": "List available configuration sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The return type is null in the spec, meaning the useful data is in the array of child links — iterate those to discover which /config/* endpoints are available on your PDM version.",
+    "Because this endpoint requires no parameters and is read-only, it is safe to call during health checks or capability probing."
+  ],
+  "relatedOperations": [
+    "get_config_remotes",
+    "get_config_nodes"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access.json

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_config_access",
+  "usageNotes": "Use this endpoint to discover the available sub-resources under the /config/access namespace in Proxmox Datacenter Manager. It functions as a directory index and requires no elevated privileges — any authenticated user or API token may call it. The response structure is null-typed in the spec, meaning the API returns a list of child endpoints rather than a domain object.",
+  "examples": [
+    {
+      "summary": "List available access configuration sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "No query parameters are accepted; passing any will be silently ignored or rejected.",
+    "Because permissions are 'user: all', this is safe to call with any valid API token for capability discovery.",
+    "Use the returned directory entries to determine which /config/access/* endpoints exist before drilling into a specific sub-resource."
+  ],
+  "relatedOperations": [
+    "get_config_access_domains",
+    "get_config_access_users",
+    "get_config_access_roles"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access_ad.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_config_access_ad",
+  "usageNotes": "Use this to enumerate all Active Directory (LDAP) authentication realms configured in Proxmox Datacenter Manager. Requires the Realm.Allocate privilege on /access/domains — typically held by administrators only. Call this before creating or updating AD realm settings to confirm existing realm names and server configuration.",
+  "examples": [
+    {
+      "summary": "List all configured AD realms",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'realm' field in each returned object is the identifier used when logging in as user@realm.",
+    "Check the 'default' field to see which realm is pre-selected on the PDM login screen.",
+    "The 'mode' field indicates LDAP transport security: prefer 'ldaps' or 'ldap+starttls' over plain 'ldap' in production.",
+    "If 'verify' is false, TLS certificate validation is disabled for the AD server connection — a potential security risk worth flagging during audits.",
+    "bind-dn and base-dn being absent from a realm entry means user sync is not fully configured for that realm."
+  ],
+  "relatedOperations": [
+    "get_config_access_domains",
+    "get_config_access_openid",
+    "get_config_access_ldap"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access_ad_realm.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_config_access_ad_realm",
+  "usageNotes": "Retrieves the full configuration of a specific Active Directory (LDAP) authentication realm by name — use this to inspect connection settings (server, port, TLS mode, bind DN, base DN), sync attribute mappings, and sync defaults before modifying or troubleshooting an AD realm. Requires the System.Audit privilege on the access/domains path; API tokens are supported. The realm name must already exist in PDM — use get_config_access_ad to list known realm names first.",
+  "examples": [
+    {
+      "summary": "Read configuration for the AD realm named 'corp-ad'",
+      "path_params": {
+        "realm": "corp-ad"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response omits sensitive credentials such as the bind password — use this endpoint for configuration auditing, not credential retrieval.",
+    "Check the 'mode' field (ldap / ldap+starttls / ldaps) and 'verify' flag to assess whether the realm is using an encrypted and verified connection.",
+    "If 'default' is true, this realm is pre-selected on the PDM login screen — there should only be one default realm across all realms.",
+    "The 'sync-attributes' and 'sync-defaults-options' fields control automated user synchronization behavior; review them before running a sync via post_access_domains_realm_sync."
+  ],
+  "relatedOperations": [
+    "get_config_access_ad",
+    "put_config_access_ad_realm",
+    "delete_config_access_ad_realm",
+    "post_config_access_ad"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access_ldap.json

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_config_access_ldap",
+  "usageNotes": "Use this to enumerate all LDAP authentication realms configured in Proxmox Datacenter Manager — useful before syncing users, auditing realm settings, or verifying that a specific realm (and its bind-dn, server, and mode) is present. Requires the Realm.Allocate privilege on /access/domains; API tokens are supported. The response exposes bind-dn and CA paths in plain text but never the bind password.",
+  "examples": [
+    {
+      "summary": "List all LDAP realms to verify Active Directory realm is configured with ldaps mode",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A realm with 'default: true' is pre-selected on the PDM login screen — check this when users report being sent to the wrong login provider.",
+    "The 'mode' field determines TLS behavior: prefer 'ldaps' or 'ldap+starttls' over plain 'ldap' for production. Plain text mode is the default and will appear in responses if TLS was never configured.",
+    "sync-attributes maps LDAP fields to PDM user properties (email, firstname, lastname); if these are missing, user sync will create accounts with no display name or contact info.",
+    "server2 is an optional fallback; if it is absent and server1 is unreachable, authentication will fail for all users in that realm."
+  ],
+  "relatedOperations": [
+    "get_config_access_ldap_realm",
+    "post_config_access_ldap",
+    "put_config_access_ldap_realm",
+    "delete_config_access_ldap_realm",
+    "post_config_access_ldap_realm_sync"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access_ldap_realm.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_config_access_ldap_realm",
+  "usageNotes": "Use this to inspect the full configuration of a specific LDAP authentication realm configured in Proxmox Datacenter Manager, including server addresses, bind DN, TLS mode, sync attribute mappings, and sync defaults. Requires the System.Audit privilege on the access/domains path — API tokens are supported. Note that the bind-dn credential (password) is not returned; only the structural config is exposed.",
+  "examples": [
+    {
+      "summary": "Retrieve the configuration for an LDAP realm named 'corp-ad'",
+      "path_params": {
+        "realm": "corp-ad"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response omits the bind password even if one is configured — use this call only to verify structural settings, not credential presence.",
+    "Check the 'mode' field (ldap / ldap+starttls / ldaps) and 'verify' flag together when troubleshooting TLS handshake failures during user sync.",
+    "If 'default' is true, this realm is pre-selected on the PDM login screen — changing it affects all users who rely on the default.",
+    "sync-attributes and sync-defaults-options are returned as formatted strings (comma-separated key=value pairs), not nested objects."
+  ],
+  "relatedOperations": [
+    "list_config_access_ldap",
+    "update_config_access_ldap_realm",
+    "delete_config_access_ldap_realm",
+    "create_config_access_ldap_realm"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access_openid.json

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_config_access_openid",
+  "usageNotes": "Use this to retrieve all OpenID Connect realms configured in Proxmox Datacenter Manager, including their issuer URLs, client IDs, scopes, and autocreate settings. Requires the 'Realm.Allocate' privilege on the 'access/domains' path — typically held by administrators only. The client-key field (shared secret) is returned in the response, so treat the output as sensitive.",
+  "examples": [
+    {
+      "summary": "List all configured OpenID realms",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'client-key' (OIDC client secret) is included in plain text in the response — avoid logging or storing the full output.",
+    "If 'autocreate' is true on a realm, any authenticating user not yet in PDM will be automatically provisioned — audit this setting when reviewing your IdP.",
+    "The 'username-claim' field controls which IdP claim maps to the PDM username; if left unset, the OIDC 'sub' (subject) claim is used, which may produce opaque usernames.",
+    "The 'default' flag indicates which realm is pre-selected on the login page; only one realm should have this set to true."
+  ],
+  "relatedOperations": [
+    "get_config_access_domains",
+    "get_config_access_tfa"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access_openid_realm.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_config_access_openid_realm",
+  "usageNotes": "Use this to inspect the full OpenID Connect configuration for a specific realm before modifying it or troubleshooting SSO login failures. The caller must hold the System.Audit privilege on /access/domains — API tokens are supported. Note that client-key (the client secret) is returned in the response, so treat the output as sensitive.",
+  "examples": [
+    {
+      "summary": "Retrieve the configuration for an OpenID realm named 'sso-azure'",
+      "path_params": {
+        "realm": "sso-azure"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The realm name must be 2–32 characters and match /^(?:[A-Za-z0-9_][A-Za-z0-9._\\-]*)$/ — names starting with a dot or hyphen are rejected.",
+    "client-key (the OIDC client secret) is included in the response; avoid logging or storing the output in plain text.",
+    "If autocreate is false and a user does not yet exist in PDM, their first SSO login will fail even if the IdP authenticates them successfully.",
+    "scopes defaults to 'email profile'; if username-claim references a non-standard claim (e.g. 'preferred_username'), ensure that scope is included in the realm config.",
+    "Use this endpoint to capture the current state before calling the corresponding update operation, so you can diff and restore if needed."
+  ],
+  "relatedOperations": [
+    "get_config_access_openid",
+    "put_config_access_openid_realm",
+    "delete_config_access_openid_realm",
+    "post_config_access_openid"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access_tfa.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_config_access_tfa",
+  "usageNotes": "Use this endpoint to discover the available sub-resources under the /config/access/tfa namespace in Proxmox Datacenter Manager. It acts as a directory index for TFA configuration — call it to enumerate which TFA-related child endpoints are exposed before drilling into a specific one. No elevated privileges are required; any authenticated user or API token can call it.",
+  "examples": [
+    {
+      "summary": "List available TFA configuration sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "No query parameters are accepted — the response is a fixed directory listing.",
+    "Because permissions are 'user: all', this is safe to use with any valid API token for capability discovery.",
+    "Use the returned directory entries to identify which /config/access/tfa/* endpoints are available before querying or modifying TFA settings."
+  ],
+  "relatedOperations": [
+    "get_config_access",
+    "get_access_tfa",
+    "get_access_tfa_userid",
+    "get_access_tfa_userid_id",
+    "post_access_tfa_userid",
+    "put_access_tfa_userid_id",
+    "delete_access_tfa_userid_id"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_access_tfa_webauthn.json

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_config_access_tfa_webauthn",
+  "usageNotes": "Returns the WebAuthn (FIDO2) relying-party configuration currently active in Proxmox Datacenter Manager — specifically the RP ID, RP name, origin, and subdomain policy. Call this before enrolling hardware keys or troubleshooting failed WebAuthn assertions to confirm the relying-party settings match the URL users actually browse to. Any authenticated user or API token may call it; no elevated privilege is required.",
+  "examples": [
+    {
+      "summary": "Fetch the current WebAuthn relying-party config",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `id` field is the Relying Party ID (domain only, no scheme/port). It must exactly match the eTLD+1 of the URL users browse — a mismatch causes every WebAuthn assertion to fail.",
+    "If `origin` is omitted, PDM derives it automatically; set it explicitly when your PDM instance is behind a reverse proxy or load balancer with a different hostname.",
+    "`allow-subdomains: true` (the default) lets credentials registered on `pdm.example.com` authenticate on `other.example.com` — disable it in strict single-host deployments.",
+    "Changing `id` or `rp` invalidates all existing registered hardware keys; warn users before modifying those fields via the corresponding PUT/POST endpoint."
+  ],
+  "relatedOperations": [
+    "put_config_access_tfa_webauthn",
+    "get_config_access_tfa",
+    "post_access_tfa"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_acme.json

@@ -0,0 +1,16 @@
+{
+  "operationId": "get_config_acme",
+  "usageNotes": "Returns the ACME configuration directory index for Proxmox Datacenter Manager, listing available ACME sub-resources (accounts, plugins, etc.). Use this as a discovery call before working with ACME certificate automation. Requires no special privileges — any authenticated user or API token can call it.",
+  "examples": [
+    {
+      "summary": "List available ACME config sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a directory index endpoint — it lists sub-resource paths, not ACME account or plugin data itself. Follow up with more specific ACME endpoints to read or manage accounts and plugins.",
+    "The returns type is 'null' in the spec, meaning the response structure is not formally typed; treat the response as an informational directory listing."
+  ],
+  "relatedOperations": []
+}

package/dist/catalog-pdm/enrichment/get_config_acme_account.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_config_acme_account",
+  "usageNotes": "Lists all ACME accounts registered on the Proxmox Datacenter Manager instance. Use this before creating or assigning an ACME account to a certificate order to confirm which named accounts are available. Requires the System.Modify privilege on the system/certificates path.",
+  "examples": [
+    {
+      "summary": "List all registered ACME accounts",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response only returns account names — fetch individual account details via the account-specific endpoint if you need contact email or directory URL.",
+    "A fresh PDM install returns an empty array until at least one ACME account is registered.",
+    "Account names follow the pattern [A-Za-z0-9_][A-Za-z0-9._-]* — useful to know when scripting lookups by name."
+  ],
+  "relatedOperations": [
+    "post_config_acme_account",
+    "get_config_acme_account_name",
+    "put_config_acme_account_name",
+    "delete_config_acme_account_name",
+    "get_config_acme_directories"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_acme_account_name.json

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_config_acme_account_name",
+  "usageNotes": "Use this to inspect the current state of a registered ACME account on Proxmox Datacenter Manager, including its contact email, status (valid/deactivated/revoked), and the ACME directory it was registered with. Requires System.Modify on /system/certificates — the same privilege needed to manage certificates. Check the returned account.status field before attempting any certificate order; a non-'valid' status means the account cannot be used for issuance.",
+  "examples": [
+    {
+      "summary": "Fetch details for the default ACME account",
+      "path_params": {
+        "name": "default"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Account names must start with an alphanumeric or underscore character and may contain dots, dashes, and underscores (pattern: /^(?:[A-Za-z0-9_][A-Za-z0-9.\\-_]*)$/).",
+    "The 'directory' field in the response identifies whether the account is registered with Let's Encrypt production, Let's Encrypt staging, or a custom ACME CA.",
+    "If account.status is 'deactivated' or 'revoked', certificate renewals will fail silently until the account is replaced or re-registered.",
+    "The 'location' URL is the account's canonical URL at the ACME provider and can be used to verify account identity independently."
+  ],
+  "relatedOperations": [
+    "get_config_acme_account",
+    "post_config_acme_account",
+    "put_config_acme_account_name",
+    "delete_config_acme_account_name"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_acme_challenge_schema.json

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_config_acme_challenge_schema",
+  "usageNotes": "Use this endpoint to discover which ACME challenge plugin types are available on the PDM instance and what configuration parameters each plugin expects. The returned schema objects are used as a reference when creating or updating ACME plugins via the config/acme/plugins endpoints — match the plugin `id` and populate fields according to the `schema` object. No authentication privileges beyond a valid API token are required (user: all).",
+  "examples": [
+    {
+      "summary": "List all available ACME challenge plugin schemas",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `schema` property within each item uses additionalProperties:true, so the shape varies per plugin type (e.g., dns-01 plugins expose provider-specific credential fields).",
+    "Cross-reference the returned `id` values with existing plugin configurations from get_config_acme_plugins to identify which schemas are already in use.",
+    "This endpoint is safe to call unauthenticated in practice (user: all), making it suitable for pre-flight checks before presenting a plugin-creation UI."
+  ],
+  "relatedOperations": [
+    "get_config_acme_plugins",
+    "get_config_acme_directories",
+    "get_config_acme_accounts"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_acme_directories.json

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_config_acme_directories",
+  "usageNotes": "Call this before creating or updating an ACME account to discover the available directory endpoints (e.g., Let's Encrypt production and staging). No parameters or special privileges are required — any authenticated user or API token can call it. Use the returned 'name' and 'url' fields when referencing a directory in account or plugin configuration.",
+  "examples": [
+    {
+      "summary": "List all known ACME directory endpoints",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The list is built into PDM and reflects well-known public ACME directories (e.g., Let's Encrypt v2 production and staging); it is not user-configurable.",
+    "Use the staging directory (if listed) for testing certificate workflows before switching to production to avoid Let's Encrypt rate limits.",
+    "The 'url' value from this response is the canonical endpoint to supply when referencing an ACME directory in plugin or account configurations."
+  ],
+  "relatedOperations": [
+    "get_config_acme_accounts",
+    "get_config_acme_plugins",
+    "post_config_acme_account"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_acme_plugins.json

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_config_acme_plugins",
+  "usageNotes": "Returns all ACME challenge plugin configurations registered in Proxmox Datacenter Manager, including both standalone HTTP and DNS-01 challenge plugins. Requires the caller to hold the System.Modify privilege on the system/certificates path — a read-only privilege is not sufficient. Use this before creating or updating ACME orders to confirm the desired plugin ID exists and is not disabled.",
+  "examples": [
+    {
+      "summary": "List all configured ACME challenge plugins",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Items with 'disable: true' are present in the list but will not be used by ACME certificate orders — check this field before referencing a plugin ID in a certificate configuration.",
+    "The 'validation-delay' field (in seconds) is relevant for DNS-01 plugins where the DNS provider has a long TTL; increase it if ACME validation fails intermittently.",
+    "The 'plugin' field is the ID you reference when assigning a challenge plugin to a node's ACME certificate configuration."
+  ],
+  "relatedOperations": [
+    "get_config_acme_accounts",
+    "get_config_acme_directories",
+    "get_config_acme_tos"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_acme_plugins_id.json

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_config_acme_plugins_id",
+  "usageNotes": "Use this endpoint to retrieve the full configuration of a specific ACME challenge plugin registered in Proxmox Datacenter Manager, including its DNS API name, credentials data, enabled/disabled state, and validation delay. Requires the System.Modify privilege on the system/certificates path. Call list_config_acme_plugins first to enumerate valid plugin IDs if the ID is not already known.",
+  "examples": [
+    {
+      "summary": "Fetch details for a DNS-01 ACME plugin named 'cloudflare-dns'",
+      "path_params": {
+        "id": "cloudflare-dns"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'data' field contains raw credential key-value pairs (e.g. CF_Token=xxx); treat it as sensitive — avoid logging the full response.",
+    "A plugin returned with 'disable: true' is registered but will not be used for certificate issuance until re-enabled.",
+    "The 'validation-delay' field is useful for DNS providers with slow propagation; a value of 120–300 seconds is common for high-TTL zones.",
+    "Plugin IDs must match the pattern /^(?:[A-Za-z0-9_][A-Za-z0-9._-]*)$/ and are limited to 32 characters."
+  ],
+  "relatedOperations": [
+    "get_config_acme_plugins",
+    "post_config_acme_plugins",
+    "put_config_acme_plugins_id",
+    "delete_config_acme_plugins_id",
+    "get_config_acme_accounts_name"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_acme_tos.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_config_acme_tos",
+  "usageNotes": "Call this before registering an ACME account to retrieve the Terms of Service URL that the user must agree to. If no directory parameter is supplied, PDM uses its default ACME directory. Returns an empty/null response when the directory does not publish a ToS URL.",
+  "examples": [
+    {
+      "summary": "Fetch ToS URL for the Let's Encrypt production directory",
+      "path_params": {},
+      "params": {
+        "directory": "https://acme-v02.api.letsencrypt.org/directory"
+      }
+    }
+  ],
+  "tips": [
+    "Omit the 'directory' parameter to get the ToS for PDM's default ACME directory (typically Let's Encrypt staging or production depending on configuration).",
+    "Store the returned URL and present it to the user before calling any account-registration endpoint that accepts a ToS agreement flag.",
+    "A null/empty return means the ACME provider has no ToS requirement — account creation can proceed without agreement."
+  ],
+  "relatedOperations": [
+    "get_config_acme_directories",
+    "get_config_acme_accounts",
+    "post_config_acme_account"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_certificate.json

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_config_certificate",
+  "usageNotes": "Use this to read the PDM node's current TLS certificate configuration, including which ACME account is bound and which domains (acmedomain0–acmedomain4) are configured for automatic certificate issuance. All returned fields are optional — an unconfigured node returns an empty object. Requires System.Audit privilege; a read-only API token with that privilege is sufficient.",
+  "examples": [
+    {
+      "summary": "Retrieve the current ACME certificate configuration for the PDM node",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Up to five domain slots (acmedomain0–acmedomain4) can be configured; slots absent from the response are simply unconfigured, not an error.",
+    "The 'alias' field within each acmedomain entry lets you redirect ACME DNS-01 challenges to a different domain via CNAME — useful when the PDM host's DNS zone is not directly manageable.",
+    "An empty 'plugin' field on a domain slot means standalone HTTP-01 validation is in use for that domain.",
+    "To see which ACME accounts are available to reference in the 'acme' field, call get_config_acme_account first."
+  ],
+  "relatedOperations": [
+    "get_config_acme",
+    "get_config_acme_account",
+    "get_config_acme_account_name",
+    "get_config_acme_plugins"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_notes.json

@@ -0,0 +1,19 @@
+{
+  "operationId": "get_config_notes",
+  "usageNotes": "Retrieves the PDM instance-level notes as a UTF-8 encoded Markdown string — useful for storing and reading shared operational notes visible to all Datacenter Manager admins. No parameters are required; the call simply returns whatever Markdown content has been saved at the system level. Requires the System.Audit privilege on the /system ACL path.",
+  "examples": [
+    {
+      "summary": "Fetch the current PDM instance notes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is raw Markdown text — render it client-side if displaying to users.",
+    "If no notes have been set, the API may return an empty string or null; handle both cases.",
+    "API tokens are supported (allowtoken: true), so a read-only service account token with System.Audit is sufficient."
+  ],
+  "relatedOperations": [
+    "put_config_notes"
+  ]
+}

package/dist/catalog-pdm/enrichment/get_config_views.json

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_config_views",
+  "usageNotes": "Use this endpoint to list all PDM views the authenticated user can access; no parameters are required and any valid API token is sufficient since access is user-scoped by the server. Views define named resource filters (include/exclude rules by type, pool, tag, remote, or resource ID) that scope what resources are visible in the PDM UI or downstream calls — fetch this list before referencing a view ID in other operations. The 'layout' field is an opaque JSON string intended for UI state and can be ignored in automation contexts.",
+  "examples": [
+    {
+      "summary": "List all views available to the current API token user",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "No query parameters exist — the response scope is determined entirely by the authenticated user's permissions.",
+    "Each view's 'id' is the handle used to reference that view in other config or resource-scoping operations.",
+    "Filter rules support an optional 'exact:' prefix to force exact matching rather than substring matching on pool/tag/remote names.",
+    "A view with 'include-all: true' and no exclude rules returns every resource the user can see — effectively an unfiltered view.",
+    "The 'layout' field is opaque UI state; skip it in automation and only parse 'include', 'exclude', and 'include-all' for resource scoping logic."
+  ],
+  "relatedOperations": [
+    "get_config_remotes",
+    "get_resources"
+  ]
+}