使用说明

项目简介

'vers-cli' 是一个用于管理基于虚拟机/容器的开发环境的命令行工具。它包含一个实验性的 MCP 服务器，可以将 Vers CLI 的核心操作（如启动、分支、删除虚拟机、在虚拟机中执行命令）和环境状态作为工具和资源提供给遵循 Model Context Protocol (MCP) 的 LLM 客户端。这使得 LLM 能够理解和操作开发环境，从而增强自动化和智能助理的能力。

主要功能点

虚拟机管理: LLM 客户端可以通过调用工具启动、分支和删除虚拟机环境。
命令执行: LLM 客户端能够远程在指定的虚拟机中执行命令，并接收流式输出和结构化结果。
状态查询: LLM 客户端可以获取所有虚拟机或特定虚拟机的实时状态快照，作为资源访问或通过工具调用获取。
会话感知: 支持通过 MCP 会话日志流式传输命令输出，并处理会话管理和能力声明。
安全与控制: 支持 HTTP 传输的认证，并对工具调用实施基础的速率限制。

安装步骤

'vers-cli' MCP 服务器作为其主二进制文件的一部分。

确保你已安装 Go 语言环境 (版本 1.18 或更高)。

通过以下命令安装 'vers-cli'：

go install github.com/hdresearch/vers-cli/cmd/vers@latest

这将在你的 '$GOPATH/bin' 目录下生成 'vers' 可执行文件。

（可选）如果你需要从源代码手动构建，可以克隆仓库并运行：

git clone https://github.com/hdresearch/vers-cli.git
cd vers-cli
go build -o bin/vers ./cmd/vers

MCP 服务器功能将包含在生成的 'bin/vers' 可执行文件中。

服务器配置

MCP 服务器可以通过标准输入/输出 (stdio) 或 HTTP/SSE 协议运行。LLM 客户端需要知道如何启动服务器并与其通信。以下是两种传输模式的示例配置信息：

通过 Stdio 传输协议启动 (适用于本地代理)

此模式通过标准输入/输出进行通信，通常用于与本地运行的 LLM 代理（如 Claude Desktop/Code）集成。

{
  "server_name": "vers-mcp-stdio",
  "command": "/path/to/your/vers",
  "args": ["mcp", "serve", "--transport", "stdio"],
  "description": "通过标准输入/输出与 Vers CLI MCP 服务器通信。请确保 VERS_URL 和 VERS_API_KEY 环境变量已设置。",
  "env": {
    "VERS_URL": "https://api.vers.sh",
    "VERS_API_KEY": "your_vers_api_key"
  }
}

'server_name': 服务的唯一名称，例如 'vers-mcp-stdio'。
'command': 'vers-cli' 可执行文件的完整路径，例如 '/home/user/go/bin/vers' 或 './bin/vers'。
'args': 启动 MCP 服务器的命令行参数。'mcp serve' 命令用于启动服务器，'--transport stdio' 指定使用标准输入/输出进行通信。
'description': 服务器功能的简要说明。
'env': 重要: MCP 服务器会调用 Vers 后端服务，因此必须在环境中设置 'VERS_URL' 和 'VERS_API_KEY'。请将 'your_vers_api_key' 替换为你的实际 API 密钥。

通过 HTTP/SSE 传输协议启动 (适用于 MCP 连接器)

此模式通过 HTTP/SSE 进行通信，通常用于通过 MCP 连接器或远程 LLM 客户端集成。

{
  "server_name": "vers-mcp-http",
  "command": "/path/to/your/vers",
  "args": ["mcp", "serve", "--transport", "http", "--addr", ":3920"],
  "http_url": "http://localhost:3920",
  "http_headers": {
    "Authorization": "Bearer your_secret_token"
  },
  "description": "通过 HTTP/SSE 与 Vers CLI MCP 服务器通信。推荐设置 VERS_MCP_HTTP_TOKEN 进行认证。请确保 VERS_URL 和 VERS_API_KEY 环境变量已设置。",
  "env": {
    "VERS_URL": "https://api.vers.sh",
    "VERS_API_KEY": "your_vers_api_key",
    "VERS_MCP_HTTP_TOKEN": "your_secret_token"
  }
}

'server_name': 服务的唯一名称，例如 'vers-mcp-http'。
'command': 'vers-cli' 可执行文件的完整路径。
'args': 启动 HTTP 传输的 MCP 服务器的命令行参数。'--transport http' 指定 HTTP 传输，'--addr :3920' 指定监听端口。
'http_url': MCP 服务器的 HTTP 地址，LLM 客户端将连接到此地址。
'http_headers': HTTP 请求头，用于 HTTP 认证。'VERS_MCP_HTTP_TOKEN' 环境变量的值将用作 'Authorization' 头中的 'Bearer' 令牌。请将 'your_secret_token' 替换为你的秘密令牌。
'description': 服务器功能的简要说明。
'env': 重要: 除了 'VERS_URL' 和 'VERS_API_KEY'，你还可以在这里设置 'VERS_MCP_HTTP_TOKEN' 环境变量，用于 HTTP 认证。请将 'your_vers_api_key' 和 'your_secret_token' 替换为你的实际 API 密钥和秘密令牌。

基本使用方法

MCP 服务器不是直接由用户交互的，而是由 LLM 客户端自动调用。LLM 客户端会以 JSON-RPC 请求的形式调用这些功能。以下是一些 LLM 客户端可能使用的功能示例：

获取虚拟机状态 (资源): LLM 客户端可以请求 'vers://status' 资源来获取所有虚拟机或特定虚拟机的 JSON 格式状态快照。

获取虚拟机状态 (工具): LLM 客户端可以调用 'vers.status' 工具来获取虚拟机状态。例如，LLM 可能会发送一个请求来获取名为 'my-dev-vm' 的虚拟机的状态：

{
  "jsonrpc": "2.0",
  "method": "tool_code/vers.status",
  "params": {
    "target": "my-dev-vm"
  },
  "id": 1
}

启动新的开发环境 (工具): LLM 客户端可以调用 'vers.run' 工具来启动一个新的虚拟机。例如，LLM 可能会发送一个请求来启动一个具有特定内存和 CPU 配置的虚拟机：

{
  "jsonrpc": "2.0",
  "method": "tool_code/vers.run",
  "params": {
    "memSizeMib": 2048,
    "vcpuCount": 2,
    "vmAlias": "new-env-for-llm"
  },
  "id": 2
}

在虚拟机中执行命令 (工具): LLM 客户端可以调用 'vers.execute' 工具来在指定虚拟机中执行命令。例如，LLM 可能会发送一个请求在 'my-dev-vm' 中运行 'ls -l /app'：

{
  "jsonrpc": "2.0",
  "method": "tool_code/vers.execute",
  "params": {
    "target": "my-dev-vm",
    "command": ["ls", "-l", "/app"],
    "timeoutSeconds": 60
  },
  "id": 3
}

删除虚拟机 (工具): LLM 客户端可以调用 'vers.kill' 工具来删除虚拟机。请注意，对于删除操作，通常需要设置 'skipConfirmation' 为 'true'。

{
  "jsonrpc": "2.0",
  "method": "tool_code/vers.kill",
  "params": {
    "targets": ["my-dev-vm"],
    "skipConfirmation": true
  },
  "id": 4
}

关键词