@aidalinfo/proxmox-mcp 1.0.1 → 1.1.0

package/README.md

@@ -3,7 +3,7 @@
 MCP server for a Proxmox VE cluster, with two modes:
 
 - **`readonly`** (default) — only read tools are exposed.
-- **`full`** — read tools **plus** write tools (VM/LXC lifecycle, snapshots, migrate).
+- **`full`** — read tools **plus** write tools (VM/LXC lifecycle, snapshots, migrate, typed VM provisioning).
 
 In `readonly` mode the write tools are never registered, so the model cannot call them.
 
@@ -14,7 +14,64 @@ In `readonly` mode the write tools are never registered, so the model cannot cal
 `pve_container_info`, `pve_storage`, `pve_storage_content`, `pve_tasks`, `pve_raw_get`.
 
 **Write (`full` only):** `pve_vm_action`, `pve_lxc_action`, `pve_snapshot_create`,
-`pve_snapshot_delete`, `pve_snapshot_rollback`, `pve_migrate`.
+`pve_snapshot_delete`, `pve_snapshot_rollback`, `pve_migrate`, `pve_vm_create`, `pve_vm_configure`,
+`pve_vm_delete`.
+
+## VM provisioning (`full` only)
+
+Three typed tools let an internal operation, for example the Bot Factory, provision a QEMU VM. None of them
+takes an HTTP method, a raw API path or free Proxmox parameters. Every field is typed, bounded and mapped
+by the tool, and unknown properties are refused (strict schemas). There is no generic raw
+`POST`/`PUT`/`DELETE`. Approval stays in Pulse Chat.
+
+| Tool | API | Checks before | Verified after |
+|---|---|---|---|
+| `pve_vm_create` | `POST /nodes/{sourceNode}/qemu/{templateVmid}/clone` | the source is a **template**; the target node exists and is online; the VMID is **free cluster-wide** (never overwrites) | the clone task ends OK; the new VM exists on the target node with the requested name |
+| `pve_vm_configure` | `PUT /nodes/{node}/qemu/{vmid}/config` | exact `expectedName`; not a template, not locked | every key sent is read back; reports changes still pending on a running VM |
+| `pve_vm_delete` (`destructiveHint`) | `DELETE /nodes/{node}/qemu/{vmid}` | exact `expectedName`; VM **stopped** (it is never stopped automatically); not a template, locked or protected; HA-managed only with `purge` | the destroy task ends OK; the VMID no longer exists anywhere in the cluster |
+
+`pve_vm_create` takes:
+
+- `sourceNode`, `templateVmid`, `targetNode`, `vmid` (100 to 999 999 999) and `name` (a DNS name);
+- `fullClone` (default `true`);
+- optionally `storage` (full clone only), `pool` and `description`.
+
+`pve_vm_configure` sends **only the delta**. A VM that already matches gets a no-op and nothing is sent. Allowed
+`changes`:
+
+| Field | Proxmox key | Bounds |
+|---|---|---|
+| `name` | `name` | DNS name |
+| `cores`, `sockets` | `cores`, `sockets` | 1–128, 1–8 |
+| `memoryMiB` | `memory` | 256 MiB – 1 TiB |
+| `cpuType` | `cpu` | `host`, `max`, `kvm64`, `qemu64`, `x86-64-v2`, `x86-64-v2-AES`, `x86-64-v3`, `x86-64-v4` |
+| `onboot`, `agent` | `onboot`, `agent` | booleans |
+| `description`, `tags` | `description`, `tags` | 8 KiB without control characters; 20 lowercase tags |
+| `ipConfig0` | `ipconfig0` | `{ ip: "dhcp" \| CIDR, gw?, ip6: "dhcp" \| "auto" \| CIDR, gw6? }` |
+| `nameservers`, `searchDomains` | `nameserver`, `searchdomain` | ≤ 3 IPs, ≤ 6 domain names |
+| `sshPublicKeys` | `sshkeys` | ≤ 10 OpenSSH public keys; replaces the list; only the key type and the last characters are shown back |
+
+The following are **not configurable**: `args`, hardware passthrough, disks, network devices, and any other
+Proxmox key. Creating a VM from an ISO, importing or resizing a disk, LXC containers, ACLs, pools and nodes are
+out of scope too.
+
+**Tasks are awaited.** Every UPID is validated, and its node is read from the UPID itself. The tool then polls
+`GET /nodes/{taskNode}/tasks/{encodedUpid}/status` until the task stops.
+
+- Only `exitstatus === "OK"` counts as a success.
+- The wait is bounded: 30 min for a clone, 10 min for a delete, 2 min for a configuration.
+- On a failure or a timeout, the tool returns the UPID and the last status. A timed-out task may still finish,
+  so check `pve_tasks` before retrying.
+- No success is announced before the resource has been read back.
+
+Path segments and UPIDs are always percent-encoded, and the token never appears in an error message.
+
+The API token needs these privileges:
+
+- `VM.Clone` on the template;
+- `VM.Allocate`, `Datastore.AllocateSpace` and `VM.Config.*` on the target;
+- `VM.Allocate` to delete;
+- `Pool.Allocate` when `pool` is used.
 
 ## Environment
 

package/dist/__tests__/mode-gating.test.js

@@ -2,7 +2,7 @@ import { describe, it, expect } from "@jest/globals";
 import { registerTools, parseMode } from "../register.js";
 function fakeServer() {
     const names = [];
-    const server = { tool: (name) => { names.push(name); } };
+    const server = { tool: (name) => { names.push(name); }, registerTool: (name) => { names.push(name); } };
     return { server, names };
 }
 const fakeClient = {};
@@ -21,6 +21,8 @@ describe("registerTools mode gating", () => {
         expect(names).not.toContain("pve_vm_action");
         expect(names).not.toContain("pve_snapshot_create");
         expect(names).not.toContain("pve_migrate");
+        for (const t of ["pve_vm_create", "pve_vm_configure", "pve_vm_delete"])
+            expect(names).not.toContain(t);
     });
     it("full registers read AND write tools", () => {
         const { server, names } = fakeServer();
@@ -32,5 +34,7 @@ describe("registerTools mode gating", () => {
         expect(names).toContain("pve_snapshot_delete");
         expect(names).toContain("pve_snapshot_rollback");
         expect(names).toContain("pve_migrate");
+        for (const t of ["pve_vm_create", "pve_vm_configure", "pve_vm_delete"])
+            expect(names).toContain(t);
     });
 });

package/dist/__tests__/vm-management.test.js

