# ops-automation-mcp-ts

`ops-automation-mcp-ts` 是一套面向 Codex / Claude 的运维自动化 MCP，支持：

- 服务器状态查询
- Docker / K3s / Systemd 服务管理
- Jenkins 直接构建
- 前端自动部署
- 后端自动部署
- 前后端一体项目构建
- 受控命令执行

这个包主要用于“通过 AI 对话做运维操作”。

---

## 1. 在 Codex 里接入

最常见的方式是在 Codex 配置里加入这个 MCP。

### 方式 A：使用 npm 最新版

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

### 方式 B：使用本地源码构建产物

```toml
[mcp_servers.ops_automation]
type = "stdio"
command = "node"
args = ["/绝对路径/ops-automation-mcp-ts/dist/index.js"]
```

Codex 配置文件常见位置：

- macOS / Linux：`~/.codex/config.toml`
- Windows：`C:\\Users\\<用户名>\\.codex\\config.toml`

配置完成后，重启 Codex 或重开会话即可。

---

## 2. 直接运行

```bash
npx ops-automation-mcp-ts
```

或者：

```bash
npm install -g ops-automation-mcp-ts
ops-automation-mcp-ts
```

---

## 3. 配置文件

配置目录：

```text
~/.ops-automation/
```

常见文件：

- `hosts.yaml`
- `jenkins.yaml`
- `services.yaml`

说明：

- `hosts.yaml`：服务器 SSH 与环境信息，必须有
- `jenkins.yaml`：Jenkins 配置，做构建或自动部署时必须有
- `services.yaml`：可选，用于补充常见服务查找规则

---

## 4. 推荐初始化方式

推荐直接通过 Codex 对话初始化，而不是手工创建。

例如：

- “帮我初始化 ops automation 配置”
- “帮我初始化服务器配置”
- “帮我初始化 Jenkins 配置”
- “给我看 Jenkins 配置模板”

对应能力：

- `config_init`
- `config_template`

初始化后，推荐先验证：

- “列出所有服务器”
- “看看测试服务器状态”
- “列出 Jenkins 所有视图”

---

## 5. 通过 Codex 怎么用

最推荐的说法是：

```text
动作 + 目标 + 范围 + 补充条件
```

例如：

- “看看测试服务器负载”
- “重启 87 上的 microfront-main”
- “Jenkins 构建 microfront-main 的 prev 分支”
- “部署前端：http://git.xxx/project.git”
- “部署后端：http://git.xxx/project.git，jdk17”
- “在测试机执行 df -h”

Codex 通常会：

1. 识别你的意图
2. 优先调用高层工具
3. 在需要时返回选项或配置草稿
4. 帮你继续执行并返回结果

---

## 6. 功能模块

### 6.1 配置与帮助

用于：

- 初始化配置文件
- 查看模板
- 查看 MCP 功能清单

### 6.2 服务器管理

用于：

- 列服务器
- 查资源状态
- 查服务器分组

### 6.3 服务管理

用于：

- 查 Docker / K3s / Systemd 服务
- 看状态
- 看日志
- 启动 / 重启 / 停止

### 6.4 Jenkins 直接构建

适合：

- Jenkins 里已经有项目
- 你只想触发某个分支的构建

### 6.5 前端自动部署

适合：

- 从 Git 地址开始部署前端
- 首次部署时自动 review nginx 配置

### 6.6 后端自动部署

适合：

- 从 Git 地址开始部署后端
- 首次部署时自动确认端口和健康监测
- 已迁移项目从仓库内 `deploy/helm/values*.yaml` 读取固定 Helm 配置

推荐把这些固定项收敛到项目仓库：

- `ports`
- `useHealthCheck`
- `replicaCount`
- `resources`

`image.tag` 这类每次发布都会变化的参数，继续由 Jenkins 动态传入。

详细约定和迁移方式见：

- [docs/user-guide.zh-CN.md](./docs/user-guide.zh-CN.md)

### 6.7 前后端一体项目

适合：

- `Jenkinsfile-All`
- `frontend / backend / all` 模式项目

### 6.8 受控命令执行

适合：

- 在指定服务器执行命令
- 需要风险控制和确认机制

---

## 7. 文档入口

完整用户手册：

- [docs/user-guide.zh-CN.md](./docs/user-guide.zh-CN.md)

功能清单与测试覆盖：

- [docs/feature-inventory.zh-CN.md](./docs/feature-inventory.zh-CN.md)