vps-commander/docs/MCP_INTEGRATION.md

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。

---

二、当前支持的 11 大 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	查看进程
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 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://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh | sudo bash

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

7.2 一键升级 Agent

curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/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。

---

八、后续演进

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