@nightsquawktech/proxmox-mcp-server 0.1.0

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_lxc",
+  "usageNotes": "Use this to enumerate all LXC containers on a specific node, including their running status, resource usage, and configuration metadata. Results are scoped to the caller's VM.Audit permissions — containers the caller cannot audit are silently omitted, so an empty list does not mean no containers exist. The target node must be online; requests to an offline or unreachable node will return an error.",
+  "examples": [
+    {
+      "summary": "List all LXC containers on node 'pve1'",
+      "path_params": {
+        "node": "pve1"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Entries with 'template': true are container templates, not running guests — filter these out when looking for active workloads.",
+    "The 'lock' field (e.g., 'backup', 'migrate', 'snapshot') indicates the container is mid-operation; avoid config changes or power actions until the lock clears.",
+    "CPU, mem, disk I/O, and network counters are only populated for running containers; stopped containers will have those fields absent or zero.",
+    "Pressure fields (pressurecpusome, pressureiosome, etc.) reflect Linux PSI metrics and are only available on nodes running a kernel with PSI support enabled."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_lxc_vmid_config",
+    "get_cluster_resources",
+    "get_nodes_node_qemu"
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid",
+  "usageNotes": "Returns the directory index (list of available sub-resource paths) for a specific LXC container on a given node. Use this as a discovery call to determine which sub-endpoints are available for a container (e.g., config, status, snapshot, firewall). No privileges beyond basic cluster access are required since permissions are set to 'all', but the target node must be reachable and the VMID must exist on that node.",
+  "examples": [
+    {
+      "summary": "List available sub-resources for LXC container 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The returned 'subdir' values map directly to child API paths — append them to this endpoint's path to reach specific container operations (e.g., /nodes/pve1/lxc/110/config).",
+    "This is a read-only discovery endpoint; it reveals no sensitive container data, only the names of available sub-resources.",
+    "If the VMID does not exist on the specified node, the API returns a 500 error rather than 404 — verify the container is on the correct node before calling."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc",
+    "get_nodes_node_lxc_vmid_config",
+    "get_nodes_node_lxc_vmid_status_current"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_config",
+  "usageNotes": "Use this to read the full configuration of a specific LXC container, including CPU, memory, network interfaces, mount points, and rootfs details. By default the API returns pending (not-yet-applied) values; pass `current: true` to get the live running configuration. To inspect a historical state, provide a `snapshot` name instead — `current` and `snapshot` are mutually exclusive.",
+  "examples": [
+    {
+      "summary": "Fetch the current running config for LXC container 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "current": true
+      }
+    }
+  ],
+  "tips": [
+    "The `digest` field in the response is a SHA1 of the config file — pass it back in write operations to guard against concurrent modifications.",
+    "A `lock` field in the response indicates an in-progress operation (backup, migrate, snapshot, etc.); writes will be rejected until the lock clears.",
+    "Network interfaces are returned as `net0`, `net1`, ... and mount points as `mp0`, `mp1`, ... — enumerate these keys in your client since the count varies per container.",
+    "If `unprivileged` is false, the container runs as root on the host; treat privileged containers with extra care when reading security-sensitive config.",
+    "Omitting both `current` and `snapshot` returns pending config, which may differ from what is actually running if a config change has not been applied yet."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_lxc_vmid_config",
+    "get_nodes_node_lxc_vmid_snapshot",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_lxc"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_feature",
+  "usageNotes": "Use this before attempting a snapshot, clone, or copy operation on an LXC container to confirm the underlying storage driver supports it — not all storage types (e.g. NFS, ZFS without snapshots enabled) support every feature. Pass `snapname` when checking feature availability against a specific existing snapshot rather than the running container. Returns a single boolean `hasFeature`; gate any dependent operation on a `true` result.",
+  "examples": [
+    {
+      "summary": "Check whether LXC 110 on node pve1 supports cloning",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {
+        "feature": "clone"
+      }
+    }
+  ],
+  "tips": [
+    "Feature support is determined by the storage backend of the container's root disk, not the container config itself — a container on local-lvm may behave differently than one on a directory-backed storage.",
+    "Use `snapname` to verify that a specific snapshot can still be cloned or copied after the container config has changed.",
+    "This endpoint is read-only and lightweight; safe to call in pre-flight checks before any clone/snapshot/copy workflow."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_snapshot",
+    "post_nodes_node_lxc_vmid_clone",
+    "get_nodes_node_lxc_vmid_snapshot"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall",
+  "usageNotes": "Returns the directory index of firewall sub-resources available for a specific LXC container, useful for discovering which firewall endpoints (rules, aliases, ipsets, options, log, refs) are accessible before making targeted calls. No special privileges are required — all authenticated users can query this index. Use this as a starting point when building firewall management workflows to confirm available sub-paths before operating on them.",
+  "examples": [
+    {
+      "summary": "List firewall sub-resources for LXC container 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The response is a navigation index only — it returns sub-resource names (e.g. 'rules', 'options', 'log', 'aliases', 'ipset', 'refs'), not actual firewall configuration data.",
+    "To retrieve or modify the container's actual firewall rules, follow up with the specific child endpoint such as get_nodes_node_lxc_vmid_firewall_rules or get_nodes_node_lxc_vmid_firewall_options.",
+    "This endpoint accepts API tokens (allowtoken: true), making it safe to use in automated scripts that discover firewall structure before reading or writing firewall config."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_rules",
+    "get_nodes_node_lxc_vmid_firewall_options",
+    "get_nodes_node_lxc_vmid_firewall_log",
+    "get_nodes_node_lxc_vmid_firewall_aliases",
+    "get_nodes_node_lxc_vmid_firewall_ipset",
+    "get_nodes_node_lxc_vmid_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_aliases",
+  "usageNotes": "Lists all firewall IP aliases defined at the container level for a specific LXC guest. These aliases are container-scoped (not cluster- or datacenter-wide) and can be referenced by name in the container's firewall rules to simplify rule management. Requires VM.Audit on the target VMID; the node must be reachable and the container must exist.",
+  "examples": [
+    {
+      "summary": "List firewall aliases for LXC container 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Each alias entry includes a digest field — pass this digest when creating or updating aliases to guard against concurrent modifications.",
+    "Aliases defined here are container-scoped; they are not visible to other containers or the datacenter firewall unless also defined at those levels.",
+    "If the container's firewall is not enabled, aliases still exist in config but have no active effect on traffic."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_firewall_aliases",
+    "get_nodes_node_lxc_vmid_firewall_aliases_name",
+    "put_nodes_node_lxc_vmid_firewall_aliases_name",
+    "delete_nodes_node_lxc_vmid_firewall_aliases_name",
+    "get_nodes_node_lxc_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_aliases_name",
+  "usageNotes": "Retrieves a single named firewall alias defined at the LXC container level, returning its CIDR value and any comment. Use this to inspect or verify a specific alias before referencing it in firewall rules. Alias names must start with a letter and match the pattern [A-Za-z][A-Za-z0-9\\-\\_]+; the caller must hold VM.Audit on the container.",
+  "examples": [
+    {
+      "summary": "Read the 'WebBackend' alias on LXC container 110 hosted on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110,
+        "name": "WebBackend"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Aliases defined at the container level are scoped only to that container's firewall — they are not shared with the node or datacenter alias pools.",
+    "If the alias name does not exist, the API returns a 500 error rather than a 404; handle accordingly in error logic.",
+    "Use the list endpoint (get_nodes_node_lxc_vmid_firewall_aliases) first to confirm an alias exists before reading it by name."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_aliases",
+    "post_nodes_node_lxc_vmid_firewall_aliases",
+    "put_nodes_node_lxc_vmid_firewall_aliases_name",
+    "delete_nodes_node_lxc_vmid_firewall_aliases_name"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_ipset",
+  "usageNotes": "Use this to enumerate all named IP sets defined in a container's firewall configuration. Each returned object includes the set name, an optional human-readable comment, and a digest you can pass to write operations to prevent concurrent modification conflicts. Requires VM.Audit permission on /vms/{vmid}; the container does not need to be running.",
+  "examples": [
+    {
+      "summary": "List all firewall IP sets for LXC container 200 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "IP set names follow the pattern [A-Za-z][A-Za-z0-9\\-\\_]+ and are referenced by name in firewall rules — use this listing to confirm exact names before building rules.",
+    "The digest field in each returned item reflects the current state of the firewall config; supply it in subsequent write calls to guard against race conditions.",
+    "IP sets defined at the cluster level are separate from container-level sets — this endpoint only returns sets scoped to this specific LXC."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_ipset_name",
+    "post_nodes_node_lxc_vmid_firewall_ipset",
+    "get_nodes_node_lxc_vmid_firewall_rules",
+    "get_cluster_firewall_ipset"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_ipset_name",
+  "usageNotes": "Use this to list all CIDR entries within a named IPSet scoped to a specific LXC container's firewall. The IPSet must already exist on the container; call the IPSet list endpoint first if you need to confirm the name. Each returned entry includes a digest — capture it before any subsequent add/remove operations to guard against concurrent modifications.",
+  "examples": [
+    {
+      "summary": "List all CIDRs in the 'trusted-mgmt' IPSet for LXC 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110,
+        "name": "trusted-mgmt"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "IPSet names must start with a letter and match [A-Za-z][A-Za-z0-9\\-\\_]+; names like '10net' are invalid.",
+    "The 'nomatch' flag on an entry inverts that CIDR (acts as an exclusion within the set); check it before assuming all returned CIDRs are allow-listed.",
+    "This endpoint reads the container-level IPSet, which is separate from cluster-level IPSets defined under datacenter firewall — verify scope when troubleshooting rule mismatches.",
+    "The digest in each entry is per-entry, not per-set; use it with modification calls to prevent race conditions when multiple admins manage the same set."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_ipsets",
+    "post_nodes_node_lxc_vmid_firewall_ipset_name",
+    "delete_nodes_node_lxc_vmid_firewall_ipset_name_cidr",
+    "get_nodes_node_lxc_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_ipset_name_cidr",
+  "usageNotes": "Use this to retrieve the details (comment, nomatch flag, etc.) for a specific IP or CIDR entry within a named IPSet on an LXC container's firewall. The `cidr` path param accepts a plain IP address, a CIDR prefix, or an alias — it must exactly match the value used when the entry was created. Requires VM.Audit on the container; the target node must be online and the container's firewall configuration accessible.",
+  "examples": [
+    {
+      "summary": "Read a specific CIDR entry from the 'trusted-mgmt' IPSet on LXC 110",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110,
+        "name": "trusted-mgmt",
+        "cidr": "10.10.10.0/24"
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The `cidr` field accepts aliases (e.g. `dc/myalias`) in addition to raw IPs and CIDR blocks — the format is IPorCIDRorAlias.",
+    "A successful response returns an object that may include a `comment` field and a `nomatch` boolean; check for `nomatch: true` to identify negation entries that block a specific address within the set.",
+    "IPSet names must start with a letter and be 2–64 characters; use list_ipset first to confirm the exact name before calling this endpoint."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_ipset_name",
+    "post_nodes_node_lxc_vmid_firewall_ipset_name",
+    "put_nodes_node_lxc_vmid_firewall_ipset_name_cidr",
+    "delete_nodes_node_lxc_vmid_firewall_ipset_name_cidr",
+    "get_nodes_node_lxc_vmid_firewall_ipset"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_log",
+  "usageNotes": "Retrieves firewall log entries for a specific LXC container; useful for auditing traffic, diagnosing dropped packets, or confirming that firewall rules are matching as expected. The caller must have VM.Console permission on the container's /vms/{vmid} path. Use `since`/`until` (UNIX epoch integers) to narrow results to a time window, and `start`/`limit` for pagination through large logs.",
+  "examples": [
+    {
+      "summary": "Fetch the 50 most recent firewall log lines for container 110, filtered to the last hour",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {
+        "since": 1751158800,
+        "limit": 50
+      }
+    }
+  ],
+  "tips": [
+    "Each returned object has 'n' (line number) and 't' (raw log text); parse 't' to extract action, interface, source/destination IP and port.",
+    "Firewall logging must be enabled on the container's firewall rules (log level != nolog) — this endpoint returns nothing if no rules are set to log.",
+    "For high-traffic containers, always supply `limit` to avoid pulling thousands of lines in a single call; paginate with `start` offsets.",
+    "Log entries reflect the host-level nftables/iptables kernel log, so timestamps are in local node time — correlate against node timezone when comparing across cluster nodes."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_rules",
+    "get_nodes_node_lxc_vmid_firewall_options",
+    "get_nodes_node_firewall_log",
+    "get_cluster_firewall_log"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_options",
+  "usageNotes": "Use this to inspect the top-level firewall configuration for a specific LXC container, including whether the firewall is enabled, default input/output policies, and which protocol helpers (DHCP, NDP, MAC filter, IP filter) are active. Requires VM.Audit on the container's path — no write privilege needed. Note that this returns container-level options only; individual firewall rules are fetched via the separate rules endpoint.",
+  "examples": [
+    {
+      "summary": "Retrieve firewall options for LXC container 110 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "If 'enable' is false (the default), all firewall rules for the container are bypassed regardless of what rules exist.",
+    "ipfilter=true is the recommended security baseline for containers — it auto-populates interface ipsets with MAC-derived IPv6 link-local restrictions and the container's configured IP addresses.",
+    "macfilter defaults to true (enabled), providing an extra layer against ARP spoofing; verify it is not unexpectedly disabled on untrusted networks.",
+    "log_level_in and log_level_out default to 'nolog' — set to 'info' or 'debug' temporarily when troubleshooting dropped traffic."
+  ],
+  "relatedOperations": [
+    "put_nodes_node_lxc_vmid_firewall_options",
+    "get_nodes_node_lxc_vmid_firewall_rules",
+    "get_nodes_node_lxc_vmid_firewall_ipsets",
+    "get_nodes_node_lxc_vmid_firewall_aliases",
+    "get_nodes_node_lxc_vmid_firewall_log"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_refs",
+  "usageNotes": "Use this endpoint to discover which IPSet and Alias names are valid in the source/destination fields of firewall rules for a specific LXC container. This is useful before creating or editing firewall rules to avoid referencing undefined objects. The caller requires VM.Audit permission on the target VMID.",
+  "examples": [
+    {
+      "summary": "List all firewall reference objects (aliases and ipsets) for LXC 110 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Omit the 'type' query parameter to return both aliases and ipsets in one call.",
+    "The 'scope' field in each result indicates whether the reference is defined at the container level or the cluster/datacenter level.",
+    "Use the returned 'ref' value (not 'name') when constructing firewall rule source/destination strings."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_rules",
+    "get_nodes_node_lxc_vmid_firewall_aliases",
+    "get_nodes_node_lxc_vmid_firewall_ipset",
+    "get_cluster_firewall_refs"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_rules",
+  "usageNotes": "Returns the ordered list of container-level firewall rules for a specific LXC guest; rules are applied in position order (pos field), so sequence matters for policy evaluation. Requires VM.Audit permission on /vms/{vmid} — read-only and safe to call at any time regardless of container run state. Use this before modifying rules to capture current state or to verify a rule was applied correctly after a create/update operation.",
+  "examples": [
+    {
+      "summary": "List all firewall rules for LXC container 110 on node pve01",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rules are returned in ascending pos order; lower pos values are evaluated first.",
+    "The 'enable' field is an integer flag (1 = enabled, 0 = disabled) — a rule present in the list is not necessarily active.",
+    "Container-level rules are evaluated after datacenter and node-level firewall policies; check those layers if a rule here appears to have no effect.",
+    "An empty array response means no container-level rules are defined — inherited cluster/datacenter rules may still apply if the firewall is enabled on the container."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_options",
+    "post_nodes_node_lxc_vmid_firewall_rules",
+    "get_nodes_node_lxc_vmid_firewall_rules_pos",
+    "put_nodes_node_lxc_vmid_firewall_rules_pos",
+    "delete_nodes_node_lxc_vmid_firewall_rules_pos"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_firewall_rules_pos",
+  "usageNotes": "Retrieves a single firewall rule for an LXC container by its zero-based position in the ruleset. Use this to inspect a specific rule's full details (action, proto, ports, source/dest, enable state) before modifying or deleting it. Requires VM.Audit on /vms/{vmid}; the container does not need to be running.",
+  "examples": [
+    {
+      "summary": "Fetch the first firewall rule for LXC 200 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200,
+        "pos": 0
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "Rule positions are zero-indexed; use get_nodes_node_lxc_vmid_firewall_rules (list) first to enumerate positions before fetching a specific one.",
+    "The 'enable' field returns 0 (disabled) or 1 (enabled) as an integer, not a boolean.",
+    "If 'macro' is set, it overrides proto/dport/sport — individual port/protocol fields may be absent or ignored."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_firewall_rules",
+    "put_nodes_node_lxc_vmid_firewall_rules_pos",
+    "delete_nodes_node_lxc_vmid_firewall_rules_pos",
+    "post_nodes_node_lxc_vmid_firewall_rules"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_interfaces",
+  "usageNotes": "Use this endpoint to retrieve the live IP and MAC addresses of all network interfaces inside a running LXC container; the guest agent (qemu-guest-agent equivalent for LXC) must be active and the container must be in a running state for data to be returned. Requires VM.Audit on /vms/{vmid}. Results reflect the in-guest network state, not just the Proxmox config, so DHCP-assigned or manually configured addresses appear here.",
+  "examples": [
+    {
+      "summary": "List all network interfaces and IPs for container 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The container must be running; a stopped container returns an error or empty result.",
+    "Both 'inet' (legacy flat field) and 'ip-addresses' (structured array) may be present — prefer 'ip-addresses' for CIDR prefix information.",
+    "The 'hardware-address' and 'hwaddr' fields carry the same MAC; 'hwaddr' is the older alias.",
+    "If the container uses a veth bridge, lo (loopback) will always appear in the list — filter it out when enumerating externally-reachable addresses."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_config",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_lxc"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_migrate",
+  "usageNotes": "Call this before initiating an LXC container migration to determine which nodes are valid targets and whether any HA affinity rules or running state will affect the move. The response includes allowed and blocked target nodes with blocking reasons, which helps surface HA conflicts before committing to the actual migrate POST. Requires VM.Migrate on /vms/{vmid}.",
+  "examples": [
+    {
+      "summary": "Check migration preconditions for container 110, targeting node pve2",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {
+        "target": "pve2"
+      }
+    }
+  ],
+  "tips": [
+    "Omit the 'target' param to get a full picture of all allowed and not-allowed nodes at once, rather than checking one target at a time.",
+    "Inspect 'not-allowed-nodes' and its 'blocking-ha-resources' list to understand whether node-affinity or resource-affinity rules are preventing migration to a specific host.",
+    "If 'dependent-ha-resources' is non-empty, those HA resources will follow the container to the same target node — confirm the target has capacity for them before migrating.",
+    "A 'running: true' response means the container is live; hot migration is supported for LXC but may require shared storage depending on your setup."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_migrate",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_cluster_ha_resources"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_mtunnelwebsocket",
+  "usageNotes": "This endpoint is strictly internal to the Proxmox live-migration subsystem — it upgrades an HTTP connection to a WebSocket tunnel used to relay data between source and destination nodes during LXC container migration. It should not be called directly by external tooling; the correct entry point is the mtunnel API call, which issues the socket path and ticket required here. The ticket is short-lived and scoped to the specific unix socket, so both values must be obtained immediately before use.",
+  "examples": [
+    {
+      "summary": "WebSocket upgrade for an in-progress LXC migration (as initiated by the migration subsystem)",
+      "path_params": {
+        "node": "pve-htz-de1",
+        "vmid": 201
+      },
+      "params": {
+        "socket": "/var/run/pve/migration-201.sock",
+        "ticket": "MIGRATE:pve-htz-de1:201:abc123def456"
+      }
+    }
+  ],
+  "tips": [
+    "Never call this endpoint manually — it is invoked automatically by pve-manager during container live migration.",
+    "The ticket is obtained from the initial mtunnel call or via the 'ticket' tunnel command; it expires quickly.",
+    "Permissions are validated through the ticket itself, not through the standard PVE privilege tree, which is why 'user: all' is shown in the spec.",
+    "A failed or stale ticket will result in an authentication error; restart the migration rather than retrying with the same ticket."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_migrate",
+    "get_nodes_node_lxc_vmid_mtunnel"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_pending",
+  "usageNotes": "Use this endpoint to inspect an LXC container's current configuration alongside any pending changes that will take effect after the next container restart. Each item in the response array represents one config key with its current `value`, pending `value` (if a change is queued), and a `delete` flag (non-zero means the key is queued for removal). Requires `VM.Audit` on `/vms/{vmid}`; API tokens are supported.",
+  "examples": [
+    {
+      "summary": "Check pending configuration changes for container 200 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 200
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "A non-null `pending` field alongside a `value` field means the config key was changed but the container has not yet been restarted to apply it.",
+    "A `delete` value of 1 or 2 means the key is scheduled for removal on next restart — treat the current `value` as still active until then.",
+    "This endpoint is read-only and synchronous; no UPID is returned."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_config",
+    "post_nodes_node_lxc_vmid_config",
+    "post_nodes_node_lxc_vmid_reboot",
+    "post_nodes_node_lxc_vmid_shutdown"
+  ]
+}

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

@@ -0,0 +1,29 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_rrd",
+  "usageNotes": "Use this endpoint to fetch a prerendered RRD performance graph (returned as a PNG filename path) for a specific LXC container. The caller must specify at least one datasource (e.g., `cpu`, `mem`, `netin`, `netout`, `diskread`, `diskwrite`) and a timeframe; the node must be online and the container must exist. The response returns a `filename` pointing to the generated PNG on the Proxmox host, not the raw image bytes — use the file path to retrieve the image separately if needed.",
+  "examples": [
+    {
+      "summary": "Get a 24-hour CPU and memory usage graph for LXC container 101 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 101
+      },
+      "params": {
+        "ds": "cpu,mem",
+        "timeframe": "day",
+        "cf": "AVERAGE"
+      }
+    }
+  ],
+  "tips": [
+    "Common datasource names for LXC containers: cpu, mem, netin, netout, diskread, diskwrite — these match the names shown in the Proxmox web UI graphs.",
+    "The `cf` parameter defaults to AVERAGE when omitted; use MAX to see peak spikes rather than averaged values.",
+    "The returned `filename` is a server-side path to the PNG; you cannot download it directly from this endpoint — pair it with a file fetch or use rrddata endpoint if you need raw data points instead of an image.",
+    "Use `get_nodes_node_lxc_vmid_rrddata` instead if you need numeric time-series data rather than a rendered graph."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_rrddata",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_qemu_vmid_rrd"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_rrddata",
+  "usageNotes": "Retrieves time-series performance data (CPU, memory, network, disk I/O) for an LXC container from the node's RRD database. The container must exist on the specified node and the caller needs VM.Audit on /vms/{vmid}. Use 'AVERAGE' for trend graphs and 'MAX' to surface peak spikes; omitting 'cf' lets Proxmox apply its default consolidation.",
+  "examples": [
+    {
+      "summary": "Fetch the last hour of average performance data for container 110",
+      "path_params": {
+        "node": "pve01",
+        "vmid": 110
+      },
+      "params": {
+        "timeframe": "hour",
+        "cf": "AVERAGE"
+      }
+    }
+  ],
+  "tips": [
+    "Returned data points are spaced according to the RRD resolution for the chosen timeframe — finer resolution for 'hour', coarser for 'year'.",
+    "Fields in each returned object vary by what metrics Proxmox has recorded; check for null/missing keys before graphing.",
+    "If the container was recently created or was stopped for most of the window, many data points will be empty or zero.",
+    "MAX consolidation is most useful for 'week' or longer timeframes where average values can mask short bursts."
+  ],
+  "relatedOperations": [
+    "get_nodes_node_lxc_vmid_rrd",
+    "get_nodes_node_lxc_vmid_status_current",
+    "get_nodes_node_rrddata"
+  ]
+}

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

@@ -0,0 +1,25 @@
+{
+  "operationId": "get_nodes_node_lxc_vmid_snapshot",
+  "usageNotes": "Returns the full snapshot list for a specific LXC container, including a synthetic 'current' entry representing the live state. Use this before creating, rolling back, or deleting snapshots to confirm names and the parent-child chain. Requires VM.Audit on /vms/{vmid}; the node must be online and the container must exist.",
+  "examples": [
+    {
+      "summary": "List all snapshots for LXC container 110 on node pve1",
+      "path_params": {
+        "node": "pve1",
+        "vmid": 110
+      },
+      "params": {}
+    }
+  ],
+  "tips": [
+    "The 'current' entry in the result is not a real snapshot — it marks the live container state and has no snaptime.",
+    "Use the 'parent' field to reconstruct the snapshot tree before deciding which snapshot to roll back to.",
+    "snaptime is a Unix timestamp; convert it to a human-readable date when displaying to users."
+  ],
+  "relatedOperations": [
+    "post_nodes_node_lxc_vmid_snapshot",
+    "delete_nodes_node_lxc_vmid_snapshot_snapname",
+    "post_nodes_node_lxc_vmid_snapshot_snapname_rollback",
+    "get_nodes_node_lxc_vmid_snapshot_snapname_config"
+  ]
+}