@bldg-7/proxmox-mcp 0.2.0 → 0.4.0

package/README.md

@@ -8,7 +8,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
 
-A comprehensive MCP server providing 55 tools for managing Proxmox Virtual Environment, including QEMU VMs and LXC containers.
+A comprehensive MCP server providing 143 tools for managing Proxmox Virtual Environment, including QEMU VMs and LXC containers.
 
 ## Credits & Background
 
@@ -23,20 +23,20 @@ This project is a TypeScript rewrite of [mcp-proxmox-server](https://github.com/
 - Giant switch statement (55 cases) → tool registry with handler/schema pairs
 
 **Quality**:
-- 0 tests → 373 tests (351 unit + 22 integration)
+- 0 tests → 405 tests (351 unit + 22 integration)
 - No input validation → Zod runtime validation on every tool call
 - Implicit error handling → structured MCP error responses with context
 - No permission checks → two-tier permission model (basic / elevated)
 
 **Developer Experience**:
 - `npx @bldg-7/proxmox-mcp` just works
-- All 55 tool descriptions exposed via MCP `ListTools`
+- All 143 tool descriptions exposed via MCP `ListTools`
 - Rate limiter middleware included
 - Pino structured logging instead of `console.log`
 
 ## Features
 
-- **55 comprehensive tools** for Proxmox management
+- **143 comprehensive tools** for Proxmox management
 - **Full TypeScript implementation** with strict type safety
 - **Support for both QEMU VMs and LXC containers**
 - **Secure authentication** (API token)
@@ -125,776 +125,28 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
 
 ## Available Tools
 
-### Node & Cluster Management (4 tools)
-
-#### `proxmox_get_nodes`
-List all Proxmox cluster nodes with their status and resources.
-
-**Parameters**: None
-
-**Example**:
-```json
-{}
-```
-
-#### `proxmox_get_node_status` 🔒
-Get detailed status information for a specific Proxmox node.
-
-**Parameters**:
-- `node` (string): Node name
-
-**Example**:
-```json
-{
-  "node": "pve1"
-}
-```
-
-#### `proxmox_get_cluster_status`
-Get overall cluster status including nodes and resource usage.
-
-**Parameters**: None
-
-**Example**:
-```json
-{}
-```
-
-#### `proxmox_get_next_vmid`
-Get the next available VM/Container ID number.
-
-**Parameters**: None
-
-**Example**:
-```json
-{}
-```
-
----
-
-### VM Query (3 tools)
-
-#### `proxmox_get_vms`
-List all virtual machines across the cluster with their status.
-
-**Parameters**:
-- `node` (string, optional): Filter by specific node
-- `type` (string, optional): Filter by type (`qemu` or `lxc`)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "type": "qemu"
-}
-```
-
-#### `proxmox_get_vm_status`
-Get detailed status information for a specific VM.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM/Container ID
-- `type` (string): VM type (`qemu` or `lxc`)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "type": "qemu"
-}
-```
-
-#### `proxmox_get_storage`
-List all storage pools and their usage across the cluster.
-
-**Parameters**:
-- `node` (string, optional): Filter by specific node
-
-**Example**:
-```json
-{
-  "node": "pve1"
-}
-```
-
----
-
-### VM Lifecycle (12 tools) 🔒
-
-All lifecycle operations require elevated permissions.
-
-#### `proxmox_start_lxc` 🔒
-Start an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100
-}
-```
-
-#### `proxmox_start_vm` 🔒
-Start a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101
-}
-```
-
-#### `proxmox_stop_lxc` 🔒
-Stop an LXC container (forceful).
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-
-#### `proxmox_stop_vm` 🔒
-Stop a QEMU virtual machine (forceful).
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-
-#### `proxmox_shutdown_lxc` 🔒
-Gracefully shutdown an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-
-#### `proxmox_shutdown_vm` 🔒
-Gracefully shutdown a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-
-#### `proxmox_reboot_lxc` 🔒
-Reboot an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-
-#### `proxmox_reboot_vm` 🔒
-Reboot a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-
-#### `proxmox_pause_vm` 🔒
-Pause a QEMU virtual machine (suspend to RAM).
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-
-#### `proxmox_resume_vm` 🔒
-Resume a paused QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-
-#### `proxmox_delete_lxc` 🔒
-Delete an LXC container permanently.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-
-#### `proxmox_delete_vm` 🔒
-Delete a QEMU virtual machine permanently.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-
----
-
-### VM Modify (4 tools) 🔒
-
-#### `proxmox_clone_lxc` 🔒
-Clone an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Source container ID
-- `newid` (number): New container ID
-- `hostname` (string, optional): New hostname
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "newid": 200,
-  "hostname": "cloned-container"
-}
-```
-
-#### `proxmox_clone_vm` 🔒
-Clone a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Source VM ID
-- `newid` (number): New VM ID
-- `name` (string, optional): New VM name
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "newid": 201,
-  "name": "cloned-vm"
-}
-```
-
-#### `proxmox_resize_lxc` 🔒
-Resize an LXC container CPU/memory.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `memory` (number, optional): Memory in MB
-- `cores` (number, optional): Number of CPU cores
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "memory": 2048,
-  "cores": 2
-}
-```
-
-#### `proxmox_resize_vm` 🔒
-Resize a QEMU VM CPU/memory.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `memory` (number, optional): Memory in MB
-- `cores` (number, optional): Number of CPU cores
-
----
-
-### Snapshots (8 tools)
-
-#### `proxmox_create_snapshot_lxc` 🔒
-Create a snapshot of an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `snapname` (string): Snapshot name
-- `description` (string, optional): Snapshot description
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "snapname": "before-update",
-  "description": "Snapshot before system update"
-}
-```
-
-#### `proxmox_create_snapshot_vm` 🔒
-Create a snapshot of a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `snapname` (string): Snapshot name
-- `description` (string, optional): Snapshot description
-
-#### `proxmox_list_snapshots_lxc`
-List all snapshots of an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100
-}
-```
-
-#### `proxmox_list_snapshots_vm`
-List all snapshots of a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-
-#### `proxmox_rollback_snapshot_lxc` 🔒
-Rollback an LXC container to a snapshot.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `snapname` (string): Snapshot name
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "snapname": "before-update"
-}
-```
-
-#### `proxmox_rollback_snapshot_vm` 🔒
-Rollback a QEMU virtual machine to a snapshot.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `snapname` (string): Snapshot name
-
-#### `proxmox_delete_snapshot_lxc` 🔒
-Delete a snapshot of an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `snapname` (string): Snapshot name
-
-#### `proxmox_delete_snapshot_vm` 🔒
-Delete a snapshot of a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `snapname` (string): Snapshot name
-
----
-
-### Backups (6 tools) 🔒
-
-All backup operations require elevated permissions.
-
-#### `proxmox_create_backup_lxc` 🔒
-Create a backup of an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `storage` (string, optional): Storage name (default: `local`)
-- `mode` (string, optional): Backup mode: `snapshot`, `suspend`, `stop` (default: `snapshot`)
-- `compress` (string, optional): Compression: `none`, `lzo`, `gzip`, `zstd` (default: `zstd`)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "storage": "backup-storage",
-  "mode": "snapshot",
-  "compress": "zstd"
-}
-```
-
-#### `proxmox_create_backup_vm` 🔒
-Create a backup of a QEMU virtual machine.
-
-**Parameters**: Same as `proxmox_create_backup_lxc`
-
-#### `proxmox_list_backups` 🔒
-List all backups on a storage.
-
-**Parameters**:
-- `node` (string): Node name
-- `storage` (string): Storage name
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "storage": "backup-storage"
-}
-```
-
-#### `proxmox_restore_backup_lxc` 🔒
-Restore an LXC container from backup.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): New container ID
-- `archive` (string): Backup archive path (e.g., `local:backup/vzdump-lxc-100-...`)
-- `storage` (string, optional): Target storage for restored container
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 300,
-  "archive": "local:backup/vzdump-lxc-100-2024_01_01-12_00_00.tar.zst",
-  "storage": "local-lvm"
-}
-```
-
-#### `proxmox_restore_backup_vm` 🔒
-Restore a QEMU virtual machine from backup.
-
-**Parameters**: Same as `proxmox_restore_backup_lxc`
-
-#### `proxmox_delete_backup` 🔒
-Delete a backup file from storage.
-
-**Parameters**:
-- `node` (string): Node name
-- `storage` (string): Storage name
-- `volume` (string): Volume ID (e.g., `local:backup/vzdump-lxc-100-...`)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "storage": "local",
-  "volume": "local:backup/vzdump-lxc-100-2024_01_01-12_00_00.tar.zst"
-}
-```
-
----
-
-### Disks (8 tools) 🔒
-
-All disk operations require elevated permissions.
-
-#### `proxmox_add_disk_vm` 🔒
-Add a new disk to a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `disk` (string): Disk ID (e.g., `scsi0`, `virtio0`, `sata0`, `ide0`)
-- `storage` (string): Storage name
-- `size` (string): Disk size (e.g., `10` for 10GB)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "disk": "scsi1",
-  "storage": "local-lvm",
-  "size": "50"
-}
-```
-
-#### `proxmox_add_mountpoint_lxc` 🔒
-Add a mount point to an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `mp` (string): Mount point ID (e.g., `mp0`, `mp1`)
-- `storage` (string): Storage name
-- `size` (string): Size (e.g., `10` for 10GB)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "mp": "mp0",
-  "storage": "local-lvm",
-  "size": "20"
-}
-```
-
-#### `proxmox_resize_disk_vm` 🔒
-Resize a QEMU VM disk (expansion only).
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `disk` (string): Disk ID
-- `size` (string): New size (e.g., `+10G` to add 10GB, or `50G` for absolute size)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "disk": "scsi0",
-  "size": "+20G"
-}
-```
-
-#### `proxmox_resize_disk_lxc` 🔒
-Resize an LXC container disk or mount point (expansion only).
-
-**Parameters**: Same as `proxmox_resize_disk_vm`
-
-#### `proxmox_remove_disk_vm` 🔒
-Remove a disk from a QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `disk` (string): Disk ID
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "disk": "scsi1"
-}
-```
-
-#### `proxmox_remove_mountpoint_lxc` 🔒
-Remove a mount point from an LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `mp` (string): Mount point ID
-
-#### `proxmox_move_disk_vm` 🔒
-Move a QEMU VM disk to different storage.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `disk` (string): Disk ID
-- `storage` (string): Target storage name
-- `delete` (boolean, optional): Delete source after move (default: `true`)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "disk": "scsi0",
-  "storage": "fast-ssd",
-  "delete": true
-}
-```
-
-#### `proxmox_move_disk_lxc` 🔒
-Move an LXC container disk to different storage.
-
-**Parameters**: Same as `proxmox_move_disk_vm`
-
----
-
-### Network (6 tools) 🔒
-
-All network operations require elevated permissions.
-
-#### `proxmox_add_network_vm` 🔒
-Add network interface to QEMU VM.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `net` (string): Network interface ID (e.g., `net0`, `net1`)
-- `bridge` (string): Bridge name (e.g., `vmbr0`)
-- `model` (string, optional): Network model: `virtio`, `e1000`, `rtl8139`, `vmxnet3`
-- `macaddr` (string, optional): MAC address
-- `tag` (number, optional): VLAN tag
-- `firewall` (boolean, optional): Enable firewall
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "net": "net1",
-  "bridge": "vmbr0",
-  "model": "virtio",
-  "tag": 100,
-  "firewall": true
-}
-```
-
-#### `proxmox_add_network_lxc` 🔒
-Add network interface to LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `net` (string): Network interface ID (e.g., `net0`, `net1`)
-- `bridge` (string): Bridge name
-- `ip` (string, optional): IP address with CIDR (e.g., `192.168.1.100/24`) or `dhcp`
-- `gw` (string, optional): Gateway IP
-- `firewall` (boolean, optional): Enable firewall
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "net": "net1",
-  "bridge": "vmbr0",
-  "ip": "192.168.1.100/24",
-  "gw": "192.168.1.1",
-  "firewall": true
-}
-```
-
-#### `proxmox_update_network_vm` 🔒
-Update/modify VM network interface configuration.
-
-**Parameters**: Same as `proxmox_add_network_vm` (updates existing interface)
-
-#### `proxmox_update_network_lxc` 🔒
-Update/modify LXC network interface configuration.
-
-**Parameters**: Same as `proxmox_add_network_lxc` (updates existing interface)
-
-#### `proxmox_remove_network_vm` 🔒
-Remove network interface from QEMU VM.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `net` (string): Network interface ID
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "net": "net1"
-}
-```
-
-#### `proxmox_remove_network_lxc` 🔒
-Remove network interface from LXC container.
-
-**Parameters**: Same as `proxmox_remove_network_vm`
-
----
-
-### Command Execution (1 tool) 🔒
-
-#### `proxmox_execute_vm_command` 🔒
-Execute a shell command on a virtual machine via Proxmox API.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM/Container ID
-- `type` (string): VM type (`qemu` or `lxc`)
-- `command` (string): Shell command to execute
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "type": "qemu",
-  "command": "uptime"
-}
-```
-
-**Note**: Command validation blocks potentially dangerous characters for security.
-
----
-
-### VM Creation (3 tools)
-
-#### `proxmox_list_templates`
-List available LXC container templates on a storage.
-
-**Parameters**:
-- `node` (string): Node name
-- `storage` (string): Storage name
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "storage": "local"
-}
-```
-
-#### `proxmox_create_lxc` 🔒
-Create a new LXC container.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): Container ID
-- `ostemplate` (string): Template path (e.g., `local:vztmpl/debian-12-standard_12.2-1_amd64.tar.gz`)
-- `hostname` (string): Container hostname
-- `password` (string, optional): Root password (auto-generated if not provided)
-- `memory` (number, optional): Memory in MB (default: 512)
-- `storage` (string, optional): Storage name (default: `local-lvm`)
-- `rootfs_size` (string, optional): Root filesystem size in GB (default: `8`)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 100,
-  "ostemplate": "local:vztmpl/debian-12-standard_12.2-1_amd64.tar.gz",
-  "hostname": "my-container",
-  "password": "SecurePassword123!",
-  "memory": 1024,
-  "storage": "local-lvm",
-  "rootfs_size": "16"
-}
-```
-
-#### `proxmox_create_vm` 🔒
-Create a new QEMU virtual machine.
-
-**Parameters**:
-- `node` (string): Node name
-- `vmid` (number): VM ID
-- `name` (string): VM name
-- `memory` (number, optional): Memory in MB (default: 512)
-- `cores` (number, optional): CPU cores (default: 1)
-- `sockets` (number, optional): CPU sockets (default: 1)
-- `disk_size` (string, optional): Disk size (e.g., `20G`) (default: `8G`)
-- `storage` (string, optional): Storage name (default: `local-lvm`)
-- `iso` (string, optional): ISO image path (e.g., `local:iso/debian-12.2-amd64-netinst.iso`)
-- `ostype` (string, optional): OS type (default: `l26` for Linux 2.6+)
-- `bridge` (string, optional): Network bridge (default: `vmbr0`)
-
-**Example**:
-```json
-{
-  "node": "pve1",
-  "vmid": 101,
-  "name": "my-vm",
-  "memory": 2048,
-  "cores": 2,
-  "sockets": 1,
-  "disk_size": "50G",
-  "storage": "local-lvm",
-  "iso": "local:iso/debian-12.2-amd64-netinst.iso",
-  "ostype": "l26",
-  "bridge": "vmbr0"
-}
-```
-
----
+This server provides **143 comprehensive tools** for Proxmox management:
+
+| Category | Tools | Permission |
+|----------|-------|------------|
+| Node & Cluster | 7 | Mixed |
+| Node Management | 8 | Mixed |
+| Cluster Management | 33 | Mixed |
+| Storage Management | 12 | Mixed |
+| VM Query | 5 | Basic |
+| VM Lifecycle | 12 | Elevated 🔒 |
+| VM Modify | 4 | Elevated 🔒 |
+| VM/LXC Advanced | 26 | Mixed |
+| Snapshots | 8 | Mixed |
+| Backups | 6 | Elevated 🔒 |
+| Disks | 8 | Elevated 🔒 |
+| VM/LXC Network | 6 | Elevated 🔒 |
+| Command Execution | 1 | Elevated 🔒 |
+| VM Creation | 3 | Mixed |
+| Node Disk Query | 4 | Basic |
+| **Total** | **143** | |
+
+📖 **[Full Tools Reference →](docs/TOOLS.md)**
 
 ## Error Handling