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");