@@ -0,0 +1,268 @@
+import { describe, it, expect } from "@jest/globals";
+import { z } from "zod";
+import { registerTools } from "../register.js";
+import { ProxmoxClient, parseUpid, waitForTask, seg } from "../proxmox-client.js";
+import { toConfig, delta, changesSchema } from "../tools/vm-management.js";
+const SECRET = "11111111-2222-3333-4444-555555555555";
+const KEY = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICdITSnEqbi1VNk1AE1DZ4t3RRUwENyJ2Vb4omm0iZ1c bot@factory";
+const upidOf = (node, type, id) => `UPID:${node}:0000A1B2:0001C3D4:6720F00D:${type}:${id}:root@pam!bot:`;
+/** Stateful fake Proxmox: VMs, clone/config/delete, tasks that run for `taskPolls` polls. */
+function world(opts = {}) {
+    const vms = new Map([
+        [9000, { node: "pve1", config: { name: "tpl-debian12", template: 1, cores: 2, memory: 2048 }, status: "stopped" }],
+        [101, { node: "pve1", config: { name: "app-01", cores: 2, memory: 4096, agent: "1", tags: "prod;web" }, status: "running" }],
+        [102, { node: "pve2", config: { name: "old-vm", cores: 1, memory: 1024 }, status: "stopped" }],
+    ]);
+    const tasks = new Map();
+    const calls = [];
+    const nodes = [{ node: "pve1", status: "online" }, { node: "pve2", status: "online" }, { node: "pve3", status: "offline" }];
+    const startTask = (upid, after) => {
+        tasks.set(upid, { polls: opts.taskPolls ?? 2, after, exit: opts.failTask ?? "OK" });
+        return upid;
+    };
+    const json = (data, status = 200) => ({ ok: status < 300, status, text: async () => JSON.stringify(status < 300 ? { data } : { errors: data }) });
+    const fetcher = async (url, init) => {
+        const u = new URL(url);
+        const path = u.pathname.replace(/^\/api2\/json/, "");
+        const body = init.body ? new URLSearchParams(init.body) : undefined;
+        calls.push({ method: init.method, path, body, query: u.searchParams, headers: init.headers });
+        const m = (re) => path.match(re);
+        let r;
+        if (init.method === "GET" && path === "/nodes")
+            return json(nodes);
+        if (init.method === "GET" && path === "/cluster/resources")
+            return json([...vms].map(([id, v]) => ({ vmid: id, node: v.node, type: "qemu", name: v.config.name })));
+        if ((r = m(/^\/nodes\/([^/]+)\/tasks\/([^/]+)\/status$/))) {
+            const upid = decodeURIComponent(r[2]);
+            const t = tasks.get(upid);
+            if (!t)
+                return json("no such task", 404);
+            if (opts.malformed)
+                return json({ weird: true });
+            if (opts.neverEnds || t.polls-- > 0)
+                return json({ status: "running" });
+            if (t.exit === "OK")
+                t.after();
+            return json({ status: "stopped", exitstatus: t.exit });
+        }
+        if ((r = m(/^\/nodes\/([^/]+)\/qemu\/(\d+)(\/.*)?$/))) {
+            const [n, id, rest = ""] = [r[1], Number(r[2]), r[3]];
+            const vm = vms.get(id);
+            if (!vm || vm.node !== n)
+                return json(`Configuration file 'nodes/${n}/qemu-server/${id}.conf' does not exist`, 500);
+            if (init.method === "GET" && rest === "/config")
+                return json(vm.config);
+            if (init.method === "GET" && rest === "/status/current")
+                return json({ status: vm.status, ...(vm.ha ? { ha: { managed: 1 } } : {}) });
+            if (init.method === "GET" && rest === "/pending")
+                return json(Object.entries(vm.config).map(([key, value]) => ({ key, value, ...(key === "memory" && vm.status === "running" ? { pending: value } : {}) })));
+            if (init.method === "POST" && rest === "/clone") {
+                const newid = Number(body.get("newid"));
+                return json(startTask(upidOf(n, "qmclone", id), () => vms.set(newid, { node: body.get("target"), status: "stopped", config: { ...vm.config, name: body.get("name"), template: 0, ...(body.get("description") ? { description: body.get("description") } : {}) } })));
+            }
+            if (init.method === "PUT" && rest === "/config") {
+                const apply = () => {
+                    for (const [k, v] of body)
+                        if (k !== opts.dropChange)
+                            vm.config[k] = v;
+                };
+                if (opts.putReturnsUpid)
+                    return json(startTask(upidOf(n, "qmconfig", id), apply));
+                apply();
+                return json(null);
+            }
+            if (init.method === "DELETE" && rest === "")
+                return json(startTask(upidOf(n, "qmdestroy", id), () => vms.delete(id)));
+        }
+        return json(`no route ${init.method} ${path}`, 501);
+    };
+    const pve = new ProxmoxClient({ host: "https://pve.test:8006", tokenId: "root@pam!bot", tokenSecret: SECRET }, fetcher);
+    const tools = new Map();
+    const server = {
+        tool: () => { },
+        registerTool: (name, def, handler) => tools.set(name, { schema: def.inputSchema, def, handler }),
+    };
+    let clock = 0;
+    registerTools(server, pve, "full", { wait: { sleep: async (ms) => void (clock += ms), now: () => clock, intervalMs: 1000 } });
+    /** Parses like the SDK would (strict schema), then calls. */
+    const call = async (name, args) => {
+        const t = tools.get(name);
+        const parsed = t.schema.safeParse(args);
+        if (!parsed.success)
+            return { text: `INVALID: ${parsed.error.issues.map((i) => i.message).join("; ")}`, isError: true };
+        const r = await t.handler(parsed.data);
+        return { text: r.content[0].text, isError: r.isError === true };
+    };
+    return { vms, calls, call, tools, pve };
+}
+describe("client", () => {
+    it("PUT and DELETE: form body for PUT, query for DELETE, { data } envelope unwrapped", async () => {
+        const seen = [];
+        const pve = new ProxmoxClient({ host: "https://pve:8006", tokenId: "t@pam!x", tokenSecret: SECRET }, async (url, init) => {
+            seen.push({ url, ...init });
+            return { ok: true, status: 200, text: async () => JSON.stringify({ data: "UPID:x" }) };
+        });
+        expect(await pve.put("/nodes/n/qemu/1/config", { cores: 2, name: "a b", skip: undefined })).toBe("UPID:x");
+        expect(seen[0]).toMatchObject({ method: "PUT", body: "cores=2&name=a+b" });
+        expect(seen[0].headers["Content-Type"]).toBe("application/x-www-form-urlencoded");
+        await pve.del("/nodes/n/qemu/1", { purge: 1 });
+        expect(seen[1].url).toBe("https://pve:8006/api2/json/nodes/n/qemu/1?purge=1");
+        expect(seen[1].body).toBeUndefined();
+    });
+    it("errors never carry the token, even when the server echoes it", async () => {
+        const pve = new ProxmoxClient({ host: "https://pve:8006", tokenId: "t@pam!x", tokenSecret: SECRET }, async (_u, init) => ({ ok: false, status: 401, text: async () => `bad header ${init.headers.Authorization}` }));
+        const err = (await pve.get("/nodes").catch((e) => e));
+        expect(err.message).toMatch(/401/);
+        expect(err.message).not.toContain(SECRET);
+    });
+    it("UPID: parsed, node extracted, encoded in the status path; malformed ones refused", () => {
+        const u = upidOf("pve2", "qmclone", 9000);
+        expect(parseUpid(u)).toEqual({ upid: u, node: "pve2" });
+        expect(seg(u)).not.toContain(":");
+        for (const bad of ["UPID:../x:1:2:3:t:i:u:", "nope", 42, null, "UPID:pve1:0000A1B2:0001C3D4:6720F00D:qmclone:9000:root@pam!bot", `${u}/../..`])
+            expect(() => parseUpid(bad)).toThrow(/Malformed/);
+    });
+});
+describe("waitForTask", () => {
+    it("running → stopped/OK; error exit; timeout; malformed status", async () => {
+        const t = world({ taskPolls: 2 });
+        const r = await t.call("pve_vm_create", { sourceNode: "pve1", templateVmid: 9000, targetNode: "pve2", vmid: 200, name: "bot-01" });
+        expect(r.isError).toBe(false);
+        const statusCalls = t.calls.filter((c) => c.path.includes("/tasks/"));
+        expect(statusCalls.length).toBe(3);
+        expect(statusCalls[0].path).toBe(`/nodes/pve1/tasks/${encodeURIComponent(upidOf("pve1", "qmclone", 9000))}/status`);
+        const failed = await world({ failTask: "clone failed: storage full" }).call("pve_vm_create", { sourceNode: "pve1", templateVmid: 9000, targetNode: "pve2", vmid: 200, name: "bot-01" });
+        expect(failed.text).toMatch(/Task failed: clone failed: storage full — task UPID:pve1:.*last status: stopped \/ clone failed/);
+        const slow = await world({ neverEnds: true }).call("pve_vm_delete", { node: "pve2", vmid: 102, expectedName: "old-vm" });
+        expect(slow.text).toMatch(/still running after 600s — it may still complete; check pve_tasks/);
+        const odd = await world({ malformed: true }).call("pve_vm_delete", { node: "pve2", vmid: 102, expectedName: "old-vm" });
+        expect(odd.text).toMatch(/Malformed task status/);
+        await expect(waitForTask(t.pve, "garbage", { timeoutMs: 1 })).rejects.toThrow(/Malformed task id/);
+    });
+});
+describe("pve_vm_create", () => {
+    const base = { sourceNode: "pve1", templateVmid: 9000, targetNode: "pve2", vmid: 200, name: "bot-01" };
+    it("clones a template, waits for the task and verifies the new VM", async () => {
+        const w = world();
+        const r = await w.call("pve_vm_create", { ...base, storage: "local-lvm", pool: "bots", description: "Bot Factory" });
+        expect(r.isError).toBe(false);
+        expect(r.text).toMatch(/VM 200 "bot-01" created on pve2/);
+        expect(r.text).toMatch(/full clone to local-lvm · pool bots/);
+        const clone = w.calls.find((c) => c.method === "POST");
+        expect(clone.path).toBe("/nodes/pve1/qemu/9000/clone");
+        expect(Object.fromEntries(clone.body)).toEqual({ newid: "200", name: "bot-01", target: "pve2", full: "1", storage: "local-lvm", pool: "bots", description: "Bot Factory" });
+        expect(w.vms.get(200)?.node).toBe("pve2");
+    });
+    it("refuses a non-template source, a used VMID, an unknown or offline node — without any write", async () => {
+        for (const [args, msg] of [
+            [{ ...base, templateVmid: 101 }, /not a template/],
+            [{ ...base, vmid: 102 }, /VMID 102 is already used .*old-vm.*refusing to overwrite/],
+            [{ ...base, targetNode: "pve9" }, /not in the cluster/],
+            [{ ...base, targetNode: "pve3" }, /is offline/],
+            [{ ...base, templateVmid: 9999 }, /Template 9999 not found/],
+            [{ ...base, fullClone: false, storage: "local-lvm" }, /storage only applies to a full clone/],
+        ]) {
+            const w = world();
+            const r = await w.call("pve_vm_create", args);
+            expect(r.isError).toBe(true);
+            expect(r.text).toMatch(msg);
+            expect(w.calls.filter((c) => c.method !== "GET")).toEqual([]);
+        }
+    });
+    it("strict schema: unknown properties, bad VMIDs and names are rejected", async () => {
+        const w = world();
+        for (const args of [
+            { ...base, args: "-cpu host" },
+            { ...base, vmid: 99 },
+            { ...base, vmid: 1.5 },
+            { ...base, name: "bot_01;rm" },
+            { ...base, name: "-bot" },
+            { ...base, sourceNode: "../etc" },
+            { ...base, storage: "local lvm" },
+        ]) {
+            const r = await w.call("pve_vm_create", args);
+            expect(r.text).toMatch(/^INVALID/);
+        }
+        expect(w.calls).toEqual([]);
+    });
+});
+describe("pve_vm_configure", () => {
+    it("sends only the delta, verifies it, reports pending changes on a running VM; SSH keys never fully echoed", async () => {
+        const w = world();
+        const r = await w.call("pve_vm_configure", {
+            node: "pve1",
+            vmid: 101,
+            expectedName: "app-01",
+            changes: { cores: 2, memoryMiB: 8192, agent: true, tags: ["web", "prod"], ipConfig0: { ip: "10.0.0.20/24", gw: "10.0.0.1" }, nameservers: ["1.1.1.1"], sshPublicKeys: [KEY] },
+        });
+        expect(r.isError).toBe(false);
+        const put = w.calls.find((c) => c.method === "PUT");
+        expect([...put.body.keys()].sort()).toEqual(["ipconfig0", "memory", "nameserver", "sshkeys"]);
+        expect(put.body.get("ipconfig0")).toBe("ip=10.0.0.20/24,gw=10.0.0.1");
+        expect(decodeURIComponent(put.body.get("sshkeys"))).toBe(KEY + "\n");
+        expect(r.text).toMatch(/unchanged \(not sent\): cores, agent, tags/);
+        expect(r.text).toMatch(/memory apply at the next reboot \(pending\)/);
+        expect(r.text).toMatch(/sshkeys: 1 key\(s\): ssh-ed25519 …/);
+        expect(r.text).not.toContain("AAAAC3NzaC1lZDI1NTE5AAAAICdITSnEqbi1VNk1AE1DZ4t3RRUwENyJ2Vb4omm0iZ1c");
+    });
+    it("already conforming → no-op, nothing sent", async () => {
+        const w = world();
+        const r = await w.call("pve_vm_configure", { node: "pve1", vmid: 101, expectedName: "app-01", changes: { cores: 2, agent: true, tags: ["prod", "web"], onboot: false } });
+        expect(r.text).toMatch(/^No-op/);
+        expect(w.calls.some((c) => c.method === "PUT")).toBe(false);
+    });
+    it("wrong expectedName, template, empty or non-allowlisted changes are refused", async () => {
+        const w = world();
+        expect((await w.call("pve_vm_configure", { node: "pve1", vmid: 101, expectedName: "app-02", changes: { cores: 4 } })).text).toMatch(/Identity check failed/);
+        expect((await w.call("pve_vm_configure", { node: "pve1", vmid: 9000, expectedName: "tpl-debian12", changes: { cores: 4 } })).text).toMatch(/is a template/);
+        for (const changes of [{}, { args: "-device vfio" }, { net0: "virtio,bridge=vmbr0" }, { scsi0: "local:10" }, { cores: 0 }, { memoryMiB: 100 }, { cpuType: "evil" }, { sshPublicKeys: ["not a key"] }, { ipConfig0: { ip: "dhcp", gw: "10.0.0.1" } }, { description: "a\u0000b" }, { tags: ["Bad Tag"] }]) {
+            expect((await w.call("pve_vm_configure", { node: "pve1", vmid: 101, expectedName: "app-01", changes })).text).toMatch(/^INVALID/);
+        }
+        expect(w.calls.some((c) => c.method === "PUT")).toBe(false);
+    });
+    it("a change the server did not apply fails verification; a UPID answer is awaited", async () => {
+        const dropped = await world({ dropChange: "memory" }).call("pve_vm_configure", { node: "pve2", vmid: 102, expectedName: "old-vm", changes: { memoryMiB: 2048 } });
+        expect(dropped.text).toMatch(/not verified for: memory/);
+        const w = world({ putReturnsUpid: true });
+        const ok = await w.call("pve_vm_configure", { node: "pve2", vmid: 102, expectedName: "old-vm", changes: { name: "new-vm", onboot: true } });
+        expect(ok.isError).toBe(false);
+        expect(w.calls.filter((c) => c.path.includes("/tasks/")).length).toBeGreaterThan(0);
+        expect(w.vms.get(102).config.name).toBe("new-vm");
+    });
+});
+describe("pve_vm_delete", () => {
+    it("deletes a stopped VM, waits, verifies it is gone; options are explicit", async () => {
+        const w = world();
+        const r = await w.call("pve_vm_delete", { node: "pve2", vmid: 102, expectedName: "old-vm" });
+        expect(r.isError).toBe(false);
+        expect(r.text).toMatch(/Verified: the VMID no longer exists/);
+        const del = w.calls.find((c) => c.method === "DELETE");
+        expect(Object.fromEntries(del.query)).toEqual({ purge: "0", "destroy-unreferenced-disks": "0" });
+        expect(w.vms.has(102)).toBe(false);
+    });
+    it("refuses a running VM (never stops it), a wrong name, a template, HA without purge", async () => {
+        const w = world();
+        expect((await w.call("pve_vm_delete", { node: "pve1", vmid: 101, expectedName: "app-01" })).text).toMatch(/is running: stop it first .* never stopped automatically/);
+        expect((await w.call("pve_vm_delete", { node: "pve2", vmid: 102, expectedName: "old" })).text).toMatch(/Identity check failed/);
+        expect((await w.call("pve_vm_delete", { node: "pve1", vmid: 9000, expectedName: "tpl-debian12" })).text).toMatch(/is a template/);
+        expect((await w.call("pve_vm_delete", { node: "pve1", vmid: 555, expectedName: "x" })).text).toMatch(/not found/);
+        w.vms.get(102).ha = true;
+        expect((await w.call("pve_vm_delete", { node: "pve2", vmid: 102, expectedName: "old-vm" })).text).toMatch(/managed by HA: pass purge=true/);
+        expect(w.calls.some((c) => c.method !== "GET")).toBe(false);
+    });
+    it("is annotated destructive; all three are [WRITE] and strict", () => {
+        const w = world();
+        expect(w.tools.get("pve_vm_delete").def.annotations).toMatchObject({ destructiveHint: true, readOnlyHint: false });
+        expect(w.tools.get("pve_vm_create").def.annotations.destructiveHint).toBe(false);
+        for (const n of ["pve_vm_create", "pve_vm_configure", "pve_vm_delete"]) {
+            expect(w.tools.get(n).def.description).toMatch(/^\[WRITE\]/);
+            expect(z.toJSONSchema(w.tools.get(n).schema).additionalProperties).toBe(false);
+        }
+    });
+});
+describe("config mapping", () => {
+    it("normalises current values so equal configs compare equal", () => {
+        expect(delta({ agent: "enabled=1,fstrim_cloned_disks=1", cpu: "cputype=x86-64-v2-AES,flags=+aes", tags: "web;prod" }, toConfig(changesSchema.parse({ agent: true, cpuType: "x86-64-v2-AES", tags: ["prod", "web"] })))).toEqual({});
+        expect(delta({}, toConfig(changesSchema.parse({ cores: 1, onboot: false })))).toEqual({});
+    });
+});

