VergeOS MCP Server

Instructions

Implementation Reference

• src/mcp-http-server.js:151-170 (handler)

  Primary handler function for get_vm_status tool. Fetches VM details by ID, retrieves all machine statuses, matches by machine ID, and returns formatted status information.

  async getVMStatus(id) {
    // Get VM to find machine ID, then get status
    const vm = await this.request(`/api/v4/vms/${id}?fields=most`);
    const statuses = await this.request("/api/v4/machine_status");
    const status = statuses.find(s => s.machine === vm.machine);
    
    if (!status) {
      return { vm_id: id, name: vm.name, power_state: "unknown", running: false };
    }
    
    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,
    };
  }

• src/mcp-http-server.js:587-587 (registration)

  Tool registration in the TOOLS array, including name, description, and input schema for MCP server.

  { name: "get_vm_status", description: "Get the current status of a VM", inputSchema: { type: "object", properties: { id: { type: "number", description: "VM ID" } }, required: ["id"] } },

• src/index.js:113-115 (handler)

  Simplified handler in stdio MCP server that directly queries machine_status assuming id is machine ID.

  async getVMStatus(id) {
    return this.request(`/api/v4/machine_status?machine=${id}`);
  }

• src/index.js:280-292 (registration)

  Tool registration definition in stdio MCP server.

    name: "get_vm_status",
    description: "Get the current status of a VM (running, stopped, etc.)",
    inputSchema: {
      type: "object",
      properties: {
        id: {
          type: "number",
          description: "VM ID",
        },
      },
      required: ["id"],
    },
  },

• local-proxy/index-direct.js:128-133 (handler)

  Handler in direct connection MCP server, similar to mcp-http-server, mapping VM ID to machine status.

  async function getVMStatus(id) {
    const vm = await apiRequest(`/api/v4/vms/${id}?fields=most`);
    const statuses = await apiRequest("/api/v4/machine_status");
    const status = statuses.find(s => s.machine === vm.machine) || {};
    return { id, name: vm.name, running: status.running || false, status: status.running ? "running" : "stopped" };
  }