feat: Add multi-cluster support with JSON config

README.md

@@ -1,90 +1,96 @@
 # Custom Proxmox MCP Server
 
-A robust, maintenance-free Model Context Protocol (MCP) server for Proxmox VE, built with Python and `proxmoxer`.
+A robust, maintenance-free Model Context Protocol (MCP) server for Proxmox VE with **multi-cluster support**.
 
-## Philosophy: The Hybrid Approach
+## Features
 
-Most MCP servers suffer from "feature rot" where the author implements 10 tools (`start_vm`, `stop_vm`) but misses 500 others. This project takes a hybrid approach:
-
-1.  **Core Tools:** A small set of high-value tools for discovery and context.
-2.  **Raw API Access:** A single powerful tool `proxmox_api` that allows the LLM to call *any* Proxmox API endpoint dynamically. This ensures 100% API coverage without writing wrappers for every function.
+- **Multi-Cluster:** Manage multiple Proxmox clusters from a single container
+- **Hybrid Approach:** Curated high-level tools + raw API access for 100% coverage
+- **Zero Maintenance:** Raw API tool works with any Proxmox feature without code changes
 
 ## Tools
 
-### `list_nodes`
-Returns a list of all nodes in the cluster with their status.
+| Tool | Description |
+|------|-------------|
+| `list_clusters` | Lists all configured Proxmox clusters |
+| `list_nodes` | Lists nodes in a cluster |
+| `get_cluster_resources` | Gets VMs, LXCs, and storage summary |
+| `proxmox_api_call` | Execute any Proxmox API call directly |
 
-### `get_cluster_resources`
-Returns a summary of all resources (VMs, LXC containers, storage) across the cluster.
-
-### `proxmox_api_call`
-Executes a raw API call to Proxmox.
-*   `path`: API path (e.g., `nodes/pve1/qemu/100/status/start`).
-*   `method`: HTTP method (GET, POST, PUT, DELETE).
-*   `data`: Optional JSON payload for POST/PUT requests.
+All tools accept a `cluster` parameter. If only one cluster is configured, it's optional.
 
 ## Configuration
 
-Environment Variables:
+### 1. Create `clusters.json`
 
-| Variable | Required | Description | Example |
-|----------|----------|-------------|---------|
-| `PROXMOX_URL` | Yes | Proxmox host and port (no `https://`) | `pve.local.example.io:8006` |
-| `PROXMOX_USER` | Yes | Full `user@realm` format | `proxmox-mcp@pam` |
-| `PROXMOX_TOKEN_ID` | Yes* | Token name only (not full ID) | `token` |
-| `PROXMOX_PASSWORD` | Yes | Token secret or password | `xxxxxxxx-xxxx-...` |
-| `PROXMOX_VERIFY_SSL` | No | SSL verification (default: `false`) | `false` |
-| `MCP_ALLOWED_HOSTS` | No | Allowed Host headers for reverse proxy | `mcp.example.io,localhost:*` |
+```json
+{
+  "clusters": {
+    "production": {
+      "url": "pve-prod.example.io:8006",
+      "user": "mcp@pam",
+      "token_id": "token",
+      "token_secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      "verify_ssl": false
+    },
+    "homelab": {
+      "url": "pve-home.local:8006",
+      "user": "root@pam",
+      "token_id": "mcp",
+      "token_secret": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+      "verify_ssl": false
+    }
+  }
+}
+```
 
-> **Note:** If your full token is `proxmox-mcp@pam!mytoken`, set `PROXMOX_USER=proxmox-mcp@pam` and `PROXMOX_TOKEN_ID=mytoken`.
+> **Token Format:** If your full token is `user@pam!mytoken`, set `user: "user@pam"` and `token_id: "mytoken"`
 
-## Deployment
-
-### Docker Compose
+### 2. Deploy with Docker Compose
 
 ```yaml
 services:
   proxmox-mcp:
     image: gitea.ext.ben.io/b3nw/proxmox-mcp-custom:latest
     environment:
-      - PROXMOX_URL=pve.local.example.io:8006
-      - PROXMOX_USER=proxmox-mcp@pam
-      - PROXMOX_TOKEN_ID=token
-      - PROXMOX_PASSWORD=your-token-secret
-      - PROXMOX_VERIFY_SSL=false
       - MCP_ALLOWED_HOSTS=proxmox-mcp.example.io,localhost:*
+    volumes:
+      - ./clusters.json:/app/clusters.json:ro
     ports:
       - "8000:8000"
     restart: unless-stopped
 ```
 
-### MCP Client Configuration
+### 3. Connect MCP Client
 
-Connect via SSE endpoint: `https://your-host/sse`
+SSE endpoint: `https://your-host/sse`
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_ALLOWED_HOSTS` | `localhost:*,127.0.0.1:*` | Allowed Host headers |
+| `CLUSTERS_CONFIG_PATH` | `/app/clusters.json` | Path to clusters config |
 
 ## Local Development
 
 ```bash
 # Setup
-cp .env.example .env
-# Edit .env with your Proxmox credentials
+cp clusters.json.example clusters.json
+# Edit clusters.json with your credentials
 
 # Build and run
 make build
 make dev
 
 # Test
-make logs      # View container logs
-make test-sse  # Test SSE endpoint
-
-# Cleanup
+make logs
+make test-sse
 make stop
 ```
 
 ## Tech Stack
 
-*   **Language:** Python 3.11+
-*   **MCP SDK:** `mcp` with `FastMCP`
-*   **Proxmox Client:** `proxmoxer`
-*   **Transport:** SSE (Server-Sent Events)
-*   **Server:** `uvicorn` (ASGI)
+- Python 3.11+ / FastMCP / proxmoxer
+- SSE transport / uvicorn
+- Docker with multi-stage build