feat: initial commit of vps-commander release v1.0.0

2026-09-28 07:48:01 +08:00
commit 467e28a6a1
48 changed files with 3851 additions and 0 deletions
@@ -0,0 +1,50 @@
+# VPS-Commander MCP (Model Context Protocol) 接入指南
+
+## 一、概述
+为了应对 OpenAI Custom GPTs 退役及新一代 Plugins/Skills 规范转型，VPS-Commander 现已全面支持标准 **MCP (Model Context Protocol)** 协议。
+
+- **零侵入**：原有 REST API、OpenAPI 3.1、Web 面板及 WebSocket 多节点连接池 100% 保持不变。
+- **纯 Go 原生**：零外部庞大框架依赖，常驻内存基线依然保持在极低水平。
+- **双模支持**：同时支持 **远程 SSE 模式** 与 **本地 stdio 模式**。
+
+---
+
+## 二、支持的 4 大 MCP Tools
+
+| Tool 名称 | 参数说明 | 描述 |
+| :--- | :--- | :--- |
+| `list_devices` | 无 | 列出当前所有已注册的受控 VPS 节点（如本机 `wjyhk` 及远程 `m4-live-agent` 等）及在线状态 |
+| `exec_command` | `device` (可选), `command` (必填), `workdir` (可选), `timeout` (可选, 默认30) | 在指定受控节点执行任意 Shell 命令并返回退出码与输出 |
+| `read_file` | `device` (可选), `path` (必填), `offset` (可选), `limit` (可选) | 读取指定受控节点的文件内容（支持安全分页读取） |
+| `write_file` | `device` (可选), `path` (必填), `content` (必填) | 在指定受控节点创建或覆写文件 |
+
+---
+
+## 三、接入方式
+
+### 方式 1：远程 SSE 模式（适用于远程 Agent、OpenAI 新生态端点）
+
+Hub 原生提供 MCP SSE 端点（需带 Bearer Token 鉴权）：
+- **SSE 建立端点**：`GET https://vpstool.kory.kdns.fr/mcp/sse`
+- **消息交互端点**：`POST https://vpstool.kory.kdns.fr/mcp/message?sessionId=<sessionId>`
+- **请求头**：`Authorization: Bearer <YOUR_API_KEY>`
+
+### 方式 2：本地 stdio 模式（适用于 Claude Desktop、Cursor、VS Code）
+
+直接使用编译好的极轻量 Go 二进制 `vps-commander-mcp-stdio-linux-amd64`。
+
+#### 客户端配置示例 (`claude_desktop_config.json` 或 Cursor MCP 设置)：
+
+```json
+{
+  "mcpServers": {
+    "vps-commander": {
+      "command": "/root/.openclaw/workspace/vps-commander/bin/vps-commander-mcp-stdio-linux-amd64",
+      "args": [
+        "-hub", "https://vpstool.kory.kdns.fr",
+        "-key", "YOUR_API_KEY"
+      ]
+    }
+  }
+}
+```