# Cloud2Local

**让云端智能体安全地操作你的本机。**

云端 Agent 本来够不着你的电脑。`Cloud2Local` 在本机开一个 **MCP Server**，把文件读写、目录浏览、白名单命令、截屏等能力暴露成标准 MCP 接口；云端填 URL + Token 即可接入。

---

## 项目特色

| 特色 | 说明 |
|---|---|
| **标准 MCP 协议** | 支持 Streamable HTTP（`/mcp`）与兼容旧客户端的 SSE（`/sse`） |
| **云端即连** | 启动后直接给出云端接入地址，可一键复制客户端配置 |
| **按需公网暴露** | 默认仅本机访问，需要时再手动开启自动暴露 |
| **鉴权与边界** | Token 鉴权、`fileRoot` 路径沙箱、命令白名单、脚本超时 |
| **本机工具箱** | `read_file` / `write_file` / `list_directory` / `run_command` / `screenshot` |
| **桌面可视化** | 状态、配置、运行日志、启停都在 GUI 里完成 |
| **跨平台** | Windows / macOS / Linux（Electron） |

> 本机已经在跑的 Agent **不必**再绕一层 MCP 调本机；这套主要给 **云端 / 远程智能体** 用。  
> 连上后工具列表由协议 `list_tools` 自动发现，不需要客户端手写工具目录。

---

## 30 秒上手

**两个端口别混：** 本机 MCP 默认 `8000`；云端访问默认公网口 **`18000`**。云端不要填 8000。

1. 启动应用，首页先连上外网通道  
2. 打开 **MCP Server** 页  
3. 设置 **Token**、收窄 **文件根目录**、确认允许命令  
4. 本机端口 `8000`，**公网端口 `18000`**，先设 Token；需要公网时再开「自动公网暴露」 → **保存** → **启动**  
5. 确认「运行中」，云端地址端口是 **18000**  
6. 云端客户端填：

```json
{
  "mcpServers": {
    "cloud-to-local": {
      "url": "http://PUBLIC_HOST:18000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

服务器至少放行：控制口 `7000` + 公网业务口 `18000`。

更细的接入步骤见 [docs/云端MCP接入教程.md](docs/云端MCP接入教程.md)。  
Skill：`docs/cloud-to-local/`（可装到 WorkBuddy 等客户端）。

---

## 安全（必读）

这是把本机能力放到网上，请当生产接口对待：

1. **Token 必开**，不要空着给公网  
2. **fileRoot 收窄**到工作目录，不要整盘  
3. **allowedCommands 只留必要命令**  
4. 不用时 **停止 Server**（若开了自动暴露会一并关掉）  
5. 有条件上 HTTPS / 反代；裸 HTTP 会明文传 Token  

---

## 开发

```bash
npm install
# Windows / 部分环境需清除 ELECTRON_RUN_AS_NODE
env -u ELECTRON_RUN_AS_NODE npm run dev

npm run build
npm run build:electron
```

技术栈：Electron + Vue3 + Vite + Element Plus + MCP SDK。

---

## License

[MIT](LICENSE)