@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_snapshot",
+  "usageNotes": "Use this to enumerate all snapshots for a QEMU VM before performing rollback, deletion, or backup decisions. The response always includes a synthetic 'current' entry representing the live VM state, so filter it out when counting user-created snapshots. Requires VM.Audit on /vms/{vmid}; the node must be reachable and the VM does not need to be running.",
+  "examples": [
+    {
+      "summary": "List all snapshots for VM 105 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'current' name entry is always present and represents the live VM, not a real snapshot — skip it when iterating snapshots for rollback or cleanup.",
+    "Check the 'vmstate' field to know whether a snapshot captured RAM; snapshots with vmstate=true take longer to create and consume extra disk space.",
+    "The 'parent' field lets you reconstruct the snapshot chain; a null/absent parent means that snapshot is a root with no ancestor.",
+    "snaptime is a Unix timestamp — render it for human-readable display when surfacing snapshot age to users."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_snapshot",
+    "get_nodes_node_qemu_vmid_snapshot_snapname_config",
+    "post_nodes_node_qemu_vmid_snapshot_snapname_rollback",
+    "delete_nodes_node_qemu_vmid_snapshot_snapname"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_snapshot_snapname",
+  "usageNotes": "Returns the list of sub-commands available under a specific QEMU VM snapshot (e.g., 'config' and 'rollback'). Use this as a discovery step to confirm which actions are exposed before calling a snapshot sub-resource. The snapshot must already exist on the specified node; the snapname must match exactly (case-sensitive, pve-configid format).",
+  "examples": [
+    {
+      "summary": "List available sub-commands for a snapshot named 'pre-upgrade' on VM 101",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101,
+        "snapname": "pre-upgrade"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is an index array of child links (e.g., 'config', 'rollback') — not snapshot content itself. Call the child endpoints to read config or perform a rollback.",
+    "snapname follows pve-configid rules: alphanumeric plus hyphens/underscores, max 40 characters, no spaces.",
+    "This endpoint returns HTTP 500/not-found if the snapshot does not exist; use list_nodes_node_qemu_vmid_snapshot to enumerate valid snapnames first.",
+    "Accessible by all authenticated users (no VM.Snapshot privilege required), but child operations like rollback will enforce their own privilege checks."
+  ],
+  "relatedOperations": [
+    "list_nodes_node_qemu_vmid_snapshot",
+    "get_nodes_node_qemu_vmid_snapshot_snapname_config",
+    "post_nodes_node_qemu_vmid_snapshot_snapname_rollback",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "delete_nodes_node_qemu_vmid_snapshot_snapname"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_snapshot_snapname_config",
+  "usageNotes": "Returns the VM configuration that was captured at snapshot time, including CPU, memory, and disk settings as they existed when the snapshot was taken. Useful for auditing what changed between a snapshot and the current VM config, or verifying a snapshot captured the expected state before rolling back. Requires VM.Snapshot, VM.Snapshot.Rollback, or VM.Audit permission on the VM (any one suffices); the node must be online.",
+  "examples": [
+    {
+      "summary": "Retrieve the config captured in the 'pre-upgrade' snapshot for VM 105",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105,
+        "snapname": "pre-upgrade"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "snapname must follow the pve-configid format (alphanumeric, hyphens allowed, max 40 chars) — use list_nodes_node_qemu_vmid_snapshot to see valid snapshot names for the VM.",
+    "The returned object reflects the hardware config at snapshot creation time, not the current VM config; diff it against the live config endpoint to identify drift.",
+    "This endpoint has no query parameters; all required values are path parameters."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_snapshot",
+    "post_nodes_node_qemu_vmid_snapshot_snapname_rollback",
+    "delete_nodes_node_qemu_vmid_snapshot_snapname",
+    "get_nodes_node_qemu_vmid_config"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_status",
+  "usageNotes": "Returns the list of available status sub-endpoints for a QEMU VM (e.g. current, start, stop, reset, shutdown, suspend, resume, reboot) — useful for discovery but rarely needed directly since the sub-endpoint paths are fixed. Call this before navigating the status tree programmatically, or to confirm which lifecycle actions are exposed for a given VM. No privileges beyond 'all' are required, so any authenticated token can call it.",
+  "examples": [
+    {
+      "summary": "List status sub-endpoints for VM 105 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values are the literal path segments appended to this URL to reach each status action (e.g. 'current', 'start', 'stop').",
+    "This is a directory index only — it carries no live VM state. Use get_nodes_node_qemu_vmid_status_current for power state, CPU, memory, and uptime.",
+    "Because permissions are 'user: all', this call succeeds even with a read-only API token, making it safe for health-check and discovery scripts."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_status_current",
+    "post_nodes_node_qemu_vmid_status_start",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "post_nodes_node_qemu_vmid_status_shutdown",
+    "post_nodes_node_qemu_vmid_status_reboot",
+    "post_nodes_node_qemu_vmid_status_reset",
+    "post_nodes_node_qemu_vmid_status_suspend",
+    "post_nodes_node_qemu_vmid_status_resume"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_status_current",
+  "usageNotes": "Use this to poll the live runtime state of a specific QEMU VM — power state, CPU/memory usage, uptime, and I/O counters since last boot. The caller must have VM.Audit permission on /vms/{vmid} and the target node must be reachable in the cluster; querying a VM on an offline node returns an error, not a stopped status. Check the 'lock' field before issuing any write operations (migrate, backup, snapshot) — a non-empty lock means another task already owns the VM.",
+  "examples": [
+    {
+      "summary": "Get current status of VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'status' field returns only 'stopped' or 'running'; use 'qmpstatus' for finer-grained QEMU states such as 'paused' or 'prelaunch'.",
+    "diskread/diskwrite counters reset to zero on each VM start; they are cumulative since last boot, not lifetime totals.",
+    "mem reflects ballooning-reported usage when the guest agent supports it; memhost reflects actual host-level allocation — these can differ significantly under memory pressure.",
+    "The 'ha' object is always present but will be empty/minimal if HA is not configured for the VM.",
+    "Pressure stall metrics (pressurecpu*, pressureio*, pressuremem*) require a Linux host kernel with PSI support and are absent on older PVE hosts."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_status_start",
+    "post_nodes_node_qemu_vmid_status_stop",
+    "post_nodes_node_qemu_vmid_status_shutdown",
+    "get_nodes_node_qemu_vmid_status_vnc"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_vncwebsocket",
+  "usageNotes": "This endpoint upgrades the HTTP connection to a WebSocket tunnel for VNC traffic and must always be preceded by a call to the vncproxy endpoint (post_nodes_node_qemu_vmid_vncproxy), which returns the required port (5900–5999) and vncticket. The WebSocket handshake is handled by the Proxmox noVNC proxy; callers should not attempt to open this as a plain HTTP GET — it will only work when the client negotiates a WebSocket upgrade. The vncticket is short-lived, so the WebSocket connection must be initiated immediately after the vncproxy call.",
+  "examples": [
+    {
+      "summary": "Open VNC WebSocket for VM 101 on node pve1 using port and ticket from a prior vncproxy call",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "port": 5901,
+        "vncticket": "PVEVNC:65f3a1b2::abcdef1234567890abcdef1234567890"
+      }
+    }
+  ],
+  "tips": [
+    "Always call post_nodes_node_qemu_vmid_vncproxy first — the port and vncticket it returns are required inputs here.",
+    "The port range is 5900–5999; Proxmox allocates from this pool dynamically per vncproxy call.",
+    "The vncticket expires quickly; open the WebSocket connection within a few seconds of receiving it.",
+    "API tokens are allowed (allowtoken: true), so service accounts can automate console access without a user session.",
+    "The caller needs VM.Console privilege on /vms/{vmid} — ensure the token or user has this role assigned."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_vncproxy",
+    "get_nodes_node_qemu_vmid_termproxy",
+    "get_nodes_node_qemu_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_query_oci_repo_tags",
+  "usageNotes": "Use this to discover available tags for an OCI container image repository before pulling or deploying a container (e.g., when creating an LXC from an OCI image). The `reference` must be a valid OCI repository path without a tag or digest (e.g., `docker.io/library/debian` or a private registry path); the node performs the remote registry query outbound, so it must have network access to the registry. Requires `Sys.AccessNetwork` on the node — API tokens are supported.",
+  "examples": [
+    {
+      "summary": "List all available tags for the official Debian image on Docker Hub",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "reference": "docker.io/library/debian"
+      }
+    }
+  ],
+  "tips": [
+    "The reference pattern does not allow a tag suffix (no `:latest`) — pass only the repository path.",
+    "If the registry requires authentication, configure registry credentials on the node before calling this endpoint.",
+    "Large public registries (Docker Hub) may rate-limit unauthenticated tag-list requests; use a pull-through cache or authenticated token to avoid 429 errors.",
+    "The response is a flat string array of tag names; sort or filter client-side as needed."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_query_url_metadata",
+  "usageNotes": "Use this endpoint to inspect a remote URL's file size, filename, and MIME type before initiating a download — for example, to validate an ISO or cloud image URL before passing it to a storage import job. The request is made by the target node, so the node must be online and able to reach the URL. Disable certificate verification (`verify-certificates: false`) only for trusted internal sources with self-signed certs, as it bypasses TLS validation.",
+  "examples": [
+    {
+      "summary": "Check metadata for a Debian cloud image before importing to storage",
+      "path_params": {
+        "node": "pve01"
+      },
+      "params": {
+        "url": "https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2",
+        "verify-certificates": true
+      }
+    }
+  ],
+  "tips": [
+    "All three return fields (filename, mimetype, size) are optional — the remote server may omit any of them depending on its HTTP headers.",
+    "A returned size of 0 or a missing size field may indicate the server does not send a Content-Length header; do not assume the file is empty.",
+    "Requires either Sys.Audit or Sys.Modify at root, or Sys.AccessNetwork scoped to the specific node — the node-scoped privilege is the least-privilege path."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_storage_storage_download_url",
+    "get_nodes_node_storage_storage_content"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_replication",
+  "usageNotes": "Use this to inspect the current status of all replication jobs running on a specific node, including last sync time, next scheduled run, and any error states. The target node must be online and reachable within the cluster; calling against an offline node will fail. Requires VM.Audit on each VM whose replication jobs you want to see — jobs for VMs the caller cannot audit are omitted from results.",
+  "examples": [
+    {
+      "summary": "List all replication jobs on node pve1, filtered to VM 105",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "guest": 105
+      }
+    }
+  ],
+  "tips": [
+    "Omit the 'guest' filter to see every replication job on the node at once — useful for a quick cluster health check.",
+    "Each returned object includes an 'id' in the form '<vmid>-<jobnum>' (e.g. '105-0'); use that id to drill into per-job details via the child endpoint.",
+    "A job with 'fail_count' > 0 and a non-null 'error' field indicates the last sync failed — check the node's replication log for details.",
+    "Replication only applies to VMs and containers configured with at least one replication target; VMs without replication jobs will not appear in the response."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_replication_id_log",
+    "get_nodes_node_replication_id_status",
+    "get_replication",
+    "post_nodes_node_replication_id_schedule_now"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_replication_id",
+  "usageNotes": "Returns the directory index of sub-resources available under a specific replication job on a node — useful for discovering what child endpoints (e.g. log, schedule, status) are exposed for a given job. The replication job must exist on the specified node; use `get_nodes_node_replication` first to list valid job IDs. Accessible by all authenticated users since permissions are set to 'user: all'.",
+  "examples": [
+    {
+      "summary": "List sub-resources for replication job 101-0 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "id": "101-0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The job ID format is '<GUEST_ID>-<JOBNUM>' (e.g. '101-0'), where the guest ID is a 3–9 digit VM or CT ID and the job number starts at 0.",
+    "This endpoint is a directory index — it returns an array of child resource names (e.g. 'log', 'schedule', 'status'), not job configuration or status data directly.",
+    "To inspect actual replication status or logs, follow up with the child endpoints returned by this call."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_replication",
+    "get_nodes_node_replication_id_log",
+    "get_nodes_node_replication_id_schedule_now",
+    "get_nodes_node_replication_id_status"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_replication_id_log",
+  "usageNotes": "Use this to inspect the output of a specific replication job run on a given node — useful for diagnosing sync failures, verifying successful snapshot transfer, or auditing replication history. The caller must have VM.Audit on the replicated VM's /vms/<vmid> or Sys.Audit on /nodes/<node>. Paginate large logs with 'start' and 'limit'; each item returns line number ('n') and text ('t').",
+  "examples": [
+    {
+      "summary": "Fetch the first 50 lines of the replication log for job 101-0 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "id": "101-0"
+      },
+      "params": {
+        "start": 0,
+        "limit": 50
+      }
+    }
+  ],
+  "tips": [
+    "The job ID format is '<VMID>-<JOBNUM>' (e.g. '101-0'). VMID must be 3–9 digits starting with 1-9; JOBNUM is 1–9 digits.",
+    "If the log is empty, the job may not have run yet or the node may not be the replication source for that job.",
+    "Omit 'limit' to retrieve all available log lines in a single response; use pagination for very verbose jobs.",
+    "Replication logs are ephemeral per-run; only the most recent job execution log is available via this endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_replication",
+    "get_nodes_node_replication_id_status",
+    "post_nodes_node_replication_id_schedule_now"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_replication_id_status",
+  "usageNotes": "Use this endpoint to check the current status of a specific replication job on a given node, including last sync time, next scheduled run, error state, and transfer duration. The caller must query the source node (the node that owns the job), not the target. Requires VM.Audit on the guest's /vms/<vmid> path; API token access is supported.",
+  "examples": [
+    {
+      "summary": "Check status of replication job 0 for VM 105 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "id": "105-0"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The job ID format is '<VMID>-<JOBNUM>' (e.g. '105-0'); the VMID must be 3-9 digits and JOBNUM 1-9 digits.",
+    "A non-null 'error' field in the response indicates the last replication run failed — cross-reference with the node's task log using list_nodes_node_tasks.",
+    "This endpoint is node-scoped: the same job ID queried on the wrong node will return 404 since each node tracks only its own outgoing replication jobs.",
+    "Poll this endpoint after triggering a manual replication run (via post_nodes_node_replication_id_schedule_now) to confirm completion."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_replication",
+    "post_nodes_node_replication_id_schedule_now",
+    "get_replication",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_report",
+  "usageNotes": "Use this endpoint to collect a comprehensive diagnostics snapshot of a single node — similar to the 'pvereport' CLI output — covering hardware, kernel, PVE versions, storage, and network state. The response is a raw text string (not JSON); it is intended for support submissions or offline analysis. The node must be online and reachable by the API host; calling against an offline node will return an error.",
+  "examples": [
+    {
+      "summary": "Fetch the full diagnostic report for node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned string is the same content produced by running 'pvereport' on the node's shell — useful for sharing with Proxmox support.",
+    "Output can be several hundred kilobytes; consider writing it to a file rather than displaying it inline.",
+    "Because there are no filtering parameters, parse or grep the returned string client-side if you only need a specific section (e.g., SMART data, subscription status)."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_status",
+    "get_nodes_node_syslog",
+    "get_nodes_node_journal",
+    "get_nodes_node_subscription"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_rrd",
+  "usageNotes": "Use this endpoint to retrieve a pre-rendered RRD graph (returned as a PNG filename path) for a specific node's performance datasources over a chosen timeframe. The caller requires Sys.Audit on /nodes/{node}. For raw numeric time-series data instead of a PNG, use the rrddata endpoint.",
+  "examples": [
+    {
+      "summary": "Fetch a 24-hour average CPU and memory usage graph for node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "ds": "cpu,memused",
+        "timeframe": "day",
+        "cf": "AVERAGE"
+      }
+    }
+  ],
+  "tips": [
+    "The response contains a filename path to the PNG on the PVE host, not the image bytes themselves — the file is served separately via the Proxmox web UI.",
+    "Common datasource names include cpu, memused, memtotal, netin, netout, roottotal, rootused, swaptotal, swapused — check the rrddata endpoint to discover what is actually recorded for a given node.",
+    "Omitting cf defaults to AVERAGE on most PVE versions; specify MAX explicitly when you need peak-usage graphs.",
+    "The decade timeframe produces very coarse resolution and is only useful for long-term trend overviews."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_rrddata"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_rrddata",
+  "usageNotes": "Use this endpoint to retrieve time-series performance metrics (CPU, memory, network, disk I/O) for a specific node over a chosen timeframe. The node must be online and reachable; requests against offline nodes may return empty or stale data. The `cf` parameter controls whether data points are averaged (`AVERAGE`) or show peak values (`MAX`) — omitting it lets Proxmox choose a default.",
+  "examples": [
+    {
+      "summary": "Fetch the last hour of averaged node metrics for pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "timeframe": "hour",
+        "cf": "AVERAGE"
+      }
+    }
+  ],
+  "tips": [
+    "Use `MAX` consolidation function to surface peak spikes that would be smoothed away by AVERAGE — useful for capacity planning.",
+    "Longer timeframes (month, year, decade) return fewer data points due to RRD downsampling; granularity decreases as timeframe increases.",
+    "Requires `Sys.Audit` on `/nodes/{node}` — a read-only audit token is sufficient; no admin privilege needed.",
+    "Returns an array of objects where each object is a timestamp bucket; individual metric keys (cpu, mem, netin, netout, etc.) may be absent if not recorded for that interval."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_rrd",
+    "get_nodes_node_status",
+    "get_cluster_metrics"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_scan",
+  "usageNotes": "Use this to discover which storage/network scan methods are available on a given node before calling a specific scan sub-endpoint (e.g., scan/nfs, scan/iscsi, scan/zfs). The node must be online and reachable by the cluster; calling against an offline node returns an error. No special privilege is required — any authenticated user can list scan methods.",
+  "examples": [
+    {
+      "summary": "List available scan methods on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'method' values map directly to child paths under /nodes/{node}/scan/ — use them to enumerate which subsequent scan calls are valid.",
+    "This is a discovery/index endpoint; it returns method names only, not scan results. Follow up with the appropriate scan sub-endpoint (e.g., get_nodes_node_scan_nfs) to retrieve actual data."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_scan_nfs",
+    "get_nodes_node_scan_iscsi",
+    "get_nodes_node_scan_zfs",
+    "get_nodes_node_scan_glusterfs",
+    "get_nodes_node_scan_cifs",
+    "get_nodes_node_scan_pbs"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_scan_cifs",
+  "usageNotes": "Use this to discover the list of shares exported by a remote CIFS/SMB server before adding it as a Proxmox storage backend. The scan is performed from the specified cluster node, so that node must be online and have network connectivity to the target server. Credentials are optional for guest-accessible shares but required for authenticated shares; omitting them on a protected server will return an empty list or an error rather than an explicit auth failure.",
+  "examples": [
+    {
+      "summary": "List all CIFS shares on a NAS at 192.168.10.50 using domain credentials",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "server": "192.168.10.50",
+        "username": "svcproxmox",
+        "password": "s3cr3t!",
+        "domain": "HOMELAB"
+      }
+    }
+  ],
+  "tips": [
+    "If the target server only allows guest access, omit username/password/domain entirely.",
+    "The scan runs synchronously and returns results directly — there is no UPID/task to poll.",
+    "Run this from the node that will actually mount the share; cross-node routing differences can make a share reachable from one node but not another.",
+    "Share names returned here map directly to the 'share' field used when creating a CIFS storage entry via post_storage."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_scan_nfs",
+    "post_storage",
+    "get_storage"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_scan_iscsi",
+  "usageNotes": "Use this to discover available iSCSI targets on a remote portal before configuring iSCSI storage in Proxmox. The scan is executed on the specified node, so that node must be online and able to reach the portal over the network. Requires Datastore.Allocate on /storage; the portal parameter accepts an IP address or DNS name with an optional port (e.g. '192.168.1.100' or 'iscsi.example.com:3260').",
+  "examples": [
+    {
+      "summary": "Scan an iSCSI portal at 192.168.10.50 from node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "portal": "192.168.10.50"
+      }
+    }
+  ],
+  "tips": [
+    "Run this scan from the node that will actually mount the iSCSI storage — network reachability is node-specific.",
+    "If the portal uses a non-standard port, append it with a colon, e.g. '192.168.10.50:3260'.",
+    "Use the returned target IQNs directly when adding an iSCSI storage definition via the storage API."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_scan_lvm",
+    "get_nodes_node_scan_lvmthin",
+    "get_storage",
+    "post_storage"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_scan_lvm",
+  "usageNotes": "Use this endpoint to discover existing LVM volume groups on a node before provisioning new LVM-backed storage. The caller requires the Datastore.Allocate privilege on /storage, so API tokens used for storage setup must hold that permission. Only volume groups already present on the node's block devices are returned — run this before calling the storage creation endpoint to verify the VG name.",
+  "examples": [
+    {
+      "summary": "List all LVM volume groups on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The node must be online and reachable within the cluster; scanning a node that is down returns an error rather than an empty list.",
+    "Volume group names returned here (the 'vg' field) map directly to the 'vgname' parameter used when creating an LVM storage entry via POST /storage.",
+    "If a VG you expect is missing, check that the underlying physical volume is visible to the OS (pvs/vgs in a node shell) — Proxmox scans what the kernel sees at call time."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_scan_lvmthin",
+    "get_nodes_node_scan_disks",
+    "get_storage",
+    "post_storage"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_scan_lvmthin",
+  "usageNotes": "Use this endpoint to discover which LVM Thin Pools exist within a specific Volume Group on a node before adding LVM-thin storage to Proxmox. The `vg` parameter is required — you must already know the Volume Group name (use the LVM scan endpoint `get_nodes_node_scan_lvm` first if needed). The caller must have `Datastore.Allocate` on `/storage`; the target node must be online and reachable by the cluster.",
+  "examples": [
+    {
+      "summary": "List thin pools inside Volume Group 'pve' on node 'pve1'",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "vg": "pve"
+      }
+    }
+  ],
+  "tips": [
+    "The `vg` name must start with an alphanumeric, dot, plus, or underscore character and be at least 2 characters long (enforced by the pattern).",
+    "If the VG exists but has no thin pools, the response is an empty array — this is normal.",
+    "Use `get_nodes_node_scan_lvm` first to enumerate available Volume Groups if the VG name is unknown.",
+    "Results reflect the live state of the node's LVM metadata; no caching occurs."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_scan_lvm",
+    "get_nodes_node_storage",
+    "post_nodes_node_storage"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_scan_nfs",
+  "usageNotes": "Use this before adding an NFS storage backend to discover which paths a remote NFS server is exporting and what options each export carries. The scan is performed from the specified Proxmox node, so the node must be online and have network connectivity to the target NFS server. The caller must hold Datastore.Allocate on /storage; API tokens are supported.",
+  "examples": [
+    {
+      "summary": "List all NFS exports on a NAS at 192.168.10.50, scanned from node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "server": "192.168.10.50"
+      }
+    }
+  ],
+  "tips": [
+    "The scan initiates an rpcbind/mountd query from the Proxmox node itself — firewall rules must allow TCP/UDP 111 and 2049 from the node to the NFS server.",
+    "Returns an empty array (not an error) when the server is reachable but exports nothing; verify NFS server config if you expect exports.",
+    "Use the returned 'path' values directly as the 'path' parameter when creating an NFS storage entry via POST /storage."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_scan_cifs",
+    "post_storage",
+    "get_storage"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "get_nodes_node_scan_pbs",
+  "usageNotes": "Use this endpoint to discover which datastores are available on a remote Proxmox Backup Server before adding it as a PVE storage target. The scan is performed from the specified cluster node, so that node must be online and able to reach the PBS server over the network. The caller must hold the Datastore.Allocate privilege on /storage, and credentials (username + password or API token) for the PBS server are passed in the query string — supply the certificate fingerprint when the PBS server uses a self-signed TLS certificate to avoid rejection.",
+  "examples": [
+    {
+      "summary": "Discover datastores on an internal PBS server using an API token",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "server": "192.168.10.50",
+        "port": 8007,
+        "username": "backup@pbs!mcp-token",
+        "password": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+        "fingerprint": "A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2:C3:D4:E5:F6:A1:B2"
+      }
+    }
+  ],
+  "tips": [
+    "Credentials are sent as query parameters (GET request); prefer API tokens over plain passwords to limit exposure.",
+    "If the PBS server uses a self-signed certificate and no fingerprint is provided, the scan will fail with a TLS verification error — copy the fingerprint from the PBS web UI under Administration > Certificates.",
+    "The default port is 8007; only specify port if the PBS instance listens on a non-standard port.",
+    "Results feed directly into the storage add workflow — use the returned store names as the datastore value when calling the PBS storage create endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_scan_nfs",
+    "get_nodes_node_scan_cifs",
+    "get_storage",
+    "post_storage"
+  ]
+}