# Ops Automation MCP 用户使用手册

适用版本：`3.1.x`

`ops-automation-mcp-ts` 是一个无状态运维 MCP。它提供 SSH、Docker、K3s、Systemd、Jenkins、Nacos、镜像部署和 HTTP/HTTPS 路由接口，但不保存公司环境配置，也不会根据服务器名称、环境名称或域名猜测目标。

## 1. 安装

在支持 MCP 的客户端中加入：

```toml
[mcp_servers.ops_automation]
type = "stdio"
command = "npx"
args = ["-y", "ops-automation-mcp-ts@3"]
```

生产环境建议固定补丁版本：

```toml
args = ["-y", "ops-automation-mcp-ts@3.1.2"]
```

本地开发：

```bash
npm install
npm run build
node dist/index.js
```

启动 MCP 不会创建 `~/.ops-automation`、YAML 配置或服务目录。

## 2. 一个 Codex Skill，两个部分

Skill 可以同时包含通用规则和本地环境资料：

```text
~/.codex/skills/ops-automation-mcp/
├── SKILL.md
├── agents/
├── procedures/             # 通用流程，随 npm 发布
└── references/             # 用户本地维护，不发布到 npm
    ├── servers.md
    ├── services.md
    ├── jenkins.md
    ├── nacos.md
    ├── deployment.md
    └── routing.md
```

`SKILL.md` 负责入口边界；`procedures/` 提供通用流程和安全规则；`references/` 可以使用 Markdown、YAML、JSON 或自然语言，负责记录服务器、服务、Jenkins、Nacos、部署和路由资料。Agent/Skill 可以读取 references 并提取参数，但 MCP 永远不会读取这些文件。

`agents/openai.yaml` 只负责 Codex 界面的显示名称、简介和默认提示，不保存服务器或业务规则。公开 npm 包包含入口、界面元数据和通用 procedures；`references/` 不发布，用户可在安装后的同一 Skill 目录自行维护。

没有 references 时，Agent 必须向用户索要缺失的连接、端口、路径、namespace、group 和流程参数，不能读取旧配置或使用历史值猜测。

仓库不会在 MCP 启动时自动复制 Skill，也不会创建、读取或修改 `.ops-automation` 配置。references 缺失时这是预期状态，不是安装失败。

## 3. 显式参数模型

每次调用都传入完整目标。常用连接对象如下：

```json
{
  "host": "<host-or-ip>",
  "port": 22,
  "user": "<ssh-user>",
  "password": "<password>",
  "privateKeyPath": "<local-private-key>"
}
```

密码和私钥二选一。Jenkins 和 Nacos 使用：

```json
{
  "jenkins": {
    "endpoint": "https://<jenkins-host>",
    "auth": { "username": "<username>", "token": "<token>" }
  },
  "nacos": {
    "endpoint": "https://<nacos-host>",
    "auth": { "username": "<username>", "password": "<password>" },
    "apiVersion": "auto",
    "contextPath": "/nacos"
  }
}
```

MCP 不自动填充 `public`、`DEFAULT_GROUP`、TQ、ZH、测试环境或任何公司默认值。

## 4. 确认模型

所有会产生副作用的操作遵循：

```text
预览/检查 → 返回一次性审阅令牌 → 用户确认 → 仅凭令牌执行
```

令牌只保存在当前 MCP 进程内，过期、重放、参数变化、目标变化或远程文件变化都会导致执行失败。`warning`、`recommendation`、`next_action` 只是提示，不代表用户授权。旧的 `confirm_*` 布尔参数不能代替令牌。

典型执行入口：

| 操作 | 预览 | 执行 |
|---|---|---|
| 远程危险命令 | `execute_prepare` | `execute_execute` |
| 启动服务 | `service_start` | `service_start_execute` |
| 重启服务 | `service_restart` | `service_restart_execute` |
| 停止服务 | `service_stop` | `service_stop_execute` |
| 镜像部署 | `deploy_image_auto` | `deploy_image_execute` |
| 域名路由 | `configure_company_domain` | `configure_company_domain_execute` |
| Jenkins 构建 | `jenkins_do_build` | `jenkins_do_build_execute` |
| Jenkins 创建项目 | `jenkins_ensure_project` | `jenkins_ensure_project_execute` |
| Nacos 删除 | `nacos_prepare_delete` | `nacos_do_delete` |

