VergeOS MCP Server

Instructions

Implementation Reference

• src/index.js:159-161 (handler)

  Core handler function in the VergeOSAPI class that executes the tool logic by making an authenticated HTTP request to the VergeOS API endpoint for tenant details.
  async getTenant(id) { return this.request(`/api/v4/tenants/${id}?fields=most`); }
• src/index.js:417-430 (schema)

  Input schema definition for the get_tenant tool, specifying the required 'id' parameter as a number.
  { name: "get_tenant", description: "Get detailed information about a specific tenant", inputSchema: { type: "object", properties: { id: { type: "number", description: "Tenant ID", }, }, required: ["id"], }, },
• src/index.js:579-581 (registration)

  Registration and dispatch logic within the MCP CallToolRequest handler switch statement that routes the tool call to the getTenant function.
  case "get_tenant": result = await api.getTenant(args.id); break;
• src/mcp-http-server.js:161-472 (handler)

  Identical handler function in the HTTP MCP server variant.
  return { vm_id: id, name: vm.name, machine: vm.machine, running: status.running, power_state: status.status, status_info: status.status_info || "", migratable: status.migratable, }; } async vmAction(id, action) { return this.request("/api/v4/vm_actions", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ vm: id, action }), }); } async powerOnVM(id) { const status = await this.getVMStatus(id); if (status.running) { return { success: false, error: `VM '${status.name}' is already running`, current_state: status.power_state }; } await this.vmAction(id, "poweron"); return { success: true, message: `Power on command sent to VM '${status.name}'`, previous_state: status.power_state }; } 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" }; } async forceOffVM(id) { const status = await this.getVMStatus(id); if (!status.running) { return { success: true, message: `VM '${status.name}' is already stopped`, current_state: status.power_state }; } await this.vmAction(id, "kill"); return { success: true, message: `Force power off (kill) command sent to VM '${status.name}'`, previous_state: status.power_state }; } async resetVM(id) { const status = await this.getVMStatus(id); if (!status.running) { return { success: false, error: `VM '${status.name}' is not running - cannot reset`, current_state: status.power_state }; } await this.vmAction(id, "reset"); return { success: true, message: `Reset command sent to VM '${status.name}'`, previous_state: status.power_state }; } async getVMNics(vmId) { // Get VM to find machine ID const vm = await this.getVM(vmId); const machineId = vm.machine; const nics = await this.request(`/api/v4/machine_nics?machine=${machineId}&fields=all`); return nics.filter((nic) => nic.machine === machineId).map(n => ({ id: n.$key, name: n.name, mac: n.macaddress, network_id: n.vnet, ip: n.ipaddress, interface: n.interface, enabled: n.enabled, })); } async getVMDrives(vmId) { // Get VM to find machine ID (same pattern as getVMNics) const vm = await this.getVM(vmId); const machineId = vm.machine; const drives = await this.request(`/api/v4/machine_drives?machine=${machineId}&fields=all`); // Filter by machine ID and return simplified info return drives .filter((d) => d.machine === machineId) .map((d) => ({ id: d.$key, name: d.name, interface: d.interface, size_gb: d.disksize ? Math.round(d.disksize / (1024 * 1024 * 1024)) : null, size_bytes: d.disksize || null, enabled: d.enabled, media_type: d.media_type, description: d.description || "", })); } async resizeDrive(driveId, newSizeGB) { // Get current drive info const drive = await this.request(`/api/v4/machine_drives/${driveId}?fields=all`); if (!drive) { return { success: false, error: `Drive ${driveId} not found` }; } const currentSizeGB = Math.round(drive.disksize / (1024 * 1024 * 1024)); const newSizeBytes = newSizeGB * 1024 * 1024 * 1024; if (newSizeGB <= currentSizeGB) { return { success: false, error: `New size (${newSizeGB} GB) must be larger than current size (${currentSizeGB} GB). Shrinking disks is not supported.`, current_size_gb: currentSizeGB }; } // Resize the drive await this.request(`/api/v4/machine_drives/${driveId}`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ disksize: newSizeBytes }), }); return { success: true, message: `Drive '${drive.name}' resized from ${currentSizeGB} GB to ${newSizeGB} GB`, drive_id: driveId, previous_size_gb: currentSizeGB, new_size_gb: newSizeGB, note: "You may need to extend the partition/filesystem inside the VM to use the new space" }; } async addDrive(machineId, options = {}) { const { name, size_gb, interface_type = "virtio-scsi", description = "" } = options; if (!name) { return { success: false, error: "Drive name is required" }; } if (!size_gb || size_gb < 1) { return { success: false, error: "Size in GB is required and must be at least 1 GB" }; } const sizeBytes = size_gb * 1024 * 1024 * 1024; // Create the drive const result = await this.request("/api/v4/machine_drives", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ machine: machineId, name: name, disksize: sizeBytes, interface: interface_type, media: "disk", description: description, enabled: true, }), }); return { success: true, message: `Drive '${name}' (${size_gb} GB) added to machine ${machineId}`, drive_id: result.$key, name: name, size_gb: size_gb, interface: interface_type, note: "The VM may need to be restarted to detect the new drive" }; } async modifyVM(vmId, options = {}) { const { cpu_cores, ram_mb, shutdown_if_running = false, wait_timeout = 60, force_after_timeout = true } = options; if (!cpu_cores && !ram_mb) { return { success: false, error: "Must specify cpu_cores and/or ram_mb to modify" }; } // Get current VM info and status const vm = await this.getVM(vmId); const status = await this.getVMStatus(vmId); const changes = {}; if (cpu_cores) changes.cpu_cores = cpu_cores; if (ram_mb) changes.ram = ram_mb; // Check if VM is running if (status.running) { if (!shutdown_if_running) { return { success: false, error: `VM '${vm.name}' is currently running. CPU/RAM changes require the VM to be powered off.`, current_state: status.power_state, current_cpu: vm.cpu_cores, current_ram_mb: vm.ram, requested_cpu: cpu_cores || vm.cpu_cores, requested_ram_mb: ram_mb || vm.ram, hint: "Set shutdown_if_running=true to automatically shut down the VM, apply changes, and optionally restart it" }; } // Shut down the VM const shutdownResult = await this.powerOffVM(vmId, { wait_timeout, force_after_timeout }); if (!shutdownResult.success && !shutdownResult.message?.includes("already stopped")) { return { success: false, error: `Failed to shut down VM '${vm.name}': ${shutdownResult.error}`, shutdown_result: shutdownResult }; } } // Apply changes await this.request(`/api/v4/vms/${vmId}`, { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify(changes), }); return { success: true, message: `VM '${vm.name}' modified successfully`, vm_id: vmId, previous_cpu: vm.cpu_cores, previous_ram_mb: vm.ram, new_cpu: cpu_cores || vm.cpu_cores, new_ram_mb: ram_mb || vm.ram, was_running: status.running, note: status.running ? "VM was shut down to apply changes. Use power_on_vm to restart it." : "VM is stopped. Use power_on_vm to start it with new settings." }; } // Network Operations async listNetworks(options = {}) { const { type, name, enabled, limit = 100, offset = 0 } = options; const networks = await this.request("/api/v4/vnets?fields=most"); // Filter let filtered = networks; if (type) filtered = filtered.filter(n => n.type === type); if (name) filtered = filtered.filter(n => n.name?.toLowerCase().includes(name.toLowerCase())); if (enabled !== undefined) filtered = filtered.filter(n => n.enabled === enabled); // Paginate and return summary view return filtered.slice(offset, offset + limit).map(n => ({ id: n.$key, name: n.name, type: n.type, network: n.network, enabled: n.enabled, running: n.running, description: n.description || null, })); } async getNetwork(id) { return this.request(`/api/v4/vnets/${id}?fields=most`); } async networkAction(id, action) { return this.request("/api/v4/vnet_actions", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ vnet: id, action }), }); } // Tenant Operations async listTenants() { return this.request("/api/v4/tenants?fields=most"); } async getTenant(id) { return this.request(`/api/v4/tenants/${id}?fields=most`); }
• src/mcp-http-server.js:601-602 (schema)

  Schema in the HTTP MCP server's compact TOOLS array.
  { name: "get_tenant", description: "Get tenant details", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } }, { name: "tenant_action", description: "Perform tenant action", inputSchema: { type: "object", properties: { id: { type: "number" }, action: { type: "string", enum: ["poweron", "poweroff", "reset"] } }, required: ["id", "action"] } },