@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_info",
+  "usageNotes": "Executes the QEMU Guest Agent 'info' command on a running VM, returning metadata about the guest agent itself (version, supported commands, etc.). The VM must be running and have the QEMU Guest Agent installed and active; the call will fail if the agent is not responsive. Requires either VM.GuestAgent.Audit or VM.GuestAgent.Unrestricted on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Retrieve guest agent info for VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If the call returns an error like 'QEMU guest agent is not running', verify the agent service is started inside the guest OS (e.g., qemu-guest-agent.service on Linux).",
+    "The returned 'result' object typically lists the agent version and which guest-agent commands are supported — useful before calling less-common agent subcommands.",
+    "This is a synchronous GET; no UPID is returned. Results are available immediately in the response."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_get_osinfo",
+    "get_nodes_node_qemu_vmid_agent_network_get_interfaces",
+    "post_nodes_node_qemu_vmid_agent_ping"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_agent_network_get_interfaces",
+  "usageNotes": "Queries the QEMU Guest Agent (qemu-guest-agent) running inside the VM to return all network interface names, MAC addresses, IP addresses (v4 and v6), and their associated prefixes. The guest agent must be installed and running inside the VM, and the VM must be powered on; if the agent is not responsive the call will return an error rather than empty data. Requires either VM.GuestAgent.Audit or VM.GuestAgent.Unrestricted on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "List network interfaces for VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If the call fails with 'guest agent is not running', check that qemu-guest-agent is installed in the guest OS and that the virtio-serial channel is present in the VM config.",
+    "The returned result object structure mirrors the QEMU Guest Agent protocol: an array of interface objects each containing 'name', 'hardware-address', and 'ip-addresses'.",
+    "IP addresses include both IPv4 and IPv6 entries; filter by 'ip-address-type' field ('ipv4' or 'ipv6') to isolate the address family you need.",
+    "This is the reliable way to discover guest IPs when DHCP leases or cloud-init records may be stale — the agent reads directly from the OS network stack."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_agent_info",
+    "get_nodes_node_qemu_vmid_agent_get_host_name",
+    "get_nodes_node_qemu_vmid_agent_get_osinfo",
+    "get_nodes_node_qemu_vmid_config"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_cloudinit",
+  "usageNotes": "Use this to inspect the cloud-init configuration of a QEMU VM, showing both the values that were used to generate the currently active cloud-init image and any pending changes not yet applied. A config change is only reflected in the VM after a cloud-init image regeneration (via the update endpoint) followed by a reboot — this endpoint lets you detect that drift before it bites you. Requires VM.Audit on the target VM.",
+  "examples": [
+    {
+      "summary": "Get cloud-init config for VM 105 on node pve1, showing current vs pending values",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Items with a 'pending' field but no 'value' field are newly added options not yet baked into the drive image.",
+    "Items with 'delete': 1 are staged for removal but still active until the cloud-init drive is regenerated.",
+    "Both 'value' and 'pending' being present on the same key means the option was changed but the drive hasn't been rebuilt yet — the VM is still running with the old value.",
+    "Cloud-init changes only take effect after regenerating the drive (POST /cloudinit) and rebooting the VM; this read endpoint is safe to poll without side effects."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_qemu_vmid_cloudinit",
+    "get_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_cloudinit"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_cloudinit_dump",
+  "usageNotes": "Use this to inspect the cloud-init configuration that Proxmox auto-generates for a VM before or after first boot — useful for verifying that user-data, network config, or metadata will be rendered as expected. The VM must exist on the specified node and have cloud-init configured (cicustom or inline ci* options set); calling this on a VM without cloud-init yields an empty or minimal response. Requires only VM.Audit on the VM path, so it is safe to call in read-only monitoring contexts.",
+  "examples": [
+    {
+      "summary": "Dump the generated network config for VM 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {
+        "type": "network"
+      }
+    }
+  ],
+  "tips": [
+    "Run with type=user, type=network, and type=meta separately — each returns a distinct cloud-init document (user-data YAML, network-config YAML, and meta-data respectively).",
+    "The output reflects the config that will be written to the cloud-init ISO at next VM start; changes to cicustom or inline ci* options are not reflected until the VM is restarted or the cloud-init drive is regenerated.",
+    "If the VM was cloned from a template, verify the dump to confirm hostname, IP, and SSH keys were correctly inherited or overridden before first boot."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_config",
+    "put_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_cloudinit"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_config",
+  "usageNotes": "Use this to read a QEMU VM's full configuration before making changes — the response includes a 'digest' field that should be passed to write operations to guard against concurrent modifications. By default the response reflects pending (not-yet-applied) config changes; pass 'current: true' to see what is actually running, or 'snapshot' to inspect a named snapshot's config. Requires VM.Audit permission on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Get the pending config for VM 101 on node pve1, requesting the running state instead",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "current": true
+      }
+    }
+  ],
+  "tips": [
+    "The 'digest' in the response is a SHA1 hash of the config file — include it in subsequent PUT calls to prevent overwriting changes made by another session.",
+    "Omitting 'current' (the default) returns pending values that will take effect after next VM restart; use 'current: true' when you need the live running config.",
+    "The 'snapshot' param accepts a snapshot name (pve-configid, max 40 chars) and returns that snapshot's frozen config rather than the live or pending config.",
+    "Fields like 'runningmachine', 'runningcpu', and 'vmstate' are internal snapshot bookkeeping values and should not be modified directly."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_qemu_vmid_config",
+    "get_nodes_node_qemu_vmid_pending",
+    "post_nodes_node_qemu_vmid_snapshot",
+    "get_nodes_node_qemu_vmid_agent_get_osinfo"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_feature",
+  "usageNotes": "Use this before attempting a snapshot, clone, or linked-copy operation to confirm the VM's storage backend supports it — not all storage types (e.g. raw on LVM) support all features. When checking snapshot support for a specific existing snapshot rather than the live VM state, pass the optional `snapname` to scope the check to that snapshot's storage. Returns `hasFeature: false` if any disk in the VM is on an unsupported storage, along with the `nodes` array listing cluster nodes where the feature is available.",
+  "examples": [
+    {
+      "summary": "Check whether VM 105 supports cloning on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {
+        "feature": "clone"
+      }
+    }
+  ],
+  "tips": [
+    "A VM with mixed storage (e.g., one disk on ZFS, one on LVM-thin) may return hasFeature: false for snapshot/clone even if most disks are compatible — all disks must be on supported storage.",
+    "The `nodes` array in the response reflects cluster-wide availability; a non-empty array does not mean every node listed has the VM — it means those nodes' storage pools support the feature.",
+    "Run this check programmatically before calling clone or snapshot creation endpoints to surface a clear error rather than a mid-task UPID failure."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_snapshot",
+    "post_nodes_node_qemu_vmid_clone",
+    "get_nodes_node_qemu_vmid_snapshot"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall",
+  "usageNotes": "Returns the directory index of firewall sub-resources available for a specific QEMU VM (rules, ipset, aliases, options, refs, log). Use this as a discovery call to confirm which firewall endpoints are reachable before navigating to a specific sub-resource. No special privilege is required beyond being an authenticated user.",
+  "examples": [
+    {
+      "summary": "List firewall sub-resources for VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "This is a pure directory index — it does not return actual firewall rules or settings; follow up with sub-resource endpoints (e.g., get_nodes_node_qemu_vmid_firewall_rules) for actionable data.",
+    "The response links use a relative {name} href pattern, meaning each object's 'name' field is the sub-path segment to append.",
+    "VM-level firewall settings are independent of the node-level firewall; both must be enabled for VM firewall rules to take effect."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "get_nodes_node_qemu_vmid_firewall_options",
+    "get_nodes_node_qemu_vmid_firewall_ipset",
+    "get_nodes_node_qemu_vmid_firewall_aliases",
+    "get_nodes_node_qemu_vmid_firewall_log",
+    "get_nodes_node_qemu_vmid_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_aliases",
+  "usageNotes": "Returns all IP/CIDR aliases defined in a VM's firewall configuration, which can be referenced by name in firewall rules instead of raw addresses. Requires VM.Audit on the target VM — no node-level privilege is needed. Aliases are VM-scoped; to see cluster-wide aliases shared across all VMs, query the cluster firewall aliases endpoint instead.",
+  "examples": [
+    {
+      "summary": "List firewall aliases for VM 105 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each returned object includes a 'digest' field — pass it to create/update/delete alias calls to guard against concurrent modifications.",
+    "Alias names are case-sensitive and must be unique within the VM's firewall scope; they do not collide with cluster-level alias names.",
+    "An empty array response means no aliases have been defined yet — the VM's firewall may still be enabled with inline CIDRs in rules."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_refs",
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "get_cluster_firewall_aliases"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_aliases_name",
+  "usageNotes": "Retrieves a single named firewall alias defined at the VM (QEMU guest) level, returning its CIDR value and any comment. Use this to inspect a specific alias before referencing it in firewall rules, or to verify the IP/network it resolves to. Requires VM.Audit on /vms/{vmid}; alias names must start with a letter and be 2–64 characters.",
+  "examples": [
+    {
+      "summary": "Read the 'WebServers' alias for VM 201 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 201,
+        "name": "WebServers"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Alias names are case-sensitive and must match the pattern [A-Za-z][A-Za-z0-9\\-\\_]+.",
+    "VM-level aliases are scoped to the individual VM firewall; they do not exist in the cluster-level alias namespace.",
+    "If the alias is not found the API returns a 500-series error, not a 404 — check spelling and scope before assuming it is absent.",
+    "Use list_aliases (GET /nodes/{node}/qemu/{vmid}/firewall/aliases) first if you are unsure of the exact alias name."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_aliases",
+    "post_nodes_node_qemu_vmid_firewall_aliases",
+    "put_nodes_node_qemu_vmid_firewall_aliases_name",
+    "delete_nodes_node_qemu_vmid_firewall_aliases_name"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_ipset",
+  "usageNotes": "Lists all named IP sets defined in a VM's guest-level firewall. Use this before creating or referencing an IP set in firewall rules to confirm the set exists and retrieve its digest for safe concurrent-edit protection. Requires VM.Audit on the VM path; the node must be online and the QEMU guest must exist.",
+  "examples": [
+    {
+      "summary": "List all firewall IP sets for VM 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each returned object includes a 'digest' field — pass it to write operations (create/update/delete on IP set entries) to prevent race conditions with concurrent modifications.",
+    "An empty array means no IP sets have been created for this VM's guest firewall yet; guest-level IP sets are separate from cluster-level IP sets.",
+    "IP set names follow the pattern [A-Za-z][A-Za-z0-9\\-\\_]+ — useful to know when scripting lookups by name."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_ipset_name",
+    "post_nodes_node_qemu_vmid_firewall_ipset",
+    "delete_nodes_node_qemu_vmid_firewall_ipset_name",
+    "get_nodes_node_qemu_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_ipset_name",
+  "usageNotes": "Lists all CIDR entries inside a named IPSet scoped to a specific VM's firewall. The IPSet must already exist on that VM — use the list-ipsets endpoint first if the name is unknown. Each returned entry includes the CIDR, an optional comment, a digest (use it as an optimistic-lock token for subsequent writes), and an optional 'nomatch' flag that inverts the entry's match behavior.",
+  "examples": [
+    {
+      "summary": "List all entries in the 'trusted-mgmt' IPSet for VM 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110,
+        "name": "trusted-mgmt"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'digest' field in each entry is used to prevent concurrent modifications — pass it when updating or deleting an entry to ensure the set hasn't changed since you read it.",
+    "The 'nomatch' flag negates a CIDR entry, effectively creating an exclusion within the IPSet — useful for carving out a subnet from a broader range.",
+    "IPSet names must start with a letter and can only contain letters, digits, hyphens, and underscores (2–64 chars).",
+    "This endpoint is VM-firewall scoped; cluster-level IPSets live under a different path (/cluster/firewall/ipset/{name})."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_ipset",
+    "post_nodes_node_qemu_vmid_firewall_ipset_name",
+    "delete_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+    "get_nodes_node_qemu_vmid_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+  "usageNotes": "Retrieves the settings for a single IP or CIDR entry within a named IPSet on a QEMU VM's firewall. Use this to inspect a specific entry (including any attached comment) when you already know the exact CIDR value; if you need to enumerate all entries in the set, list the IPSet instead. Requires VM.Audit on the target VM; the hosting node must be online.",
+  "examples": [
+    {
+      "summary": "Read a specific CIDR entry from a VM's firewall IPSet",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 200,
+        "name": "trusted-mgmt",
+        "cidr": "10.10.5.0/24"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'cidr' path param accepts bare IPs (e.g. 192.168.1.50), CIDR ranges, or IPSet aliases — match exactly what was used when the entry was created.",
+    "The IPSet name must match the pattern [A-Za-z][A-Za-z0-9\\-\\_]+ (2–64 chars); names starting with a digit are invalid.",
+    "A 'nomatch' flag on the entry (negation prefix '!') is returned in the response object — check for it when building firewall logic."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_ipset_name",
+    "get_nodes_node_qemu_vmid_firewall_ipset",
+    "post_nodes_node_qemu_vmid_firewall_ipset_name",
+    "put_nodes_node_qemu_vmid_firewall_ipset_name_cidr",
+    "delete_nodes_node_qemu_vmid_firewall_ipset_name_cidr"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_log",
+  "usageNotes": "Use this to retrieve per-VM firewall log entries from the node's kernel log; the VM's firewall must be enabled and the node hosting the VM must be online. Requires VM.Console on the VM's path — standard VM.Audit is not sufficient. Use 'since'/'until' UNIX epoch filters to narrow results for a specific incident window rather than fetching the entire log.",
+  "examples": [
+    {
+      "summary": "Fetch the 50 most recent firewall log entries for VM 101 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 101
+      },
+      "params": {
+        "limit": 50
+      }
+    }
+  ],
+  "tips": [
+    "Each returned item has 'n' (line number) and 't' (log text); line numbers can be used with 'start' for cursor-style pagination through large logs.",
+    "Log entries only appear if the VM's firewall is enabled at both the datacenter/node level and the VM level — a missing log is often a sign the firewall is disabled, not that traffic is allowed.",
+    "Use 'since' and 'until' together to scope a specific time window; both accept UNIX epoch integers."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "get_nodes_node_qemu_vmid_firewall_options",
+    "get_nodes_node_firewall_log"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_options",
+  "usageNotes": "Use this to read the current firewall behavior settings for a specific QEMU VM — including whether the firewall is enabled, default input/output policies, DHCP/NDP/MAC filter state, and log levels. Requires VM.Audit on the VM's path; no node-level privilege is needed. If the firewall has never been explicitly configured for the VM, most fields will be absent (falling back to their documented defaults).",
+  "examples": [
+    {
+      "summary": "Retrieve firewall options for VM 105 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Fields not returned in the response are at their default values (e.g. enable defaults to false, macfilter defaults to true).",
+    "A VM firewall being enabled here does not mean rules exist — check the rules endpoint separately to confirm active rule coverage.",
+    "policy_in and policy_out are only meaningful when the firewall is enabled; the default implicit policy when no policy is set is ACCEPT.",
+    "ipfilter, when enabled, auto-populates per-interface ipsets with link-local restrictions — useful for preventing IP spoofing without manual ipset management."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_qemu_vmid_firewall_options",
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "get_nodes_node_qemu_vmid_firewall_ipsets",
+    "get_nodes_node_qemu_vmid_firewall_log"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_refs",
+  "usageNotes": "Use this endpoint to discover which IPSet and Alias names are valid when building firewall rules for a specific VM — these are the values you can reference in the source/destination fields of a rule. Results include both VM-level and datacenter-level references that are in scope for this VM. Requires VM.Audit on the target VM's path; no node-online requirement beyond normal API reachability.",
+  "examples": [
+    {
+      "summary": "List all firewall references (aliases and IPSets) available for VM 105 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Omit the 'type' filter to see all available references in one call; use 'type=alias' or 'type=ipset' when you only need one kind.",
+    "The 'scope' field in each result indicates whether the reference is defined at the VM level or inherited from the datacenter/cluster firewall.",
+    "Use this before creating or validating firewall rules to confirm the exact 'ref' string to use — rule creation will reject unknown references."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "post_nodes_node_qemu_vmid_firewall_rules",
+    "get_nodes_node_firewall_refs",
+    "get_cluster_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_rules",
+  "usageNotes": "Returns the ordered list of firewall rules applied to a specific QEMU VM, including rule position, action, protocol filters, and enabled/disabled state. Requires VM.Audit permission on the VM path; the node must be online and the VM does not need to be running. Rules are returned in position order (pos field) — this order matters because Proxmox evaluates them top-down.",
+  "examples": [
+    {
+      "summary": "List all firewall rules for VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The pos field is the authoritative rule order — use it as the index when referencing a specific rule for updates or deletions.",
+    "Rules with enable=0 are defined but inactive; check this field to understand why traffic may be passing through unexpectedly.",
+    "An action value that doesn't match ACCEPT/DROP/REJECT is a security group reference — the rule delegates to that group's ruleset.",
+    "VM-level rules are evaluated after the datacenter and node-level rules; a DROP at the datacenter level will never reach these rules."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_rules_pos",
+    "post_nodes_node_qemu_vmid_firewall_rules",
+    "put_nodes_node_qemu_vmid_firewall_rules_pos",
+    "delete_nodes_node_qemu_vmid_firewall_rules_pos",
+    "get_nodes_node_qemu_vmid_firewall_options",
+    "get_nodes_node_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_firewall_rules_pos",
+  "usageNotes": "Use this to inspect a single firewall rule for a QEMU VM by its zero-based position index in the ruleset; call the rule-list endpoint first to discover valid positions. Requires VM.Audit on /vms/{vmid} — read-only, safe to call at any time regardless of VM power state. The pos path parameter is marked optional in the spec but must be supplied to target a specific rule.",
+  "examples": [
+    {
+      "summary": "Fetch rule at position 2 for VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101,
+        "pos": 2
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rule positions are zero-indexed and shift when rules above them are inserted or deleted — always re-query the list before referencing a position by number.",
+    "The 'enable' field in the response is an integer (1 = enabled, 0 = disabled), not a boolean.",
+    "If the VM uses firewall security groups, the 'action' field will contain the group name rather than ACCEPT/DROP/REJECT."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_firewall_rules",
+    "put_nodes_node_qemu_vmid_firewall_rules_pos",
+    "delete_nodes_node_qemu_vmid_firewall_rules_pos",
+    "post_nodes_node_qemu_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_migrate",
+  "usageNotes": "Call this before initiating a VM migration to check whether the migration is feasible. The response identifies blocking local resources (e.g. passthrough PCI/USB devices), local disks that cannot follow the VM, storage unavailability on candidate nodes, and HA affinity constraints — all of which must be resolved before POST migrate will succeed. Pass an optional `target` node to get a targeted feasibility report including `not_allowed_nodes` detail for all other cluster members.",
+  "examples": [
+    {
+      "summary": "Check migration preconditions for VM 105 on node pve1, scoped to target node pve2",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 105
+      },
+      "params": {
+        "target": "pve2"
+      }
+    }
+  ],
+  "tips": [
+    "If `local_resources` is non-empty, live migration is impossible without removing or mapping the listed PCI/USB devices first.",
+    "Local disks (especially CD-ROM images or disks on non-shared storage) listed in `local_disks` must be moved to shared storage or the migration must use offline mode.",
+    "`dependent-ha-resources` lists HA resources that will automatically follow the VM to the target — verify the target node satisfies their affinity rules before migrating.",
+    "Use the `mapped-resource-info` field (not the deprecated `mapped-resources`) to determine whether any mapped resources support live migration.",
+    "A `running: true` response means the VM is live; factor this in when choosing between live and offline migration via the POST endpoint."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_migrate",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_cluster_resources"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_mtunnelwebsocket",
+  "usageNotes": "This endpoint is an internal migration tunnel used exclusively by Proxmox's live migration subsystem to upgrade an HTTP connection to a WebSocket that proxies a Unix socket on the destination node. It should not be called directly by operators or tools — it is invoked automatically during a VM migration handshake. Both the `socket` path and `ticket` must be obtained from a prior `mtunnel` API call; the ticket is short-lived and scoped to the specific socket being forwarded.",
+  "examples": [
+    {
+      "summary": "WebSocket upgrade for VM 105 migration tunnel (internal use)",
+      "path_params": {
+        "node": "pve-hetzner-01",
+        "vmid": 105
+      },
+      "params": {
+        "socket": "/var/run/qemu-server/105.mtunnel",
+        "ticket": "MIGRATE:pve-hetzner-01:105:abc123def456"
+      }
+    }
+  ],
+  "tips": [
+    "Never call this endpoint directly from scripts or MCP tools — it is part of the internal migration protocol and requires a valid short-lived ticket from the mtunnel handshake.",
+    "The ticket is obtained via the POST /nodes/{node}/qemu/{vmid}/mtunnel endpoint or the 'ticket' tunnel command during migration setup.",
+    "The response may return a `port` or `socket` confirming the forwarding target, but the primary mechanism is the WebSocket protocol upgrade itself.",
+    "If a migration stalls or fails with a WebSocket-related error, check that the source and destination nodes can reach each other on the migration network and that the ticket has not expired."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_qemu_vmid_migrate",
+    "get_nodes_node_qemu_vmid_migrate",
+    "post_nodes_node_qemu_vmid_mtunnel"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_pending",
+  "usageNotes": "Use this endpoint to inspect a VM's configuration diff — it returns every config key alongside its current live value and any pending value that will take effect after the next VM reboot. This is the right call before rebooting a VM to confirm what changes are queued, or after editing config to verify the pending state was recorded correctly. Requires VM.Audit permission on /vms/{vmid}; the node must be online.",
+  "examples": [
+    {
+      "summary": "Check pending configuration changes on VM 105 before a scheduled reboot",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 105
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A row with only 'value' (no 'pending') means that key has no queued changes.",
+    "A row with 'delete' set to 1 means the key is queued for removal on next reboot; value 2 means a force-delete is pending.",
+    "A row with 'pending' but no 'value' means the key is being added for the first time.",
+    "Compare 'value' vs 'pending' on the 'memory' or 'cores' keys to confirm a resize will take effect without a live migration.",
+    "If there are no pending changes, the response array will still list all current config keys with only 'value' populated."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_config",
+    "put_nodes_node_qemu_vmid_config",
+    "post_nodes_node_qemu_vmid_reboot"
+  ]
+}

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

@@ -0,0 +1,30 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_rrd",
+  "usageNotes": "Fetches a pre-rendered RRD graph (returned as a PNG filename reference) for a specific QEMU VM on a given node; requires the VM to exist on that node and the caller to hold VM.Audit on /vms/{vmid}. The 'ds' parameter accepts a comma-separated list of RRD datasource names (e.g. 'cpu,mem,netin,netout,diskread,diskwrite'); omitting 'cf' defaults to AVERAGE. Use rrddata (get_nodes_node_qemu_vmid_rrddata) instead if you need raw numeric time-series values rather than a PNG graph.",
+  "examples": [
+    {
+      "summary": "Get a day-view CPU and memory RRD graph for VM 101 on pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "ds": "cpu,mem",
+        "timeframe": "day",
+        "cf": "AVERAGE"
+      }
+    }
+  ],
+  "tips": [
+    "Valid datasource names for QEMU VMs include: cpu, mem, netin, netout, diskread, diskwrite, maxcpu, maxmem.",
+    "The response contains a 'filename' string pointing to the generated PNG on the Proxmox host — the file is ephemeral and served via the web UI's file endpoint.",
+    "Use 'MAX' as the consolidation function (cf) to surface burst peaks over longer timeframes like week or month.",
+    "For programmatic time-series data (JSON array of values), use the sibling rrddata endpoint instead."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_rrddata",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_rrd",
+    "get_nodes_node_lxc_vmid_rrd"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_qemu_vmid_rrddata",
+  "usageNotes": "Returns historical RRD metric data points (CPU, memory, disk I/O, network) for a specific QEMU VM. The `timeframe` parameter is required and determines the data resolution and range — shorter timeframes give finer granularity. Use `cf=AVERAGE` for trend analysis and `cf=MAX` for spike detection; omitting `cf` defaults to AVERAGE on most Proxmox versions. The VM must exist on the specified node and the caller needs `VM.Audit` on `/vms/{vmid}`.",
+  "examples": [
+    {
+      "summary": "Fetch last hour of average metrics for VM 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "timeframe": "hour",
+        "cf": "AVERAGE"
+      }
+    }
+  ],
+  "tips": [
+    "Data resolution decreases as timeframe increases (e.g. 'year' returns one point per week, 'hour' returns one point per minute).",
+    "RRD data lags real-time by up to one RRD step interval (~70 seconds for the hour timeframe); do not use for live monitoring.",
+    "If the VM was recently created or migrated, older timeframes may return sparse or empty arrays for the period before the VM existed on that node.",
+    "Use `cf=MAX` when alerting on peak resource usage; `cf=AVERAGE` smooths out transient spikes and is better for capacity trending."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_qemu_vmid_rrd",
+    "get_nodes_node_qemu_vmid_status_current",
+    "get_nodes_node_rrddata"
+  ]
+}