@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pve_remotes_remote_tasks_upid_status",
+  "usageNotes": "Poll this endpoint after any async PVE operation returns a UPID to determine whether the task is still running or has completed. The caller must hold Resource.Audit on the remote; the remote PVE node must be reachable from PDM at call time. Set wait=true to block until the task finishes instead of polling in a loop, but note that long-running tasks (migrations, backups) may cause the request to time out.",
+  "examples": [
+    {
+      "summary": "Check status of a VM migration task on the pve-prod remote",
+      "path_params": {
+        "remote": "pve-prod",
+        "upid": "UPID:pve1:001A2B3C:00ABCDEF:67890ABC:qmmove:101:root@pam:"
+      },
+      "params": {
+        "wait": false
+      }
+    }
+  ],
+  "tips": [
+    "exitstatus is only present in the response when status='stopped'; check for its presence before reading it.",
+    "exitstatus='OK' indicates success; any other value (e.g. 'ERROR: ...') indicates failure.",
+    "Use wait=true for short-lived tasks (snapshot, config change) to avoid a polling round-trip; avoid it for migrations or backups where the PDM request may time out.",
+    "The UPID minimum length of 42 chars includes the node name and timestamps — pass it verbatim from the originating operation response."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes_remote_tasks",
+    "get_pve_remotes_remote_tasks_upid_log"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pve_remotes_remote_updates",
+  "usageNotes": "Use this to check pending package updates on a PVE remote without triggering a live refresh — PDM returns its cached snapshot, so results reflect the last time the remote synced update metadata. The caller needs Resource.Audit on the remote resource; no query parameters are accepted. If the cache is stale, trigger a refresh via the corresponding update-fetch operation before calling this endpoint.",
+  "examples": [
+    {
+      "summary": "Get cached update list for a PVE remote named 'pve-hetzner'",
+      "path_params": {
+        "remote": "pve-hetzner"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response reflects cached data — it does not poll the remote live. Schedule or manually trigger a cache refresh if up-to-date package counts are needed.",
+    "The remote name must be 2–32 characters and match the pattern ^[A-Za-z0-9_][A-Za-z0-9._-]*$ — alphanumeric/underscore start, dots and hyphens allowed after.",
+    "API tokens are accepted (allowtoken: true); no special protected-resource flag means standard PDM token scopes apply."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes",
+    "get_pve_remotes_remote",
+    "get_pve_remotes_remote_status"
+  ]
+}

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

@@ -0,0 +1,19 @@
+{
+  "operationId": "get_remotes",
+  "usageNotes": "Use this to list all remote endpoints (PVE and PBS) configured in Proxmox Datacenter Manager. This is the top-level directory index for the /remotes tree, and is typically called first to discover available remote names before drilling into type-specific paths like /pve/remotes or /pbs/remotes. No parameters are required and any authenticated user can call it.",
+  "examples": [
+    {
+      "summary": "List all configured remotes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a directory index, not a typed remote list — use get_pve_remotes or get_pbs_remotes to get structured remote details with connection status.",
+    "Accessible to all authenticated users including API tokens; no special privilege is needed."
+  ],
+  "relatedOperations": [
+    "get_pve_remotes",
+    "get_pbs_remotes"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_remotes_metric_collection_status",
+  "usageNotes": "Use this to check whether PDM is successfully collecting metrics from each configured remote. Each entry reports the remote name, the Unix timestamp of the last successful collection, and any error from the most recent attempt — making it useful for diagnosing stale or missing metric data. No parameters are required; all configured remotes are returned in a single call.",
+  "examples": [
+    {
+      "summary": "Retrieve metric collection status for all remotes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A missing 'last-collection' field on an entry means no successful collection has ever completed for that remote — check connectivity and credentials.",
+    "An 'error' field present alongside a valid 'last-collection' timestamp means the last attempt failed but a prior one succeeded; metric data exists but may be stale.",
+    "Poll this endpoint after adding or modifying a remote to confirm collection begins within the expected interval."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "get_remotes_metric_collection_config"
+  ]
+}

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

@@ -0,0 +1,22 @@
+{
+  "operationId": "get_remotes_remote",
+  "usageNotes": "Use this to enumerate all remote PVE or PBS instances registered in Proxmox Datacenter Manager, including their node addresses, auth IDs, and type. No parameters are required and all authenticated users receive results filtered to the remotes they have access to. This is typically the first call when building remote-aware workflows such as migration, backup, or replication targeting.",
+  "examples": [
+    {
+      "summary": "List all configured remotes to discover available PVE clusters and PBS instances",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'token' field in each result is the API token secret — treat these values as credentials; mask them in logs.",
+    "Each remote's 'type' field will be either 'pve' (Proxmox VE cluster) or 'pbs' (Proxmox Backup Server) — filter by type before passing a remote ID to type-specific operations.",
+    "The 'nodes' array may contain multiple addresses for clustered remotes; PDM will attempt each in order for connectivity.",
+    "Use the returned 'id' value as the remote identifier in subsequent operations that require a remote parameter."
+  ],
+  "relatedOperations": [
+    "create_remotes_remote",
+    "get_remotes_remote_id",
+    "delete_remotes_remote_id"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_remotes_remote_id",
+  "usageNotes": "Use this endpoint to retrieve the directory index for a specific PDM remote by its ID, confirming the remote exists and is registered. No query parameters are accepted; authentication is required but the endpoint is accessible to all authenticated users including API tokens. Note that the API returns null as its declared return type, so this acts more as an existence check or sub-resource anchor than a data-returning call.",
+  "examples": [
+    {
+      "summary": "Fetch the directory index for a remote named 'pve-hetzner'",
+      "path_params": {
+        "id": "pve-hetzner"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returns type is 'null', so do not expect a structured body — use this call to verify a remote ID is valid before attempting sub-resource operations.",
+    "Remote IDs in PDM typically correspond to the name given when the remote was added; check 'list_remotes' if the exact ID is unknown.",
+    "API token authentication is supported (allowtoken: true), making this safe to call from automation without a full session."
+  ],
+  "relatedOperations": [
+    "list_remotes"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_remotes_remote_id_config",
+  "usageNotes": "Use this to retrieve the full connection configuration for a registered PDM remote, including its node addresses, authentication ID, token secret, and type (pve or pbs). Requires Resource.Audit privilege on the specific remote resource. Note that the response includes the token secret in plaintext, so treat the result with the same care as credentials.",
+  "examples": [
+    {
+      "summary": "Fetch config for a registered PVE remote named 'hetzner-pve'",
+      "path_params": {
+        "id": "hetzner-pve"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'authid' field uses the format 'user@realm!tokenid' — this is the API token identity, not a password.",
+    "The 'type' field distinguishes PVE clusters from PBS backup servers; default is 'pve' if not explicitly set.",
+    "The optional 'web-url' field controls how PDM generates clickable links to the remote's web UI — absence does not affect API connectivity.",
+    "Remote IDs must be 2–32 characters and match the pattern [A-Za-z0-9_][A-Za-z0-9._-]* — use this to validate IDs before calling.",
+    "This endpoint returns the stored token secret; avoid logging or caching the full response."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "get_remotes_remote_id_status",
+    "put_remotes_remote_id_config"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_remotes_remote_id_rrddata",
+  "usageNotes": "Use this endpoint to retrieve historical metric-collection performance data for a specific PDM remote, typically to assess polling health or response-time trends over time. Both `cf` and `timeframe` are required; choose `AVERAGE` for trend analysis and `MAX` to surface worst-case API response spikes. The only metric currently returned per data point is `metric-collection-response-time` (milliseconds), so this is most useful for diagnosing slow or degraded remote polling rather than guest-level metrics.",
+  "examples": [
+    {
+      "summary": "Fetch last hour of average metric-collection response times for remote 'pve-prod-01'",
+      "path_params": {
+        "id": "pve-prod-01"
+      },
+      "params": {
+        "cf": "AVERAGE",
+        "timeframe": "hour"
+      }
+    }
+  ],
+  "tips": [
+    "If metric-collection-response-time values are consistently high (e.g., >2000ms), check network latency between PDM and the remote PVE node or consider increasing the polling interval.",
+    "Use timeframe=decade sparingly — RRD data is heavily consolidated at that resolution and may mask short-duration anomalies.",
+    "The remote `id` must match the identifier assigned in PDM (2–32 chars, alphanumeric/dot/dash/underscore); verify with the list-remotes endpoint if unsure."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "get_remotes_remote_id",
+    "get_remotes_remote_id_rrd"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_remotes_remote_id_version",
+  "usageNotes": "Use this to verify the Proxmox VE version running on a specific PDM-registered remote before performing operations that may require a minimum PVE version. Requires `Resource.Audit` privilege on the remote resource. The remote must be reachable from PDM at call time; a timeout or unreachable host will surface as an error rather than a stale cached value.",
+  "examples": [
+    {
+      "summary": "Get version info for remote 'pve-hetzner'",
+      "path_params": {
+        "id": "pve-hetzner"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `version` field is the full pve-manager package version string (e.g. '8.2.4'); `release` is the shorter `x.y` form (e.g. '8.2') useful for major/minor compatibility checks.",
+    "The `repoid` field is a short git hash useful when cross-referencing changelogs or bug reports against a specific build.",
+    "Remote IDs follow the pattern `[A-Za-z0-9_][A-Za-z0-9._-]*` with length 2–32; use list-remotes first if the ID is unknown."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "get_remotes_remote_id",
+    "get_version"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_remotes_tasks",
+  "usageNotes": "Returns a directory index of available task-related sub-endpoints under /remotes/tasks; useful for discovering what task operations are exposed for remotes without requiring any elevated privilege. No parameters are accepted, so the response is the same for all authenticated callers. Use this as an exploration step before calling specific remote-task endpoints.",
+  "examples": [
+    {
+      "summary": "List available task sub-endpoints for remotes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a pure directory/discovery endpoint — it does not return actual task records or UPIDs.",
+    "Accessible to all authenticated users (privilege: all), including API tokens."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "get_nodes_tasks",
+    "get_nodes_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_remotes_tasks_list",
+  "usageNotes": "Use this to audit or monitor background task activity across all PDM-managed remotes (Proxmox Backup Server nodes). Filter by remote ID to scope results to a single remote, or combine `running: true` with a `typefilter` (e.g. 'sync') to watch live sync jobs. Results default to 50 tasks ordered by start time descending; set `limit: 0` to retrieve all tasks, but prefer `since`/`until` bounds on busy remotes to avoid large payloads.",
+  "examples": [
+    {
+      "summary": "List the last 20 failed tasks on a specific remote since the start of the month",
+      "path_params": {},
+      "params": {
+        "remote": "pbs-hetzner",
+        "errors": true,
+        "limit": 20,
+        "since": 1748736000
+      }
+    }
+  ],
+  "tips": [
+    "Use `running: true` to poll for active sync or verify jobs before triggering a new one — PDM may queue or reject duplicate runs.",
+    "The `upid` field in each result is the Unique Process ID; pass it to the PDM task log endpoint to retrieve full task output.",
+    "`statusfilter` is an array of status strings (e.g. ['error', 'warning']); an empty array behaves as no filter.",
+    "`typefilter` is a substring match against worker_type, so 'sync' will match 'sync', 'pull-sync', etc.",
+    "Pagination is controlled by `start` + `limit`; iterate by incrementing `start` by `limit` until fewer results than `limit` are returned."
+  ],
+  "relatedOperations": [
+    "get_remotes_list",
+    "get_remotes_read"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_remotes_tasks_statistics",
+  "usageNotes": "Use this endpoint to get a high-level summary of task outcomes grouped by remote and by worker type — useful for health dashboards and spotting which remotes or task types have elevated error rates. All query parameters are optional; omit them to get aggregate statistics across all remotes and all time. The caller only sees statistics for remotes on which they hold Resource.Audit privilege; filter results may appear empty rather than returning an error if privilege is absent for a given remote.",
+  "examples": [
+    {
+      "summary": "Fetch error statistics for a specific remote over the last 7 days",
+      "path_params": {},
+      "params": {
+        "remote": "hetzner-de",
+        "errors": true,
+        "since": 1750982400,
+        "limit": 100
+      }
+    }
+  ],
+  "tips": [
+    "The 'since' and 'until' params accept UNIX epoch integers — convert human-readable dates before passing them.",
+    "Set 'errors: true' together with a 'remote' filter to quickly triage a specific remote after a known incident window.",
+    "The 'by-remote' and 'by-type' maps in the response use dynamic keys; iterate them rather than assuming fixed property names.",
+    "A limit of 0 disables the cap — use with caution on busy PDM instances with long task histories.",
+    "The 'running' and 'errors' flags are mutually exclusive in intent; combining them will typically return zero results since running tasks have no final error status yet."
+  ],
+  "relatedOperations": [
+    "get_remotes_tasks",
+    "get_remotes_tasks_upid_status",
+    "get_remotes_tasks_upid_log"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_remotes_updates",
+  "usageNotes": "Use this endpoint to discover which update-related sub-resources or actions are available under the /remotes/updates namespace. It is a directory index that requires no parameters and is accessible by all authenticated users. Because it returns null, it is most useful for capability probing rather than retrieving actual update data.",
+  "examples": [
+    {
+      "summary": "List available update sub-resources under remotes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns null — treat this as a capability or namespace probe, not a data fetch.",
+    "No privilege escalation needed; any valid API token or session can call this.",
+    "Pair with specific update-action endpoints discovered via this index to perform actual remote update operations."
+  ],
+  "relatedOperations": [
+    "get_remotes",
+    "get_remotes_remote"
+  ]
+}

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

@@ -0,0 +1,17 @@
+{
+  "operationId": "get_remotes_updates_summary",
+  "usageNotes": "Use this to get a at-a-glance count of pending updates across all PDM-managed remote nodes without querying each node individually. The caller must hold Resource.Modify on /resource/{remote} for each remote they want included in the result; remotes the token lacks access to will be omitted. Returns synchronously — no UPID.",
+  "examples": [
+    {
+      "summary": "Fetch pending update counts for all managed remotes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'remotes' object is keyed by remote name; missing remotes typically indicate a permission gap or an unreachable node.",
+    "Use this as a lightweight poll before deciding whether to invoke a per-remote package update operation.",
+    "API tokens are supported (allowtoken: true), making this safe to call from automation without interactive credentials."
+  ],
+  "relatedOperations": []
+}

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

@@ -0,0 +1,16 @@
+{
+  "operationId": "get_resources",
+  "usageNotes": "Returns the top-level resource directory index for the Proxmox Datacenter Manager API. Use this as a discovery call to enumerate available API resource categories — useful for probing what the connected PDM instance exposes before making targeted requests. No parameters are required and all authenticated users have access.",
+  "examples": [
+    {
+      "summary": "List all top-level PDM API resources",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a pure discovery endpoint — the response is the API directory index, not operational data about managed nodes or VMs.",
+    "Because permissions are 'user: all', any valid API token can call this regardless of role."
+  ],
+  "relatedOperations": []
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_resources_list",
+  "usageNotes": "Use this as the primary inventory sweep across all PDM-managed remotes — it returns nodes, VMs, containers, storage, datastores, and networks in one call grouped by remote. Results are served from a cache; lower `max-age` (e.g. 0) forces a live fetch at the cost of higher latency, while the 30-second default is appropriate for dashboards. If a remote is unreachable, its entry will contain an `error` field alongside an empty or partial `resources` array rather than failing the entire response.",
+  "examples": [
+    {
+      "summary": "Fetch only running QEMU VMs across all remotes with a fresh cache",
+      "path_params": {},
+      "params": {
+        "resource-type": "qemu",
+        "max-age": 0
+      }
+    }
+  ],
+  "tips": [
+    "Each top-level array item maps to one remote; always check the `error` field on each item before processing its `resources` — a reachable remote returns null/omitted error, an unreachable one may still appear with an error string.",
+    "The `type` discriminator property on each resource entry (e.g. pve-qemu, pbs-datastore) is the reliable way to branch parsing logic — do not rely on which fields are present.",
+    "Omitting `resource-type` returns all resource kinds in one pass, which is more efficient than making separate filtered requests when you need a full inventory.",
+    "The `view` parameter (2-32 chars, alphanumeric/dot/dash/underscore) selects a saved PDM view; omit it to get the unfiltered resource list.",
+    "The `search` parameter syntax is not yet documented (spec contains a TODO); treat it as experimental and prefer `resource-type` for reliable filtering."
+  ],
+  "relatedOperations": [
+    "get_remotes_list"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_resources_location_info",
+  "usageNotes": "Use this endpoint to retrieve geographic or datacenter location metadata for resources across all remotes, or scoped to a named view. No special privileges are required — any authenticated user can call it. If a remote is temporarily unreachable, PDM will fall back to cached data up to `max-age` seconds old (default 86400 = 24 hours), so results may be stale for offline remotes.",
+  "examples": [
+    {
+      "summary": "Get location info scoped to a specific view, with a 1-hour cache tolerance",
+      "path_params": {},
+      "params": {
+        "view": "eu-cluster",
+        "max-age": 3600
+      }
+    }
+  ],
+  "tips": [
+    "Omitting `view` returns location info across all remotes known to PDM — useful for a global inventory sweep.",
+    "Set `max-age=0` to force a live fetch from all remotes instead of accepting any cached data; expect higher latency.",
+    "Cached data is always returned when a remote is unreachable, regardless of `max-age` — the param only controls staleness tolerance for reachable remotes."
+  ],
+  "relatedOperations": [
+    "get_resources",
+    "get_remotes",
+    "get_resources_remote"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_resources_status",
+  "usageNotes": "Use this endpoint to get a cross-remote inventory snapshot of all resource types (VMs, containers, nodes, storages, PBS datastores, SDN networks) registered in PDM. Results are served from a per-remote cache with a default max-age of 30 seconds, so resource states may lag real-time by up to that window; lower max-age for fresher data at the cost of more remote round-trips. The optional 'view' parameter filters results to a named PDM view, which must already exist under /config/views.",
+  "examples": [
+    {
+      "summary": "Fetch all resources with a tighter 10-second cache window",
+      "path_params": {},
+      "params": {
+        "max-age": 10
+      }
+    }
+  ],
+  "tips": [
+    "Each object in the 'resources' array carries a 'type' discriminator field (pve-qemu, pve-lxc, pve-node, pve-storage, pve-network, pbs-node, pbs-datastore) — filter on this to process only the resource class you need.",
+    "If a remote is unreachable, PDM returns the last cached data and populates the top-level 'error' field with a description; always check for 'error' before trusting stale resource states.",
+    "Setting max-age=0 forces a live fetch from every remote on every call — use sparingly in polling loops to avoid hammering remote APIs.",
+    "The 'view' parameter must match the pattern /^(?:[A-Za-z0-9_][A-Za-z0-9._\\-]*)$/ — use get_config_views to enumerate valid view names before passing one here."
+  ],
+  "relatedOperations": [
+    "get_resources",
+    "get_config_views",
+    "get_config_views_id",
+    "get_pve_remotes_remote_resources",
+    "get_remotes_metric_collection_status"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_resources_subscription",
+  "usageNotes": "Use this endpoint to audit subscription compliance across all remotes registered in Proxmox Datacenter Manager — for example, before a maintenance window or when onboarding a new remote cluster. The `state` field in each result summarizes the remote as `active`, `mixed` (some nodes unsubscribed), `none`, or `unknown`; drill into per-node detail with `verbose=true` if you need to identify which specific nodes are out of compliance. Cached results are returned by default (up to 24 hours old); pass `max-age=0` to force a live fetch from all remotes.",
+  "examples": [
+    {
+      "summary": "Fetch live subscription status for all remotes with per-node detail",
+      "path_params": {},
+      "params": {
+        "max-age": 0,
+        "verbose": true
+      }
+    }
+  ],
+  "tips": [
+    "The default max-age of 86400 seconds means you may see stale subscription state; use max-age=0 when accuracy matters (e.g. compliance checks or after adding a subscription key).",
+    "The `node-status` map is only populated when verbose=true and the caller has sufficient privileges on the remote; without it, only the aggregate `state` enum is returned.",
+    "A `state` of `unknown` typically means PDM could not reach the remote to check — verify remote connectivity before treating it as a subscription problem.",
+    "This endpoint requires no special privilege beyond `user: all`, so API tokens with minimal scope can poll it safely."
+  ],
+  "relatedOperations": [
+    "get_resources_remotes",
+    "get_resources_resources"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_resources_top_entities",
+  "usageNotes": "Use this endpoint to get a cross-remote leaderboard of the highest-consuming VMs/containers (guest-cpu), hypervisor nodes (node-cpu), and hypervisor nodes by RAM (node-memory) — useful for capacity planning and identifying runaway workloads across all remotes in one call. Each result entry includes both the current resource snapshot and an RRD time-series for the chosen timeframe, so omitting 'timeframe' returns only point-in-time data without historical trend. Only remotes and resources for which the authenticated user holds Resource.Audit on /resource/{remote_name} are included; remotes without that privilege are silently excluded from the rankings.",
+  "examples": [
+    {
+      "summary": "Get top CPU/memory consumers over the past day across all remotes",
+      "path_params": {},
+      "params": {
+        "timeframe": "day"
+      }
+    }
+  ],
+  "tips": [
+    "RRD data points may contain null values for intervals where no sample was collected; handle sparse arrays in the client.",
+    "The 'view' parameter scopes results to a named PDM view — omit it to query across all remotes the token can see.",
+    "CPU values (cpu field) are fractional utilization ratios (0.0–1.0 per vCPU allocated), not percentages.",
+    "Results are returned pre-sorted descending by utilization; no client-side sorting is needed."
+  ],
+  "relatedOperations": [
+    "get_resources",
+    "get_resources_location_info",
+    "get_pve_remotes_remote_nodes_node_rrddata",
+    "get_pve_remotes_remote_qemu_vmid_rrddata",
+    "get_pbs_remotes_remote_rrddata"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_sdn",
+  "usageNotes": "Use this as a discovery call to confirm that the PDM SDN API surface is reachable and to enumerate available SDN sub-resources before drilling into zones, vnets, or subnets. No parameters are required and it is accessible to all authenticated users, so it is safe to call as a health-check or capability probe. The endpoint returns a directory index (null body per the spec), so meaningful SDN data must be retrieved from child endpoints such as those under /sdn/zones or /sdn/vnets.",
+  "examples": [
+    {
+      "summary": "Probe the SDN directory index to confirm API availability",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns a directory index with null body — do not expect SDN configuration data from this call; follow up with child-resource endpoints.",
+    "Accessible to all authenticated users (permissions: user=all), making it safe to use for capability detection without elevated privileges.",
+    "If this endpoint returns an error, SDN may be disabled or not licensed on the PDM instance."
+  ],
+  "relatedOperations": [
+    "get_sdn_zones",
+    "get_sdn_vnets",
+    "get_sdn_controllers"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_sdn_controllers",
+  "usageNotes": "Use this to enumerate SDN controllers (BGP, EVPN, IS-IS, Faucet) across all remotes managed by PDM, or narrow results to specific remotes and/or a controller type via query params. By default the response reflects the pending (not yet applied) configuration; pass `running: true` to see what is actually active on nodes. Results are scoped to remotes for which the caller holds `Resource.Audit` on `/resource/{remote_name}`, so a filtered response does not necessarily mean no controllers exist.",
+  "examples": [
+    {
+      "summary": "List all BGP controllers across all remotes, showing running config and any pending changes",
+      "path_params": {},
+      "params": {
+        "ty": "bgp",
+        "running": true,
+        "pending": true
+      }
+    }
+  ],
+  "tips": [
+    "Omitting `ty` returns all controller types in one call — useful for a full SDN inventory.",
+    "The `pending` field on each returned object (when `pending: true` is passed) shows only the attributes that differ from the running config, not the full object.",
+    "A controller with `state: 'deleted'` has been marked for removal but `pvesh apply` (or equivalent) has not run yet — it is still active.",
+    "The `remote` field on each item identifies which PDM remote the controller belongs to, which maps to `Resource.Audit` privilege scope."
+  ],
+  "relatedOperations": [
+    "get_sdn_vnets",
+    "get_sdn_zones",
+    "get_remotes"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_sdn_vnets",
+  "usageNotes": "Use this to inventory all SDN VNets across one or more PVE remotes managed by PDM. By default the response reflects the running configuration; pass `running: false` (or omit it) to see the pending/saved configuration, or `pending: true` to surface attributes that have been changed but not yet applied. Results are silently scoped to remotes where the caller holds `Resource.Audit` on `/resource/{remote_name}`, so a partial list is normal when the token lacks broad permissions.",
+  "examples": [
+    {
+      "summary": "List all VNets across two specific remotes, showing any unapplied pending changes",
+      "path_params": {},
+      "params": {
+        "remotes": ["pve-hetzner", "pve-ovh"],
+        "pending": true,
+        "running": false
+      }
+    }
+  ],
+  "tips": [
+    "A VNet whose `state` field is `new` or `changed` has been saved to the SDN configuration but not yet applied — run `apply_sdn_config` on the relevant remote to push it to the dataplane.",
+    "The `tag` field carries a VLAN tag (1–4094 range typical) for VLAN/QinQ zones but a VXLAN VNI (up to 16777215) for VXLAN/EVPN zones — interpret it relative to the parent zone type.",
+    "When `isolate-ports` is true, VMs on the same VNet cannot talk to each other at L2; useful for tenant isolation without separate zones.",
+    "The `remotes` filter accepts an array of remote IDs; omit it to query all remotes the caller can see."
+  ],
+  "relatedOperations": [
+    "get_sdn_zones",
+    "get_sdn_controllers",
+    "get_sdn_subnets"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_sdn_zones",
+  "usageNotes": "Use this to enumerate SDN zones across one or more PDM-managed remotes, optionally filtered by zone type or scoped to specific remotes. By default the response reflects the running configuration; pass `pending: true` to surface unapplied changes, or `running: false` to see the pending-only view. Only zones from remotes where the caller holds `Resource.Audit` on `/resource/{remote_name}` are returned, so a partial result set is normal in multi-tenant environments.",
+  "examples": [
+    {
+      "summary": "List all EVPN zones with pending-change details across a specific remote",
+      "path_params": {},
+      "params": {
+        "ty": "evpn",
+        "remotes": ["hetzner-de"],
+        "pending": true,
+        "running": true
+      }
+    }
+  ],
+  "tips": [
+    "The `state` field on each returned zone (`new`, `deleted`, `changed`) indicates SDN objects that have been modified but not yet applied — useful for detecting drift before running an SDN apply operation.",
+    "Use `ty` to narrow large environments; scanning all zones across many remotes without a type filter can return a verbose payload with many zone-type-specific fields that will be null for non-matching types.",
+    "Each result includes a `remote` field identifying which PDM remote the zone belongs to, making cross-remote aggregation straightforward without additional lookups.",
+    "EVPN zones carry BGP-specific fields (`controller`, `vrf-vxlan`, `exitnodes`, `rt-import`) that are absent on simpler zone types — check the `type` field before accessing these properties."
+  ],
+  "relatedOperations": [
+    "get_sdn_controllers",
+    "get_sdn_vnets",
+    "get_sdn_subnets",
+    "get_remotes"
+  ]
+}

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

@@ -0,0 +1,17 @@
+{
+  "operationId": "get_subscriptions",
+  "usageNotes": "Returns a directory index of subscription entries registered in Proxmox Datacenter Manager. Use this as a discovery call to determine which subscription resources are available before fetching or managing individual subscription details. No authentication role restrictions apply — any authenticated user or API token may call it.",
+  "examples": [
+    {
+      "summary": "List all PDM subscription directory entries",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returns type is 'null' in the spec, meaning the API may return an empty body or a bare list — inspect the raw response rather than expecting a typed schema.",
+    "This is a directory index, not a full subscription detail endpoint; a follow-up call may be needed to retrieve subscription key or status fields.",
+    "Accessible to all authenticated users, so no elevated privilege is required to probe subscription availability."
+  ],
+  "relatedOperations": []
+}