# CloudOps MCP Server

统一云运维 MCP (Model Context Protocol) 服务器，让 AI Agent 具备**全栈云运维能力**。

一个 MCP Server 同时管理阿里云 + 腾讯云，覆盖**服务器管理、项目部署、数据库查询、文件操作、云实例查询、DNS/CDN 管理** 6 大场景，**26 个工具**。

## 版本

- 当前版本：**v1.0.0**（详见 [CHANGELOG.md](CHANGELOG.md)）。

## 文档导航

- **README.md（本文件）**：连接器总文档 —— 工具清单、**一键安装（复制粘贴给 AI）**、手动安装、配置向导、架构、工具详解、扩展指南。
- **OPERATIONS.md**：真实运维 Playbook（P1–P8），沉淀「获取密钥 / 上传 SSH 公钥 / 建立 NOPASSWD sudo / CDN 改源站」等「目标 + 流程」式实操手册。需要手动操作云控制台时优先查它。
- **CHANGELOG.md**：版本更新记录。

---

## 工具总览（26 个）

| 模块 | 工具 | 说明 |
|------|------|------|
| 服务器管理 | `server_exec`, `server_info`, `server_list`, `server_add` | SSH 远程执行命令、系统信息、服务器列表、**运行时注册服务器** |
| 项目部署 | `deploy_project`, `deploy_status` | Git 拉取/构建/重启、Docker 部署、**自定义脚本（script）部署** |
| 数据库 | `db_query`, `db_list_tables`, `db_list_databases` | SQL 查询、表管理（支持 SSH 隧道） |
| 文件管理 | `file_list`, `file_read`, `file_write`, `file_search` | 远程文件列表/读写/搜索 |
| 云平台 | `cloud_list_instances`, `cloud_instance_info` | 阿里云 ECS + SWAS(轻量) + 腾讯云 CVM + **Lighthouse(轻量)** |
| DNS/CDN | `dns_list_domains`, `dns_list_records`, `dns_create_record`, `dns_delete_record`, `cdn_list_domains`, `cdn_refresh`, `cdn_task_status` | 腾讯云 DNSPod 解析 + CDN 加速域名/缓存刷新/**刷新任务进度查询** |

## 一键安装（复制粘贴给 AI）⭐ 推荐

> 仓库已公开，任何支持第三方 MCP 的 AI 工具都能直接克隆使用。**把下面这段话原样复制给你的 AI 助手**，它会自己完成：克隆 → 读文档 → 安装依赖 → 配置 → 注册连接器 → 验证 26 个工具。适配 WorkBuddy、Hermes Agent、Claude Code、Codex CLI 等主流 Agent。**比手动安装更快，优先使用。**

```text
请帮我安装并学会使用 CloudOps MCP Server（统一云运维 MCP 连接器，GitHub: https://github.com/rowanlin-dev/cloud-ops-mcp）。

步骤：
1. 克隆仓库：git clone https://github.com/rowanlin-dev/cloud-ops-mcp.git && cd cloud-ops-mcp
2. 通读仓库内 README.md 与 OPERATIONS.md，掌握 26 个工具（server_exec / deploy_project / db_query / file_list / cloud_list_instances / dns_list_domains / cdn_refresh / cdn_task_status 等）的能力与用法
3. 安装依赖：npm install
4. 初始化配置：cp .env.example .env，然后引导我填写最小配置（至少一台 SSH 服务器：host / username / privateKey 或 password；云 AK、数据库等用到再填）
5. 按下方「各客户端注册方式」把我注册为 MCP 连接器
6. 验证：重启后应能列出 26 个工具，用 server_info 或 server_exec 测试连通

注意：.env 含云密钥、SSH 私钥路径等敏感信息，绝不可提交到 git（.gitignore 已排除）。
```

### 各客户端注册方式

把下面的 `<路径>` 换成你的实际克隆路径（如 `E:/WorkSpace/cloud-ops-mcp`、`/home/user/cloud-ops-mcp`）。
`.env` 按**源码路径**自动加载（不依赖进程启动目录），因此以下注册方式均无需额外设置工作目录。

| 客户端 | 注册方式 | 配置位置 |
|--------|---------|---------|
| **WorkBuddy** | 编辑 JSON（见下） | `~/.workbuddy/mcp.json` → `mcpServers` |
| **Hermes Agent** | 编辑 YAML（见下） | `~/.hermes/config.yaml` → `mcp_servers` |
| **Claude Code** | 一条命令 | `claude mcp add --transport stdio cloud-ops -- npx tsx <路径>/cloud-ops-mcp/src/index.ts` |
| **Codex CLI** | 编辑 TOML（见下） | `~/.codex/config.toml` → `[mcp_servers.cloud-ops]` |

**WorkBuddy**（`~/.workbuddy/mcp.json`）：

```json
{
  "mcpServers": {
    "cloud-ops": {
      "command": "npx",
      "args": ["tsx", "<路径>/cloud-ops-mcp/src/index.ts"],
      "cwd": "<路径>/cloud-ops-mcp"
    }
  }
}
```

**Hermes Agent**（`~/.hermes/config.yaml`）：

```yaml
mcp_servers:
  cloud-ops:
    command: "npx"
    args: ["tsx", "<路径>/cloud-ops-mcp/src/index.ts"]
```

**Claude Code**（一条命令，需先 `cd` 到项目目录或在项目内执行）：

```bash
claude mcp add --transport stdio cloud-ops -- npx tsx <路径>/cloud-ops-mcp/src/index.ts
```

**Codex CLI**（`~/.codex/config.toml`）：

```toml
[mcp_servers.cloud-ops]
command = "npx"
args = ["tsx", "<路径>/cloud-ops-mcp/src/index.ts"]
```

> 注册后重启对应 AI 客户端（或执行其 MCP 重载命令，如 Hermes 的 `/reload-mcp`），即可看到 `server_exec`、`deploy_project`、`db_query`、`cdn_refresh` 等 26 个工具。

## 手动安装（快速开始）

> 以下为手动安装步骤（克隆 → 配置 → 注册 → 验证）。想更快？用上面的「一键安装（复制粘贴给 AI）」让 AI 自动完成。

### 1. 克隆 & 安装

```bash
git clone <your-repo-url> cloud-ops-mcp
cd cloud-ops-mcp
npm install
```

> 项目使用 [tsx](https://github.com/privatenumber/tsx) 作为 TypeScript 运行时，无需编译步骤。

### 2. 配置

```bash
cp .env.example .env
# 编辑 .env 填入你的配置
```

**最小配置（只需 SSH）**：

```bash
SSH_HOST=your-server-ip
SSH_PORT=22
SSH_USER=root
SSH_PRIVATE_KEY=~/.ssh/id_rsa
```

完整配置项参见 `.env.example`，支持多服务器、数据库、阿里云/腾讯云 AK。

> 💡 **运行时注册服务器**：除了手改 `.env` 的 `SSH_SERVERS`，也可以用 `server_add` 工具在运行时注册（写入 `.env` 并热更新内存缓存，**无需重启连接器**）。详见下文「工具详解 → server_add」。

### 3. 注册到 MCP 客户端（任意支持第三方 MCP 的 AI 工具）

> 本连接器**不是 WorkBuddy 专属**。只要你的 AI 工具满足两点即可使用：
> 1. 能安装 **kimi-webbridge** 这个 skill（用于无公开 API 的控制台自动化兜底）；
> 2. 支持安装**第三方 MCP 连接器**（stdio 协议）。
> 常见如 WorkBuddy、Claude Desktop、Cursor、VS Code（Cline/Continue 等扩展）均可。

通用注册片段（把 `/absolute/path/to/cloud-ops-mcp` 换成你的实际路径）：

```json
{
  "mcpServers": {
    "cloud-ops": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/cloud-ops-mcp/src/index.ts"],
      "cwd": "/absolute/path/to/cloud-ops-mcp"
    }
  }
}
```

各客户端配置文件位置：

| 客户端 | 配置文件路径 |
|--------|-------------|
| WorkBuddy | `~/.workbuddy/mcp.json`（`mcpServers` 键） |
| Claude Desktop | macOS `~/Library/Application Support/Claude/claude_desktop_config.json`；Windows `%APPDATA%\Claude\claude_desktop_config.json` |
| Claude Code | `claude mcp add --transport stdio cloud-ops -- npx tsx <路径>/src/index.ts`（存入 `~/.claude.json`） |
| Codex CLI | `~/.codex/config.toml`（`[mcp_servers.cloud-ops]`） |
| Hermes Agent | `~/.hermes/config.yaml`（`mcp_servers` 键） |
| Cursor | `~/.cursor/mcp.json`（或项目 `.cursor/mcp.json`） |
| VS Code（Cline/Continue） | 扩展设置中的 MCP 配置项 |

> `cwd` 必须指向项目根目录，MCP Server 需要从该目录加载 `.env` 和 `node_modules`。
> 配置向导默认**不会**自动改写任何客户端的 MCP 配置；如需向导自动写入，可设置环境变量 `CLOUD_OPS_MCP_CONFIG_PATH` 指向目标配置文件路径（可选）。

### 4. 验证

```bash
# 测试阿里云工具
npx tsx src/test-aliyun.ts

# 测试 SSH 工具
npx tsx src/test-ssh.ts

# 直接启动 MCP Server（查看日志）
npx tsx src/index.ts
```

## 配置向导（推荐）

配置向导是一个 **Web UI**，让你用浏览器可视化编辑 `.env` 的全部内容——既能**自动获取**（依赖 Kimi WebBridge 扫云控制台）云实例与密钥并回填，也能**手动填写** SSH 私钥路径、远程登录密码、数据库账号密码、部署默认等所有字段。0 基础用户也能直接上手。

> 你仍可以随时直接手改 `.env` 文件（参见 `OPERATIONS.md` 手动 playbook）；向导只是更友好的入口，不是唯一方式。

### 需要先准备哪些配置（必要 / 可选）

| 配置项 | 必要 / 可选 | 作用 | 填写方式 |
|--------|------------|------|---------|
| SSH 服务器（`SSH_SERVERS` 或 `SSH_HOST`） | **必要** | 远程命令执行 / 部署 / 数据库隧道 | 向导自动获取或手动填 |
| 数据库（`DATABASES`） | 可选 | MySQL 查询（可走 SSH 隧道） | 仅手动填 |
| 阿里云（`ALIBABA_CLOUD_*`） | 可选 | 查询 ECS / SWAS 实例 | 向导自动获取或手动填 |
| 腾讯云（`TENCENT_CLOUD_*`） | 可选 | 查询 CVM / Lighthouse、CDN 刷新、DNSPod | 向导自动获取或手动填 |
| 部署默认（`DEPLOY_DEFAULT_*`） | 可选 | `deploy_project` 默认构建/重启命令 | 仅手动填 |

> 只有 SSH 服务器是必须的；云 AK、数据库、部署默认都是「用到才配」。纯手动部署（如只 `server_exec` + `deploy_project`）可只配 SSH。

### 前置条件

- [Kimi WebBridge](https://github.com/nicepkg/kimi-webbridge) 浏览器自动化守护进程（`npm run config` 会自动检测 / 启动 / 安装；也可手动装）
- 浏览器扩展需手动安装：https://www.kimi.com/zh-cn/features/webbridge

> **Kimi WebBridge 的定位**：它用于那些**没有干净公开 API 的控制台操作**（例如扫码登录云厂商控制台、读取 AK/SK、部分 CDN 高级配置）。对于已有公开 API 的能力（密钥配置、CDN 缓存刷新、实例查询等），优先使用工具自动化，Kimi WebBridge 是「无 API 时的可选兜底」。

### 使用步骤

```bash
# 1. 启动配置向导（会自动检测 / 启动 / 安装 Kimi WebBridge，无需手动先 start）
npm run config

# 2. 打开浏览器访问 http://localhost:3456
# 3. 点击「阿里云全自动配置」或「腾讯云全自动配置」
# 4. 扫码登录云控制台（唯一手动步骤）
# 5. 向导自动读取服务器实例（阿里云同时扫描 ECS + SWAS 轻量服务器，腾讯云扫描 CVM + Lighthouse）和 AK/SK
# 6. 点击「保存配置」完成
```

> **Kimi WebBridge 自动处理**：`npm run config` 会自动检测守护进程——已在运行则直接用；已安装未运行则自动启动；未安装则按官方命令自动安装（Windows: `irm https://cdn.kimi.com/webbridge/install.ps1 | iex`；macOS/Linux: `curl -fsSL https://cdn.kimi.com/webbridge/install.sh | bash`）再启动。自动安装失败或你想手动时，按上面命令自行安装即可。

> ⚠️ **浏览器扩展需手动安装**：守护进程可自动化安装，但浏览器扩展（让守护进程接管你真实浏览器会话）无法自动安装，请到 https://www.kimi.com/zh-cn/features/webbridge 手动安装并登录。WebBridge 仅用于「云 AK 自动获取」兜底；**未安装时向导仍可手动填写 .env，不阻断**。

### RAM 用户（推荐，自动）

阿里云与腾讯云在「创建密钥」时都会弹出**建议使用 RAM/子账号而非主账号密钥**的确认框。配置向导现在会**识别该弹窗并自动转入子用户流程**：

1. 在 RAM/CAM 控制台创建专用子用户 `cloud-ops-mcp`（勾选编程访问）；
2. 为该子用户生成 AccessKey，读取 KeyId/Secret；
3. 尽力附加连接器所需的最小权限策略（ECS/SWAS/Lighthouse 只读、CDN 刷新、DNS 解析）；
4. 把**子用户密钥**写入 `.env`，绝不落主账号密钥。

若自动附加策略失败，向导会生成 `MANUAL_STEPS.md`，内含需手动附加的最小权限策略 JSON，按步骤补齐即可。所有控制台 UI 检测信号均为可配置列表，识别失败时一律降级为手动步骤，不会把「点过弹窗」误判为成功。

> 最小权限（禁用全管理员 `AdministratorAccess` / `QcloudAdministrator`）：阿里云 `AliyunECSReadOnlyAccess` / `AliyunSWASReadOnlyAccess` / `AliyunCDNFullAccess` / `AliyunDNSFullAccess`；腾讯云 `QcloudCVMReadOnlyAccess` / `QcloudLighthouseReadOnlyAccess` / `QcloudCDNFullAccess` / `QcloudDNSPodFullAccess`。

### 重跑向导的幂等行为（重要）

配置向导**可安全反复运行**，已针对「重复造 AK / 重复建子用户」做了幂等处理：

1. **已有 AK 不会重复获取**：`.env` 里已存在阿里云 `ALIBABA_CLOUD_ACCESS_KEY_ID` 时，点「阿里云全自动配置」会**默认保留现有配置**、跳过浏览器自动获取，并在日志提示「已保留现有」。若确实要重新抓取，**点击「重新获取」按钮**即可（走强制刷新路径）。
2. **RAM/CAM 子用户自动复用**：向导固定使用名为 `cloud-ops-mcp` 的子用户。重跑时先查该子用户是否已存在——**存在则复用，不会重复创建**（阿里云 `CreateUser` 同名会直接报错，这正是早期重复运行的坑）。
3. **AccessKey 轮换而非堆积**：复用既有子用户时，向导会先清理该子用户下已有的 AccessKey（best-effort），再新建一对写入 `.env`，避免密钥超过 2 把上限或长期堆积。
4. **留痕方便清理**：凡经向导创建/复用 RAM 子用户，都会在 `.env` 写入 `ALIYUN_RAM_USER=cloud-ops-mcp` 标记。日后想彻底移除时，到阿里云 RAM 控制台删除该子用户即可（删除前请确认连接器不再使用其密钥）。

> 一句话：反复点「全自动配置」是安全的——它要么保留、要么复用、要么轮换，不会凭空多出子用户或密钥。

### 配置完成后关闭守护进程

```bash
# 1. 关闭配置向导（在运行 npm run config 的终端按 Ctrl+C）

# 2. 关闭 Kimi WebBridge 守护进程
# Windows PowerShell:
& "$env:USERPROFILE\.kimi-webbridge\bin\kimi-webbridge.exe" stop

# 验证已关闭（无输出或进程不存在即已停止）
& "$env:USERPROFILE\.kimi-webbridge\bin\kimi-webbridge.exe" status
```

> 配置向导是可选的。手动编辑 `.env` 文件永远可用（参见 `OPERATIONS.md` 中的手动 playbook）。

### 配置向导 API 接口

向导后端（Express）暴露以下接口，供前端调用：

| 接口 | 方法 | 功能 |
|------|------|------|
| `GET /api/daemon-status` | GET | 检查 Kimi WebBridge 守护进程状态 |
| `GET /api/get-config` | GET | 读取当前 `.env` 全量配置（SSH/数据库/云平台/部署），用于表单回填 |
| `POST /api/save-config` | POST | 接收完整表单，**全量写回** `.env`（含 DATABASES / SSH_PASSWORD / DEPLOY_*，不再丢失） |
| `POST /api/auto-config-aliyun` | POST | 阿里云全自动配置（ECS + AK/SK） |
| `POST /api/auto-config-tencent` | POST | 腾讯云全自动配置（CVM + AK/SK） |
| `POST /api/check-login` | POST | 检查用户是否已登录云控制台 |
| `POST /api/generate-config` | POST | 兼容接口：合并写入 `SSH_SERVERS` 与云 AK（保留旧行为） |

### 全自动流程（简述）

- **阿里云**：打开 ECS 控制台 → 检测/扫码登录 → 从实例列表提取 IP 与名称 → 跳 RAM「API 密钥」→ 识别「建议用 RAM 用户」弹窗并转子用户流程 → 取 AK/SK → 回填表单。
- **腾讯云**：打开 CVM 控制台 → 检测/扫码登录 → 提取实例 → 跳 CAM「API 密钥」→ 识别弹窗转子用户流程 → 取 SecretId/Key → 回填表单。

> 两朵云可分别点击，配置会**合并进同一个 `.env`**。

### 注意事项

1. **浏览器自动化可能需要微调**：云控制台页面结构会变，自动提取失败时会展示页面预览便于排查。
2. **SecretKey 可能无法自动提取**：部分云平台安全策略会隐藏 Secret，此时需手动复制粘贴。
3. **SSH 密钥路径**：自动配置默认 `~/.ssh/id_rsa`，若路径不同请在配置预览中手动修改（Windows 下建议用 `/C:/Users/<LOCAL_USER>/.ssh/...` 绝对路径）。
4. **多云平台合并**：可分别点击阿里云 / 腾讯云按钮，两边配置会合并进同一个 `.env`。

## 架构

```
AI Agent（任意支持 MCP 的客户端，如 Claude / Cursor / WorkBuddy）
        │
    MCP Protocol (stdio)
        │
CloudOps MCP Server (TypeScript + tsx)
   │       │       │       │       │       │
 server   deploy    db     file    cloud    dnscdn   ← 工具模块 (26 tools)
   │       │       │       │       │       │
   SSH    MySQL   Git   AliSDK  TcSDK   DNSPod/CDN SDK
   │       │       │       │       │       │
   Alibaba Cloud / Tencent Cloud                  ← 目标云平台
   (ECS, SWAS, CVM, Lighthouse, CDN, DNSPod)

Kimi WebBridge（可选）── 浏览器自动化，兜底无公开 API 的控制台操作
```

## 项目结构

```
cloud-ops-mcp/
├── src/
│   ├── index.ts                 # MCP Server 主入口
│   ├── config.ts                # 配置加载（.env + 环境变量）+ 运行时 server_add
│   ├── types.ts                 # TypeScript 类型定义
│   ├── clients/
│   │   ├── ssh.ts               # SSH 客户端 (ssh2)
│   │   ├── aliyun.ts            # 阿里云客户端 (ECS + SWAS)
│   │   ├── tencent.ts           # 腾讯云客户端 (CVM + Lighthouse，整包命名空间)
│   │   ├── cdn.ts               # 腾讯云 CDN 客户端
│   │   └── dnspod.ts            # 腾讯云 DNSPod 客户端
│   ├── tools/
│   │   ├── server.ts            # 服务器管理 (exec/info/list/add)
│   │   ├── deploy.ts            # 项目部署
│   │   ├── database.ts          # 数据库
│   │   ├── file.ts              # 文件管理
│   │   ├── cloud.ts             # 云实例查询 (ECS/SWAS/CVM/Lighthouse)
│   │   └── dnscdn.ts            # DNSPod + CDN 管理
│   ├── utils/
│   │   └── logger.ts            # 日志
│   ├── config-wizard/           # 配置向导（可选，依赖 Kimi WebBridge）
│   │   ├── server.cjs           # 向导后端
│   │   └── web/                 # 向导前端
│   ├── test-aliyun.ts           # 阿里云工具测试
│   └── test-ssh.ts              # SSH 工具测试
├── .env.example                 # 配置模板
├── .gitignore
├── package.json
├── tsconfig.json
├── OPERATIONS.md                # 运维 Playbook（P1–P7 实操手册）
└── README.md                    # 项目总文档（本文件）
```

## 工具详解

### server_exec — 远程命令执行

```
参数: server(服务器名), command(命令), cwd(可选), timeout(可选, 默认60s, 最大600s)
超时: 默认 60 秒；构建/部署等长命令请显式加大 timeout；超时错误会附带提示
示例: 在 Tencent-LH 服务器上执行 docker ps
```

### server_add — 运行时注册 SSH 服务器

```
参数: name, host, port(默认22), username, privateKey(可选), password(可选)
行为: 写入 .env 的 SSH_SERVERS 并热更新内存缓存，无需重启连接器即可被 server_exec 使用
示例: server_add(name="Tencent-LH", host="<LIGHTHOUSE_PUBLIC_IP>", port=22, username="<SSH_USER>", privateKey="C:/Users/xxx/.ssh/id_ed25519")
注意: 特权写文件请用 `echo x | sudo tee file`，勿用 `sudo cmd > file`（重定向由非 sudo shell 执行会 Permission denied）
```

### deploy_project — 项目部署

```
参数: server, projectPath, method(git-pull|upload|docker|script), branch, scriptCommand, buildCommand, restartCommand
示例: 将 /data/www/myapp 拉取最新代码并重启
script 方式: method="script", scriptCommand="bash /tmp/deploy_backend.sh" —— 在 projectPath 下执行自定义部署脚本
           （适合「备份→停服→换包→启服」这类现成脚本化流程，执行超时 5 分钟）
```

### db_query — 数据库查询

```
参数: database(配置名), query(SQL), maxRows(默认100)
安全: 自动阻止 DROP/TRUNCATE/ALTER 等危险操作
```

### file_read / file_write / file_search — 文件操作

```
file_read:   读取远程文件内容（支持 tail 模式用于日志）
file_write:  写入内容到远程文件（建议配合 sudo tee 使用）
file_search: 用 grep 搜索文件内容
```

### cloud_list_instances — 云实例列表

```
参数: provider(aliyun|tencent|all, 默认all)
支持:
  - 阿里云 ECS + SWAS(轻量应用服务器)   ← SWAS 自动扫描多个区域
  - 腾讯云 CVM(云服务器) + Lighthouse(轻量应用服务器)
```

### cdn_refresh — CDN 缓存刷新（自动化，无需进控制台）

```
参数: urls(URL/目录列表), type(url|path)
示例: cdn_refresh(urls=["https://<YOUR_DOMAIN>/","https://<YOUR_DOMAIN>/index.html"], type="url")
注意: type=path 时每个目录路径必须以 / 结尾（如 https://<YOUR_DOMAIN>/assets/），否则校验失败
```

### cdn_task_status — CDN 刷新任务进度查询（v1.0.0 新增）

```
参数: taskId(可选，cdn_refresh 返回的任务ID), limit(默认10)
示例: cdn_task_status(taskId="<TASK_ID>") —— 查询任务是否 done/process/fail
用途: 刷新后轮询任务状态，替代「等 60 秒盲查 CDN」；留空可查最近记录
```

> 更多「目标 + 流程」式手动操作说明（获取密钥、上传 SSH 公钥、建立 NOPASSWD sudo、CDN 改主源站等），参见 **`OPERATIONS.md`**。

## 常见使用场景

以下是 AI Agent 通过自然语言驱动连接器的典型流程：

- **查看服务器状态**：「看看 Tencent-LH 的 CPU 和内存」 → `server_info` → 表格展示。
- **部署项目**：「把 myapp 部署到 Tencent-LH」 → `deploy_project`（SSH 拉取最新代码 → 构建 → 重启）。
- **查询数据库**：「查 prod-db 用户表前 10 条」 → `db_query`（经 SSH 隧道连库，自动拦截危险 SQL）。
- **管理云资源**：「列出腾讯云广州区所有 Lighthouse 实例」 → `cloud_list_instances tencent`。
- **刷新 CDN**：「刷新 <YOUR_DOMAIN> 缓存」 → `cdn_refresh`。

## 支持的云平台

| 平台 | 产品 | SDK |
|------|------|-----|
| 阿里云 | ECS (弹性计算服务) | `@alicloud/ecs20140526` |
| 阿里云 | SWAS (轻量应用服务器) | `@alicloud/swas-open20200601` |
| 腾讯云 | CVM (云服务器) | `tencentcloud-sdk-nodejs` (整包 `cvm` 命名空间) |
| 腾讯云 | Lighthouse (轻量应用服务器) | `tencentcloud-sdk-nodejs` (整包 `lighthouse` 命名空间) |
| 腾讯云 | CDN (内容分发网络) | `tencentcloud-sdk-nodejs-cdn` |
| 腾讯云 | DNSPod (域名解析) | `tencentcloud-sdk-nodejs-dnspod` |

> 腾讯云 SDK 采用**整包 `tencentcloud-sdk-nodejs`** 并按命名空间访问（`cvm` / `lighthouse`），避免引入未安装的产品分包导致 "Cannot find module" 错误。整包与各产品分包均放在 `optionalDependencies` 中，未安装不影响其他功能。

## 操作理念：自动化优先，手动有 playbook

连接器的设计边界（来自 owner 定义）：

1. **操作阿里云/腾讯云公开 API** —— 凡有干净 API 的（密钥配置、CDN 刷新、实例查询、DNS 解析），优先用工具自动化。
2. **通过 SSH 连接云服务器执行命令** —— `server_add` 注册 + `server_exec` 远程执行。
3. **（可选）调用 Kimi WebBridge 浏览器自动化** —— 用于没有公开 API 的控制台操作（扫码登录、读取 AK/SK、部分 CDN 高级配置）。
4. **用户手动操作时必须给「目标 + 流程」说明** —— 缺 API 能力的，由连接器产出标准步骤，由人去控制台执行。

具体 playbook（含命令、控制台路径、已知坑）统一维护在 **`OPERATIONS.md`**。

## 安全特性

- SSH 密钥认证优先于密码
- 数据库查询自动阻止危险操作 (DROP/TRUNCATE/ALTER)
- 所有敏感配置（云 AK、SSH 私钥路径）通过 `.env` 管理，`.env` 已在 `.gitignore` 中排除；SSH 私钥实体请放在你自己的安全位置（如 `~/.ssh/`），经 `privateKey` 字段按路径引用，勿纳入项目目录
- SQL 注入防护（参数化查询，限制结果集大小）
- 命令执行超时机制（默认 60s，最大 10 分钟，可调）
- CDN 刷新目标输入校验（URL 须 http(s):// 开头；目录刷新路径须以 / 结尾）
- `server_add` 写入 `.env` 时做同名校验，避免覆盖已有服务器
- `.env` 文件建议权限设为仅用户可读写（`chmod 600 .env`）
- 定期轮换云服务 AK/密钥；为连接器创建专用云子账号并遵循最小权限（详见上文「配置向导 → RAM 用户」）

## 扩展指南

### 添加新工具

1. 在 `src/tools/` 下创建新模块
2. 导出 `registerXxxTools(server: McpServer)` 函数
3. 在 `src/index.ts` 中注册

### 添加新的云平台 / 产品

1. 在 `src/clients/` 下创建或扩展 SDK 封装（优先复用整包 `tencentcloud-sdk-nodejs` 的命名空间）
2. 在 `src/config.ts` 添加配置类型
3. 在 `src/tools/cloud.ts` 添加工具

## 许可证

MIT