使用说明

VergeOS MCP服务器

一种用于交互的模型上下文协议（MCP）服务器 VergeOS 虚拟化平台。这使得像Claude、Windsurf/Cascade和其他MCP兼容客户端这样的AI助手能够通过自然语言管理VM、网络、租户和监控您的VergeOS集群。

架构概述

此项目提供了两种部署选项：

┌─────────────────────────────────────────────────────────────────────────────┐
│                           DEPLOYMENT OPTIONS                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  Option 1: Local (stdio)              Option 2: Remote (HTTP + Local Proxy) │
│  ─────────────────────────            ───────────────────────────────────── │
│                                                                              │
│  ┌──────────┐    stdio    ┌─────────┐     ┌──────────┐   HTTP   ┌─────────┐│
│  │ Windsurf │◄──────────►│  MCP    │     │ Windsurf │◄────────►│  Local  ││
│  │ /Claude  │            │ Server  │     │ /Claude  │  stdio   │  Proxy  ││
│  └──────────┘            └────┬────┘     └──────────┘          └────┬────┘│
│                               │                                      │     │
│                               │ HTTPS                          HTTPS │     │
│                               ▼                                      ▼     │
│                          ┌─────────┐                          ┌──────────┐ │
│                          │VergeOS │                          │ K8s MCP  │ │
│                          │  API   │                          │ Server   │ │
│                          └─────────┘                          └────┬─────┘ │
│                                                                    │       │
│                                                               HTTPS│       │
│                                                                    ▼       │
│                                                              ┌──────────┐  │
│                                                              │ VergeOS  │  │
│                                                              │   API    │  │
│                                                              └──────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

何时使用每个选项

选项	用例
本地（stdio）	AI客户端在可以访问VergeOS的同一台机器上运行
远程（HTTP）	AI客户端是远程的（例如笔记本电脑），VergeOS位于专用网络上

特性

MCP工具

VM电源控制

工具	说明
`list_vms`	列出所有虚拟机（按运行/名称筛选）
`get_vm`	按ID获取详细的VM信息
`get_vm_status`	获取VM运行状态和电源状态
`power_on_vm`	打开虚拟机电源
`power_off_vm`	优雅地关闭电源，可选等待和自动强制
`force_off_vm`	强制断电（硬关机）
`reset_vm`	重置/重新启动虚拟机

虚拟机配置

工具	说明
`modify_vm`	更改CPU内核和/或RAM（处理正在运行的VM）
`add_drive`	向虚拟机添加新的磁盘驱动器
`resize_drive`	扩展现有磁盘（仅增加）
`get_vm_nics`	获取VM网络接口
`get_vm_drives`	获取具有大小的VM磁盘驱动器

网络管理

工具	说明
`list_networks`	列出所有虚拟网络
`get_network`	获取网络详细信息
`network_action`	开机/关机、重置、应用规则

租户管理

工具	说明
`list_tenants`	列出所有租户
`get_tenant`	获取租户详细信息
`tenant_action`	打开/关闭电源，重置租户

集群和节点管理

工具	说明
`list_nodes`	列出群集节点
`get_node_stats`	获取节点统计信息
`get_cluster_status`	获取群集运行状况
`get_cluster_stats`	获取存储层统计信息

存储和监控

工具	说明
`list_volumes`	列出存储卷
`get_logs`	获取系统日志（按级别/对象类型筛选）
`get_alarms`	获取活动警报

快照管理

工具	说明
`list_vm_snapshots`	列出VM的快照
`create_vm_snapshot`	创建快照（可选过期和暂停）
`delete_vm_snapshot`	删除VM快照
`restore_vm_snapshot`	从快照还原虚拟机

智能功能

优雅的关机与等待: power_off_vm 可以等待VM关闭，并在超时后自动强制执行
正在运行VM处理: modify_vm 检测正在运行的虚拟机，并可以自动关闭以应用CPU/RAM更改
日志过滤：按级别筛选日志(error, warning, audit)或对象类型(vm, node, vnet)
快照过期: create_vm_snapshot 支持自动过期（默认7天）
静止快照：在快照之前暂停VM的选项（需要来宾代理）

MCP资源

vergeos://cluster/status -集群状态概述
vergeos://vms/list -所有虚拟机
vergeos://networks/list -所有虚拟网络
vergeos://alarms/active -主动系统报警

选项1：本地安装（stdio）

如果您的AI客户端运行在可以直接访问您的VergeOS实例的机器上，请使用此选项。

安装

git clone <repo-url> vergeos-mcp-server
cd vergeos-mcp-server
npm install

配置

创建一个 .env 文件：

