VergeOS MCP Server

Instructions

Implementation Reference

• src/index.js:109-111 (handler)

  The core handler function for the 'get_vm' tool. It retrieves detailed VM information by proxying to the VergeOS API endpoint `/api/v4/vms/${id}?fields=most` using the shared request method.

  async getVM(id) {
    return this.request(`/api/v4/vms/${id}?fields=most`);
  }

• src/index.js:265-278 (schema)

  The input schema definition for the 'get_vm' tool, specifying that a numeric 'id' parameter is required.

  {
    name: "get_vm",
    description: "Get detailed information about a specific VM by ID",
    inputSchema: {
      type: "object",
      properties: {
        id: {
          type: "number",
          description: "VM ID",
        },
      },
      required: ["id"],
    },
  },

• src/index.js:542-544 (registration)

  The registration/dispatch logic in the tool call handler switch statement that routes 'get_vm' calls to the api.getVM method.

  case "get_vm":
    result = await api.getVM(args.id);
    break;

• src/index.js:526-528 (registration)

  Registers the list_tools handler which returns the TOOLS array containing the 'get_vm' tool definition.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return { tools: TOOLS };
  });

• local-proxy/index-direct.js:109-126 (handler)

  Alternative direct-mode handler for 'get_vm' that fetches VM details and enriches with status information, formatting a structured response.

  async function getVM(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: vm.$key,
      name: vm.name,
      machine: vm.machine,
      enabled: vm.enabled,
      running: status.running || false,
      status: status.running ? "running" : "stopped",
      cpu_cores: vm.cpu_cores,
      ram: vm.ram,
      os_family: vm.os_family,
      description: vm.description || "",
    };
  }