# 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 强制执行的授权门禁。

---

## 三、统一安全链路

```text
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 建立

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

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

```text
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 等本地客户端。

```json
{
  "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 获取对应二进制。

```bash
curl -fsSL https://raw.githubusercontent.com/kyaring/vps-commander/main/deploy/install.sh | sudo bash
```

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

### 7.2 一键升级 Agent

```bash
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。

```text
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。