VERGEOS_HOST=your-vergeos-host
VERGEOS_USER=admin
VERGEOS_PASS=your-password

或者使用API令牌（推荐）：

# Get a token
curl -sk -X POST "https://your-vergeos-host/api/sys/tokens" \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"password"}' | jq -r '."$key"'

# Set in .env
VERGEOS_HOST=your-vergeos-host
VERGEOS_TOKEN=your-token-here

Claude桌面配置

添加到 ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vergeos": {
      "command": "node",
      "args": ["/path/to/vergeos-mcp-server/src/index.js"],
      "env": {
        "VERGEOS_HOST": "your-vergeos-host",
        "VERGEOS_USER": "admin",
        "VERGEOS_PASS": "your-password"
      }
    }
  }
}

风帆配置

添加到 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vergeos": {
      "command": "node",
      "args": ["/path/to/vergeos-mcp-server/src/index.js"],
      "env": {
        "VERGEOS_HOST": "your-vergeos-host",
        "VERGEOS_USER": "admin",
        "VERGEOS_PASS": "your-password"
      }
    }
  }
}

选项2：远程安装（Kubernetes+本地代理）

如果您的AI客户端（例如笔记本电脑上的Windsurf）无法直接访问VergeOS，但您有一个可以访问的Kubernetes集群，请使用此功能。

建筑

┌─────────────┐      ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Windsurf  │─────►│ Local Proxy │─────►│  K8s MCP    │─────►│   VergeOS   │
│  (Laptop)   │stdio │  (Laptop)   │HTTPS │  Server     │HTTPS │    API      │
└─────────────┘      └─────────────┘      └─────────────┘      └─────────────┘
                                                │
                                          ┌─────┴─────┐
                                          │  Traefik  │
                                          │  Ingress  │
                                          └───────────┘

步骤1：部署到Kubernetes

# Clone the repo on your K8s host
cd vergeos-mcp-server

# Edit credentials in deploy.sh or create ~/.vergeos-credentials
cat > ~/.vergeos-credentials << EOF
VERGEOS_USER=admin
VERGEOS_PASS=your-password
EOF

# Deploy
./deploy.sh

这将创建：

命名空间： vergeos-mcp
运行HTTP MCP服务器的部署
服务暴露端口3002
外部访问入口路由（Traefik）

步骤2：配置DNS

添加指向Traefik入口的DNS记录：

vergeos-mcp.yourdomain.com → <traefik-ip>

步骤3：测试服务器

# Health check
curl https://vergeos-mcp.yourdomain.com/health

# List VMs
curl https://vergeos-mcp.yourdomain.com/vms

# MCP protocol test
curl -X POST https://vergeos-mcp.yourdomain.com/message \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

步骤4：安装本地代理（在笔记本电脑上）

由于Windsurf仅支持基于stdio的MCP服务器，因此您需要一个本地代理：

# Create directory
mkdir -p ~/.mcp/vergeos
cd ~/.mcp/vergeos

# Create package.json
cat > package.json << 'EOF'
{
  "name": "vergeos-mcp-proxy",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0",
    "node-fetch": "^3.3.2"
  }
}
EOF

# Create index.js
cat > index.js << 'EOF'
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const SERVER_URL = process.env.VERGEOS_MCP_URL || "https://vergeos-mcp.yourdomain.com";

async function apiCall(path, options = {}) {
  const fetch = (await import("node-fetch")).default;
  const response = await fetch(`${SERVER_URL}${path}`, {
    ...options,
    headers: { "Content-Type": "application/json", ...options.headers },
  });
  if (!response.ok) throw new Error(`API Error: ${response.status}`);
  return response.json();
}

const server = new Server({ name: "vergeos", version: "1.0.0" }, { capabilities: { tools: {} } });

const TOOLS = [
  { name: "list_vms", description: "List all VMs in VergeOS", inputSchema: { type: "object", properties: {} } },
  { name: "get_vm", description: "Get VM details by ID", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
  { name: "power_on_vm", description: "Power on a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
  { name: "power_off_vm", description: "Power off a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
  { name: "reset_vm", description: "Reset a VM", inputSchema: { type: "object", properties: { id: { type: "number" } }, required: ["id"] } },
  { name: "list_networks", description: "List virtual networks", inputSchema: { type: "object", properties: {} } },
  { name: "list_tenants", description: "List tenants", inputSchema: { type: "object", properties: {} } },
  { name: "list_nodes", description: "List cluster nodes", inputSchema: { type: "object", properties: {} } },
  { name: "get_cluster_status", description: "Get cluster status", inputSchema: { type: "object", properties: {} } },
  { name: "get_alarms", description: "Get active alarms", inputSchema: { type: "object", properties: {} } },
  { name: "get_logs", description: "Get system logs", inputSchema: { type: "object", properties: { limit: { type: "number" } } } },
];

server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  try {
    const result = await apiCall(`/tools/${name}`, { method: "POST", body: JSON.stringify(args || {}) });
    return { content: [{ type: "text", text: JSON.stringify(result.result, null, 2) }] };
  } catch (error) {
    return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);
EOF

# Install dependencies
npm install

步骤5：配置Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vergeos": {
      "command": "node",
      "args": ["/Users/yourusername/.mcp/vergeos/index.js"],
      "env": {
        "VERGEOS_MCP_URL": "https://vergeos-mcp.yourdomain.com"
      }
    }
  }
}

