@nightsquawktech/proxmox-mcp-server 0.1.0

package/dist/catalog-pve/endpoints/put_storage_storage.json

@@ -0,0 +1,522 @@
+{
+  "operationId": "put_storage_storage",
+  "surface": "pve",
+  "resource": "storage",
+  "category": "Storage",
+  "name": "update",
+  "method": "PUT",
+  "path": "/storage/{storage}",
+  "description": "Update storage configuration.",
+  "writeOperation": true,
+  "destructive": false,
+  "protected": true,
+  "allowtoken": true,
+  "paramLocation": "body",
+  "pathParams": [
+    {
+      "name": "storage",
+      "type": "string",
+      "required": true,
+      "description": "The storage identifier.",
+      "format": "pve-storage-id",
+      "typetext": "<storage ID>"
+    }
+  ],
+  "params": [
+    {
+      "name": "blocksize",
+      "type": "string",
+      "required": false,
+      "description": "ZFS block size",
+      "format": "pve-storage-zfs-blocksize",
+      "typetext": "<a power of 2 with optional k or m suffix>"
+    },
+    {
+      "name": "bwlimit",
+      "type": "string",
+      "required": false,
+      "description": "Set I/O bandwidth limit for various operations (in KiB/s).",
+      "format": {
+        "clone": {
+          "description": "bandwidth limit in KiB/s for cloning disks",
+          "format_description": "LIMIT",
+          "minimum": "0",
+          "optional": 1,
+          "type": "number"
+        },
+        "default": {
+          "description": "default bandwidth limit in KiB/s",
+          "format_description": "LIMIT",
+          "minimum": "0",
+          "optional": 1,
+          "type": "number"
+        },
+        "migration": {
+          "description": "bandwidth limit in KiB/s for migrating guests (including moving local disks)",
+          "format_description": "LIMIT",
+          "minimum": "0",
+          "optional": 1,
+          "type": "number"
+        },
+        "move": {
+          "description": "bandwidth limit in KiB/s for moving disks",
+          "format_description": "LIMIT",
+          "minimum": "0",
+          "optional": 1,
+          "type": "number"
+        },
+        "restore": {
+          "description": "bandwidth limit in KiB/s for restoring guests from backups",
+          "format_description": "LIMIT",
+          "minimum": "0",
+          "optional": 1,
+          "type": "number"
+        }
+      },
+      "typetext": "[clone=<LIMIT>] [,default=<LIMIT>] [,migration=<LIMIT>] [,move=<LIMIT>] [,restore=<LIMIT>]"
+    },
+    {
+      "name": "comstar_hg",
+      "type": "string",
+      "required": false,
+      "description": "host group for comstar views",
+      "typetext": "<string>"
+    },
+    {
+      "name": "comstar_tg",
+      "type": "string",
+      "required": false,
+      "description": "target group for comstar views",
+      "typetext": "<string>"
+    },
+    {
+      "name": "content",
+      "type": "string",
+      "required": false,
+      "description": "Allowed content types.\n\nNOTE: the value 'rootdir' is used for Containers, and value 'images' for VMs.\n",
+      "format": "pve-storage-content-list",
+      "typetext": "<string>"
+    },
+    {
+      "name": "content-dirs",
+      "type": "string",
+      "required": false,
+      "description": "Overrides for default content type directories.",
+      "format": "pve-dir-override-list",
+      "typetext": "<string>"
+    },
+    {
+      "name": "create-base-path",
+      "type": "boolean",
+      "required": false,
+      "description": "Create the base directory if it doesn't exist.",
+      "default": "yes",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "create-subdirs",
+      "type": "boolean",
+      "required": false,
+      "description": "Populate the directory with the default structure.",
+      "default": "yes",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "data-pool",
+      "type": "string",
+      "required": false,
+      "description": "Data Pool (for erasure coding only)",
+      "typetext": "<string>"
+    },
+    {
+      "name": "delete",
+      "type": "string",
+      "required": false,
+      "description": "A list of settings you want to delete.",
+      "format": "pve-configid-list",
+      "maxLength": 4096,
+      "typetext": "<string>"
+    },
+    {
+      "name": "digest",
+      "type": "string",
+      "required": false,
+      "description": "Prevent changes if current configuration file has a different digest. This can be used to prevent concurrent modifications.",
+      "maxLength": 64,
+      "typetext": "<string>"
+    },
+    {
+      "name": "disable",
+      "type": "boolean",
+      "required": false,
+      "description": "Flag to disable the storage.",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "domain",
+      "type": "string",
+      "required": false,
+      "description": "CIFS domain.",
+      "maxLength": 256,
+      "typetext": "<string>"
+    },
+    {
+      "name": "encryption-key",
+      "type": "string",
+      "required": false,
+      "description": "Encryption key. Use 'autogen' to generate one automatically without passphrase.",
+      "typetext": "<string>"
+    },
+    {
+      "name": "fingerprint",
+      "type": "string",
+      "required": false,
+      "description": "Certificate SHA 256 fingerprint.",
+      "pattern": "([A-Fa-f0-9]{2}:){31}[A-Fa-f0-9]{2}"
+    },
+    {
+      "name": "format",
+      "type": "string",
+      "required": false,
+      "description": "Default image format.",
+      "enum": [
+        "raw",
+        "qcow2",
+        "subvol",
+        "vmdk"
+      ]
+    },
+    {
+      "name": "fs-name",
+      "type": "string",
+      "required": false,
+      "description": "The Ceph filesystem name.",
+      "format": "pve-configid",
+      "typetext": "<string>"
+    },
+    {
+      "name": "fuse",
+      "type": "boolean",
+      "required": false,
+      "description": "Mount CephFS through FUSE.",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "is_mountpoint",
+      "type": "string",
+      "required": false,
+      "description": "Assume the given path is an externally managed mountpoint and consider the storage offline if it is not mounted. Using a boolean (yes/no) value serves as a shortcut to using the target path in this field.",
+      "default": "no",
+      "typetext": "<string>"
+    },
+    {
+      "name": "keyring",
+      "type": "string",
+      "required": false,
+      "description": "Client keyring contents (for external clusters).",
+      "typetext": "<string>"
+    },
+    {
+      "name": "krbd",
+      "type": "boolean",
+      "required": false,
+      "description": "Always access rbd through krbd kernel module.",
+      "default": 0,
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "lio_tpg",
+      "type": "string",
+      "required": false,
+      "description": "target portal group for Linux LIO targets",
+      "typetext": "<string>"
+    },
+    {
+      "name": "master-pubkey",
+      "type": "string",
+      "required": false,
+      "description": "Base64-encoded, PEM-formatted public RSA key. Used to encrypt a copy of the encryption-key which will be added to each encrypted backup.",
+      "typetext": "<string>"
+    },
+    {
+      "name": "max-protected-backups",
+      "type": "integer",
+      "required": false,
+      "description": "Maximal number of protected backups per guest. Use '-1' for unlimited.",
+      "default": "Unlimited for users with Datastore.Allocate privilege, 5 for other users",
+      "minimum": -1,
+      "typetext": "<integer> (-1 - N)"
+    },
+    {
+      "name": "mkdir",
+      "type": "boolean",
+      "required": false,
+      "description": "Create the directory if it doesn't exist and populate it with default sub-dirs. NOTE: Deprecated, use the 'create-base-path' and 'create-subdirs' options instead.",
+      "default": "yes",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "monhost",
+      "type": "string",
+      "required": false,
+      "description": "IP addresses of monitors (for external clusters).",
+      "format": "pve-storage-portal-dns-list",
+      "typetext": "<string>"
+    },
+    {
+      "name": "mountpoint",
+      "type": "string",
+      "required": false,
+      "description": "mount point",
+      "format": "pve-storage-path",
+      "typetext": "<string>"
+    },
+    {
+      "name": "namespace",
+      "type": "string",
+      "required": false,
+      "description": "Namespace.",
+      "typetext": "<string>"
+    },
+    {
+      "name": "nocow",
+      "type": "boolean",
+      "required": false,
+      "description": "Set the NOCOW flag on files. Disables data checksumming and causes data errors to be unrecoverable from while allowing direct I/O. Only use this if data does not need to be any more safe than on a single ext4 formatted disk with no underlying raid system.",
+      "default": 0,
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "nodes",
+      "type": "string",
+      "required": false,
+      "description": "List of nodes for which the storage configuration applies.",
+      "format": "pve-node-list",
+      "typetext": "<string>"
+    },
+    {
+      "name": "nowritecache",
+      "type": "boolean",
+      "required": false,
+      "description": "disable write caching on the target",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "options",
+      "type": "string",
+      "required": false,
+      "description": "NFS/CIFS mount options (see 'man nfs' or 'man mount.cifs')",
+      "format": "pve-storage-options",
+      "typetext": "<string>"
+    },
+    {
+      "name": "password",
+      "type": "string",
+      "required": false,
+      "description": "Password for accessing the share/datastore.",
+      "maxLength": 256,
+      "typetext": "<string>"
+    },
+    {
+      "name": "pool",
+      "type": "string",
+      "required": false,
+      "description": "Pool.",
+      "typetext": "<string>"
+    },
+    {
+      "name": "port",
+      "type": "integer",
+      "required": false,
+      "description": "Use this port to connect to the storage instead of the default one (for example, with PBS or ESXi). For NFS and CIFS, use the 'options' option to configure the port via the mount options.",
+      "minimum": 1,
+      "maximum": 65535,
+      "typetext": "<integer> (1 - 65535)"
+    },
+    {
+      "name": "preallocation",
+      "type": "string",
+      "required": false,
+      "description": "Preallocation mode for raw and qcow2 images. Using 'metadata' on raw images results in preallocation=off.",
+      "enum": [
+        "off",
+        "metadata",
+        "falloc",
+        "full"
+      ],
+      "default": "metadata"
+    },
+    {
+      "name": "prune-backups",
+      "type": "string",
+      "required": false,
+      "description": "The retention options with shorter intervals are processed first with --keep-last being the very first one. Each option covers a specific period of time. We say that backups within this period are covered by this option. The next option does not take care of already covered backups and only considers older backups.",
+      "format": "prune-backups",
+      "typetext": "[keep-all=<1|0>] [,keep-daily=<N>] [,keep-hourly=<N>] [,keep-last=<N>] [,keep-monthly=<N>] [,keep-weekly=<N>] [,keep-yearly=<N>]"
+    },
+    {
+      "name": "saferemove",
+      "type": "boolean",
+      "required": false,
+      "description": "Zero-out data when removing LVs.",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "saferemove-stepsize",
+      "type": "integer",
+      "required": false,
+      "description": "Wipe step size in MiB. It will be capped to the maximum supported by the storage.",
+      "enum": [
+        "1",
+        "2",
+        "4",
+        "8",
+        "16",
+        "32"
+      ],
+      "default": 32
+    },
+    {
+      "name": "saferemove_throughput",
+      "type": "string",
+      "required": false,
+      "description": "Wipe throughput (cstream -t parameter value).",
+      "typetext": "<string>"
+    },
+    {
+      "name": "server",
+      "type": "string",
+      "required": false,
+      "description": "Server IP or DNS name.",
+      "format": "pve-storage-server",
+      "typetext": "<string>"
+    },
+    {
+      "name": "shared",
+      "type": "boolean",
+      "required": false,
+      "description": "Indicate that this is a single storage with the same contents on all nodes (or all listed in the 'nodes' option). It will not make the contents of a local storage automatically accessible to other nodes, it just marks an already shared storage as such!",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "skip-cert-verification",
+      "type": "boolean",
+      "required": false,
+      "description": "Disable TLS certificate verification, only enable on fully trusted networks!",
+      "default": "false",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "smbversion",
+      "type": "string",
+      "required": false,
+      "description": "SMB protocol version. 'default' if not set, negotiates the highest SMB2+ version supported by both the client and server.",
+      "enum": [
+        "default",
+        "2.0",
+        "2.1",
+        "3",
+        "3.0",
+        "3.11"
+      ],
+      "default": "default"
+    },
+    {
+      "name": "snapshot-as-volume-chain",
+      "type": "boolean",
+      "required": false,
+      "description": "Enable support for creating storage-vendor agnostic snapshot through volume backing-chains.",
+      "default": 0,
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "sparse",
+      "type": "boolean",
+      "required": false,
+      "description": "use sparse volumes",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "subdir",
+      "type": "string",
+      "required": false,
+      "description": "Subdir to mount.",
+      "format": "pve-storage-path",
+      "typetext": "<string>"
+    },
+    {
+      "name": "tagged_only",
+      "type": "boolean",
+      "required": false,
+      "description": "Only list logical volumes tagged with 'pve-vm-ID'.",
+      "typetext": "<boolean>"
+    },
+    {
+      "name": "username",
+      "type": "string",
+      "required": false,
+      "description": "RBD Id.",
+      "typetext": "<string>"
+    },
+    {
+      "name": "zfs-base-path",
+      "type": "string",
+      "required": false,
+      "description": "Base path where to look for the created ZFS block devices. Set automatically during creation if not specified. Usually '/dev/zvol'.",
+      "format": "pve-storage-path",
+      "typetext": "<string>"
+    }
+  ],
+  "returns": {
+    "properties": {
+      "config": {
+        "additionalProperties": 1,
+        "description": "Partial, possibly server generated, configuration properties.",
+        "optional": 1,
+        "properties": {
+          "encryption-key": {
+            "description": "The, possibly auto-generated, encryption-key.",
+            "optional": 1,
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "storage": {
+        "description": "The ID of the created storage.",
+        "type": "string"
+      },
+      "type": {
+        "description": "The type of the created storage.",
+        "enum": [
+          "btrfs",
+          "cephfs",
+          "cifs",
+          "dir",
+          "esxi",
+          "iscsi",
+          "iscsidirect",
+          "lvm",
+          "lvmthin",
+          "nfs",
+          "pbs",
+          "rbd",
+          "zfs",
+          "zfspool"
+        ],
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  "permissions": {
+    "check": [
+      "perm",
+      "/storage",
+      [
+        "Datastore.Allocate"
+      ]
+    ]
+  },
+  "requestSample": "curl -k -X PUT -H 'Authorization: PVEAPIToken=USER@REALM!TOKENID=SECRET' -H 'Content-Type: application/json' \\\n  -d '{}' 'https://PVE_HOST:8006/api2/json/storage/<storage>'"
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "delete_access_domains_realm",
+  "usageNotes": "Permanently removes an authentication realm (e.g. LDAP, AD, OpenID Connect) from Proxmox VE. The built-in 'pve' and 'pam' realms cannot be deleted. Existing users assigned to the deleted realm will lose the ability to authenticate — consider reassigning or removing those users first.",
+  "examples": [
+    {
+      "summary": "Delete an LDAP authentication domain named 'corp-ldap'",
+      "path_params": {
+        "realm": "corp-ldap"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the authentication realm configuration; any users bound to this realm will immediately be unable to log in.",
+  "tips": [
+    "List current realms with get_access_domains before deleting to confirm the target realm ID.",
+    "Built-in realms 'pve' and 'pam' are protected and cannot be deleted via this endpoint.",
+    "Audit users assigned to the realm (get_access_users) and reassign or disable them before deletion to avoid orphaned accounts.",
+    "The operation returns null synchronously — no UPID is issued; the realm is removed immediately."
+  ],
+  "relatedOperations": [
+    "get_access_domains",
+    "get_access_domains_realm",
+    "create_access_domains",
+    "update_access_domains_realm",
+    "get_access_users"
+  ]
+}

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

@@ -0,0 +1,27 @@
+{
+  "operationId": "delete_access_groups_groupid",
+  "usageNotes": "Use this to permanently remove a Proxmox access group that is no longer needed. The group must exist; deleting a non-existent group returns an error. Removing a group immediately revokes all ACL entries assigned to that group across all nodes and resources — member users lose any privileges they held solely through this group.",
+  "examples": [
+    {
+      "summary": "Delete the 'helpdesk' access group",
+      "path_params": {
+        "groupid": "helpdesk"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently deletes the group and removes all associated ACL assignments, which may immediately revoke resource access for every user who was a member of this group.",
+  "tips": [
+    "Check group membership and ACL assignments before deleting (use get_access_groups_groupid) to understand the access impact.",
+    "There is no soft-delete or recycle bin — deletion is immediate and irreversible.",
+    "API tokens with the Group.Allocate privilege on /access/groups can perform this operation."
+  ],
+  "relatedOperations": [
+    "get_access_groups_groupid",
+    "get_access_groups",
+    "post_access_groups",
+    "put_access_groups_groupid",
+    "get_access_acl",
+    "put_access_acl"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "delete_access_roles_roleid",
+  "usageNotes": "Use this to permanently remove a custom role from the Proxmox cluster. Built-in roles (e.g., Administrator, PVEAdmin, NoAccess) cannot be deleted and will return an error. Before deleting, verify the role is not assigned to any users or groups via ACLs, as deletion does not automatically revoke existing ACL entries referencing the role.",
+  "examples": [
+    {
+      "summary": "Delete a custom helpdesk role",
+      "path_params": {
+        "roleid": "HelpDesk-Readonly"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Permanently removes the role definition from the cluster; any ACL entries that still reference this roleid will become orphaned and may behave unexpectedly.",
+  "tips": [
+    "List existing roles first with GET /access/roles to confirm the roleid and that it is not a built-in role.",
+    "Audit ACLs with GET /access/acl before deleting to find and clean up any assignments that reference the role.",
+    "Requires Sys.Modify on /access — a privilege held by the built-in Administrator role but not PVEAdmin."
+  ],
+  "relatedOperations": [
+    "get_access_roles",
+    "get_access_roles_roleid",
+    "post_access_roles",
+    "put_access_roles_roleid",
+    "get_access_acl"
+  ]
+}

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

@@ -0,0 +1,28 @@
+{
+  "operationId": "delete_access_tfa_userid_id",
+  "usageNotes": "Use this to permanently remove a specific TFA entry (TOTP, WebAuthn, recovery codes, etc.) from a user account. A user can delete their own TFA entries; an admin with User.Modify permission can delete entries for any user. Note that API tokens cannot perform this operation — it requires a full user session (allowtoken: false), and the optional password field is required in some realm configurations as a confirmation safeguard.",
+  "examples": [
+    {
+      "summary": "Remove a TOTP entry from a local PVE user",
+      "path_params": {
+        "userid": "jsmith@pve",
+        "id": "totp-7a3c1b2e"
+      },
+      "params": {
+        "password": "CurrentP@ss1"
+      }
+    }
+  ],
+  "destructiveReason": "Permanently deletes the specified TFA entry; the user will no longer be challenged by that factor, and the entry cannot be recovered.",
+  "tips": [
+    "This endpoint cannot be called with an API token — authenticate as a full user session.",
+    "If the target user has only one TFA entry and the realm enforces MFA, removing it may lock the user out or force re-enrollment on next login.",
+    "Obtain the TFA entry id first via the corresponding GET /access/tfa/{userid} listing endpoint.",
+    "Admins with User.Modify can act on any user; non-admins are limited to their own account (self)."
+  ],
+  "relatedOperations": [
+    "get_access_tfa_userid",
+    "post_access_tfa_userid",
+    "put_access_tfa_userid_id"
+  ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "operationId": "delete_access_users_userid",
+  "usageNotes": "Permanently removes a user account from the Proxmox authentication realm. The caller must hold both `Realm.AllocateUser` on the target realm and `User.Modify` on any group the user belongs to — both checks must pass. Built-in accounts (e.g., `root@pam`) cannot be deleted.",
+  "examples": [
+    {
+      "summary": "Delete a local PAM user named jsmith",
+      "path_params": {
+        "userid": "jsmith@pam"
+      },
+      "params": {}
+    }
+  ],
+  "destructiveReason": "Immediately and permanently deletes the user account; all associated API tokens are also removed and any active sessions for that user will lose access.",
+  "tips": [
+    "The `userid` must be in `name@realm` format (e.g., `alice@pve`, `bob@pam`) — bare usernames are rejected.",
+    "Deleting a user does not remove files, VMs, or permissions assigned to that user ID; revoke or reassign those first.",
+    "API tokens belonging to the deleted user are also destroyed — ensure no automation depends on them before proceeding.",
+    "To temporarily disable access without deleting, use update_access_users_userid (PUT) and set `enable=0` instead."
+  ],
+  "relatedOperations": [
+    "get_access_users_userid",
+    "put_access_users_userid",
+    "post_access_users",
+    "get_access_users"
+  ]
+}