@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_cluster_sdn_vnets_vnet_firewall_rules",
+  "usageNotes": "Use this endpoint to append a new firewall rule to a specific SDN VNet's ruleset. The caller must hold SDN.Allocate on the vnet's zone path ('/sdn/zones/<zone>/<vnet>'); without it the call returns 403. Rules are appended at the end by default — use 'pos' to insert at a specific index (0-based). The call returns null on success, so confirm insertion by reading back the rules list.",
+  "examples": [
+    {
+      "summary": "Block all inbound traffic from a known malicious subnet to vnet 'prod01'",
+      "path_params": {
+        "vnet": "prod01"
+      },
+      "params": {
+        "type": "in",
+        "action": "DROP",
+        "source": "198.51.100.0/24",
+        "proto": "tcp",
+        "comment": "Block malicious subnet - added 2026-06-29",
+        "log": "warning",
+        "enable": 1
+      }
+    }
+  ],
+  "tips": [
+    "The vnet identifier must be 2–8 alphanumeric characters starting with a letter — single-char names are rejected.",
+    "Rules are evaluated top-down; insert at 'pos' 0 to make a rule take effect before existing ones.",
+    "Use 'macro' (e.g. 'SSH', 'HTTP') to avoid specifying proto/dport manually for common services.",
+    "Set 'enable' to 0 to add a rule in disabled state for testing before activating it.",
+    "SDN firewall rules live at the cluster level and apply across all nodes — changes take effect cluster-wide after the next SDN apply cycle.",
+    "Use 'digest' from a prior GET to guard against concurrent edits overwriting each other."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets_vnet_firewall_rules",
+    "get_cluster_sdn_vnets_vnet_firewall_rules_pos",
+    "put_cluster_sdn_vnets_vnet_firewall_rules_pos",
+    "delete_cluster_sdn_vnets_vnet_firewall_rules_pos",
+    "get_cluster_sdn_vnets_vnet_firewall"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_cluster_sdn_vnets_vnet_ips",
+  "usageNotes": "Use this to register a static IP-to-MAC mapping within a specific VNet, enabling IPAM-managed address assignment for VMs or containers in SDN zones. The caller must have SDN.Allocate on the zone/vnet path before any mapping is accepted. The `zone` param must match the SDN zone that owns the target VNet, and `vnet` must already exist; creating either on the fly is not supported here.",
+  "examples": [
+    {
+      "summary": "Bind a VM's MAC address to a static IP in vnet 'tenant1' under zone 'sdnzone1'",
+      "path_params": {
+        "vnet": "tenant1"
+      },
+      "params": {
+        "ip": "10.10.20.50",
+        "mac": "BC:24:11:AB:CD:EF",
+        "zone": "sdnzone1"
+      }
+    }
+  ],
+  "tips": [
+    "The vnet identifier must be 2–8 alphanumeric characters, starting and ending with a letter or digit (pattern: [a-zA-Z][a-zA-Z0-9]*[a-zA-Z0-9]).",
+    "MAC address is optional — omitting it creates an IP-only reservation useful for reserving addresses before a VM is provisioned.",
+    "Changes to SDN IP mappings typically require an SDN apply step (PUT /cluster/sdn) to propagate to nodes.",
+    "Returns null on success; any error (duplicate IP, wrong zone/vnet pairing) surfaces as an HTTP error response.",
+    "Both `ip` and `zone` are required; `mac` is the only optional field."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets_vnet_ips",
+    "put_cluster_sdn_vnets_vnet_ips",
+    "delete_cluster_sdn_vnets_vnet_ips",
+    "put_cluster_sdn",
+    "get_cluster_sdn_vnets_vnet"
+  ]
+}

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

