PVE

供 Codex 與 Claude Code 使用的 Proxmox／gateway MCP plugin。從 zyx1121/plugin 的 utils 拆出，提供原有 16 個 PVE tools：

查詢、建立、啟動、停止與刪除 VM／LXC。
管理主機 port forwarding。
管理 gateway dnsmasq 的內部 DNS。
管理 Caddy 站點，包含 diff 預覽、驗證與 reload 失敗回復。

透過自然語言要求 agent 操作，例如「列出目前的 VM」或「查看 book-prod 狀態」。本 plugin 只有 MCP 與底層 scripts；工具 schema 是參數與操作語意的來源，不另維護一份 skill 工具手冊。FDE 可在部署流程中組合使用這些工具。

安裝與設定

請 agent 從 zyx1121/marketplace 安裝 pve@zyx1121。

# Claude Code
claude plugin marketplace add zyx1121/marketplace
claude plugin install pve@zyx1121

# Codex
codex plugin marketplace add zyx1121/marketplace
codex plugin add pve@zyx1121

需要 Bun 1.3.13+、uv、SSH，以及 Python 3.11+（uv 可管理）。 MCP 已打包，不需在安裝目錄執行 bun install； uv 在首次操作時依 scripts 的 PEP 723 宣告取得 Python 套件。

請 agent 依範例建立 ~/.config/pve/config.json（建議權限 0600），填入現有環境設定。也支援 XDG_CONFIG_HOME 與 PVE_CONFIG_PATH。SSH 主機、使用者及金鑰仍由 SSH config 管理；gateway 的 secrets 留在 gateway。Plugin 升級不覆寫 profile。

設定載入器的 FIELDS 定義環境變數對應； PVE_<suffix> 優先於舊的 UTILS_PVE_<suffix>，再優先於 profile。所有操作都使用同一份設定。缺少設定時回傳 setup 錯誤，不會使用某個私人網段。

操作範圍

保留原有 yes／confirm 參數。停止是強制斷電；刪除會連帶清理資源，工具描述會列出影響。安裝 plugin 不代表授權任意修改基礎設施。

DNS tools 只管理內部 dnsmasq，不會設定 Cloudflare 公網 DNS。 Provisioning 沿用既有單節點、IPv4 /24、VMID／SSH port 與 firewall group 慣例；這不是任意 Proxmox cluster 的通用管理套件。Profile 中的 template、 bridge、firewall group 與 gateway 服務必須先存在。

Caddy 操作沿用既有驗證、備份與 reload／rollback 實作。 MCP 呼叫有 120 秒期限；逾時後先查遠端狀態再決定是否重試，不代表遠端操作已回滾。正式環境的可用性操作仍依使用者指示執行。

從 zyx 遷移

安裝並驗證本 plugin 後，將 zyx 更新到移除 PVE 的版本。工具短名稱與參數保持相同；完整 MCP namespace 會由 plugin_zyx_utils 改為 plugin_pve_pve，依 host 顯示為準。引用完整名稱的權限設定、hooks 或消費端需一併調整。其餘 utils 工具繼續由 zyx 提供，不要同時另註冊同名 pve server。

維護

bun install --frozen-lockfile，接著 bun run check。測試在本機假 SSH／暫存檔案上驗證參數、confirmation、錯誤 contract 與 iptables persistence，不會改動真實 PVE。

Root plugin.json 與 mcp.json 是唯一 manifest 來源。Build 產生 Claude 相容格式和 dist；生成檔一起提交，CI 檢查是否過期。發佈使用獨立版本，marketplace 固定到 release commit。

原始 PVE script、schemas、必要 helper 與 persistence test 來自 zyx1121/plugin@06270b0，保留 MIT。本套件沒有對原 repo 的 runtime 依賴。