## 5. 服务器和服务查询

### 查询服务器

使用 `list_servers` 查看调用方提供的目标，使用 `query_servers` 查询 CPU、内存和磁盘：

```json
{
  "targets": [{
    "name": "<display-name>",
    "environment": "<environment>",
    "runtime": "docker",
    "connection": { "host": "<host>", "user": "<user>", "privateKeyPath": "<key>" }
  }]
}
```

### 查询和扫描服务

- `service_find`：在一个明确目标上查找服务。
- `service_list`：列出一个明确目标上的服务。
- `service_scan`：扫描本次传入的多个目标，不写入本地服务目录。
- `service_status`、`service_logs`：实时获取状态和日志。

服务操作始终传入 `runtime`、`connection`、`service`。K3s 还必须传入 `namespace`；状态、日志、启动、重启和停止必须传入实际的 `resource_kind`（`deployment` 或 `statefulset`）。

## 6. 远程命令

安全检查：

```json
{
  "command": "docker ps",
  "connection": { "host": "<host>", "user": "<user>", "privateKeyPath": "<key>" }
}
```

先调用 `prepare_execute` 查看命令风险。需要确认的命令调用 `execute_prepare` 获取令牌，经用户确认后调用 `execute_execute`。致命命令会直接拒绝。

远程执行结果统一包含：

```json
{ "stdout": "...", "stderr": "...", "exitCode": 0 }
```

非零退出码返回 MCP 错误。密码、Token、私钥路径不会出现在输出、错误或日志中。

## 7. Jenkins 和 Git 部署

Jenkins 工具不读取本地配置，所有调用都传入：

```json
{
  "jenkins": {
    "endpoint": "https://<jenkins-host>",
    "auth": { "username": "<username>", "token": "<token>" }
  }
}
```

推荐流程：

1. 用 `jenkins_list_views`、`jenkins_list_jobs` 和 `jenkins_list_branches` 查询目标。
2. 用 `jenkins_menu` 或 `jenkins_do_build` 生成构建令牌。
3. 用户确认后调用 `jenkins_do_build_execute`。
4. 用 `jenkins_wait_build` 等待构建结果。

如果项目不存在，只有明确 HTTP 404 才会进入创建流程。401、403、429、500、网络错误或认证错误会直接停止。创建新项目必须由调用方提供完整 `project_xml`，MCP 不生成公司模板。

`deploy_frontend_auto` 和 `deploy_backend_auto` 还必须显式提供 SSH 目标、部署目录、构建参数和 `deployment_command`。构建暂停时只返回 `paused` 状态和构建地址，不伪造部署成功。

Git 地址继续走 Jenkins；容器镜像应使用 `deploy_image_auto`。

## 8. Nacos 配置管理

版本、context path 或认证方式不明确时，先调用：

```text
nacos_discover
→ nacos_list_namespaces
→ nacos_list_groups
```

常用工具：

- `nacos_list_configs`：列出配置。
- `nacos_get_config`：读取单条配置。
- `nacos_publish`：新增或修改配置。
- `nacos_prepare_publish`：只预览差异。
- `nacos_prepare_delete` / `nacos_do_delete`：预览并删除。

单条配置操作必须显式传入 `dataId`、`namespace` 和 `group`。发布/修改在参数明确后可以直接执行；删除始终需要确认令牌。`expected_fingerprint` 用于防止覆盖外部刚修改的内容。

读取和预览会脱敏 `password`、`passwd`、`token`、`secret`、`api-key`、`access-key` 等字段；指纹仍然基于原始内容计算。

## 9. Docker/K3s 镜像部署

`deploy_image_auto` 只接受容器镜像。镜像必须带 tag 或 digest，MCP 不会自动补 `latest`。必须明确提供：

- `service`、`image`、`runtime`；
- SSH `connection` 和绝对 `deployDir`；
- 每个端口的容器端口、对外端口、`protocol`（TCP/UDP）和 `scheme`（例如 http/https）；
- K3s 的 `cluster`、`namespace`、`resourceKind`、`serviceType`；
- 每个挂载的 host/container 路径及存储策略；
- 私有仓库凭证（如需要）；
- 环境变量和健康检查信息（如需要）。