@@ -0,0 +1,36 @@
+{
+  "operationId": "post_cluster_sdn_vnets_vnet_subnets",
+  "usageNotes": "Use this to define an IP subnet within an existing SDN VNet — a required step before VMs on that VNet can receive DHCP leases or participate in layer-3 routing. The caller must hold SDN.Allocate on '/sdn/zones/<zone>/<vnet>'; after creating the subnet, run 'apply' (POST /cluster/sdn) to push the configuration to nodes. The 'gateway' field is only meaningful on layer-3 zone VNets; setting 'snat' enables NAT masquerade via pve-firewall for outbound traffic from this subnet.",
+  "examples": [
+    {
+      "summary": "Create a /24 subnet with a gateway, DHCP range, and SNAT enabled on VNet 'tenant-vnet1'",
+      "path_params": {
+        "vnet": "tenant-vnet1"
+      },
+      "params": {
+        "subnet": "10.10.20.0/24",
+        "type": "subnet",
+        "gateway": "10.10.20.1",
+        "dhcp-dns-server": "10.10.20.1",
+        "dhcp-range": [
+          "start-address=10.10.20.100,end-address=10.10.20.200"
+        ],
+        "dnszoneprefix": "tenant1",
+        "snat": true
+      }
+    }
+  ],
+  "tips": [
+    "The 'subnet' identifier must match the pve-sdn-subnet-id format — typically CIDR notation such as '10.10.20.0/24'.",
+    "After creating or modifying SDN objects, call POST /cluster/sdn to apply pending changes cluster-wide; subnets are not active until applied.",
+    "DHCP ranges require the Proxmox IPAM integration (dnsmasq) to be configured on the zone; without it the range is stored but not served.",
+    "Setting 'snat' without pve-firewall enabled on the node has no effect — verify firewall is active before relying on masquerade."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_vnets_vnet_subnets",
+    "get_cluster_sdn_vnets_vnet_subnets_subnet",
+    "put_cluster_sdn_vnets_vnet_subnets_subnet",
+    "delete_cluster_sdn_vnets_vnet_subnets_subnet",
+    "post_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "operationId": "post_cluster_sdn_zones",
+  "usageNotes": "Creates a new SDN zone object in the cluster-wide SDN configuration. The required `zone` identifier must be 2–8 alphanumeric characters starting with a letter, and `type` must match the intended networking model (e.g., `evpn` for BGP/EVPN overlay, `vlan` for simple VLAN-backed networks). After creating the zone you must call `put_cluster_sdn` (apply pending SDN changes) before the zone becomes active on any node; zone-type-specific params (controller, peers, vrf-vxlan, exitnodes, etc.) are only relevant for the matching type.",
+  "examples": [
+    {
+      "summary": "Create a simple VXLAN zone across two cluster nodes",
+      "path_params": {},
+      "params": {
+        "zone": "vxz1",
+        "type": "vxlan",
+        "peers": "10.0.0.1,10.0.0.2",
+        "nodes": "pve1,pve2",
+        "mtu": 1450
+      }
+    }
+  ],
+  "tips": [
+    "Zone IDs are cluster-global and immutable after creation — choose a short, descriptive name up front.",
+    "For EVPN zones, a BGP controller must already exist (post_cluster_sdn_controllers) before referencing it via `controller`.",
+    "VXLAN zones require `peers` (node IPs) and should set `mtu` to 50 bytes below the underlay MTU to account for VXLAN encapsulation overhead.",
+    "After any SDN object create/update, run `put_cluster_sdn` to push pending changes; nodes will not see the zone until the config is applied.",
+    "The `dhcp: dnsmasq` option requires the dnsmasq package to be installed on each participating node."
+  ],
+  "relatedOperations": [
+    "get_cluster_sdn_zones",
+    "get_cluster_sdn_zones_{zone}",
+    "put_cluster_sdn_zones_{zone}",
+    "delete_cluster_sdn_zones_{zone}",
+    "post_cluster_sdn_vnets",
+    "put_cluster_sdn"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_aplinfo",
+  "usageNotes": "Use this to download an LXC appliance template from the Proxmox template repository to a local storage. The caller must have `Datastore.AllocateTemplate` permission on the target storage, and the node must be online with internet access to reach the template source. The return value is a task UPID — poll the task status endpoint to confirm the download completes before attempting to provision a container from the template.",
+  "examples": [
+    {
+      "summary": "Download the Ubuntu 22.04 LXC template to local storage on pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "storage": "local",
+        "template": "ubuntu-22.04-standard_22.04-1_amd64.tar.zst"
+      }
+    }
+  ],
+  "tips": [
+    "Use GET /nodes/{node}/aplinfo first to list available templates and get the exact template string required by this endpoint.",
+    "The returned UPID can be tracked via GET /nodes/{node}/tasks/{upid}/status to detect download failures (e.g., network errors or insufficient storage space).",
+    "Template downloads go to the 'vztmpl' content type directory on the target storage; ensure the storage is configured to accept 'vztmpl' content or the request will fail.",
+    "Large templates (several hundred MB) may take a minute or more — always wait for task completion before using the template."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_aplinfo",
+    "get_nodes_node_tasks_upid_status",
+    "post_nodes_node_lxc"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_apt_repositories",
+  "usageNotes": "Use this to enable or disable an existing APT repository entry on a specific node — it cannot add or remove repository lines, only toggle them. The `path` and `index` together uniquely identify the repository entry within its source file (indexes are 0-based as returned by GET /nodes/{node}/apt/repositories). Pass the `digest` from the GET response to guard against concurrent modifications; the call will fail if the file has changed since you last read it.",
+  "examples": [
+    {
+      "summary": "Disable the Proxmox enterprise repository on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "path": "/etc/apt/sources.list.d/pve-enterprise.list",
+        "index": 0,
+        "enabled": false,
+        "digest": "a3f1c2e4b5d6789012345678901234567890abcd"
+      }
+    }
+  ],
+  "tips": [
+    "Fetch the current repository list with GET /nodes/{node}/apt/repositories first — that response gives you the correct path, index, and digest values required here.",
+    "The digest is optional but strongly recommended in automated workflows; omitting it risks silently overwriting a concurrent change.",
+    "This endpoint returns null on success; an HTTP 4xx/5xx response indicates failure (e.g., stale digest, wrong path, or insufficient privilege).",
+    "Changes take effect immediately for subsequent apt commands — no node restart required."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_repositories",
+    "put_nodes_node_apt_repositories",
+    "post_nodes_node_apt_update"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_apt_update",
+  "usageNotes": "Runs `apt-get update` on the target node to refresh its package index from configured APT sources; call this before checking for available upgrades or listing packages. The operation is asynchronous — the returned string is a UPID (Proxmox task ID) that you must poll with the task-status endpoint to confirm completion. The calling token or user requires `Sys.Modify` on `/nodes/{node}`.",
+  "examples": [
+    {
+      "summary": "Refresh package index on node 'pve1', suppressing progress output",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "quiet": true,
+        "notify": false
+      }
+    }
+  ],
+  "tips": [
+    "The returned UPID looks like 'UPID:pve1:...' — pass it to GET /nodes/{node}/tasks/{upid}/status to check when the update finishes.",
+    "Set notify=true only when you want Proxmox to generate an internal notification about newly available packages; it does not trigger an upgrade.",
+    "Run this before calling the apt/updates list endpoint (GET /nodes/{node}/apt/updates) to ensure results reflect the current upstream state.",
+    "In large clusters, you must call this per-node — there is no cluster-wide apt update endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_apt_updates",
+    "get_nodes_node_apt_changelog",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "post_nodes_node_ceph_fs_name",
+  "usageNotes": "Use this to provision a new CephFS filesystem on an existing Ceph cluster; the target node must be a Ceph monitor/MDS-capable member and the cluster must already be initialized (OSDs and monitors up). The `name` path param defaults to `cephfs`, so only supply it when creating a second filesystem. Returns a task UPID string — poll the task API to confirm completion before mounting or using the filesystem.",
+  "examples": [
+    {
+      "summary": "Create the default CephFS and automatically register it as a PVE storage entry",
+      "path_params": {
+        "node": "pve1",
+        "name": "cephfs"
+      },
+      "params": {
+        "add-storage": true,
+        "pg_num": 64
+      }
+    }
+  ],
+  "tips": [
+    "pg_num should be sized to your OSD count: a common formula is (OSDs × 100) / replicas, rounded to the nearest power of two — the metadata pool is created automatically at pg_num / 4.",
+    "Setting add-storage=true saves a manual step; it creates a `cephfs` storage entry in /etc/pve/storage.cfg pointing to the new filesystem.",
+    "A Ceph MDS daemon must be running before the filesystem becomes accessible — deploy one via the MDS endpoints if not already present.",
+    "You can only create one CephFS per cluster with the default name; use a distinct name for additional filesystems and ensure your Ceph version supports multiple active filesystems."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_ceph_fs",
+    "post_nodes_node_ceph_mds_name",
+    "get_nodes_node_ceph_status",
+    "post_nodes_node_ceph_osd"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "post_nodes_node_ceph_init",
+  "usageNotes": "Run this once on any node in the cluster before installing OSDs or creating pools; it writes ceph.conf and sets up required symlinks. The call is idempotent — re-running it when a [global] section already exists preserves the existing fsid, auth, and pool defaults, so it is safe to retry. Requires Sys.Modify on the root path; the node must be online and reachable by the PVE API.",
+  "examples": [
+    {
+      "summary": "Initialize Ceph on pve1 with a dedicated replication/heartbeat VLAN and standard 3-replica defaults",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "network": "10.10.10.0/24",
+        "cluster-network": "10.10.20.0/24",
+        "size": 3,
+        "min_size": 2
+      }
+    }
+  ],
+  "tips": [
+    "Set 'network' and 'cluster-network' to separate CIDRs (storage vs. replication) for best isolation; these cannot be changed without re-initialising the cluster.",
+    "Leave 'pg_bits' at its default — the parameter is deprecated in recent Ceph versions and has no practical effect on modern clusters.",
+    "Never set 'disable_cephx' to true on any network that is not fully private and air-gapped; it removes authentication between all Ceph daemons.",
+    "Returns null on success (not a UPID); any error is surfaced immediately as an HTTP 4xx/5xx response rather than via a task log."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_ceph_config",
+    "post_nodes_node_ceph_osd",
+    "post_nodes_node_ceph_mon",
+    "post_nodes_node_ceph_pools"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "post_nodes_node_ceph_mds_name",
+  "usageNotes": "Creates and starts a Ceph Metadata Server (MDS) daemon on the specified node, which is required for CephFS to function. Requires `Sys.Modify` on the root path and the target node must be online with Ceph already initialized. Returns a task UPID — poll the task status to confirm the daemon reaches `active` or `standby` state before relying on CephFS.",
+  "examples": [
+    {
+      "summary": "Create an MDS on pve1 with hot-standby enabled for faster failover",
+      "path_params": {
+        "node": "pve1",
+        "name": "pve1"
+      },
+      "params": {
+        "hotstandby": true
+      }
+    }
+  ],
+  "tips": [
+    "Ceph recommends at least one active MDS plus one standby; deploy MDS daemons on at least two nodes for HA.",
+    "Setting hotstandby=true causes the standby MDS to tail the active MDS journal, enabling sub-second failover at the cost of extra RAM and CPU on the standby node.",
+    "The `name` path param defaults to the node name if omitted — using the node name keeps daemon naming predictable and consistent with Proxmox conventions.",
+    "After creation, verify daemon state with GET /nodes/{node}/ceph/mds or check the Ceph dashboard; the daemon must reach `active` or `standby` before CephFS mounts will work."
+  ],
+  "relatedOperations": [
+    "delete_nodes_node_ceph_mds_name",
+    "get_nodes_node_ceph_mds",
+    "post_nodes_node_ceph_fs_name",
+    "get_nodes_node_ceph_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_ceph_mgr_id",
+  "usageNotes": "Use this to deploy a Ceph Manager (MGR) daemon on a specific cluster node; run it on at least two nodes for high availability (active + standby). The target node must be online and already participating in the Ceph cluster (i.e., a MON or OSD node). The `id` path parameter defaults to the node name, which is the conventional choice — only supply a custom id if you need multiple MGRs on the same node.",
+  "examples": [
+    {
+      "summary": "Create a Ceph MGR on node 'pve2' using the default id (node name)",
+      "path_params": {
+        "node": "pve2",
+        "id": "pve2"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A minimum of two MGR daemons across different nodes is recommended for HA; the active MGR handles dashboard and module duties while standbys are on hot standby.",
+    "After creation, verify the daemon with `ceph mgr stat` or GET /nodes/{node}/ceph/mgr to confirm the active MGR elected.",
+    "The Ceph dashboard and several Ceph modules (prometheus exporter, pg_autoscaler) require at least one active MGR — deploy MGR before enabling those modules.",
+    "The `id` must match the pattern [a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])? and is limited to 200 characters; stick to the node name to avoid confusion."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_ceph_mgr",
+    "delete_nodes_node_ceph_mgr_id",
+    "post_nodes_node_ceph_mon_monid",
+    "get_nodes_node_ceph_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_ceph_mon_monid",
+  "usageNotes": "Use this to add a Ceph Monitor (and, for the very first monitor, also a Ceph Manager) to an existing Ceph cluster on a given PVE node. The target node must be online and already have Ceph installed; the caller requires Sys.Modify at the root level. Returns a task UPID string — poll the task API to confirm the monitor comes up before continuing with additional cluster changes.",
+  "examples": [
+    {
+      "summary": "Add a monitor on pve2 using the node name as the monitor ID",
+      "path_params": {
+        "node": "pve2",
+        "monid": "pve2"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Omitting monid defaults it to the node name, which is the standard Ceph convention and avoids ID mismatches.",
+    "Only supply mon-address if autodetection picks the wrong interface (e.g., on multi-homed nodes where the storage/Ceph network differs from the management network).",
+    "A healthy Ceph cluster requires an odd number of monitors (3 or 5) for quorum; plan additions accordingly.",
+    "The first monitor created on a fresh cluster also auto-creates a Manager (ceph-mgr) process on the same node."
+  ],
+  "relatedOperations": [
+    "delete_nodes_node_ceph_mon_monid",
+    "get_nodes_node_ceph_mon",
+    "post_nodes_node_ceph_mgr_id",
+    "get_nodes_node_ceph_status"
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "operationId": "post_nodes_node_ceph_osd",
+  "usageNotes": "Use this to provision a new Ceph OSD on a bare block device attached to the target node; the node must be online and already joined to the Ceph cluster before calling this. The operation is asynchronous — the return value is a task UPID; poll the task status endpoint to confirm the OSD comes up. The target device will be wiped, so ensure it holds no data and is not mounted.",
+  "examples": [
+    {
+      "summary": "Create a basic OSD on /dev/sdb with a separate NVMe DB device",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "dev": "/dev/sdb",
+        "db_dev": "/dev/nvme0n1",
+        "db_dev_size": 30,
+        "crush-device-class": "hdd"
+      }
+    }
+  ],
+  "tips": [
+    "Use 'osds-per-device' (≥2) only on high-throughput NVMe drives; it is mutually exclusive with db_dev and wal_dev.",
+    "Set 'encrypted' to true before the OSD is created — encryption cannot be toggled after the fact.",
+    "crush-device-class should match the physical media type ('hdd', 'ssd', or 'nvme') so CRUSH rules can tier storage correctly.",
+    "db_dev and wal_dev should reside on a faster device (SSD/NVMe) than the main OSD device to improve small-write performance."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_ceph_osd",
+    "delete_nodes_node_ceph_osd_osdid",
+    "get_nodes_node_ceph_status",
+    "post_nodes_node_ceph_init",
+    "get_nodes_node_disks_list"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_ceph_osd_osdid_in",
+  "usageNotes": "Marks a Ceph OSD as 'in', causing it to rejoin the CRUSH map and resume data responsibility — use this to reactivate an OSD that was previously removed from the cluster with the corresponding 'out' operation (e.g., during maintenance). The call is synchronous and returns null on success; wait for Ceph to finish rebalancing data before assuming the OSD is fully healthy. Requires 'Sys.Modify' at the root level and the target node must be reachable.",
+  "examples": [
+    {
+      "summary": "Reactivate OSD 3 on node pve1 after maintenance",
+      "path_params": {
+        "node": "pve1",
+        "osdid": 3
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Pair with 'ceph osd out' (post_nodes_node_ceph_osd_osdid_out) for safe maintenance cycles: out before work, in after.",
+    "After calling this endpoint, monitor 'ceph -s' or the PVE dashboard to confirm the OSD transitions from 'out' to 'in' and that PGs rebalance cleanly.",
+    "If the OSD daemon is stopped, mark it 'in' first and then start the daemon — doing it the other way can cause a brief degraded-cluster state.",
+    "This operation does not start the OSD process; use the OSD start endpoint if the daemon is down."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_ceph_osd_osdid_out",
+    "post_nodes_node_ceph_osd_osdid_scrub",
+    "get_nodes_node_ceph_osd",
+    "delete_nodes_node_ceph_osd_osdid"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_nodes_node_ceph_osd_osdid_out",
+  "usageNotes": "Marks a Ceph OSD as 'out', causing the cluster to begin migrating its data to other OSDs — use this as the first step before physically removing a drive or decommissioning an OSD. The operation completes synchronously and returns null; data rebalancing happens asynchronously in the background and can be monitored via Ceph cluster status. The target OSD does not need to be running, but the Ceph cluster must be reachable from the specified node and the caller needs Sys.Modify at the root level.",
+  "examples": [
+    {
+      "summary": "Mark OSD 3 as out before removing a failed drive on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "osdid": 3
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "After marking out, watch 'ceph -s' or the Proxmox dashboard until recovery I/O drops to zero before proceeding with physical removal.",
+    "To reverse the action and bring the OSD back into the cluster, use the sibling 'in' endpoint (post_nodes_node_ceph_osd_osdid_in).",
+    "Marking out does not stop the OSD process — follow up with the destroy endpoint if you intend full decommission.",
+    "Avoid marking multiple OSDs out simultaneously on small clusters (< 3x replication factor worth of OSDs remaining) to prevent data unavailability."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_ceph_osd_osdid_in",
+    "delete_nodes_node_ceph_osd_osdid",
+    "get_nodes_node_ceph_osd"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_ceph_osd_osdid_scrub",
+  "usageNotes": "Triggers a Ceph OSD scrub to detect data inconsistencies; use deep scrub (deep=true) periodically to also verify stored checksums against on-disk data. The call returns null immediately — scrub progress is tracked via Ceph itself (e.g., `ceph pg dump` or the Proxmox Ceph dashboard), not via a UPID. The target node must be online and the OSD must be in an 'up' state for the scrub to proceed.",
+  "examples": [
+    {
+      "summary": "Trigger a deep scrub on OSD.3 via node pve1",
+      "path_params": {
+        "node": "pve1",
+        "osdid": 3
+      },
+      "params": {
+        "deep": true
+      }
+    }
+  ],
+  "tips": [
+    "Normal scrubs verify object existence and metadata; deep scrubs additionally read and verify all object data checksums — they are more I/O intensive and take longer.",
+    "Scrub frequency is also controlled by Ceph's automatic scheduler (osd_scrub_min_interval / osd_scrub_max_interval); use this endpoint to force an immediate scrub outside of that schedule.",
+    "If the cluster is under heavy load, consider setting 'noscrub' or 'nodeep-scrub' flags via the Ceph CLI before triggering manual scrubs to control timing.",
+    "Requires the Sys.Modify privilege at the root ('/') level — API tokens must have this privilege explicitly granted."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_ceph_osd",
+    "get_nodes_node_ceph_status",
+    "get_nodes_node_ceph_osd_osdid_lv_info"
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "operationId": "post_nodes_node_ceph_pool",
+  "usageNotes": "Use this to provision a new Ceph storage pool on the cluster via the specified node (any healthy monitor node works). The operation is asynchronous — the return value is a task UPID; poll the task until complete before referencing the pool in storage config. Requires `Sys.Modify` at the root (`/`) and Ceph must already be initialized on the cluster; set `add_storages: true` to automatically wire the pool as a Proxmox storage entry (mandatory for EC pools to be useful).",
+  "examples": [
+    {
+      "summary": "Create a standard 3-replica RBD pool for VM disks with PG autoscaling enabled",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "name": "vm-data",
+        "application": "rbd",
+        "size": 3,
+        "min_size": 2,
+        "pg_autoscale_mode": "on",
+        "add_storages": true
+      }
+    }
+  ],
+  "tips": [
+    "The `name` param must be cluster-unique and cannot contain colons, slashes, or whitespace.",
+    "For erasure-coded pools, `size`/`min_size`/`crush_rule` apply to the companion metadata (replicated) pool, not the EC pool itself.",
+    "Leave `pg_num` unset and set `pg_autoscale_mode` to `on` for new clusters — Ceph will size PGs correctly as data grows.",
+    "Providing `target_size` or `target_size_ratio` gives the PG autoscaler a better hint and avoids the default `warn` state on small pools.",
+    "The returned UPID can be tracked via `get_nodes_node_tasks_upid_status` to confirm the pool creation completed before adding VMs."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_ceph_pool",
+    "get_nodes_node_ceph_pools",
+    "put_nodes_node_ceph_pool_name",
+    "delete_nodes_node_ceph_pool_name",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "post_nodes_node_ceph_restart",
+  "usageNotes": "Use this to restart Ceph services on a specific node after configuration changes, daemon failures, or as part of a troubleshooting workflow. Omitting the `service` parameter restarts the entire `ceph.target` unit (all Ceph services on the node); pass a specific service name (e.g., `mon.pve1`) to restart only that daemon. The call returns a task UPID string — poll it with the task status endpoint to confirm completion before performing dependent operations.",
+  "examples": [
+    {
+      "summary": "Restart all Ceph services on node pve1",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Restarting `ceph.target` briefly interrupts I/O on all OSDs on that node; ensure Ceph health is HEALTH_OK and PGs are active+clean before restarting to avoid degraded state.",
+    "To restart only the monitor daemon on pve1, set service to `mon.pve1` — this is less disruptive than restarting the full target.",
+    "The returned UPID can be tracked via GET /nodes/{node}/tasks/{upid}/status."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_ceph_start",
+    "post_nodes_node_ceph_stop",
+    "get_nodes_node_ceph_status",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "post_nodes_node_ceph_start",
+  "usageNotes": "Use this endpoint to start Ceph services on a specific cluster node — either all services at once (default `ceph.target`) or a single named service such as a monitor, OSD, MDS, or manager. The calling principal requires `Sys.Modify` on `/`. Returns a task UPID string; poll the task endpoint to confirm the service reaches a running state before proceeding with dependent operations.",
+  "examples": [
+    {
+      "summary": "Start all Ceph services on node pve1 (default target)",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Omitting the `service` parameter starts the `ceph.target` systemd unit, which brings up all Ceph daemons on the node in dependency order — safest for a full node restart.",
+    "To start only a specific OSD (e.g., osd.2), set service to `osd.2`; use `mon.<id>`, `mds.<id>`, or `mgr.<id>` for other daemon types.",
+    "The returned string is a UPID; use get_nodes_node_tasks_upid_status to confirm the service started successfully before running workloads.",
+    "The node must be online and reachable by the Proxmox API; if the node is unreachable, the call will fail before a task is even queued."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_ceph_stop",
+    "post_nodes_node_ceph_restart",
+    "get_nodes_node_ceph_status",
+    "get_nodes_node_tasks_upid_status"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "post_nodes_node_ceph_stop",
+  "usageNotes": "Stops one or all Ceph services on a specific PVE node; omitting 'service' stops the entire ceph.target unit, which halts all Ceph daemons (MON, OSD, MGR, MDS) on that node. Use when decommissioning a node from the Ceph cluster, performing maintenance, or diagnosing daemon-level issues. Returns a task UPID string — poll the task endpoint to confirm completion before assuming services are fully stopped.",
+  "examples": [
+    {
+      "summary": "Stop all Ceph services on node pve1 (default ceph.target)",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Stopping Ceph services on a node removes that node's OSDs and MON from active cluster participation, reducing redundancy and potentially causing I/O degradation or client-visible storage interruptions if the cluster lacks sufficient remaining active OSDs to maintain quorum or the configured replication count.",
+  "tips": [
+    "To stop a single daemon rather than all services, pass the 'service' param using the pattern e.g. 'osd.0' or 'mon.pve1'.",
+    "Before stopping on a multi-OSD node, verify the cluster is HEALTH_OK and has enough remaining OSDs to maintain the replication minimum (default min_size=2).",
+    "Use 'get_nodes_node_ceph_status' to check cluster health before and after this call.",
+    "Stopping services does not remove them from the cluster config — use the appropriate remove/destroy endpoints for permanent removal."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_ceph_start",
+    "post_nodes_node_ceph_restart",
+    "get_nodes_node_ceph_status",
+    "get_nodes_node_tasks"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "post_nodes_node_certificates_acme_certificate",
+  "usageNotes": "Orders a new TLS certificate from the configured ACME CA (e.g., Let's Encrypt) for the specified node using the domain and challenge plugin already set up under Node > ACME. The operation is asynchronous — the returned string is a task UPID; poll it via GET /nodes/{node}/tasks/{upid}/status to confirm success. The node must have a valid ACME account and at least one domain configured before calling this endpoint.",
+  "examples": [
+    {
+      "summary": "Issue a new ACME certificate for node pve1, overwriting any existing custom cert",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {
+        "force": true
+      }
+    }
+  ],
+  "tips": [
+    "ACME account and domain(s) must be configured first via /nodes/{node}/config (acmedomain0, acmedomain1, etc.) before ordering a certificate.",
+    "Omit 'force' (or set it to false) if you want the call to fail rather than silently overwrite a manually-installed certificate.",
+    "Let's Encrypt rate-limits certificate issuance to 5 duplicate certificates per week — use the staging directory for testing.",
+    "After a successful order, Proxmox automatically replaces the node's pveproxy certificate and reloads the service; an active browser session will need to be refreshed."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_certificates_acme_certificate",
+    "delete_nodes_node_certificates_acme_certificate",
+    "get_nodes_node_certificates_info",
+    "get_nodes_node_tasks"
+  ]
+}