# Implementation Details

Technical documentation for the Proxmox MCP Server.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    MCP Client (Gemini CLI)              │
└─────────────────────────┬───────────────────────────────┘
                          │ SSE
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Docker Container (proxmox-mcp)             │
│  ┌───────────────────────────────────────────────────┐  │
│  │              FastMCP + uvicorn (:8000)            │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │                  ClusterManager                   │  │
│  │    ┌─────────┐  ┌─────────┐  ┌─────────┐         │  │
│  │    │ prod    │  │ homelab │  │  ...    │         │  │
│  │    └────┬────┘  └────┬────┘  └────┬────┘         │  │
│  └─────────┼────────────┼────────────┼──────────────┘  │
└────────────┼────────────┼────────────┼──────────────────┘
             │            │            │
             ▼            ▼            ▼
      ┌──────────┐  ┌──────────┐  ┌──────────┐
      │ Proxmox  │  │ Proxmox  │  │ Proxmox  │
      │ Cluster 1│  │ Cluster 2│  │ Cluster N│
      └──────────┘  └──────────┘  └──────────┘
```

## Components

### ClusterManager
- Loads cluster configs from `clusters.json`
- Maintains `ProxmoxAPI` connections for each cluster
- Handles cluster selection logic (default if single cluster)

### Transport Security
- `TransportSecuritySettings` validates Host headers
- Configurable via `MCP_ALLOWED_HOSTS`

### Tool Strategy

**Layer 1: Curated Tools**
- `list_clusters()` - Discovery
- `list_nodes(cluster)` - Node status
- `get_cluster_resources(cluster)` - Resource summary

**Layer 2: Raw Access**
- `proxmox_api_call(cluster, path, method, data)` - Any API endpoint

## Configuration Format

```json
{
  "clusters": {
    "<name>": {
      "url": "host:port",
      "user": "user@realm",
      "token_id": "token_name",
      "token_secret": "secret",
      "verify_ssl": false
    }
  }
}
```

### Token Authentication

The `proxmoxer` library uses:
```
Authorization: PVEAPIToken={user}!{token_id}={token_secret}
```

So for token `mcp@pam!mytoken`:
- `user` = `mcp@pam`
- `token_id` = `mytoken`

## Build & Deploy

- **Build:** `uv` + multi-stage Docker
- **Registry:** Gitea Container Registry
- **CI/CD:** Gitea Actions
- **Deploy:** Docker Compose / Portainer