重新启动Windsurf以加载新的MCP服务器。

REST API参考

HTTP服务器还公开了一个用于直接访问的REST API：

端点	方法	描述
`/health`	GET	健康检查
`/tools`	GET	列出可用的MCP工具
`/tools/:name`	POST	执行MCP工具
`/vms`	GET	列出所有虚拟机
`/vms/:id`	GET	获取VM详细信息
`/vms/:id/:action`	POST	VM操作（开机/关机/重置）
`/networks`	GET	列出网络
`/tenants`	GET	列出租户
`/nodes`	GET	列出节点
`/cluster/status`	GET	群集状态
`/alarms`	GET	活动警报
`/logs`	GET	系统日志

MCP协议端点

端点	方法	描述
`/sse`	GET	服务器发送事件连接
`/message`	POST	MCP JSON-RPC消息

交互示例

连接后，您可以询问您的AI助手：

“列出VergeOS中的所有虚拟机”
“关闭名为'test-VM'的VM的电源”
“显示群集状态”
“哪些警报处于活动状态？”
“列出所有虚拟网络”
“获取VM ID 34的详细信息”
“群集中有多少个节点？”
“显示最近20个日志条目”
“创建名为“升级前”的VM 34快照”
“列出web服务器VM的所有快照”
“从快照ID 123还原VM 34”
“向数据库VM添加2GB RAM”
“向VM 34添加50GB数据磁盘”

VergeOS API说明

认证

VergeOS使用基于cookie的身份验证：

张贴到 /api/sys/tokens 使用基本身份验证
响应中包含令牌 $key 领域
使用令牌作为cookie： Cookie: token=<value>

# Get token
TOKEN=$(curl -sk -X POST "https://vergeos/api/sys/tokens" \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"password"}' | jq -r '."$key"')

# Use token
curl -sk "https://vergeos/api/v4/vms" -b "token=$TOKEN"

API测验

VM具有 is_snapshot: true 是模板，不运行虚拟机
/machine_nics?machine=<ID> 可以从其他机器返回NIC；始终按机器ID筛选
使用 fields=most 获取详细的响应，但要注意较大的有效载荷

安全考虑

自签名证书的SSL验证已禁用（在家庭实验室中很常见）
将凭据存储在环境变量或Kubernetes secrets中
尽可能使用API令牌而不是用户名/密码
HTTP服务器应位于TLS之后（由Traefik/Ingress处理）
考虑网络策略以限制对MCP服务器的访问

故障排除

连接问题

# Test VergeOS API directly
curl -sk https://your-vergeos-host/api/v4/vms -b "token=YOUR_TOKEN"

# Test MCP server
curl https://vergeos-mcp.yourdomain.com/health

令牌到期

令牌可能会过期。如果已配置，服务器将使用用户名/密码自动获取新令牌。

# Manually refresh token
curl -sk -X POST "https://your-vergeos-host/api/sys/tokens" \
  -u "admin:password" \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"password"}'

Kubernetes日志

kubectl logs -n vergeos-mcp deployment/vergeos-mcp
kubectl get pods -n vergeos-mcp

本地代理问题

# Test proxy directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node ~/.mcp/vergeos/index.js

文件结构

vergeos-mcp-server/
├── src/
│   ├── index.js           # Stdio MCP server (local use)
│   ├── http-server.js     # HTTP server (legacy)
│   ├── mcp-http-server.js # HTTP+MCP server (K8s deployment)
│   └── stdio-proxy.js     # Stdio proxy for remote server
├── local-proxy/
│   ├── package.json       # Local proxy dependencies
│   └── index.js           # Local proxy for Windsurf
├── deploy.sh              # Kubernetes deployment script
├── k8s-deployment.yaml    # Kubernetes manifests
├── package.json
├── .env.example
└── README.md

许可证

麻省理工学院