Ben
4b576d40ad
All checks were successful
Build and Push Proxmox MCP Docker Image / build (push) Successful in 8s
87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
# 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
|