@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_acl",
+  "usageNotes": "Use this endpoint to inspect the ACL tree for a PDM realm — either the full tree or a scoped subtree by path. Pass `exact=true` to avoid inheriting child ACEs and get only the entry at that exact path. Use `all-for-authid=true` when you want to see the effective permissions of the currently authenticated identity (token or user), but note that results are normalized to `ugid_type: user` and cannot be used as input to rebuild the ACL tree.",
+  "examples": [
+    {
+      "summary": "List all ACL entries under the /datacenters path",
+      "path_params": {},
+      "params": {
+        "path": "/datacenters",
+        "exact": false
+      }
+    }
+  ],
+  "tips": [
+    "Omitting `path` returns the entire ACL tree — useful for a full audit but can be verbose on busy deployments.",
+    "`propagate: true` on an entry means the role is inherited by child paths; audit entries where propagate is false if narrowing access.",
+    "When `all-for-authid=true`, the response always reports `ugid_type: user` regardless of actual group membership — do not rely on it to determine group ACEs."
+  ],
+  "relatedOperations": [
+    "update_access_acl",
+    "get_access_users",
+    "get_access_groups",
+    "get_access_roles"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_access_domains",
+  "usageNotes": "Use this to enumerate all configured authentication realms on the PDM instance — useful before attempting login, provisioning users, or validating that a specific realm (e.g. an LDAP or OpenID provider) is registered. Requires no authentication, so it can be called before any token is available. Returns only basic realm metadata; for detailed realm configuration use an authenticated admin endpoint.",
+  "examples": [
+    {
+      "summary": "List all authentication realms configured on the PDM instance",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'default' boolean field identifies the realm pre-selected on the login page; there will be at most one entry with default=true.",
+    "Realm type 'pam' refers to Linux PAM (local OS users), 'pdm' is the built-in PDM realm, 'openid'/'ad'/'ldap' are external providers.",
+    "This endpoint is unauthenticated (user: world) — safe to call before obtaining a session token or API token.",
+    "Use the returned 'realm' string as the realm component when constructing user IDs (e.g. 'root@pam', 'admin@ldap')."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "get_access_ticket"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_access_openid",
+  "usageNotes": "Returns the directory index of available OpenID Connect sub-resources under /access/openid. Use this as a discovery call to enumerate what OpenID endpoints PDM exposes before calling specific OpenID operations (e.g. login, callback). No parameters are required and no special privilege is needed — all authenticated users can call it.",
+  "examples": [
+    {
+      "summary": "Discover available OpenID sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns null per the spec — the actual directory listing is embedded in the API envelope (data field), not a typed schema.",
+    "Useful as a connectivity/auth smoke-test since it requires no privilege beyond a valid token."
+  ],
+  "relatedOperations": [
+    "get_access",
+    "post_access_openid_login",
+    "post_access_openid_auth_url"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_access_permissions",
+  "usageNotes": "Use this to inspect what privileges a user or API token holds, either across all ACL paths or scoped to a specific path. Without `auth-id`, it returns the calling identity's own permissions; with `auth-id` specified, `Sys.Audit` on `/access` is required. Useful before performing privileged operations to confirm the caller has the necessary rights without triggering a failed request.",
+  "examples": [
+    {
+      "summary": "Get permissions for a specific API token scoped to the /nodes path",
+      "path_params": {},
+      "params": {
+        "auth-id": "admin@pam!monitoring-token",
+        "path": "/nodes"
+      }
+    }
+  ],
+  "tips": [
+    "Omit both params to quickly audit your own token's full permission map — useful when debugging 403 errors.",
+    "The `path` filter narrows results to a single ACL tree node; without it you receive the entire permission map, which can be large.",
+    "The `auth-id` format differs between users (`user@realm`) and API tokens (`user@realm!tokenid`) — the pattern enforces this distinction.",
+    "The response map keys are ACL paths (e.g. `/nodes/pve`) and values are maps of privilege name to propagate flag (1 = propagate, 0 = no propagate)."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "get_access_roles",
+    "get_access_acl",
+    "get_access_tokens"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_access_roles",
+  "usageNotes": "Use this to enumerate all roles defined in Proxmox Datacenter Manager, including both built-in system roles and any custom roles. Available to every authenticated user and API token — no special privilege required. Useful before assigning permissions to a user or token, so you can confirm the exact roleid and its associated privilege set.",
+  "examples": [
+    {
+      "summary": "List all available roles to find the right role before assigning permissions",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response includes a 'privs' array on each role — inspect it to verify a role grants the exact privileges needed before assigning it.",
+    "Built-in system roles (e.g. Administrator, NoAccess, PVEAdmin) are included alongside any custom roles; filter by roleid prefix if you only want one category.",
+    "This endpoint is safe to call with a least-privilege API token since it requires no elevated permissions."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "get_access_acl",
+    "get_access_tokens"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_access_tfa",
+  "usageNotes": "Use this endpoint to audit all TFA configurations across users in the Proxmox Datacenter Manager instance. Unprivileged users receive only their own entry; admin-level access is required to see all users. The response also surfaces lockout state — check `totp-locked` and `tfa-locked-until` to identify accounts currently blocked from second-factor authentication.",
+  "examples": [
+    {
+      "summary": "List all TFA entries (admin token)",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A user with no TFA entries will not appear in the result array; absence from the list means no TFA is configured, not that the request failed.",
+    "The `tfa-locked-until` field is only present when a lockout is active — always check for its existence before reading it.",
+    "Entry type `recovery` indicates one-time recovery codes; audit these alongside `totp` and `webauthn` entries when reviewing security posture.",
+    "API tokens (`allowtoken: true`) can call this endpoint, making it safe for automated compliance scans without exposing a user password."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "post_access_tfa_userid",
+    "delete_access_tfa_userid_id",
+    "get_access_users"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_tfa_userid",
+  "usageNotes": "Use this to list all TFA entries (TOTP, WebAuthn, YubiKey, recovery codes, U2F) registered for a specific user. Callers must either hold Access.Modify on /access/users or be the user themselves (self-lookup is permitted). Returns an empty array if the user has no TFA configured — not an error.",
+  "examples": [
+    {
+      "summary": "List all TFA entries for admin@pam",
+      "path_params": {
+        "userid": "admin@pam"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The userid must match the PDM realm format: localname@realm (e.g. kevin@pve, service-account@pam). The pattern enforces no whitespace, colons, or control characters before the @.",
+    "A disabled TFA entry (enable: false) is still returned in the list — check the enable field to determine which entries are actively enforced.",
+    "Recovery-type entries are one-time-use codes; their presence in this list does not mean any codes remain unused.",
+    "API tokens (allowtoken: true) may call this endpoint, making it suitable for automated auditing scripts."
+  ],
+  "relatedOperations": [
+    "post_access_tfa_userid",
+    "put_access_tfa_userid_id",
+    "delete_access_tfa_userid_id",
+    "get_access_users"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_access_tfa_userid_id",
+  "usageNotes": "Use this to inspect a specific TFA entry (TOTP, WebAuthn, YubiKey, recovery, or U2F) for a given user — useful when you need to check whether a particular second factor is enabled or to retrieve its type and creation timestamp. The caller must either have the `Access.Modify` privilege on `/access/users` or be the same user referenced by `userid`. The `id` path parameter is the opaque entry ID returned by the list-TFA endpoints, not a human-readable label.",
+  "examples": [
+    {
+      "summary": "Retrieve a specific TOTP entry for a PDM user",
+      "path_params": {
+        "userid": "admin@pve",
+        "id": "totp-7f3a1c9b2e4d"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `userid` must match the pattern user@realm (e.g. admin@pve, kevin@pbs); bare usernames without a realm are invalid.",
+    "TFA entry IDs are opaque strings — obtain them first from the list endpoint (GET /access/tfa/{userid}) before calling this endpoint.",
+    "The `enable` field indicates if the entry is active; a user may have multiple entries where some are disabled.",
+    "API tokens are permitted (allowtoken: true), so automation scripts can query TFA state without interactive credentials."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "post_access_tfa_userid",
+    "put_access_tfa_userid_id",
+    "delete_access_tfa_userid_id"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_users",
+  "usageNotes": "Use this to enumerate all PDM user accounts — any authenticated user can call it, but non-admin callers only receive their own record. Pass include_tokens=true when auditing API token usage or preparing to rotate tokens. The response includes account enable/disable state and expiration timestamps, making it useful for periodic access reviews.",
+  "examples": [
+    {
+      "summary": "List all users including their API tokens",
+      "path_params": {},
+      "params": {
+        "include_tokens": true
+      }
+    }
+  ],
+  "tips": [
+    "Non-privileged callers silently receive only their own user object — check the caller's realm privileges if the list looks unexpectedly short.",
+    "Token objects in the response never include the raw secret; use this to audit token IDs and expiry, not to retrieve secrets.",
+    "A non-zero 'tfa-locked-until' timestamp means the user is blocked from MFA-protected operations until that epoch; admin intervention is required to unlock early.",
+    "Expired users (expire > 0 and past current time) remain in the list — filter by 'enable' and 'expire' client-side if you need only active accounts."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "get_access_roles",
+    "get_access_acl",
+    "get_access_permissions"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_access_users_userid",
+  "usageNotes": "Use this to retrieve the current configuration of a specific PDM user — their display name, email, enabled state, and expiration. The caller must hold System.Audit on /access/users or be reading their own account (the userid path param matches the authenticated identity). The userid must be in user@realm format (e.g. admin@pam); supplying only a username without a realm will fail validation.",
+  "examples": [
+    {
+      "summary": "Fetch configuration for the built-in admin account",
+      "path_params": {
+        "userid": "admin@pam"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A returned 'enable: false' means the account is disabled and cannot authenticate — useful for auditing stale or locked-out accounts.",
+    "The 'expire' field is a Unix epoch integer; value 0 means the account never expires.",
+    "API tokens (allowtoken: true) can call this endpoint, making it safe to use from automation without a full session ticket."
+  ],
+  "relatedOperations": [
+    "get_access_users",
+    "put_access_users_userid",
+    "delete_access_users_userid"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_users_userid_token",
+  "usageNotes": "Use this to audit or inventory all API tokens associated with a given PDM user before rotating credentials, diagnosing auth failures, or verifying token expiry. Callers need either the `System.Audit` privilege on `/access/users` or must be querying their own userid. The response includes each token's `tokenid` (full auth ID in `user@realm!tokenname` format), enabled state, and expiry — note that `token-name` alone is not a unique identifier; always use `tokenid` when referencing a specific token in subsequent calls.",
+  "examples": [
+    {
+      "summary": "List all API tokens for a local admin user",
+      "path_params": {
+        "userid": "admin@pam"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `tokenid` field uses the full `user@realm!tokenname` format required by PDM API auth headers — copy it directly when constructing `PDMAPIToken=` credentials.",
+    "A token with `enable: false` will be rejected at auth time even if the secret is valid; check this field when troubleshooting 401s.",
+    "Tokens with `expire: 0` never expire — flag these during security audits.",
+    "This endpoint does NOT return the token secret; secrets are only available at token creation time."
+  ],
+  "relatedOperations": [
+    "post_access_users_userid_token_tokenname",
+    "get_access_users_userid_token_tokenname",
+    "delete_access_users_userid_token_tokenname",
+    "get_access_users"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_access_users_userid_token_token_name",
+  "usageNotes": "Use this to inspect the metadata (enabled state, expiry, comment) of a specific API token belonging to a user. The caller must either hold System.Audit on /access/users or be the owner of the token (the userid path param must match the authenticated principal). Note that the raw secret value is never returned — only the token's configuration properties.",
+  "examples": [
+    {
+      "summary": "Fetch metadata for the 'automation' token belonging to admin@pam",
+      "path_params": {
+        "userid": "admin@pam",
+        "token-name": "automation"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The token-name alone does not uniquely identify a token across users — the full tokenid (user@realm!token-name) is returned in the response and serves as the canonical identifier.",
+    "A response with enable: false means the token exists but is disabled and will be rejected by the API.",
+    "expire: 0 means the token never expires; any non-zero value is a Unix timestamp cutoff."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid_token",
+    "post_access_users_userid_token_token_name",
+    "put_access_users_userid_token_token_name",
+    "delete_access_users_userid_token_token_name"
+  ]
+}

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

@@ -0,0 +1,16 @@
+{
+  "operationId": "get_auto_install",
+  "usageNotes": "Returns the directory index of the auto-install API resource, listing available child endpoints under /auto-install. Use this as a discovery call to confirm which auto-install sub-resources the PDM instance exposes before calling more specific operations. Accessible by all authenticated users; no elevated privileges required.",
+  "examples": [
+    {
+      "summary": "List available auto-install sub-resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This endpoint returns null per the spec — the directory index response body may be empty or minimal; treat it as a structural probe rather than a data-bearing call.",
+    "No parameters are accepted; any query string values will be ignored."
+  ],
+  "relatedOperations": []
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_auto_install_installations",
+  "usageNotes": "Use this to monitor all automated bare-metal installations managed by proxmox-auto-installer instances connected to PDM. Each record shows the current lifecycle status ('in-progress', 'answer-sent', 'no-answer-found', 'finished') and includes rich post-hook hardware/network data once the installation completes. Requires the 'System.Audit' privilege on the '/system/auto-installation' path; the post-hook-token field is scrubbed from all API responses and never returned.",
+  "examples": [
+    {
+      "summary": "List all automated installations to check for any stuck or unanswered installs",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Filter client-side on 'status' field: 'no-answer-found' means no matching answer file was located for the machine — check answer templates and hardware identifiers.",
+    "The 'uuid' field uniquely identifies each installation session; correlate it with auto-installer logs or answer files when troubleshooting.",
+    "Post-hook data (SSH host keys, FQDN, disk layout, machine-id) is only populated after a successful installation completes and the post-install webhook fires.",
+    "The 'received-at' field is a Unix epoch integer — convert to human-readable time when triaging stalled installs.",
+    "The 'post-hook-token' is intentionally omitted from all API responses; it exists only on disk for webhook authentication."
+  ],
+  "relatedOperations": [
+    "get_auto_install_answers",
+    "create_auto_install_answer",
+    "delete_auto_install_installation"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_auto_install_prepared",
+  "usageNotes": "Use this endpoint to enumerate all prepared auto-installer answer configurations stored in PDM, which are matched against incoming PXE/network boot requests to drive unattended Proxmox installations. Requires the System.Audit privilege on the system/auto-installation path — read-only tokens are sufficient. Note that several fields (fqdn, mailto, cidr, gateway, dns) may contain MiniJinja template expressions rather than literal values; they are resolved at install-time, not at retrieval time.",
+  "examples": [
+    {
+      "summary": "List all prepared auto-install answer configurations",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Only one configuration can have is-default set to true; its target-filter is ignored — it catches any installation not matched by a more specific configuration.",
+    "Configurations with authorized-tokens restrict which API tokens may retrieve that answer at install time; an empty list means any token can retrieve it.",
+    "disk-mode determines whether disk-list (fixed) or disk-filter (dynamic udev matching) is active — check both fields when reviewing a configuration.",
+    "MiniJinja template counters in template-counters auto-increment on each instantiation, enabling unique FQDNs or IPs across bulk deployments without editing the configuration."
+  ],
+  "relatedOperations": [
+    "get_auto_install",
+    "post_auto_install_prepared",
+    "put_auto_install_prepared_id",
+    "delete_auto_install_prepared_id",
+    "get_auto_install_prepared_id"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_auto_install_prepared_id",
+  "usageNotes": "Use this endpoint to retrieve the full answer configuration for a specific prepared auto-installer definition by its ID. The caller must hold the System.Audit privilege on the system/auto-installation ACL path. The `id` must be between 3 and 64 characters; the API returns null on success, so the useful payload is in the HTTP response body rather than a typed schema.",
+  "examples": [
+    {
+      "summary": "Fetch a prepared auto-install configuration by ID",
+      "path_params": {
+        "id": "ubuntu-22-04-base"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returns type is listed as null in the spec, meaning the API currently does not define a typed schema — inspect the raw response body for the actual answer-file content.",
+    "IDs are between 3 and 64 characters; slugs like 'debian-12-standard' work well for human-readable identifiers.",
+    "API tokens are supported (allowtoken: true), so a scoped token with System.Audit is preferred over a full user credential for read operations."
+  ],
+  "relatedOperations": [
+    "get_auto_install_prepared",
+    "post_auto_install_prepared",
+    "put_auto_install_prepared_id",
+    "delete_auto_install_prepared_id"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_auto_install_tokens",
+  "usageNotes": "Use this to audit all auto-install tokens configured in Proxmox Datacenter Manager, including their enabled state, expiration, and who created them. Requires the System.Audit privilege on the system/auto-installation ACL path. Check the 'enabled' and 'expire-at' fields to identify stale or expired tokens before issuing new ones.",
+  "examples": [
+    {
+      "summary": "List all auto-install tokens to review active and expired entries",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "An 'expire-at' value of 0 means the token never expires — flag these during security audits.",
+    "Disabled tokens (enabled: false) remain listed but cannot authenticate installer requests.",
+    "Token secrets are not returned by this endpoint; the secret is only available at creation time."
+  ],
+  "relatedOperations": [
+    "create_auto_install_token",
+    "delete_auto_install_token",
+    "get_auto_install_token"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_ceph",
+  "usageNotes": "Returns the top-level Ceph directory index for the PDM API, listing available Ceph sub-resources and endpoints. Use this as a discovery call to determine which Ceph operations are exposed before drilling into specific cluster, pool, or OSD endpoints. Accessible to all authenticated users with no additional privilege requirements.",
+  "examples": [
+    {
+      "summary": "List available Ceph API sub-resources on PDM",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The return type is null in the spec, meaning the response is an index array of sub-endpoint names rather than structured Ceph cluster data — parse the links array to discover callable children.",
+    "Use this before calling any specific Ceph operation to verify which sub-resources are available on the connected PDM instance."
+  ],
+  "relatedOperations": [
+    "get_ceph_cluster",
+    "get_ceph_pools",
+    "get_ceph_osds"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_ceph_clusters",
+  "usageNotes": "Use this to enumerate all Ceph clusters registered in Proxmox Datacenter Manager and get a quick health snapshot for each. Results are filtered to clusters where the caller has at least one auditable PVE member, so unprivileged tokens will see a subset. Capacity and OSD/monitor fields are cached and may be absent if PDM has not yet polled a cluster — clusters in 'unreachable', 'gone', or 'tombstoned' states will still appear but with minimal live data.",
+  "examples": [
+    {
+      "summary": "List all accessible Ceph clusters and check health at a glance",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'state' field is key: 'detected' means reachable this sweep cycle; 'unreachable' means all probes failed but the cluster may still be healthy from another vantage; 'tombstoned' clusters are silently excluded from auto-re-detection until an admin runs the tombstone-reset command.",
+    "Capacity fields (bytes-avail, bytes-used, bytes-total) reflect cached values from the last successful poll — they are not real-time and may lag by minutes to hours.",
+    "If 'health' is absent, PDM has no cached status yet; trigger a manual cluster status fetch or wait for the next auto-detection sweep.",
+    "Use the 'remote' and 'node' fields to construct deep-links into the native PVE web UI for that cluster's Ceph panel.",
+    "A non-zero 'problem-count' paired with 'HEALTH_OK' indicates a race between the health string cache and the problem-count cache — treat either non-OK health or problem-count > 0 as needing investigation."
+  ],
+  "relatedOperations": [
+    "get_ceph_cluster",
+    "get_ceph_cluster_status",
+    "get_remotes"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_ceph_clusters_cluster",
+  "usageNotes": "Returns the sub-resource directory index for a specific Ceph cluster registered in PDM. Use it to discover what child endpoints are available under a given cluster identifier before drilling into status, OSDs, pools, or health. The cluster name must match a cluster already registered with PDM; an unknown or mis-spelled name will return a 404.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for the cluster named 'prod-ceph'",
+      "path_params": {
+        "cluster": "prod-ceph"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response type is null in the schema, meaning PDM returns a directory index (list of child links) rather than structured data — parse the 'data' array for available sub-paths.",
+    "This endpoint requires no special privilege beyond authenticated access ('user: all'), so any valid API token can call it.",
+    "Use this as a discovery call when you are unsure which sub-operations (e.g., health, OSDs, pools) are exposed for a cluster in your PDM version."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_ceph_clusters_cluster_health",
+    "get_ceph_clusters_cluster_osd",
+    "get_ceph_clusters_cluster_pools"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_ceph_clusters_cluster_flags",
+  "usageNotes": "Use this to read the current state of all cluster-wide Ceph OSD flags (e.g. noout, pause, noscrub) before performing maintenance or troubleshooting recovery stalls. The cluster identifier is the Ceph FSID, not a human-friendly name. All authenticated users can call this endpoint — no elevated privilege is required.",
+  "examples": [
+    {
+      "summary": "List all OSD flags for a known Ceph cluster",
+      "path_params": {
+        "cluster": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'noout' flag is commonly set during host reboots or disk replacements to prevent Ceph from rebalancing prematurely — check it is cleared after maintenance.",
+    "A 'pause' flag halts all client I/O cluster-wide; seeing it set unexpectedly indicates a blocked maintenance operation.",
+    "Use the returned 'description' field for human-readable context on each flag before deciding whether to set or clear it.",
+    "The cluster FSID can be retrieved from list_ceph_clusters and is stable for the lifetime of the cluster."
+  ],
+  "relatedOperations": [
+    "list_ceph_clusters",
+    "get_ceph_clusters_cluster_status",
+    "put_ceph_clusters_cluster_flags"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_ceph_clusters_cluster_fs",
+  "usageNotes": "Use this to enumerate all CephFS file systems on a given Ceph cluster before mounting, configuring, or reporting on shared filesystem capacity. The cluster path parameter is the cluster's fsid (UUID-like string), not a human-readable name — retrieve it first from the cluster list endpoint. Each returned item includes both the primary data pool (for backward-compat) and the full data_pools array, which you should prefer when a filesystem uses multiple pools.",
+  "examples": [
+    {
+      "summary": "List all CephFS file systems on a known cluster",
+      "path_params": {
+        "cluster": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A CephFS with multiple device-class-specific data pools will show them all in data_pools but only the first in data_pool — always prefer data_pools for complete pool accounting.",
+    "An empty array response means no CephFS file systems exist on this cluster yet; it does not indicate an error.",
+    "The cluster identifier is the Ceph fsid (a UUID), not the PDM cluster display name — check get_ceph_clusters if unsure."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_ceph_clusters_cluster_pools",
+    "get_ceph_clusters_cluster_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_ceph_clusters_cluster_mds",
+  "usageNotes": "Use this endpoint to list all Ceph MDS (Metadata Server) daemons for a given cluster, including both active and standby daemons. The `cluster` path parameter is the Ceph cluster FSID, not a human-friendly name — retrieve it from the cluster list endpoint first. MDS daemons only appear in CephFS deployments; clusters without a CephFS filesystem will return an empty array.",
+  "examples": [
+    {
+      "summary": "List MDS daemons for a specific Ceph cluster",
+      "path_params": {
+        "cluster": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "An MDS with rank -1 and no fs_name is in standby mode and not serving any filesystem — this is normal in resilient deployments.",
+    "Check standby_replay: true to confirm hot-standby MDSes are tailing the active MDS journal for faster failover.",
+    "The direxists field reflects whether the MDS data directory is present on the hosting node; false may indicate a misconfigured or migrated daemon.",
+    "The service field indicates whether the systemd unit is enabled — an MDS can be known to the cluster (state = up:standby) yet have service: false if it was started manually.",
+    "State values 'stopped' or 'unknown' mean PDM is aware of the MDS configuration but the daemon is not currently visible to the Ceph cluster."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_ceph_clusters_cluster",
+    "get_ceph_clusters_cluster_fs",
+    "get_ceph_clusters_cluster_status"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_ceph_clusters_cluster_mgr",
+  "usageNotes": "Use this to enumerate all Ceph Manager (MGR) daemons for a given cluster — both the single active MGR and any standby daemons. The cluster path parameter is the cluster's FSID (UUID-like string), not its friendly name; retrieve it via the clusters list endpoint first. Daemons in 'stopped' or 'unknown' state indicate a MGR that PDM is aware of but cannot see in the cluster map, which may signal a daemon crash or misconfiguration.",
+  "examples": [
+    {
+      "summary": "List all MGR daemons for a specific Ceph cluster",
+      "path_params": {
+        "cluster": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A healthy cluster should have exactly one 'active' MGR and one or more 'standby' MGRs; zero active or zero standby is a resiliency concern.",
+    "The 'direxists' field is node-local — it only reflects whether the data directory exists on the PDM-managed node, not cluster-wide.",
+    "The 'service' field being false for an active or standby MGR may mean the systemd unit was manually started or is managed outside PDM."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_ceph_clusters_cluster_mon",
+    "get_ceph_clusters_cluster_osd",
+    "get_ceph_clusters_cluster_status"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_ceph_clusters_cluster_mon",
+  "usageNotes": "Use this to list all Ceph monitors for a given cluster and verify quorum health — the `quorum` field on each entry indicates whether the monitor is currently participating in consensus. The `cluster` path param is the Ceph FSID (UUID-like string), not a human-readable name; retrieve it from the cluster list endpoint first. Monitors showing `state: 'stopped'` or `quorum: false` indicate a degraded mon that needs investigation before performing cluster operations.",
+  "examples": [
+    {
+      "summary": "List all monitors for a known Ceph cluster to verify quorum status",
+      "path_params": {
+        "cluster": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A healthy Ceph cluster requires an odd number of monitors (typically 3 or 5) with all members in quorum — if `quorum: false` appears on any entry, the cluster may reject writes.",
+    "The `direxists` field reflects whether the mon data directory is present on the hosting node; a missing directory with `service: true` suggests a misconfigured or partially removed monitor.",
+    "The `addr` field may use Ceph messenger-v2 vector format (e.g. `[v2:IP:3300,v1:IP:6789]`) on newer Ceph versions — parse accordingly if you need to extract the IP.",
+    "Monitors with `state: 'unknown'` indicate PDM could not reach the Ceph cluster via rados at query time — check PDM connectivity to the cluster, not just the mon host itself."
+  ],
+  "relatedOperations": [
+    "get_ceph_clusters",
+    "get_ceph_clusters_cluster",
+    "get_ceph_clusters_cluster_status"
+  ]
+}