virtfusion-mcp/README.md

# VirtFusion MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that wraps the [VirtFusion](https://virtfusion.com) virtualization control panel API. This enables AI assistants like Claude to manage VirtFusion infrastructure through natural language.

## Features

- **84 tools** covering the entire VirtFusion Admin API
- Server lifecycle management (create, build, delete, suspend, unsuspend)
- Power control (boot, shutdown, restart, poweroff)
- Network management (IPv4, whitelist, firewall, traffic)
- User management with external relation ID support
- Self-service operations (credit, resource packs, hourly profiles)
- Infrastructure management (hypervisors, IP blocks, packages, DNS)
- Backup and media management
- SSH key management
- Automatic API endpoint drift detection

## Prerequisites

- **Node.js** 22 or later
- **VirtFusion** panel with Admin API access
- An API token generated from your VirtFusion admin panel

## Installation

### From source

```bash
git clone https://git.ezscale.cloud/EZSCALE/virtfusion-mcp.git
cd virtfusion-mcp
npm install
npm run build
```

## Configuration

The server requires two environment variables:

| Variable | Description | Example |
|---|---|---|
| `VIRTFUSION_API_URL` | Base URL of your VirtFusion API | `https://cp.example.com/api/v1` |
| `VIRTFUSION_API_TOKEN` | Admin API bearer token | `your-api-token-here` |

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "virtfusion": {
      "command": "node",
      "args": ["/path/to/virtfusion-mcp/dist/index.js"],
      "env": {
        "VIRTFUSION_API_URL": "https://cp.example.com/api/v1",
        "VIRTFUSION_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add virtfusion -- node /path/to/virtfusion-mcp/dist/index.js \
  -e VIRTFUSION_API_URL=https://cp.example.com/api/v1 \
  -e VIRTFUSION_API_TOKEN=your-api-token
```

### VS Code / Cursor

Add to your `.vscode/mcp.json`:

```json
{
  "servers": {
    "virtfusion": {
      "command": "node",
      "args": ["/path/to/virtfusion-mcp/dist/index.js"],
      "env": {
        "VIRTFUSION_API_URL": "https://cp.example.com/api/v1",
        "VIRTFUSION_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

## Tool Reference

### General (1 tool)

| Tool | Description |
|---|---|
| `general_test_connection` | Test the API connection to VirtFusion |

### Servers (18 tools)

| Tool | Description |
|---|---|
| `servers_list` | List all servers with optional filtering |
| `servers_create` | Create a new server |
| `servers_get` | Retrieve details of a specific server |
| `servers_delete` | Delete a server |
| `servers_build` | Build/rebuild a server with an OS template |
| `servers_list_templates` | List OS templates available for a server |
| `servers_modify_name` | Change a server's display name |
| `servers_modify_cpu` | Modify CPU cores for a server |
| `servers_modify_memory` | Modify memory allocation for a server |
| `servers_throttle_cpu` | Throttle a server's CPU |
| `servers_get_traffic` | Retrieve traffic statistics |
| `servers_suspend` | Suspend a server |
| `servers_unsuspend` | Unsuspend a server |
| `servers_reset_password` | Reset a server's root/admin password |
| `servers_enable_vnc` | Enable or disable VNC |
| `servers_get_vnc` | Retrieve VNC connection details |
| `servers_set_custom_xml` | Set custom XML configuration |
| `servers_change_owner` | Change the owner of a server |
| `servers_change_package` | Change a server's package |
| `servers_set_backup_plan` | Set a server's backup plan |
| `servers_list_by_user` | List servers owned by a user |

### Servers — Power (4 tools)

| Tool | Description |
|---|---|
| `servers_power_boot` | Boot a server |
| `servers_power_shutdown` | Gracefully shutdown a server |
| `servers_power_restart` | Restart a server |
| `servers_power_poweroff` | Force power off a server |

### Servers — Network (5 tools)

| Tool | Description |
|---|---|
| `servers_network_whitelist_add` | Add an IP to a server's network whitelist |
| `servers_network_whitelist_remove` | Remove an IP from a server's whitelist |
| `servers_network_ipv4_add` | Add specific IPv4 addresses |
| `servers_network_ipv4_remove` | Remove IPv4 addresses |
| `servers_network_ipv4_add_qty` | Add a quantity of IPv4 addresses |

### Servers — Firewall (4 tools)

| Tool | Description |
|---|---|
| `servers_firewall_get` | Retrieve firewall configuration |
| `servers_firewall_enable` | Enable the firewall |
| `servers_firewall_disable` | Disable the firewall |
| `servers_firewall_set_rules` | Apply firewall rulesets |

### Servers — Traffic (4 tools)

| Tool | Description |
|---|---|
| `servers_traffic_list_blocks` | List traffic blocks |
| `servers_traffic_add_block` | Add a traffic block |
| `servers_traffic_remove_block` | Remove a traffic block |
| `servers_traffic_modify` | Modify primary traffic allowance |

### Hypervisors (2 tools)

| Tool | Description |
|---|---|
| `hypervisors_list` | List all hypervisors |
| `hypervisors_get` | Retrieve hypervisor details |

### Hypervisor Groups (3 tools)

| Tool | Description |
|---|---|
| `hypervisor_groups_list` | List all hypervisor groups |
| `hypervisor_groups_get` | Retrieve group details |
| `hypervisor_groups_get_resources` | Retrieve group resources |

### IP Blocks (3 tools)

| Tool | Description |
|---|---|
| `ip_blocks_list` | List all IP blocks |
| `ip_blocks_get` | Retrieve IP block details |
| `ip_blocks_add_ipv4_range` | Add an IPv4 range to a block |

### Packages (2 tools)

| Tool | Description |
|---|---|
| `packages_list` | List all packages |
| `packages_get` | Retrieve package details |

### Queue (1 tool)

| Tool | Description |
|---|---|
| `queue_get` | Retrieve queue item status |

### Backups (1 tool)

| Tool | Description |
|---|---|
| `backups_list_by_server` | List backups for a server |

### DNS (1 tool)

| Tool | Description |
|---|---|
| `dns_get_service` | Retrieve a DNS service |

### Media (2 tools)

| Tool | Description |
|---|---|
| `media_get_iso` | Retrieve ISO image details |
| `media_get_templates_by_package` | List OS templates for a package |

### SSH Keys (4 tools)

| Tool | Description |
|---|---|
| `ssh_keys_create` | Add an SSH key to a user |
| `ssh_keys_get` | Retrieve SSH key details |
| `ssh_keys_delete` | Delete an SSH key |
| `ssh_keys_list_by_user` | List SSH keys for a user |

### Users (7 tools)

| Tool | Description |
|---|---|
| `users_create` | Create a new user |
| `users_get` | Retrieve a user by external relation ID |
| `users_modify` | Modify a user |
| `users_delete` | Delete a user |
| `users_reset_password` | Reset a user's password |
| `users_generate_auth_tokens` | Generate login tokens |
| `users_generate_server_auth_tokens` | Generate server-scoped login tokens |

### Self Service (19 tools)

| Tool | Description |
|---|---|
| `self_service_add_credit` | Add credit to a user |
| `self_service_cancel_credit` | Cancel applied credit |
| `self_service_get_currencies` | Retrieve available currencies |
| `self_service_add_hourly_group_profile` | Add hourly group profile to user |
| `self_service_remove_hourly_group_profile` | Remove hourly group profile |
| `self_service_add_resource_group_profile` | Add resource group profile |
| `self_service_remove_resource_group_profile` | Remove resource group profile |
| `self_service_add_resource_pack` | Add resource pack to user |
| `self_service_get_resource_pack` | Retrieve a resource pack |
| `self_service_modify_resource_pack` | Modify a resource pack |
| `self_service_delete_resource_pack` | Delete a resource pack |
| `self_service_get_hourly_stats` | Retrieve hourly statistics |
| `self_service_set_hourly_resource_pack` | Set hourly resource pack |
| `self_service_modify_access` | Modify self-service access |
| `self_service_get_report` | Generate a user report |
| `self_service_get_usage` | Retrieve user usage data |
| `self_service_delete_pack_servers` | Delete all servers in a pack |
| `self_service_suspend_pack_servers` | Suspend all servers in a pack |
| `self_service_unsuspend_pack_servers` | Unsuspend all servers in a pack |

## Development

### Build

```bash
npm run build
```

### Run in development mode

```bash
VIRTFUSION_API_URL=https://cp.example.com/api/v1 \
VIRTFUSION_API_TOKEN=your-token \
npm run dev
```

### API Endpoint Sync

This project includes tooling to detect when VirtFusion adds new API endpoints:

```bash
# Extract endpoints from the current OpenAPI spec
npm run extract-endpoints > endpoint-manifest.json

# Check for drift between spec and manifest
npm run check-endpoint-drift
```

The `endpoint-sync` workflow runs weekly and on any changes to `openapi.yaml`, creating an issue if drift is detected.

#### Adding new tools when VirtFusion updates their API

1. Download the updated `openapi.yaml` from VirtFusion docs
2. Run `npm run check-endpoint-drift` to see what changed
3. Implement new tools in the appropriate `src/tools/*.ts` module
4. Update the manifest: `npm run extract-endpoints > endpoint-manifest.json`
5. Commit everything together

## License

MIT — see [LICENSE](LICENSE)