docs: Clean up README and IMPLEMENTATION for end users

README.md

@@ -0,0 +1,90 @@
+# Custom Proxmox MCP Server
+
+A robust, maintenance-free Model Context Protocol (MCP) server for Proxmox VE, built with Python and `proxmoxer`.
+
+## Philosophy: The Hybrid Approach
+
+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.
+
+## Tools
+
+### `list_nodes`
+Returns a list of all nodes in the cluster with their status.
+
+### `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.
+
+## Configuration
+
+Environment Variables:
+
+| 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:*` |
+
+> **Note:** If your full token is `proxmox-mcp@pam!mytoken`, set `PROXMOX_USER=proxmox-mcp@pam` and `PROXMOX_TOKEN_ID=mytoken`.
+
+## Deployment
+
+### 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:*
+    ports:
+      - "8000:8000"
+    restart: unless-stopped
+```
+
+### MCP Client Configuration
+
+Connect via SSE endpoint: `https://your-host/sse`
+
+## Local Development
+
+```bash
+# Setup
+cp .env.example .env
+# Edit .env with your Proxmox credentials
+
+# Build and run
+make build
+make dev
+
+# Test
+make logs      # View container logs
+make test-sse  # Test SSE endpoint
+
+# Cleanup
+make stop
+```
+
+## Tech Stack
+
+*   **Language:** Python 3.11+
+*   **MCP SDK:** `mcp` with `FastMCP`
+*   **Proxmox Client:** `proxmoxer`
+*   **Transport:** SSE (Server-Sent Events)
+*   **Server:** `uvicorn` (ASGI)