VergeOS MCP Server

Instructions

Implementation Reference

• src/mcp-http-server.js:187-251 (handler)

  Primary handler for 'power_off_vm' MCP tool. Sends graceful 'poweroff' API action, optionally waits/polls for shutdown completion, and forces 'kill' if timeout expires and force_after_timeout is true.
  async powerOffVM(id, options = {}) { const { wait_timeout = 0, force_after_timeout = false } = options; const status = await this.getVMStatus(id); if (!status.running) { return { success: true, message: `VM '${status.name}' is already stopped`, current_state: status.power_state, was_running: false }; } // Send graceful shutdown await this.vmAction(id, "poweroff"); // If no wait requested, return immediately if (wait_timeout <= 0) { return { success: true, message: `Graceful shutdown command sent to VM '${status.name}'`, previous_state: status.power_state, note: "Use wait_timeout parameter to wait for shutdown completion" }; } // Poll for shutdown with timeout const startTime = Date.now(); const pollInterval = 3000; // 3 seconds const maxWait = Math.min(wait_timeout, 300) * 1000; // Cap at 5 minutes while (Date.now() - startTime < maxWait) { await new Promise(resolve => setTimeout(resolve, pollInterval)); const currentStatus = await this.getVMStatus(id); if (!currentStatus.running) { return { success: true, message: `VM '${status.name}' shut down gracefully`, final_state: currentStatus.power_state, elapsed_seconds: Math.round((Date.now() - startTime) / 1000) }; } } // Timeout reached - check if we should force if (force_after_timeout) { await this.vmAction(id, "kill"); // Wait a moment for kill to take effect await new Promise(resolve => setTimeout(resolve, 2000)); const finalStatus = await this.getVMStatus(id); return { success: true, message: `VM '${status.name}' did not shut down within ${wait_timeout}s - forced power off`, final_state: finalStatus.power_state, forced: true, elapsed_seconds: Math.round((Date.now() - startTime) / 1000) }; } // Timeout without force const currentStatus = await this.getVMStatus(id); return { success: false, error: `VM '${status.name}' did not shut down within ${wait_timeout}s`, current_state: currentStatus.power_state, elapsed_seconds: Math.round((Date.now() - startTime) / 1000), hint: "Use force_after_timeout=true to automatically force shutdown after timeout" }; }
• src/mcp-http-server.js:623-623 (registration)

  Dispatch/execution point for 'power_off_vm' tool in MCP HTTP server's executeTool function.
  case "power_off_vm": return api.powerOffVM(args.id, { wait_timeout: args.wait_timeout, force_after_timeout: args.force_after_timeout });
• src/mcp-http-server.js:589-589 (schema)

  Tool registration entry in TOOLS array, including schema defining id (required), wait_timeout, and force_after_timeout parameters.
  { name: "power_off_vm", description: "Power off a virtual machine (graceful shutdown). Use wait_timeout to wait for completion, and force_after_timeout to auto-force if graceful shutdown fails.", inputSchema: { type: "object", properties: { id: { type: "number", description: "VM ID" }, wait_timeout: { type: "number", description: "Seconds to wait for graceful shutdown (0 = don't wait, max 300). Recommended: 60-120 for most VMs." }, force_after_timeout: { type: "boolean", description: "If true, force power off after wait_timeout expires. Recommended: true for reliable shutdown." } }, required: ["id"] } },
• src/mcp-http-server.js:171-177 (helper)

  Helper method used by powerOffVM to send the actual 'poweroff' or 'kill' action to the VergeOS API.
  async vmAction(id, action) { return this.request("/api/v4/vm_actions", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ vm: id, action }), }); }
• src/index.js:129-130 (handler)

  Simpler handler implementation in stdio MCP server, directly calls vmAction without wait/force logic.
  async powerOffVM(id) { return this.vmAction(id, "poweroff");