Docker 生成 `docker-compose.yml`，K3s 生成 `<service>.yaml`。K3s 的 PVC、hostPath、StorageClass、节点、Deployment/StatefulSet 和 Service 类型都必须由调用方选择，MCP 不隐式使用 `10Gi`、`LoadBalancer` 或默认节点。

Docker 使用 HTTPS 时还必须显式提供 TLS 证书和私钥的绝对路径；上游服务协议也必须明确传入。

执行阶段分别处理：

```text
环境初始化 → 文件写入 → 镜像部署 → LoadBalancer 无地址时的 NodePort 降级
```

每一步都有独立令牌。私有仓库登录通过 stdin 或受限临时文件处理，凭证不会出现在命令参数、预览、错误或返回值中。Git URL 不应调用此工具。

## 10. HTTP/HTTPS 域名路由

`configure_company_domain` 只处理 HTTP/HTTPS，不处理 TCP。调用方必须显式传入：

- 完整域名和外部协议；
- 服务名称、服务端口和服务协议；
- `route_kind`（`direct_ingress`、`host_nginx` 或 `gateway_nginx`；旧的 `test`、`components`、`gateway` 仅用于兼容）；
- 目标 SSH 连接，必要时提供 gateway SSH 连接；
- Ingress namespace、IngressClass、K3s namespace；
- Nginx 配置目录、主配置和监听端口；
- gateway Service、端口和 Nginx 文件路径；
- HTTPS 使用的 TLS Secret 或 cert-manager Issuer。

HTTPS 没有明确 Secret 或 Issuer 时会停止。域名后缀不会自动决定路由拓扑，也不会自动把请求转发到某台服务器。

路由执行分两步：

1. 预览并确认写入令牌，写入 Ingress/Nginx 文件；
2. 再次确认应用令牌，执行 `kubectl apply` 或 Nginx 检查/重载。

如果目标资源或远程文件已存在、内容被修改、IngressClass/TLS 资源不存在，操作会停止并要求重新检查。

## 11. 状态和错误处理

常见状态：

| 状态 | 含义 |
|---|---|
| `missing_parameters` | 缺少会影响结果的显式参数，需要询问用户 |
| `preview` | 已生成预览，尚未执行 |
| `confirm` | 已生成一次性审阅令牌 |
| `paused` | Jenkins 构建处于人工输入暂停 |
| `done` | 操作完成并通过基本验证 |
| `error` | 操作失败或安全检查拒绝 |

遇到多个目标、参数冲突、资源冲突、认证失败、非零退出码或远程内容变化时，Agent 应停止当前流程，说明需要用户确认或重新预览的字段，不得自行选择替代目标。

## 12. 安全和发布检查

不要把密码、Token、私钥、registry 凭证或内部地址写入公开 Skill、Git 提交、聊天回复或 npm 包。references 只保存在用户本地，并限制文件权限。

发布前在仓库根目录执行：

```bash
npm test -- --run
npm run build
git diff --check
npm pack --dry-run
node scripts/check-public-package.mjs
```

`package.json` 只白名单公开 Skill 文件和通用 procedures，`references/` 不应出现在 tarball 清单中。

旧版迁移：`jenkins_find_project` 改为 Agent 解析资料后调用 `jenkins_menu`；`service_find_restart/stop` 改为 `service_find` 或 `service_scan` 后调用对应启停工具；`service_id` 改为每次传完整连接、runtime、namespace 和 service；`config_init/config_template` 改为用户维护 references；旧服务库存改为 `service_scan` 实时扫描。旧名称不是当前可调用工具。

## 13. 最小示例

查询一台 Docker 主机：

```json
{
  "targets": [{
    "name": "<server-name>",
    "runtime": "docker",
    "connection": {
      "host": "<host>",
      "user": "<user>",
      "privateKeyPath": "<key-path>"
    }
  }]
}
```

重启服务：先调用 `service_restart` 传入完整 `runtime`、`connection` 和 `service`，把返回的预览展示给用户；用户确认后，仅将返回的 `token` 传给 `service_restart_execute`。

如果某个值不确定，正确做法是询问用户，而不是尝试从名称、旧配置或历史对话中推断。