# vCenter MCP Server

透過 reverse proxy（`apigw`）操作 VMware vCenter 8.0 REST API 的 MCP server。
以 **streamable-HTTP** transport 常駐於 Docker host,同時服務兩個 vCenter（DCS / Foreman）。

## 特性

- **Read / Write 權限分群**：read-only tools 一律提供;write tools（電源、CPU/記憶體修改）由 `VCENTER_ENABLE_WRITE` 控制,**預設關閉**（read 模式下這些 tool 根本不會出現在清單）。
- **寫入防護 dry-run**：所有 write tool 預設 `confirm=false`,只回報「將要做什麼」,需 `confirm=true` 才真正執行。
- **祕密不外洩**：帳密與 proxy URL 全部從環境變數讀取,不進程式碼、不進 LLM context。
- **token 自動管理**：session token（30 分鐘）由 server 快取與自動重取,client 完全不碰。

## 環境變數

| 變數 | 說明 |
|------|------|
| `VCENTER_DCS_BASE` | DCS vCenter proxy base URL |
| `VCENTER_FOREMAN_BASE` | Foreman vCenter proxy base URL |
| `VCENTER_USER` | vSphere 帳號（如 `administrator@vsphere.local`） |
| `VCENTER_PASSWORD` | 密碼 |
| `VCENTER_ENABLE_WRITE` | `true` 才註冊 write tools（預設 `false`） |
| `MCP_HOST` / `MCP_PORT` | 監聽位址(預設 `0.0.0.0:8000`) |

複製 `.env.example` 為 `.env` 並填入密碼（`.env` 已被 `.gitignore`）。

## Docker 部署（apigw / apigw）

容器部署在 `/opt/vcenter-mcp/`,**不對外開 port**,只接上 nginx(`vcenter-proxy`)的既有
docker network(`vcenter-proxy_default`),由 nginx 在 `/mcp` 加 basic auth 後反向代理。

> apigw 為封閉內網,build 需經內部 proxy 抓 base image 與 PyPI 套件。proxy 位址
> **不寫死在 repo**,部署前以環境變數帶入(見下方 `BUILD_HTTP_PROXY`)。
> base image 的 pull 走 docker daemon 既有 proxy(`/etc/systemd/system/docker.service.d/`)。

```bash
cp .env.example .env      # 填 VCENTER_PASSWORD;含 $ 要寫成 $$

# 封閉環境:build 前設定內部 proxy(位址問網管/見 docker daemon 設定)
export BUILD_HTTP_PROXY=http://<proxy-host>:<port>
export BUILD_HTTPS_PROXY=http://<proxy-host>:<port>

docker compose up -d --build
docker compose logs -f
```

### 與 nginx 的整合（重點:互不干擾）

- MCP 與 nginx 是**兩個獨立的 compose project**(`vcenter-mcp` / `vcenter-proxy`)。
  在 `/opt/vcenter-proxy` 下 `docker compose up -d` 只會動 nginx,**不會碰 MCP 容器**。
- nginx 設定:`/opt/vcenter-proxy/nginx/conf.d/vcenter.conf` 內 `location = /mcp`,
  basic auth 密碼檔 `/opt/vcenter-proxy/nginx/conf.d/.htpasswd-mcp`(帳號 `mcp`)。
- 改完 nginx 設定用 `docker exec vcenter-proxy nginx -t && nginx -s reload`(不重啟容器)。

## Client 連線（.mcp.json）

對外經 nginx 的 HTTPS + basic auth(注意 endpoint 是 `/mcp` 無尾斜線):

```json
{
  "mcpServers": {
    "vcenter": {
      "type": "http",
      "url": "https://apigw.example.com/mcp",
      "headers": {
        "Authorization": "Basic <base64(mcp:<密碼>)>"
      }
    }
  }
}
```

> `<密碼>` 為部署時產生的 basic auth 密碼。產生 header:`printf 'mcp:<密碼>' | base64`。

## Tools

每個 tool 都接受 `target`（`dcs` 預設 / `foreman`）。

### Read-only（18 個,一律啟用）

`list_vms`、`get_vm_detail`、`get_vm_power`、`get_vm_guest`、`list_clusters`、`list_hosts`、
`list_datastores`、`get_datastore_usage`、`list_networks`、`list_resource_pools`、
`list_datacenters`、`list_folders`、`list_tags`、`get_object_tags`、`get_appliance_health`、
`get_vcenter_version`、`get_resource_summary`、`get_vms_high_usage`

### Write（3 個,需 `VCENTER_ENABLE_WRITE=true`,全部 dry-run + confirm）

- `vm_power_action`：start / stop / reset / suspend
- `update_vm_cpu`：改 vCPU 核心數
- `update_vm_memory`：改記憶體（MiB）

> CPU/記憶體修改若 VM 開機且未啟用 hot-add,dry-run 會回 `warning` 提示需先關機。

## 已知限制（本環境 REST proxy）

| 功能 | 狀態 | 說明 |
|------|------|------|
| VM snapshot 清單 | ❌ 未提供 | `GET /api/vcenter/vm/{id}/snapshot` 在此 proxy 回 404,REST 不支援。 |
| Content Library template 清單 | ❌ 未提供 | `vm-template/library-items` 回 404。 |
| per-VM 時序效能 | ⚠️ 降級 | REST 僅提供 vCenter appliance 層級監控;per-VM CPU/mem **配置**可由 `get_vm_detail` / `get_vms_high_usage` 取得,但**即時利用率時序**需 pyVmomi,未實作。 |

## 本機開發

```bash
python3 -m venv .venv && .venv/bin/pip install -e .
set -a; source .env; set +a
.venv/bin/python -m vcenter_mcp.server
```

> 注意:本機若已有其他 MCP server 佔用 8000（如 google-workspace），請改 `MCP_PORT`。