@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "get_nodes_node_syslog",
+  "usageNotes": "Use this endpoint to retrieve systemd journal (syslog) entries from a PDM node for troubleshooting or auditing. Requires the System.Audit privilege on the calling token. Responses are paginated via `start` and `limit`; use them together to page through large logs, and filter by `since`/`until` to narrow a time window or by `service` to isolate a specific systemd unit.",
+  "examples": [
+    {
+      "summary": "Fetch the last 100 syslog lines from a PDM node for a specific service within a time window",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {
+        "service": "pve-cluster",
+        "since": "2026-06-29 00:00:00",
+        "until": "2026-06-29 23:59:59",
+        "start": 0,
+        "limit": 100
+      }
+    }
+  ],
+  "tips": [
+    "Each returned object contains `n` (line number) and `t` (line text); use `n` as the next `start` value to continue paging.",
+    "The `service` parameter accepts a systemd unit name (e.g., 'pve-cluster', 'sshd', 'networking'); omit it to retrieve the full journal.",
+    "Omitting both `since` and `until` returns the most recent entries; combine with `limit` to cap output size.",
+    "The `node` path parameter also accepts 'localhost' to target the node receiving the request."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_journal",
+    "get_nodes_node_tasks",
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_tasks",
+  "usageNotes": "Use this endpoint to audit or monitor task history on a specific PDM node — useful after triggering async operations to confirm completion or identify failures. Unprivileged users only see their own tasks; to see all users' tasks the caller must hold Sys.Audit on /system/tasks. The default page size is 50; use 'limit' and 'start' together for pagination, or set limit=0 to retrieve all matching tasks at once.",
+  "examples": [
+    {
+      "summary": "List only failed tasks from the last 24 hours on node 'pdm01'",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {
+        "errors": true,
+        "since": 1719532800,
+        "limit": 100
+      }
+    }
+  ],
+  "tips": [
+    "Use 'running': true to poll for in-progress tasks immediately after triggering an async operation.",
+    "'typefilter' does a substring match on worker_type (e.g. 'backup', 'vzdump', 'syncjob') — no exact-match required.",
+    "Each returned item includes a UPID string that can be passed to the task log/status endpoints to retrieve full output.",
+    "Combine 'since' and 'until' UNIX epoch values to scope results to a specific maintenance window.",
+    "Pass 'userfilter' as 'user@realm' (e.g. 'root@pam') to narrow results to a single authenticator identity."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log",
+    "delete_nodes_node_tasks_upid"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_tasks_upid",
+  "usageNotes": "Returns the directory index for a specific task identified by its UPID on a PDM node — use this to discover what sub-resources are available under a task (e.g. log, status). The UPID must belong to the specified node; querying a UPID on the wrong node will return no results or an error. No special privilege is required beyond basic authentication (permissions: all users).",
+  "examples": [
+    {
+      "summary": "Get the directory index for a task UPID on pdm-node1",
+      "path_params": {
+        "node": "pdm-node1",
+        "upid": "UPID:pdm-node1:00001A2B:0012AB34:67890ABC:vzdump::root@pam:"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The UPID format encodes node, PID, start time, task type, and user — copy it verbatim from a task-list response; do not construct it by hand.",
+    "This is a directory index, not a status or log endpoint — follow up with get_nodes_node_tasks_upid_status or get_nodes_node_tasks_upid_log to get actionable task data.",
+    "UPIDs are node-scoped; always use the same node name that appears inside the UPID string."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks_upid_log"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_tasks_upid_log",
+  "usageNotes": "Use this to retrieve paginated log output for any task identified by its UPID — most useful for polling a running task or inspecting a completed one. Obtain the UPID from the operation that launched the task (e.g. a backup, migration, or sync job). Use `start` + `limit` for pagination through large logs, or set `limit=0` to return all lines; pass `download=true` exclusively (without any other params) to stream the raw log file.",
+  "examples": [
+    {
+      "summary": "Fetch the first 100 lines of a task log on the local PDM node",
+      "path_params": {
+        "node": "localhost",
+        "upid": "UPID:localhost:00003A2F:000B1C4E:00000001:67A1B2C3:vzdump:101:root@pam:"
+      },
+      "params": {
+        "start": 0,
+        "limit": 100,
+        "test-status": true
+      }
+    }
+  ],
+  "tips": [
+    "Set `test-status: true` to check whether the task is still running alongside the log fetch — avoids a separate status call.",
+    "When paginating, use the `total` field in the response to know when you have fetched all lines.",
+    "`download=true` cannot be combined with `start`, `limit`, or `test-status` — it triggers a raw file download instead of JSON.",
+    "The UPID encodes the originating node; always route the request to that same node, not a different cluster member."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks_upid_status",
+    "get_nodes_node_tasks",
+    "delete_nodes_node_tasks_upid"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_tasks_upid_status",
+  "usageNotes": "Use this endpoint to poll the completion and outcome of any async PDM task after obtaining its UPID. Check the `status` field to distinguish a running task from a stopped one; only stopped tasks populate `exitstatus`, which will be 'OK' on success or 'Error: <msg>' on failure. The UPID must belong to the same node specified in the path — cross-node lookups will fail.",
+  "examples": [
+    {
+      "summary": "Check whether a remote sync task has finished and whether it succeeded",
+      "path_params": {
+        "node": "pdm-node1",
+        "upid": "UPID:pdm-node1:001A2B3C:0AB12CD3:0000000100000001:68123456:remsync:remote1:root@pam:"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Poll on a short interval (e.g. 2–5 seconds) until `status` transitions from 'running' to 'stopped', then read `exitstatus` for the final result.",
+    "Users can query their own tasks without extra privileges; checking another user's task requires Sys.Audit on /system/tasks.",
+    "The UPID encodes the node name — if the node segment in the UPID doesn't match the `node` path parameter, the request will return an error.",
+    "A stopped task with no `exitstatus` field indicates the task log was already pruned or the process was killed before it could write an exit code."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_tasks",
+    "get_nodes_node_tasks_upid_log",
+    "delete_nodes_node_tasks_upid"
+  ]
+}

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

@@ -0,0 +1,21 @@
+{
+  "operationId": "get_nodes_node_time",
+  "usageNotes": "Use this to verify a PDM node's current UTC time, local time, and configured timezone — useful for confirming NTP sync or diagnosing timestamp drift before correlating logs across nodes. No query parameters are required; the node must be reachable. Available to all authenticated users (no admin privilege needed).",
+  "examples": [
+    {
+      "summary": "Read time settings from a PDM node",
+      "path_params": {
+        "node": "pdm-node1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'time' field is UTC epoch seconds; 'localtime' is the same instant expressed in the node's configured timezone offset — subtract the two to derive the UTC offset in seconds.",
+    "Use 'localhost' as the node name when calling from the node itself or when only one node is present.",
+    "If 'time' and 'localtime' differ unexpectedly, check the timezone setting against /usr/share/zoneinfo/zone.tab on the node."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_vncwebsocket",
+  "usageNotes": "This endpoint upgrades an HTTP connection to a WebSocket tunnel for a node-level VNC console session. It must be called after obtaining a VNC ticket and port from the node's VNC proxy endpoint (e.g., POST /nodes/{node}/vncproxy); the ticket is short-lived and single-use. The caller must perform the WebSocket upgrade handshake — this is not a standard JSON REST call and returns null on success.",
+  "examples": [
+    {
+      "summary": "Open VNC WebSocket for node console using ticket from vncproxy",
+      "path_params": {
+        "node": "pdm01"
+      },
+      "params": {
+        "port": 5900,
+        "vncticket": "PVEVNC:65a3b2c1::abcdef1234567890abcdef1234567890"
+      }
+    }
+  ],
+  "tips": [
+    "Always call the node's vncproxy endpoint first to obtain both the port and vncticket before calling this endpoint.",
+    "The vncticket is single-use and expires quickly; initiate the WebSocket upgrade immediately after receiving it.",
+    "This endpoint must be used with a WebSocket client — a plain HTTP GET will not establish a usable session.",
+    "Requires Sys.Console on /system; API tokens are permitted (allowtoken: true)."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_vncproxy"
+  ]
+}

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

@@ -0,0 +1,16 @@
+{
+  "operationId": "get_pbs",
+  "usageNotes": "Use this endpoint to discover the top-level PBS (Proxmox Backup Server) remotes resource index on a PDM instance. It is a directory listing only and requires no parameters; any authenticated user or API token can call it. The actual list of configured PBS remotes is retrieved via child endpoints under /pbs.",
+  "examples": [
+    {
+      "summary": "Retrieve the PBS remotes directory index",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This endpoint returns null per the spec — it functions as a navigational index entry point, not a data payload; follow up with /pbs child endpoints to get actionable PBS remote data.",
+    "No privilege elevation is needed; a read-only API token scoped to any realm is sufficient."
+  ],
+  "relatedOperations": []
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pbs_realms",
+  "usageNotes": "Use this before authenticating a user against a PBS remote — it discovers which authentication realms (pam, pbs, openid, ldap, ad) are available on that host so you can present a valid realm choice. The `hostname` param must match the remote exactly as PBS expects it (including port if non-default, e.g. `pbs.example.com:8007`). Requires `System.Modify` on `/` in PDM, so API tokens scoped to narrower paths will be rejected.",
+  "examples": [
+    {
+      "summary": "List auth realms on a PBS remote at pbs.nightsquawk.tech",
+      "path_params": {},
+      "params": {
+        "hostname": "pbs.nightsquawk.tech:8007",
+        "fingerprint": "A1:B2:C3:D4:E5:F6:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:01:02:03:04:05:06:07:08:09:0A"
+      }
+    }
+  ],
+  "tips": [
+    "If `fingerprint` is omitted and TLS verification fails, the call may be rejected — always supply the fingerprint when connecting to a self-signed PBS instance.",
+    "The `default` field on each returned realm indicates which realm PBS will use if none is specified at login; useful for pre-selecting the realm in a UI.",
+    "Realm type `pbs` is PBS's built-in user database; `pam` maps to the host OS users — both are always present on a standard PBS install."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes",
+    "get_pbs_users",
+    "get_pbs_datastores"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_pbs_remotes",
+  "usageNotes": "Use this to enumerate all PBS remote instances registered in Proxmox Datacenter Manager before performing remote-specific operations such as syncing or inspecting datastores. No parameters are required — the endpoint returns every configured remote. If the list is empty, no PBS remotes have been added to PDM yet and remote-scoped operations will fail.",
+  "examples": [
+    {
+      "summary": "List all configured PBS remotes",
+      "path_params": {},
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each item in the response contains only the 'remote' ID field; use the ID to target subsequent remote-specific endpoints.",
+    "Remote IDs follow the pattern /^(?:[A-Za-z0-9_][A-Za-z0-9._\\-]*)$/ and are 2–32 characters — useful for validating user-supplied remote names before calling downstream operations.",
+    "Tokens are accepted (allowtoken: true), so API token auth is sufficient and no interactive session is needed."
+  ],
+  "relatedOperations": [
+    "get_pbs_remote_datastores",
+    "get_pbs_datastore_snapshots"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pbs_remotes_remote",
+  "usageNotes": "Returns the directory index for a specific PBS remote configured in Proxmox Datacenter Manager — effectively a lightweight existence/reachability probe for the named remote. Use this to confirm a remote is registered before attempting datastore or snapshot operations against it. No additional privileges beyond authenticated user access are required, and it accepts API tokens.",
+  "examples": [
+    {
+      "summary": "Fetch the directory index for the PBS remote named 'hetzner-pbs'",
+      "path_params": {
+        "remote": "hetzner-pbs"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response type is null — this endpoint exposes sub-routes (directory index) rather than returning structured remote config data; use it to verify the remote path exists rather than to retrieve connection settings.",
+    "To inspect the actual remote configuration (host, port, auth), query the PBS remotes list endpoint instead.",
+    "API tokens are supported (allowtoken: true), so automation scripts can poll this without session credentials."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes",
+    "get_pbs_remotes_remote_datastores",
+    "get_pbs_remotes_remote_config"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pbs_remotes_remote_datastore",
+  "usageNotes": "Use this to enumerate all datastores configured on a specific PBS remote registered in PDM, including their retention schedules, maintenance state, and GC/prune settings. The caller must hold Resource.Audit on the remote path — a read-only API token with that privilege is sufficient. Datastores in maintenance-mode (especially 'offline') will appear in the list but may be inaccessible for backup or restore operations.",
+  "examples": [
+    {
+      "summary": "List datastores on the 'hetzner-pbs' remote",
+      "path_params": {
+        "remote": "hetzner-pbs"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Check the 'maintenance-mode' field in each returned datastore before triggering sync or verify jobs — an 'offline' or 'read-only' mode will cause those jobs to fail.",
+    "Retention policy fields (keep-daily, keep-weekly, etc.) are per-datastore config snapshots from the remote; they reflect the remote PBS node's settings, not a PDM-level override.",
+    "The 'path' field is the absolute filesystem path on the remote PBS server, useful for cross-referencing with disk usage or SMART data from that host.",
+    "Remote names must match the pattern /^(?:[A-Za-z0-9_][A-Za-z0-9._\\-]*)$/ with length 2–32; mismatches will return a 400 before reaching the remote."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes",
+    "get_pbs_remotes_remote",
+    "get_pbs_remotes_remote_datastore_snapshots"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pbs_remotes_remote_datastore_datastore",
+  "usageNotes": "Returns the API directory index for a specific datastore on a PBS remote — this is a navigation/discovery endpoint that lists available sub-routes, not backup snapshot data. Use it to confirm that a remote+datastore combination is reachable and to discover child API paths before querying snapshots, namespaces, or usage stats. The PBS remote must already be configured in PDM and the datastore name must exist on that remote.",
+  "examples": [
+    {
+      "summary": "List available API sub-paths for a datastore named 'main' on PBS remote 'pbs-hetzner'",
+      "path_params": {
+        "remote": "pbs-hetzner",
+        "datastore": "main"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Returns null/empty data on success — the meaningful payload is the directory index of child routes, not backup content.",
+    "If the remote is offline or credentials are stale, this call will fail; use it as a lightweight connectivity probe before heavier datastore operations.",
+    "The 'remote' value must match the name configured in PDM under PBS Remotes, not the PBS hostname directly."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_datastore",
+    "get_pbs_remotes_remote_datastore_datastore_snapshots",
+    "get_pbs_remotes_remote_datastore_datastore_namespace"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_pbs_remotes_remote_datastore_datastore_namespaces",
+  "usageNotes": "Use this to discover what backup namespaces exist within a specific PBS remote datastore, typically before scoping a snapshot browse or restore to a sub-namespace. The calling PDM user or token requires the Resource.Audit privilege on the remote/datastore path. Without the 'parent' filter the call returns all namespaces up to PBS's 8-level depth limit; use 'max-depth' to limit the tree when datastores are heavily nested.",
+  "examples": [
+    {
+      "summary": "List all namespaces under the 'clients' parent namespace in a remote datastore, limited to two levels deep",
+      "path_params": {
+        "remote": "pbs-hetzner",
+        "datastore": "nightsquawk-backups"
+      },
+      "params": {
+        "parent": "clients",
+        "max-depth": 2
+      }
+    }
+  ],
+  "tips": [
+    "An empty 'ns' string in the response represents the root namespace of the datastore.",
+    "The 'comment' field is optional and sourced from the first line of the namespace's notes — useful for labeling namespaces by client or environment.",
+    "Namespaces support up to 8 path segments; the pattern enforces alphanumeric-plus-dots/dashes/underscores identifiers at each segment.",
+    "Omitting 'parent' lists from the datastore root; set 'max-depth=0' to return only the root namespace itself (no children)."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_datastore_datastore_snapshots",
+    "get_pbs_remotes_remote_datastore_datastore_groups",
+    "get_pbs_remotes"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_pbs_remotes_remote_datastore_datastore_rrddata",
+  "usageNotes": "Use this to retrieve historical disk usage and I/O metrics for a specific PBS datastore on a registered PDM remote — useful for trending storage consumption, capacity planning, or spotting I/O anomalies over time. Both `cf` and `timeframe` are required; use `AVERAGE` for trend graphs and `MAX` to surface peak utilization spikes. The remote must be reachable from PDM and the caller needs `Resource.Audit` on `/resource/{remote}/datastore/{datastore}`.",
+  "examples": [
+    {
+      "summary": "Fetch daily average disk stats for the 'backups' datastore on the 'pbs-hetzner' remote",
+      "path_params": {
+        "remote": "pbs-hetzner",
+        "datastore": "backups"
+      },
+      "params": {
+        "cf": "AVERAGE",
+        "timeframe": "day"
+      }
+    }
+  ],
+  "tips": [
+    "Data points are spaced according to RRD resolution for the chosen timeframe — finer resolution for 'hour', coarser for 'year'/'decade'.",
+    "disk-available + disk-used may not equal disk-total exactly due to filesystem overhead; disk-total is the authoritative capacity figure.",
+    "disk-read and disk-write are rates (bytes/sec), not cumulative totals — use AVERAGE cf for bandwidth graphs, MAX cf to find peak bursts.",
+    "If the remote is offline or unreachable, PDM may return an error rather than partial data; check remote connectivity before relying on missing data points."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_datastore_datastore_status",
+    "get_pbs_remotes_remote_rrddata",
+    "get_pbs_remotes"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_pbs_remotes_remote_datastore_datastore_snapshots",
+  "usageNotes": "Use this to list all backup snapshots in a specific datastore on a PBS remote, optionally scoped to a namespace. Requires the remote to be reachable from PDM and the caller to hold Resource.Audit on the target remote/datastore path. Each result includes backup-type (vm/ct/host), backup-time (Unix epoch), the constituent archive files, protection status, and any last verification result — making this the primary read for auditing backup coverage or checking whether a snapshot was verified.",
+  "examples": [
+    {
+      "summary": "List all snapshots in the 'main' datastore on the 'hetzner-pbs' remote, scoped to the 'clients/acme' namespace",
+      "path_params": {
+        "remote": "hetzner-pbs",
+        "datastore": "main"
+      },
+      "params": {
+        "ns": "clients/acme"
+      }
+    }
+  ],
+  "tips": [
+    "Omit the 'ns' query param to list snapshots from the datastore root namespace; nested namespaces are not returned unless explicitly targeted.",
+    "backup-time is a Unix epoch integer — convert to a human-readable date before displaying to users.",
+    "The 'fingerprint' field is present only for encrypted backups; its absence means the snapshot is unencrypted.",
+    "A snapshot with 'protected: true' will be skipped by prune jobs — check this field before assuming a snapshot is eligible for cleanup.",
+    "The verification.state field reflects the most recent verify task outcome ('ok' or 'failed'); a missing verification object means no verify has ever been run on that snapshot."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_datastore_datastore",
+    "get_pbs_remotes"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_pbs_remotes_remote_nodes_node",
+  "usageNotes": "Returns the directory index for a specific node on a PBS remote, serving as a navigation entry point that lists available sub-resources (e.g., apt, subscription, termproxy). Use this to confirm a PBS remote node is reachable via PDM and to discover what child endpoints are exposed for that node. The remote must already be configured in PDM and the named node must be a member of that remote's cluster.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for node 'pbs-hetzner' on the remote named 'hetzner-pbs'",
+      "path_params": {
+        "remote": "hetzner-pbs",
+        "node": "pbs-hetzner"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The schema declares returns type null — in practice the response is an array of directory entries (route names); treat it as a navigation index, not a data object.",
+    "Token-based authentication is supported (allowtoken: true), so this call is safe in automated scripts and health checks.",
+    "If the remote is unreachable or the node name is wrong, PDM will return an error rather than an empty index — a successful response is a lightweight connectivity check."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_nodes_node_apt",
+    "get_pbs_remotes_remote_nodes_node_apt_update",
+    "get_pbs_remotes_remote_nodes_node_subscription",
+    "get_pbs_remotes_remote_nodes_node_vncwebsocket"
+  ]
+}

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

@@ -0,0 +1,20 @@
+{
+  "operationId": "get_pbs_remotes_remote_nodes_node_apt",
+  "usageNotes": "Returns the APT sub-resource directory index for a specific node on a PBS remote, listing the available APT-related sub-endpoints (such as update, versions, changelog). Use this to discover which APT operations are exposed for a given remote node before calling a more specific APT endpoint. The target remote must be reachable from PDM and the node must be online; the call requires no special privilege beyond authenticated access (user: all).",
+  "examples": [
+    {
+      "summary": "List APT sub-endpoints for node 'pbs01' on remote 'hetzner-pbs'",
+      "path_params": {
+        "remote": "hetzner-pbs",
+        "node": "pbs01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a directory index — it returns child endpoint names, not package data itself. Follow up with a child endpoint (e.g., /apt/update or /apt/versions) to retrieve actual APT information.",
+    "Because returns is typed as null in the schema, the MCP layer may return an empty or opaque response; the real value is the HTTP 200 confirmation that the path is valid and the remote/node combination is reachable.",
+    "Token-based auth (allowtoken: true) is supported, so API tokens scoped to the PDM instance can call this without interactive credentials."
+  ],
+  "relatedOperations": []
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_pbs_remotes_remote_nodes_node_apt_changelog",
+  "usageNotes": "Use this to retrieve the Debian/Ubuntu changelog for a specific package installed on a remote PBS node, which helps assess what changed between versions before applying updates. The caller must have Resource.Modify privilege on the remote node's system resource path. Omit the version parameter to retrieve the changelog for the current candidate (latest available) version.",
+  "examples": [
+    {
+      "summary": "Get the changelog for the proxmox-backup-server package on a remote PBS node",
+      "path_params": {
+        "remote": "pbs-hetzner",
+        "node": "pbs01"
+      },
+      "params": {
+        "name": "proxmox-backup-server",
+        "version": "3.3.2-1"
+      }
+    }
+  ],
+  "tips": [
+    "Package names must match Debian naming conventions (lowercase, hyphens allowed) — the pattern rejects uppercase letters.",
+    "If the target version is not cached locally on the PBS node, the node must be able to reach the APT repository to fetch the changelog.",
+    "Use the companion apt/versions or apt/update endpoints to discover available package versions before querying a specific changelog."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_nodes_node_apt_versions",
+    "post_pbs_remotes_remote_nodes_node_apt_update",
+    "get_pbs_remotes_remote_nodes_node_apt_update"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_pbs_remotes_remote_nodes_node_apt_repositories",
+  "usageNotes": "Use this to inspect the APT repository configuration on a PBS node managed through a PDM remote — useful for verifying the node is pointing at the correct Proxmox enterprise or no-subscription repository before triggering updates. The caller needs Resource.Audit on the remote/node/system path; the target PBS node must be reachable by PDM at call time. Note that the spec declares returns as null, so the useful data is in the response envelope rather than a typed schema.",
+  "examples": [
+    {
+      "summary": "List APT repositories on the default node of a PBS remote named 'pbs-hetzner'",
+      "path_params": {
+        "remote": "pbs-hetzner",
+        "node": "localhost"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Use 'localhost' as the node value when the PBS remote exposes only a single node and you do not know its hostname.",
+    "Cross-reference results with update-related endpoints to confirm repository health before scheduling an APT upgrade.",
+    "API tokens are supported (allowtoken: true), so a read-only audit token scoped to Resource.Audit is sufficient — no interactive session needed."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_nodes_node_apt_versions",
+    "get_pbs_remotes_remote_nodes_node_apt_update",
+    "post_pbs_remotes_remote_nodes_node_apt_repositories"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pbs_remotes_remote_nodes_node_apt_update",
+  "usageNotes": "Use this to check what APT package updates are pending on a remote PBS node — useful before scheduling maintenance or deciding whether to trigger an upgrade run. The remote node must be reachable and already registered in PDM; the caller needs Resource.Modify on the remote/node/system path. Results reflect the last APT cache refresh on the node, not a live apt-get update run — if the list looks stale, trigger an apt-get update on the node first.",
+  "examples": [
+    {
+      "summary": "List pending APT updates on node 'pbs1' of remote 'hetzner-pbs'",
+      "path_params": {
+        "remote": "hetzner-pbs",
+        "node": "pbs1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Results are based on the node's local APT cache; if OldVersion equals Version the cache may be out of date.",
+    "Check the Origin field to distinguish Proxmox-signed packages from upstream Debian packages before applying updates.",
+    "The 'localhost' node alias is accepted when PDM itself is the PBS node."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_nodes_node_apt_changelog",
+    "post_pbs_remotes_remote_nodes_node_apt_update"
+  ]
+}

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

@@ -0,0 +1,23 @@
+{
+  "operationId": "get_pbs_remotes_remote_nodes_node_subscription",
+  "usageNotes": "Use this to check the subscription status of a specific PBS node registered as a PDM remote — useful for confirming a node is running a valid Proxmox Backup Server license before relying on enterprise features or repository access. Requires `Resource.Audit` on `/resource/{remote}`. The `status` field drives the result: treat anything other than `active` as a license gap requiring attention; `key` and `serverid` may be omitted if the caller lacks sufficient privilege to see them.",
+  "examples": [
+    {
+      "summary": "Check subscription status for node 'pbs01' on remote 'hetzner-pbs'",
+      "path_params": {
+        "remote": "hetzner-pbs",
+        "node": "pbs01"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `checktime` field is a Unix timestamp of the last subscription validation check; if it is very stale the node may not have had internet access to validate recently.",
+    "A status of 'notfound' (the default) means no subscription key is configured, not that the API call failed.",
+    "The `key` and `serverid` fields are only returned when the authenticated principal has sufficient privilege to view them; their absence in the response is not an error."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes_remote_nodes_node",
+    "get_pbs_remotes_remote_nodes"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_pbs_remotes_remote_nodes_node_vncwebsocket",
+  "usageNotes": "This endpoint upgrades an HTTP GET request to a VNC WebSocket connection for console access to a PBS remote node; it is not a data-returning API call but the actual WebSocket handshake. You must first obtain a valid vncticket and port from the corresponding VNC ticket creation endpoint before calling this — the ticket is short-lived and node-specific. The caller requires Sys.Console on /resource/{remote}/node/{node}; access tokens are supported.",
+  "examples": [
+    {
+      "summary": "Open a VNC WebSocket console session to node 'pbs-node1' on remote 'pbs-hetzner'",
+      "path_params": {
+        "remote": "pbs-hetzner",
+        "node": "pbs-node1"
+      },
+      "params": {
+        "port": 5900,
+        "vncticket": "PVEVNC:6b2f4a1e::abc123def456"
+      }
+    }
+  ],
+  "tips": [
+    "This is a WebSocket upgrade endpoint — standard REST clients will not receive a meaningful response body; use a WebSocket client (e.g. browser, wscat, or noVNC).",
+    "The vncticket expires quickly; call the ticket-creation endpoint immediately before initiating this WebSocket handshake.",
+    "Use 'localhost' as the node value when PDM itself is acting as the target node.",
+    "Port values are assigned dynamically by the ticket-creation call — do not hardcode a port number."
+  ],
+  "relatedOperations": [
+    "post_pbs_remotes_remote_nodes_node_vncproxy"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_pbs_remotes_remote_rrddata",
+  "usageNotes": "Use this to retrieve historical performance metrics (CPU, memory, disk, network, swap) for a PBS remote registered in PDM. The remote must already exist and be reachable; if PDM cannot contact the remote the returned array may be empty or contain gaps. Choose `cf=AVERAGE` for trend analysis and `cf=MAX` for peak/capacity planning.",
+  "examples": [
+    {
+      "summary": "Fetch last 24 hours of average stats for a remote named 'hetzner-pbs'",
+      "path_params": {
+        "remote": "hetzner-pbs"
+      },
+      "params": {
+        "cf": "AVERAGE",
+        "timeframe": "day"
+      }
+    }
+  ],
+  "tips": [
+    "All metric fields except `time` are optional — gaps appear when PDM could not poll the remote at that interval.",
+    "Disk values (disk-available, disk-total, disk-used) reflect the PBS datastore aggregate, not individual datastores.",
+    "Use `timeframe=hour` for recent incident triage; `timeframe=week` or longer for capacity planning.",
+    "The `cpu-avg1/5/15` load-average fields are raw load numbers, not percentages — divide by CPU core count to normalize."
+  ],
+  "relatedOperations": [
+    "get_pbs_remotes",
+    "get_pbs_remotes_remote",
+    "get_pbs_remotes_remote_datastores"
+  ]
+}