package/dist/proxmox-client.js

@@ -11,12 +11,32 @@ export function validatePath(path) {
 export function buildAuthHeader(tokenId, tokenSecret) {
     return `PVEAPIToken=${tokenId}=${tokenSecret}`;
 }
+/** One URL path segment (node, storage, UPID…): always percent-encoded. */
+export const seg = (v) => encodeURIComponent(String(v));
+export class ProxmoxApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
 export class ProxmoxClient {
     baseUrl;
     authHeader;
-    constructor(config) {
+    secrets;
+    fetcher;
+    constructor(config, fetcher) {
         this.baseUrl = `${config.host.replace(/\/+$/, "")}/api2/json`;
         this.authHeader = buildAuthHeader(config.tokenId, config.tokenSecret);
+        this.secrets = [this.authHeader, config.tokenSecret].filter((x) => x.length >= 4);
+        this.fetcher = fetcher ?? ((url, init) => fetch(url, init));
+    }
+    /** Error text never carries the token, even if a proxy echoes the request. */
+    scrub(text) {
+        let out = text;
+        for (const s of this.secrets)
+            out = out.split(s).join("[REDACTED]");
+        return out;
     }
     async request(method, path, opts = {}) {
         validatePath(path);
@@ -45,15 +65,16 @@ export class ProxmoxClient {
             body = form.toString();
             headers["Content-Type"] = "application/x-www-form-urlencoded";
         }
-        const res = await fetch(url, {
-            method: method.toUpperCase(),
-            headers,
-            body,
-            signal: AbortSignal.timeout(TIMEOUT_MS),
-        });
+        let res;
+        try {
+            res = await this.fetcher(url, { method: method.toUpperCase(), headers, body, signal: AbortSignal.timeout(TIMEOUT_MS) });
+        }
+        catch (err) {
+            throw new Error(this.scrub(`Proxmox API ${method.toUpperCase()} ${path} → ${err instanceof Error ? err.message : String(err)}`));
+        }
         const text = await res.text();
         if (!res.ok) {
-            throw new Error(`Proxmox API ${method.toUpperCase()} ${path} → ${res.status}: ${text.slice(0, 500)}`);
+            throw new ProxmoxApiError(res.status, this.scrub(`Proxmox API ${method.toUpperCase()} ${path} → ${res.status}: ${text.slice(0, 500)}`));
         }
         if (!text)
             return undefined;
@@ -66,7 +87,54 @@ export class ProxmoxClient {
     post(path, body) {
         return this.request("POST", path, { body });
     }
-    del(path) {
-        return this.request("DELETE", path);
+    put(path, body) {
+        return this.request("PUT", path, { body });
+    }
+    /** DELETE takes its options in the query string (Proxmox ignores a DELETE body). */
+    del(path, params) {
+        return this.request("DELETE", path, { query: params });
+    }
+}
+// ---------------------------------------------------------------- tasks (UPID)
+/** UPID:node:pid:pstart:starttime:type:id:user: — every field validated before it is used. */
+const UPID_RE = /^UPID:([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,62})):[0-9A-Fa-f]{8}:[0-9A-Fa-f]{8,16}:[0-9A-Fa-f]{8}:[a-zA-Z0-9_-]{1,64}:[^:\s]{0,128}:[^:\s]{1,256}:$/;
+export function parseUpid(upid) {
+    if (typeof upid !== "string" || !UPID_RE.test(upid))
+        throw new Error(`Malformed task id from Proxmox: ${JSON.stringify(upid)?.slice(0, 120)}`);
+    return { upid, node: upid.match(UPID_RE)[1] };
+}
+export class TaskError extends Error {
+    upid;
+    last;
+    constructor(upid, last, message) {
+        super(`${message} — task ${upid}, last status: ${last ? `${last.status}${last.exitstatus ? ` / ${last.exitstatus}` : ""}` : "none"}`);
+        this.upid = upid;
+        this.last = last;
+    }
+}
+/** Polls a task until it stops; only exitstatus "OK" is a success. Bounded by `timeoutMs`. */
+export async function waitForTask(pve, upidRaw, opts) {
+    const { upid, node } = parseUpid(upidRaw);
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = opts.now ?? (() => Date.now());
+    const deadline = now() + opts.timeoutMs;
+    let interval = opts.intervalMs ?? 1000;
+    let last;
+    for (;;) {
+        const st = await pve.get(`/nodes/${seg(node)}/tasks/${seg(upid)}/status`);
+        if (!st || typeof st !== "object" || typeof st.status !== "string")
+            throw new TaskError(upid, last, "Malformed task status from Proxmox");
+        last = st;
+        if (st.status === "stopped") {
+            if (st.exitstatus === "OK")
+                return st;
+            throw new TaskError(upid, st, `Task failed: ${st.exitstatus ?? "no exit status"}`);
+        }
+        if (st.status !== "running")
+            throw new TaskError(upid, st, `Unexpected task status "${st.status}"`);
+        if (now() + interval > deadline)
+            throw new TaskError(upid, st, `Task still running after ${Math.round(opts.timeoutMs / 1000)}s — it may still complete; check pve_tasks before retrying`);
+        await sleep(interval);
+        interval = Math.min(interval * 1.5, 5000);
     }
 }

package/dist/register.js

@@ -6,11 +6,12 @@ import { registerRawTools } from "./tools/raw.js";
 import { registerLifecycleTools } from "./tools/lifecycle.js";
 import { registerSnapshotTools } from "./tools/snapshots.js";
 import { registerMigrateTools } from "./tools/migrate.js";
+import { registerVmManagementTools } from "./tools/vm-management.js";
 export function parseMode(raw) {
     return raw === "full" ? "full" : "readonly";
 }
 /** Read tools always register; write tools only in `full` mode. */
-export function registerTools(server, client, mode) {
+export function registerTools(server, client, mode, opts = {}) {
     registerClusterTools(server, client);
     registerVmTools(server, client);
     registerStorageTools(server, client);
@@ -20,5 +21,7 @@ export function registerTools(server, client, mode) {
         registerLifecycleTools(server, client);
         registerSnapshotTools(server, client);
         registerMigrateTools(server, client);
+        // typed VM provisioning (create from template, allowlisted config, guarded delete)
+        registerVmManagementTools(server, client, opts);
     }
 }

package/dist/tools/vm-management.js

@@ -0,0 +1,313 @@
+/**
+ * Typed QEMU VM provisioning (issue #75), `full` mode only: clone from a template, apply an
+ * allowlisted configuration delta, delete a stopped VM. No raw method, path or Proxmox parameter
+ * reaches the API: every field is typed, bounded and mapped here.
+ *
+ * Every mutation waits for its task (UPID) to reach a terminal state — only exitstatus "OK" is a
+ * success — and is then verified by reading the resource back. Approval stays in Pulse Chat.
+ */
+import { z } from "zod";
+import { ProxmoxApiError, seg, waitForTask } from "../proxmox-client.js";
+import { textResult, errResult } from "./utils.js";
+export const TIMEOUTS = { create: 30 * 60_000, configure: 2 * 60_000, delete: 10 * 60_000 };
+// ---------------------------------------------------------------- schemas
+const node = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9-]{0,62}$/, "node name: letters, digits, -");
+const vmid = z.number().int().min(100).max(999_999_999);
+const vmName = z
+    .string()
+    .max(63)
+    .regex(/^[a-zA-Z0-9](?:[a-zA-Z0-9.-]*[a-zA-Z0-9])?$/, "VM name: a DNS name (letters, digits, - and .)");
+const storageId = z.string().regex(/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/, "storage id");
+const poolId = z.string().regex(/^[a-zA-Z0-9_.-]{1,64}$/, "pool id");
+const freeText = (max) => z.string().max(max).refine((s) => !/[\u0000-\u0008\u000b-\u001f\u007f]/.test(s), "control characters are not allowed");
+const ipv4 = z.ipv4();
+const cidr4 = z.cidrv4();
+const cidr6 = z.cidrv6();
+const domain = z.string().max(253).regex(/^(?=.{1,253}$)([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)(\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/, "domain name");
+const SSH_KEY_RE = /^(ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(?:256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com) [A-Za-z0-9+/]{40,}={0,3}(?: [\x21-\x7e][\x20-\x7e]{0,199})?$/;
+const sshKey = z.string().max(16_384).regex(SSH_KEY_RE, "an OpenSSH public key (type base64 [comment]), one per entry");
+export const CPU_TYPES = ["host", "max", "kvm64", "qemu64", "x86-64-v2", "x86-64-v2-AES", "x86-64-v3", "x86-64-v4"];
+const ipConfig = z
+    .strictObject({
+    ip: z.union([z.literal("dhcp"), cidr4]).optional().describe('IPv4: "dhcp" or CIDR, e.g. 10.0.0.20/24'),
+    gw: ipv4.optional().describe("IPv4 gateway (static IPv4 only)"),
+    ip6: z.union([z.literal("dhcp"), z.literal("auto"), cidr6]).optional().describe('IPv6: "dhcp", "auto" (SLAAC) or CIDR'),
+    gw6: z.ipv6().optional().describe("IPv6 gateway (static IPv6 only)"),
+})
+    .refine((c) => c.ip || c.ip6, "ipConfig0 needs ip and/or ip6")
+    .refine((c) => !c.gw || (c.ip && c.ip !== "dhcp"), "gw needs a static ip")
+    .refine((c) => !c.gw6 || (c.ip6 && c.ip6 !== "dhcp" && c.ip6 !== "auto"), "gw6 needs a static ip6");
+export const changesSchema = z
+    .strictObject({
+    name: vmName.optional(),
+    cores: z.number().int().min(1).max(128).optional(),
+    sockets: z.number().int().min(1).max(8).optional(),
+    memoryMiB: z.number().int().min(256).max(1_048_576).optional().describe("RAM in MiB (256 MiB – 1 TiB)"),
+    cpuType: z.enum(CPU_TYPES).optional(),
+    onboot: z.boolean().optional(),
+    agent: z.boolean().optional().describe("QEMU guest agent enabled"),
+    description: freeText(8192).optional(),
+    tags: z.array(z.string().regex(/^[a-z0-9_][a-z0-9_.+-]{0,63}$/, "tag: lowercase letters, digits, _ . + -")).max(20).optional(),
+    ipConfig0: ipConfig.optional().describe("cloud-init network of the first NIC"),
+    nameservers: z.array(z.union([ipv4, z.ipv6()])).min(1).max(3).optional().describe("cloud-init DNS servers"),
+    searchDomains: z.array(domain).min(1).max(6).optional().describe("cloud-init DNS search domains"),
+    sshPublicKeys: z.array(sshKey).min(1).max(10).optional().describe("cloud-init authorized SSH public keys (replaces the list)"),
+})
+    .refine((c) => Object.keys(c).length > 0, "changes must not be empty");
+/** Proxmox config keys and values for a set of changes. Pure. */
+export function toConfig(c) {
+    const out = {};
+    if (c.name !== undefined)
+        out.name = c.name;
+    if (c.cores !== undefined)
+        out.cores = String(c.cores);
+    if (c.sockets !== undefined)
+        out.sockets = String(c.sockets);
+    if (c.memoryMiB !== undefined)
+        out.memory = String(c.memoryMiB);
+    if (c.cpuType !== undefined)
+        out.cpu = c.cpuType;
+    if (c.onboot !== undefined)
+        out.onboot = c.onboot ? "1" : "0";
+    if (c.agent !== undefined)
+        out.agent = c.agent ? "1" : "0";
+    if (c.description !== undefined)
+        out.description = c.description;
+    if (c.tags !== undefined)
+        out.tags = [...new Set(c.tags)].sort().join(";");
+    if (c.ipConfig0) {
+        const i = c.ipConfig0;
+        out.ipconfig0 = [i.ip && `ip=${i.ip}`, i.gw && `gw=${i.gw}`, i.ip6 && `ip6=${i.ip6}`, i.gw6 && `gw6=${i.gw6}`].filter(Boolean).join(",");
+    }
+    if (c.nameservers)
+        out.nameserver = c.nameservers.join(" ");
+    if (c.searchDomains)
+        out.searchdomain = c.searchDomains.join(" ");
+    // Proxmox stores sshkeys URL-encoded (and the form encoding adds a second layer on the wire)
+    if (c.sshPublicKeys)
+        out.sshkeys = encodeURIComponent(c.sshPublicKeys.join("\n") + "\n");
+    return out;
+}
+/** Current value of a key, normalised the way toConfig writes it, to compare. */
+export function currentValue(cfg, key) {
+    const v = cfg[key];
+    if (v === undefined || v === null)
+        return undefined;
+    const s = String(v);
+    switch (key) {
+        case "agent":
+            // "1", "enabled=1,fstrim_cloned_disks=1", "0"…
+            return /^(1|enabled=1)(,|$)/.test(s) ? "1" : "0";
+        case "cpu":
+            return s.split(",")[0].replace(/^cputype=/, "");
+        case "tags":
+            return [...new Set(s.split(/[;, ]+/).filter(Boolean))].sort().join(";");
+        case "sshkeys":
+            return encodeURIComponent(decodeURIComponent(s)
+                .split("\n")
+                .map((l) => l.trim())
+                .filter(Boolean)
+                .join("\n") + "\n");
+        case "description":
+            return s.replace(/\n$/, "");
+        default:
+            return s;
+    }
+}
+/** Keys whose desired value differs from the current one. */
+export function delta(cfg, wanted) {
+    const out = {};
+    for (const [k, v] of Object.entries(wanted)) {
+        const cur = currentValue(cfg, k);
+        // defaults Proxmox does not write back: cores/sockets 1, onboot 0, agent 0
+        const dflt = { cores: "1", sockets: "1", onboot: "0", agent: "0" }[k];
+        if ((cur ?? dflt) !== (k === "description" ? v.replace(/\n$/, "") : v))
+            out[k] = v;
+    }
+    return out;
+}
+/** What a change looks like in the output: never a full key or a full description. */
+function show(key, value) {
+    if (key === "sshkeys") {
+        const keys = decodeURIComponent(value).split("\n").filter(Boolean);
+        return `${keys.length} key(s): ${keys.map((k) => `${k.split(" ")[0]} …${k.split(" ")[1]?.slice(-8)}`).join(", ")}`;
+    }
+    if (key === "description")
+        return `${value.length} chars`;
+    return value;
+}
+// ---------------------------------------------------------------- helpers
+const qemu = (n, id) => `/nodes/${seg(n)}/qemu/${seg(id)}`;
+const isMissing = (err) => err instanceof ProxmoxApiError && (err.status === 404 || (err.status === 500 && /does not exist|not exist/i.test(err.message)));
+async function readConfig(pve, n, id) {
+    try {
+        return await pve.get(`${qemu(n, id)}/config`);
+    }
+    catch (err) {
+        if (isMissing(err))
+            return undefined;
+        throw err;
+    }
+}
+/** Every VM/CT of the cluster with this VMID (should be zero or one). */
+async function clusterVmids(pve, id) {
+    const all = (await pve.get("/cluster/resources", { type: "vm" })) ?? [];
+    return all.filter((r) => Number(r.vmid) === id);
+}
+function identity(cfg, n, id, expectedName) {
+    if (!cfg)
+        throw new Error(`VM ${id} not found on node ${n}`);
+    if (cfg.name !== expectedName)
+        throw new Error(`Identity check failed: VM ${id} on ${n} is named "${cfg.name ?? "(none)"}", not "${expectedName}" — nothing done`);
+    if (String(cfg.template) === "1")
+        throw new Error(`VM ${id} is a template: templates are not managed by these tools — nothing done`);
+    return cfg;
+}
+const annotate = (title, destructive, idempotent) => ({ title, readOnlyHint: false, destructiveHint: destructive, idempotentHint: idempotent, openWorldHint: true });
+// ---------------------------------------------------------------- tools
+export function registerVmManagementTools(server, pve, opts = {}) {
+    const wait = (upid, timeoutMs) => waitForTask(pve, upid, { timeoutMs, ...opts.wait });
+    server.registerTool("pve_vm_create", {
+        description: "[WRITE] Create a QEMU VM by cloning an existing template (full clone by default). Checks that the source is a template, that the target node exists and that the VMID is free cluster-wide — it never overwrites. Waits for the clone task and verifies the new VM.",
+        inputSchema: z.strictObject({
+            sourceNode: node.describe("Node holding the template"),
+            templateVmid: vmid.describe("VMID of the template to clone"),
+            targetNode: node.describe("Node of the new VM"),
+            vmid: vmid.describe("VMID of the new VM (must be free in the cluster)"),
+            name: vmName.describe("Name of the new VM (DNS name)"),
+            fullClone: z.boolean().default(true).describe("Full clone (default) or linked clone"),
+            storage: storageId.optional().describe("Target storage for the disks (full clone only)"),
+            pool: poolId.optional().describe("Resource pool to add the VM to"),
+            description: freeText(8192).optional(),
+        }),
+        annotations: annotate("Create VM from template", false, false),
+    }, async (a) => {
+        try {
+            if (a.storage && !a.fullClone)
+                throw new Error("storage only applies to a full clone");
+            const [tpl, nodes, taken] = await Promise.all([readConfig(pve, a.sourceNode, a.templateVmid), pve.get("/nodes"), clusterVmids(pve, a.vmid)]);
+            if (!tpl)
+                throw new Error(`Template ${a.templateVmid} not found on node ${a.sourceNode}`);
+            if (String(tpl.template) !== "1")
+                throw new Error(`VM ${a.templateVmid} on ${a.sourceNode} is not a template — refusing to clone a regular VM`);
+            const target = (nodes ?? []).find((x) => x.node === a.targetNode);
+            if (!target)
+                throw new Error(`Target node "${a.targetNode}" is not in the cluster (${(nodes ?? []).map((x) => x.node).join(", ")})`);
+            if (target.status && target.status !== "online")
+                throw new Error(`Target node "${a.targetNode}" is ${target.status}`);
+            if (taken.length)
+                throw new Error(`VMID ${a.vmid} is already used (${taken.map((t) => `${t.type ?? "vm"} "${t.name ?? "?"}" on ${t.node ?? "?"}`).join(", ")}) — refusing to overwrite`);
+            const upid = await pve.post(`${qemu(a.sourceNode, a.templateVmid)}/clone`, {
+                newid: a.vmid,
+                name: a.name,
+                target: a.targetNode,
+                full: a.fullClone ? 1 : 0,
+                storage: a.storage,
+                pool: a.pool,
+                description: a.description,
+            });
+            const task = await wait(upid, TIMEOUTS.create);
+            const cfg = await readConfig(pve, a.targetNode, a.vmid);
+            if (!cfg)
+                throw new Error(`Clone task ${upid} ended OK but VM ${a.vmid} is not on ${a.targetNode} — check pve_tasks`);
+            if (cfg.name !== a.name)
+                throw new Error(`Clone task ended OK but VM ${a.vmid} is named "${cfg.name}", not "${a.name}" — check it before use`);
+            if (String(cfg.template) === "1")
+                throw new Error(`VM ${a.vmid} came out as a template — check it before use`);
+            return textResult([
+                `# VM ${a.vmid} "${a.name}" created on ${a.targetNode}`,
+                "",
+                `- Cloned from template ${a.templateVmid} (${tpl.name ?? "?"}) on ${a.sourceNode} — ${a.fullClone ? "full" : "linked"} clone${a.storage ? ` to ${a.storage}` : ""}${a.pool ? ` · pool ${a.pool}` : ""}`,
+                `- Task ${upid}: ${task.exitstatus}`,
+                `- Verified: config read back (${cfg.cores ?? 1} core(s) × ${cfg.sockets ?? 1}, ${cfg.memory ?? "?"} MiB). The VM is stopped; configure it with pve_vm_configure, start it with pve_vm_action.`,
+            ].join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.registerTool("pve_vm_configure", {
+        description: "[WRITE] Apply an allowlisted configuration delta to a QEMU VM: name, cores, sockets, memory, CPU type, onboot, guest agent, description, tags and structured cloud-init (ipConfig0, nameservers, search domains, SSH public keys). Requires the exact current name. Unchanged values are not sent; nothing to change is a no-op. Disks, network devices, args and passthrough are not configurable.",
+        inputSchema: z.strictObject({
+            node: node.describe("Node of the VM"),
+            vmid: vmid,
+            expectedName: vmName.describe("Exact current name of the VM (identity check)"),
+            changes: changesSchema,
+        }),
+        annotations: annotate("Configure VM", false, true),
+    }, async (a) => {
+        try {
+            const cfg = identity(await readConfig(pve, a.node, a.vmid), a.node, a.vmid, a.expectedName);
+            if (cfg.lock)
+                throw new Error(`VM ${a.vmid} is locked (${cfg.lock}) — retry when the running operation ends`);
+            const wanted = toConfig(a.changes);
+            const d = delta(cfg, wanted);
+            if (!Object.keys(d).length)
+                return textResult(`No-op: VM ${a.vmid} "${a.expectedName}" already has this configuration (${Object.keys(wanted).join(", ")}). Nothing sent.`);
+            // PUT /config is synchronous (no task); some setups answer with a UPID anyway: then wait for it
+            const res = await pve.put(`${qemu(a.node, a.vmid)}/config`, d);
+            if (typeof res === "string" && res.startsWith("UPID:"))
+                await wait(res, TIMEOUTS.configure);
+            const after = await readConfig(pve, a.node, a.vmid);
+            if (!after)
+                throw new Error(`VM ${a.vmid} disappeared after the configuration — check it`);
+            const still = delta(after, d);
+            if (Object.keys(still).length)
+                throw new Error(`Configuration written but not verified for: ${Object.keys(still).join(", ")} — read the VM config before retrying`);
+            const status = await pve.get(`${qemu(a.node, a.vmid)}/status/current`).catch(() => undefined);
+            const pending = status?.status === "running" ? await pve.get(`${qemu(a.node, a.vmid)}/pending`).catch(() => []) : [];
+            const waiting = (pending ?? []).filter((p) => p.key && p.pending !== undefined && p.key in d).map((p) => p.key);
+            return textResult([
+                `# VM ${a.vmid} "${d.name ?? a.expectedName}" configured on ${a.node}`,
+                "",
+                ...Object.entries(d).map(([k, v]) => `- ${k}: ${show(k, v)}`),
+                ...(Object.keys(wanted).length > Object.keys(d).length ? [`- unchanged (not sent): ${Object.keys(wanted).filter((k) => !(k in d)).join(", ")}`] : []),
+                "",
+                `Verified: config read back.${waiting.length ? ` The VM is running: ${waiting.join(", ")} apply at the next reboot (pending).` : ""}${"sshkeys" in d || "ipconfig0" in d || "nameserver" in d || "searchdomain" in d ? " cloud-init changes apply at the next boot." : ""}`,
+            ].join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+    server.registerTool("pve_vm_delete", {
+        description: "[WRITE][DESTRUCTIVE] Delete a stopped QEMU VM and its disks. Requires the exact current name; refuses a running, locked, protected or template VM and never stops it. purge also removes it from backup jobs, replication and HA; destroyUnreferencedDisks also deletes disks not referenced in its config. Waits for the task and verifies the VM is gone.",
+        inputSchema: z.strictObject({
+            node: node.describe("Node of the VM"),
+            vmid: vmid,
+            expectedName: vmName.describe("Exact current name of the VM (identity check)"),
+            purge: z.boolean().default(false).describe("Also remove the VMID from backup jobs, replication and HA"),
+            destroyUnreferencedDisks: z.boolean().default(false).describe("Also destroy disks with this VMID not referenced in the config"),
+        }),
+        annotations: annotate("Delete VM", true, false),
+    }, async (a) => {
+        try {
+            const cfg = identity(await readConfig(pve, a.node, a.vmid), a.node, a.vmid, a.expectedName);
+            if (String(cfg.protection) === "1")
+                throw new Error(`VM ${a.vmid} has protection enabled — disable it in Proxmox first; nothing done`);
+            if (cfg.lock)
+                throw new Error(`VM ${a.vmid} is locked (${cfg.lock}) — nothing done`);
+            const status = await pve.get(`${qemu(a.node, a.vmid)}/status/current`);
+            if (status?.status !== "stopped")
+                throw new Error(`VM ${a.vmid} is ${status?.status ?? "in an unknown state"}: stop it first (pve_vm_action shutdown) — it is never stopped automatically; nothing done`);
+            if (status.ha?.managed && !a.purge)
+                throw new Error(`VM ${a.vmid} is managed by HA: pass purge=true to remove it from HA as part of the deletion, or remove the HA resource first; nothing done`);
+            const upid = await pve.del(qemu(a.node, a.vmid), { purge: a.purge ? 1 : 0, "destroy-unreferenced-disks": a.destroyUnreferencedDisks ? 1 : 0 });
+            const task = await wait(upid, TIMEOUTS.delete);
+            const left = await readConfig(pve, a.node, a.vmid);
+            const elsewhere = await clusterVmids(pve, a.vmid);
+            if (left || elsewhere.length)
+                throw new Error(`Delete task ${upid} ended OK but VMID ${a.vmid} still exists${elsewhere.length ? ` (${elsewhere.map((e) => e.node).join(", ")})` : ""} — check it`);
+            return textResult([
+                `# VM ${a.vmid} "${a.expectedName}" deleted from ${a.node}`,
+                "",
+                `- Task ${upid}: ${task.exitstatus}`,
+                `- purge: ${a.purge ? "yes (backup jobs, replication, HA cleaned)" : "no"} · unreferenced disks: ${a.destroyUnreferencedDisks ? "destroyed" : "kept"}`,
+                "- Verified: the VMID no longer exists in the cluster.",
+            ].join("\n"));
+        }
+        catch (err) {
+            return errResult(err);
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aidalinfo/proxmox-mcp",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Proxmox VE MCP server with read-only / full-access modes — cluster, nodes, QEMU VMs, LXC, storage, backups, tasks",
   "type": "module",
   "main": "dist/index.js",