openclaw/vps-commander

Fork 0

Files

T

kory f084ac5bae

Release / Build & Release (push) Canceled after 0s

Details

feat: isolate release source for installers and provisioning

2026-10-02 15:25:19 +08:00

5.4 KiB

Raw Blame History

VPS-Commander MCP（Model Context Protocol）接入指南

本文介绍 VPS-Commander 当前 MCP 能力、客户端接入方式、工具权限以及后续 transport 演进方向。

一、MCP 总体能力

VPS-Commander 当前提供两种 MCP 接入模式：

远程 HTTP SSE 模式：适用于远程 MCP Client。
本地 stdio 模式：适用于 Claude Desktop、Cursor、VS Code 等本地客户端。

当前 MCP Server：

JSON-RPC 2.0。
server version：1.2.0。
initialize protocolVersion：2024-11-05。

当前远程 SSE 属于兼容 transport；后续新能力优先考虑 Streamable HTTP。

二、当前支持的 12 大 MCP Tools

Tool 名称	风险等级	参数/功能说明
`list_devices`	Low	列出设备、状态及资源画像
`exec_command`	High	指定节点执行 Shell
`read_file`	Low	分页读取文件
`read_multiple_files`	Low	批量读取多个文件
`create_directory`	Medium	创建目录
`move_file`	Medium	移动/重命名文件
`list_processes`	Low	查看进程
`diagnostic_command`	Low	严格白名单只读诊断，不接受任意 Shell
`edit_block`	Medium	唯一匹配 + 原子写回
`write_file`	Medium	创建或覆写文件
`list_agent_mcp`	Low	查询 Agent MCP 服务
`call_agent_mcp`	Medium	调用 Agent MCP 工具

风险等级不是客户端提示，而是 Hub 强制执行的授权门禁。

三、统一安全链路

MCP Client
    │
    ▼
Bearer Authentication
    │
    ▼
MCP JSON-RPC
    │
    ▼
Tool / Action Mapping
    │
    ▼
Authenticated Device Identity
    │
    ▼
Security Snapshot + Tool Risk
    │
    ├── DENY
    │
    ▼
Local Executor / Agent WSS
    │
    ▼
Audit

call_agent_mcp 同样必须进入 MCP risk gate，不能因为目标是 Agent MCP 就绕过 Hub 授权。

四、远程 SSE 模式

4.1 SSE 建立

GET https://your-domain.example/mcp/sse
Authorization: Bearer <YOUR_API_KEY>

服务器建立 MCP Session 后提供消息端点：

POST /mcp/message?sessionId=<sessionId>
Authorization: Bearer <YOUR_API_KEY>

4.2 注意事项

URL 中禁止放 Token。
?token=、?key=、?api_key= 不作为认证方式。
SSE 当前作为 legacy compatibility transport。

五、本地 stdio 模式

适用于 Claude Desktop、Cursor、VS Code 等本地客户端。

{
  "mcpServers": {
    "vps-commander": {
      "command": "/opt/vps-commander/vps-commander-mcp-stdio",
      "args": [
        "-hub", "https://your-domain.example",
        "-key", "YOUR_API_KEY"
      ]
    }
  }
}

API Key 不应提交到 Git 仓库。

六、主要工具参数

6.1 exec_command

device：目标节点，可选。
command：必填。
workdir：可选。
timeout：默认 30 秒，最大 300 秒。

6.2 read_file

device、path 必填。
offset 可选。
limit 默认 256 KiB，最大 1 MiB。

6.3 read_multiple_files

device 可选。
paths 必填数组。
当前 Hub 最多接受 32 个路径。

6.4 create_directory

device、path。

6.5 move_file

device、source、destination。

6.6 list_processes

device 可选。

6.7 diagnostic_command

device、action 必填。
action 仅允许：docker_ps、docker_logs、docker_inspect、systemctl_status、journalctl、ss_listen、df、free、uptime。
这是 Low 风险只读诊断通道，不接受任意 Shell；Medium 模式可使用，但 exec_command 仍保持 High。

6.7 edit_block

device、path、old_text、new_text。
old_text 必须唯一匹配。
使用 generation check + atomic write。

6.8 write_file

device、path、content。

6.9 list_agent_mcp

device 必填。

6.10 call_agent_mcp

device、server、tool 必填。
arguments 可选 JSON 对象。

七、一键安装与升级

7.1 一键安装

仓库已经提供统一安装脚本，支持 Linux amd64 与 arm64，安装时自动识别架构并从 GitHub Release 获取对应二进制。

curl -fsSL https://gitea.king.nyc.mn/openclaw/vps-commander/raw/branch/main/deploy/install.sh | sudo bash

脚本会进入交互式安装流程，可选择 Hub 或 Agent。生产环境使用时，Agent 应使用独立设备凭据，不应重新启用全局 Shared Secret。

7.2 一键升级 Agent

curl -fsSL https://gitea.king.nyc.mn/openclaw/vps-commander/raw/branch/main/deploy/upgrade-agent.sh | sudo bash

升级采用临时文件下载 → 基础完整性检查 → 旧二进制备份 → 原子替换 → systemd 重启 → 健康检查；启动失败时自动回滚旧版本。

Hub 的生产升级建议继续采用滚动发布：先完成 Release 与构建校验，再替换 Hub，确认节点重新上线后再继续后续节点。避免把 Hub 升级做成无保护的“一键重启”。

八、Agent MCP

Hub 可以发现远程 Agent 暴露的 MCP Service。

MCP Client
   ↓
Hub Authentication
   ↓
Security Gate
   ↓
Authenticated Agent
   ↓
Agent MCP Service

客户端不直接连接 Agent MCP。

八、后续演进

Streamable HTTP。
保留 SSE fallback。
Capability-based Tool Advertisement。
Principal Identity 纳入 MCP Audit Context。
长任务引入显式 Operation / Session Handle。

5.4 KiB Raw Blame History Unescape Escape