ops-automation-mcp-ts 用户使用说明

本文档面向“通过 Codex 对话来使用 MCP”的用户。

文档重点不是解释内部实现，而是说明：

你应该怎么提需求
Codex 会怎么响应
每个模块适合解决什么问题
常见流程里会发生哪些交互确认

如果你只想快速上手，先看“快速开始”和“按模块使用”两节。

1. 这是什么

ops-automation-mcp-ts 是一组运维自动化能力，接入 Codex 之后，你可以直接用自然语言完成这些工作：

查看服务器状态
管理 Docker / K3s / Systemd 服务
Jenkins 构建
前端自动部署
后端自动部署
前后端一体项目构建
在指定服务器上安全执行命令

你通常不需要记住具体工具名。
多数情况下，只要把“目标 + 动作 + 范围”说清楚，Codex 会自动选择合适的工具。

2. 快速开始

2.1 在 Codex 里接入这个 MCP

如果你是通过 Codex 使用这套能力，最常见的接入方式有两种。

方式 A：直接使用 npm 上发布的版本

在 Codex 配置文件里加入：

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

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

适合开发或联调场景：

[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.2 直接启动方式

1	npx ops-automation-mcp-ts

或者：

1 2	npm install -g ops-automation-mcp-ts ops-automation-mcp-ts

2.3 配置文件位置

配置目录：

1	~/.ops-automation/

常见文件：

hosts.yaml：服务器连接信息
jenkins.yaml：Jenkins 实例配置
services.yaml：服务补充配置

2.4 首次推荐动作

第一次接入时，推荐先做这 3 步：

让 Codex 帮你初始化配置
填写真实服务器和 Jenkins 信息
用只读能力做连通性验证

推荐说法：

“帮我初始化 ops automation 配置”
“给我看 Jenkins 配置模板”
“列出所有服务器”
“列出 Jenkins 所有视图”

2.5 服务器配置怎么初始化

如果你想先把服务器配置建出来，最直接的说法是：

“帮我初始化服务器配置”
“帮我初始化 hosts.yaml”
“给我一个完整的服务器配置模板”

Codex 一般会走这两种路径：

只看模板
调用 config_template(config="hosts", template="complete")
直接创建文件
调用 config_init(config="hosts", template="complete")

初始化后，你主要需要填写的是：

defaults.port
defaults.user
defaults.password
hosts.<服务器名>.host
hosts.<服务器名>.tags
hosts.<服务器名>.k3sCluster
hosts.<服务器名>.role

一个最常见的 hosts.yaml 结构大致是：

defaults:
  port: 22
  user: root
  password: your_password

hosts:
  测试项目服务器-87:
    host: 192.168.2.87
    tags: [test, k3s]
    k3sCluster: test
    role: control-plane

  预演项目服务器:
    host: 192.168.2.243
    tags: [prev, k3s]
    k3sCluster: prev
    role: control-plane

字段怎么理解：

host：机器 IP 或域名，必填
tags：给服务器打标签，后面可用于分组查询
k3sCluster：如果这台机器属于 K3s 集群，就填集群名
role：control-plane 或 worker

推荐验证方式：

“列出所有服务器”
“看看测试项目服务器-87 的状态”
“列出所有服务器分组”

2.6 Jenkins 配置怎么初始化

如果你想先把 Jenkins 配置建出来，推荐这样说：

“帮我初始化 Jenkins 配置”
“帮我初始化 jenkins.yaml”
“给我一个完整的 Jenkins 配置模板”

Codex 一般会走：

config_template(config="jenkins", template="complete")
或 config_init(config="jenkins", template="complete")

初始化后，你至少要填写：

instances.<实例名>.url
instances.<实例名>.username
instances.<实例名>.token

一个最常见的 jenkins.yaml 结构大致是：

instances:
  default:
    url: http://jenkins.example.com
    username: your-username
    token: your_jenkins_api_token

  tq:
    url: http://jenkins-tq.example.com
    username: your-username
    token: your_tq_token

这里要特别注意：

token 要填 Jenkins API Token，不是登录密码
default 是默认实例名
如果你有第二套 Jenkins，比如 tq，就作为第二个实例加进去

推荐验证方式：

“列出 Jenkins 所有视图”
“列出 Jenkins 所有项目”
“Jenkins 构建 microfront-main 的 prev 分支”

2.7 services.yaml 要不要配

services.yaml 不是强制项。

你可以理解为：

hosts.yaml：必须有
jenkins.yaml：做 Jenkins / 自动部署时必须有
services.yaml：可选，用于给常见服务增加查找规则

如果你暂时只想先把服务器查询、Jenkins 构建和自动部署跑起来，可以先只配：

hosts.yaml
jenkins.yaml

3. 在 Codex 里怎么用

3.1 基本原则

推荐按这个格式说：

1	动作 + 目标 + 范围 + 补充条件

例如：

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

3.2 Codex 一般会怎么处理

flowchart TD
    A["用户提出需求"] --> B["Codex 识别意图"]
    B --> C["选择高层工具或流程"]
    C --> D{"是否缺少关键信息"}
    D -- "是" --> E["返回分支/项目/参数选项"]
    D -- "否" --> F["直接执行"]
    E --> G["用户确认"]
    G --> F
    F --> H{"是否需要确认或 review"}
    H -- "需要" --> I["返回确认信息或配置草稿"]
    H -- "不需要" --> J["继续执行"]
    I --> K["用户确认或补充"]
    K --> J
    J --> L["返回结果"]

3.3 什么时候会停下来问你

Codex 通常只会在这些场景停下来：

需要你选 Jenkins 项目或分支
前端首次部署，需要确认 nginx 配置
后端首次部署，需要确认端口或健康监测
停止服务等危险操作，需要明确确认
命令风险较高，需要令牌确认

也就是说，大多数普通查询和常规更新是可以直接执行的。

4. 功能地图

模块	适合做什么	推荐说法
配置与帮助	初始化配置、查看模板、了解功能	“帮我初始化配置”
服务器管理	看服务器、看资源、看分组	“看看测试服务器负载”
服务管理	查服务、看日志、启停重启	“重启 nginx”
Jenkins 直接构建	构建已存在的 Jenkins 项目	“Jenkins 构建 microfront-main 的 prev 分支”
前端自动部署	从 Git 地址发版前端	“部署前端：http://git… ”
后端自动部署	从 Git 地址发版后端	“部署后端：http://git… ”
一体化项目	前后端一体项目构建	“构建 zh-xinglu-scheduling 的 all 模式”
受控命令执行	在服务器上执行命令	“在测试机执行 df -h”

5. 按模块使用

5.1 配置与帮助

适用场景：

第一次使用
配置文件丢失
想确认 MCP 当前都支持什么

你可以这样说：

“帮我初始化 ops automation 配置”
“给我看 hosts.yaml 模板”
“这个 MCP 现在有哪些功能”

Codex 会怎么做：

需要看模板时，返回模板内容
需要初始化时，直接写入 ~/.ops-automation/
需要了解能力时，返回功能说明

这类操作通常不需要二次确认。

5.2 服务器管理

适用场景：

想知道有哪些服务器
想看某台机器当前压力
想看服务器分组

你可以这样说：

“列出所有服务器”
“看看测试服务器 CPU 和内存”
“查看 docker 分组服务器状态”
“列出所有服务器分组”

Codex 会怎么做：

列服务器：返回服务器名、地址、标签
查状态：返回 CPU、内存、磁盘
查分组：返回分组和成员机器

推荐先用这组能力确认环境连通性，再开始部署或服务操作。

5.3 服务管理

适用场景：

想知道某个服务是不是在跑
想看某个服务日志
想重启 / 停止 / 启动某个服务

支持的服务类型：

Docker
K3s
Systemd

你可以这样说：

“查看 microfront-main 状态”
“看看 redis 最近 200 行日志”
“重启 nginx”
“停止测试机上的 microfront-main”
“启动 87 上的某某服务”

5.3.1 典型行为

查询类：

查看状态
查看日志
列出服务

这类通常直接返回结果。

操作类：

重启服务
启动服务
停止服务

这里要特别注意：

重启通常直接执行
停止服务通常是两阶段确认
Codex 可能会先返回匹配服务，再让你确认目标

5.3.2 停止服务的交互方式

flowchart TD
    A["用户说 停止某服务"] --> B["按名称查找候选服务"]
    B --> C["返回 service_id 和风险提示"]
    C --> D["用户明确确认"]
    D --> E["执行停止"]
    E --> F["返回结果"]

建议：

不要一上来就报很模糊的名字，比如“停掉前端”
最好说清楚服务名、环境或机器

例如：

“停止测试项目服务器-87 上的 microfront-main”

5.4 Jenkins 直接构建

这一类适合“Jenkins 里已经有项目，只是现在要打一次包或发一次版”。

这和“给 Git 地址走自动部署”是两回事。

适用场景：

项目已经在 Jenkins 里建好了
你知道项目名，或者知道大概关键词
你只想触发构建，不想重新走自动建项目

你可以这样说：

“Jenkins 构建 microfront-main 的 prev 分支”
“构建 center-basic-auth-server 的 prev/v1.0.0 分支”
“Jenkins 打包管网 test 分支”
“列出 Jenkins 所有视图”

5.4.1 Codex 会怎么处理

有两种常见方式：

你直接说清楚项目和分支
Codex 会直接触发构建。
你只说了模糊项目
Codex 会先帮你匹配项目，再让你选分支。

5.4.2 Jenkins 直接构建流程

flowchart TD
    A["用户说 Jenkins 构建某项目"] --> B{"项目和分支是否明确"}
    B -- "明确" --> C["直接触发构建"]
    B -- "不明确" --> D["匹配项目"]
    D --> E["用户选择项目"]
    E --> F["列出分支"]
    F --> G["用户选择分支"]
    G --> C
    C --> H["等待构建结果"]

5.4.3 推荐说法

最省事的表达：

“Jenkins 构建 microfront-main 的 prev 分支”
“构建 zh-xinglu-scheduling-map 的 test/1.0.0 分支”

如果你不确定项目名：

“Jenkins 打包用户中心的微前端项目”
“构建兴泸的排班项目”

5.5 前端自动部署

这一类适合“我有一个前端 Git 仓库地址，希望 Codex 帮我完成部署”。

适用场景：

前端项目还没在 Jenkins 建好
或者你不想关心 Jenkins 项目名
你希望 Codex 从 Git 地址开始接管部署

你可以这样说：

“部署前端：http://git.xxx/project.git”
“部署前端：http://git.xxx/project.git，分支 test/1.0.0”
“部署前端：http://git.xxx/project.git，走 prev 分支”

5.5.1 前端自动部署流程

flowchart TD
    A["用户提供前端 Git 地址"] --> B["扫描远程分支"]
    B --> C["用户选分支"]
    C --> D["确保 Jenkins 项目存在"]
    D --> E["触发 Jenkins 构建"]
    E --> F["CHECK & WAIT"]
    F --> G{"nginx 配置是否存在"}
    G -- "不存在" --> H["返回 nginx 配置草稿给用户 review"]
    H --> I["用户确认或修改"]
    I --> J["写入配置并恢复 Jenkins"]
    G -- "存在" --> J
    J --> K["继续部署并返回结果"]

5.5.2 前端首次部署时会问什么

如果目标机器上还没有 nginx 配置，Codex 会先给你一份草稿让你确认。

你通常需要确认这些字段：

server_name
前端静态目录 root
/api/ 代理地址
额外 location，例如 /websocket

推荐表达：

“/api/ 代理到 http://192.168.2.87:20408/”
“再加一个 /websocket 代理”
“域名里的 prev 改成 ceshi”

5.5.3 前端更新时会怎样

如果 nginx 配置已经存在，Codex 一般不会再停下来让你 review，而是直接继续更新。

也就是说：

首次部署：通常会有 review
后续更新：通常直接发版

5.6 后端自动部署

这一类适合“我有一个后端 Git 仓库地址，希望 Codex 帮我从分支选择一路发到环境”。

适用场景：

希望从 Git 地址开始部署后端
希望 Codex 自动处理 Jenkins 项目创建
希望首次部署时自动接管端口和健康检查交互
希望把端口、健康检查、资源限制等固定配置收敛到项目仓库里的 deploy/helm/values*.yaml

你可以这样说：

“部署后端：http://git.xxx/service.git”
“部署后端：http://git.xxx/service.git，分支 prev/2.4.0”
“部署后端：http://git.xxx/service.git，jdk17”

5.6.1 后端会先让你选什么

通常顺序是：

选分支
选运行时

运行时一般是：

jdk8
jdk17

5.6.2 后端自动部署状态判断

当前后端 k3s + helm 路线会区分这几种状态：

helm_exists
k8s_exists_but_not_helm
missing

含义分别是：

helm_exists：已经是 Helm 管理项目，直接更新
k8s_exists_but_not_helm：是老项目，按兼容逻辑更新
missing：首次部署，需要交互确认

5.6.3 项目内 Helm values 模式

如果业务仓库里已经有：

1 2	deploy/helm/values.yaml deploy/helm/values.<env>.yaml

那么后端自动部署会优先把这些文件当成固定配置来源。

环境覆盖规则是：

test / test/* -> values.test.yaml
prev / prev/* -> values.prev.yaml
master / main -> values.prod.yaml
其他分支 -> 只读 values.yaml

在这种模式下：

ports、useHealthCheck、replicaCount、resources 这类固定项应该改 values 文件
Jenkins 只继续动态传每次都会变的值，例如 image.tag
Codex 不再把 deploy_port、use_health_check 当成常规后续升级入口

5.6.4 后端首次部署时会问什么

如果项目还没有迁移到 repo values 模式，而且是首次部署，Codex 一般会问你：

端口要不要指定
健康监测是否启用

典型表达：

“端口用 20203”
“默认端口”
“健康监测关闭”
“端口 20113，健康监测不检测”

5.6.5 后端自动部署流程

flowchart TD
    A["用户提供后端 Git 地址"] --> B["扫描远程分支"]
    B --> C["用户选分支"]
    C --> D["用户选 jdk8 或 jdk17"]
    D --> E["确保 Jenkins 项目存在"]
    E --> F["触发 Jenkins 构建"]
    F --> G["CHECK & WAIT"]
    G --> H{"仓库是否存在 deploy/helm/values.yaml"}
    H -- "是" --> I["读取 values.yaml 和可选 values.<env>.yaml"]
    H -- "否" --> J{"是否需要 legacy 首次部署交互"}
    J -- "是" --> K["询问端口和健康监测"]
    J -- "否" --> L["按兼容逻辑继续部署"]
    K --> M["用户确认"]
    M --> N["继续部署"]
    I --> O["继续部署"]
    L --> P["返回结果"]
    N --> P
    O --> P

5.6.6 健康监测怎么理解

当前你可以先按“开 / 关”来理解：

开启：按 chart 默认健康检查部署
关闭：部署时显式禁用健康检查

适用场景：

服务启动慢，但临时先想验证能否起来
某些服务启动阶段健康检查容易误杀

5.6.7 哪些参数放 values，哪些继续动态传

推荐按这个边界维护：

配置项	推荐来源
`ports`	`deploy/helm/values*.yaml`
`useHealthCheck`	`deploy/helm/values*.yaml`
`replicaCount`	`deploy/helm/values*.yaml`
`resources`	`deploy/helm/values*.yaml`
`image.tag`	Jenkins 动态参数

迁移老项目时，建议顺序是：

先确认当前线上实际生效的端口和健康检查配置
在业务仓库补 deploy/helm/values.yaml
如果环境有差异，再补 deploy/helm/values.<env>.yaml
提交仓库后再重新触发后端部署

5.7 前后端一体项目

这一类适合“一个 Jenkins 项目里同时有前端和后端”的场景，比如使用 Jenkinsfile-All 的项目。

典型模式：

frontend
backend
all

你可以这样说：

“构建 zh-xinglu-scheduling 的 frontend 模式”
“构建 zh-xinglu-scheduling 的 backend 模式”
“构建 zh-xinglu-scheduling 的 all 模式”

5.7.1 `all` 模式会发生什么

all 模式不是把前后端混成一个黑盒，而是顺序执行两条子流程：

前端构建与部署
后端构建与部署

如果前端是首次部署，可能先进入 nginx review。
如果后端是首次部署，可能再进入端口 / 健康监测确认。

也就是说，all 模式本质上是“前端流程 + 后端流程”的组合。

5.8 受控命令执行

这一类适合“我要在某台服务器上执行命令，但希望有风险控制”。

你可以这样说：

“在测试机执行 df -h”
“在 87 上执行 docker ps”
“在预演机执行 kubectl get pod -n default”

5.8.1 Codex 会怎么处理

命令大致分 3 类：

安全命令
直接执行并返回结果。
高危命令
先返回风险提示和令牌，再等你确认。
致命命令
直接拒绝。

5.8.2 执行流程

flowchart TD
    A["用户请求执行命令"] --> B["检测风险等级"]
    B --> C{"风险类型"}
    C -- "安全" --> D["直接执行"]
    C -- "高危" --> E["返回令牌和确认信息"]
    C -- "致命" --> F["直接拒绝"]
    E --> G["用户明确确认"]
    G --> H["带令牌执行"]
    D --> I["返回结果"]
    H --> I

5.8.3 建议说法

尽量带上目标机器和完整命令：

“在测试项目服务器-87 执行 docker ps”
“在测试服务器执行 kubectl get deploy -n default”

6. 什么时候给 Git 地址，什么时候给 Jenkins 项目名

这是最容易混淆的地方。

6.1 给 Jenkins 项目名

适合：

项目已经建在 Jenkins 里
你只是要构建某个分支

例如：

“Jenkins 构建 microfront-main 的 prev 分支”

6.2 给 Git 地址

适合：

希望 Codex 从分支扫描开始接管
可能还需要自动创建 Jenkins 项目
这是自动部署链路

例如：

“部署前端：http://git.xxx/xxx-web.git”
“部署后端：http://git.xxx/xxx-service.git”

简单记忆：

Jenkins 构建：偏已有项目
部署前端 / 部署后端：偏自动部署

7. 推荐对话模板

7.1 服务器类

“列出所有服务器”
“查看测试服务器状态”
“看看 87 的 CPU、内存和磁盘”

7.2 服务类

“查看 microfront-main 状态”
“重启 87 上的 microfront-main”
“停止测试项目服务器-87 上的 microfront-main”
“查看 center-basic-auth-server 最近 100 行日志”

7.3 Jenkins 直接构建

“Jenkins 构建 microfront-main 的 prev 分支”
“Jenkins 构建 center-basic-auth-server 的 prev/v1.0.0 分支”
“Jenkins 打包兴泸的排班项目”

7.4 前端自动部署

“部署前端：http://git.cd.zhinf.com/qinxuan/zh-xinglu-scheduling-map.git”
“部署前端：http://git.xxx/project.git，分支 prev/1.0.0”
“部署前端：http://git.xxx/project.git，如果缺 nginx 配置先让我确认”

7.5 后端自动部署

“部署后端：http://git.xxx/service.git”
“部署后端：http://git.xxx/service.git，分支 prev/2.4.0，jdk17”
“部署后端：http://git.xxx/service.git，端口 20113，健康监测关闭”

7.6 一体化项目

“构建 zh-xinglu-scheduling 的 frontend 模式”
“构建 zh-xinglu-scheduling 的 backend 模式”
“构建 zh-xinglu-scheduling 的 all 模式”

7.7 命令执行

“在测试机执行 df -h”
“在 87 上执行 docker ps”
“在预演机执行 kubectl get pod -n default”

8. 高级用户参考：模块与工具名对应关系

如果你是高级用户，或者要排查 Codex 为什么这样执行，可以参考下面这张表。

模块	主要工具
配置与帮助	`help`、`config_template`、`config_init`
服务器管理	`list_servers`、`query_servers`、`list_groups`
服务管理	`service_find`、`service_list`、`service_status`、`service_logs`、`service_start`、`service_restart`、`service_stop`、`service_find_restart`、`service_find_stop`、`service_prepare_stop`、`service_do_stop`、`service_do_restart`
Jenkins	`jenkins_find_project`、`jenkins_menu`、`jenkins_do_build`、`jenkins_wait_build`、`jenkins_list_views`、`jenkins_list_jobs`、`jenkins_list_branches`、`jenkins_ensure_project`
前端自动部署	`deploy_frontend_auto`
后端自动部署	`deploy_backend_auto`
命令执行	`prepare_execute`、`execute_prepare`、`execute_execute`、`execute_command`

9. 常见问题

9.1 为什么 Codex 会先返回选项，而不是直接执行

通常是因为缺少关键参数，例如：

Jenkins 项目不明确
分支不明确
首次部署需要确认 nginx 配置
首次后端部署需要确认端口

9.2 为什么有些操作需要明确确认

通常有两类原因：

这是危险操作，例如停止服务、执行高危命令
这是首次部署，需要确认配置是否正确

9.3 为什么前端和后端流程不一样

因为它们的部署对象不同：

前端更关注 nginx 配置和静态资源发布
后端更关注运行时、端口、健康检查和项目状态

9.4 为什么同样是部署，有时直接继续，有时会停下来问

因为 Codex 会根据“当前是不是首次部署、配置是否缺失、风险是否较高”自动决定是否需要交互。

10. 推荐给团队的统一说法

为了让 Codex 更稳定，建议团队统一用这些说法：

“Jenkins 构建 <项目名> 的 <分支> 分支”
“部署前端：<Git 地址>”
“部署后端：<Git 地址>”
“重启 <服务名>”
“查看 <服务名> 日志”
“在 <服务器名> 执行 <命令>”

如果能一次说清楚下面几项，效果最好：

目标项目
目标分支
目标环境或服务器
是否是前端 / 后端 / 一体化项目
是否有特殊配置，例如端口、代理地址、健康监测

11. 附录

如果你想看当前模块和功能盘点，请参考：

feature-inventory.zh-CN.md

ops-automation-mcp-ts 用户使用说明

1. 这是什么

2. 快速开始

2.1 在 Codex 里接入这个 MCP

2.2 直接启动方式

2.3 配置文件位置

2.4 首次推荐动作

2.5 服务器配置怎么初始化

2.6 Jenkins 配置怎么初始化

2.7 services.yaml 要不要配

3. 在 Codex 里怎么用

3.1 基本原则

3.2 Codex 一般会怎么处理

3.3 什么时候会停下来问你

4. 功能地图

5. 按模块使用

5.1 配置与帮助

5.2 服务器管理

5.3 服务管理

5.3.1 典型行为

5.3.2 停止服务的交互方式

5.4 Jenkins 直接构建

5.4.1 Codex 会怎么处理

5.4.2 Jenkins 直接构建流程

5.4.3 推荐说法

5.5 前端自动部署

5.5.1 前端自动部署流程

5.5.2 前端首次部署时会问什么

5.5.3 前端更新时会怎样

5.6 后端自动部署

5.6.1 后端会先让你选什么

5.6.2 后端自动部署状态判断

5.6.3 项目内 Helm values 模式

5.6.4 后端首次部署时会问什么

5.6.5 后端自动部署流程

5.6.6 健康监测怎么理解

5.6.7 哪些参数放 values，哪些继续动态传

5.7 前后端一体项目

5.7.1 all 模式会发生什么

5.8 受控命令执行

5.8.1 Codex 会怎么处理

5.8.2 执行流程

5.8.3 建议说法

6. 什么时候给 Git 地址，什么时候给 Jenkins 项目名

6.1 给 Jenkins 项目名

6.2 给 Git 地址

7. 推荐对话模板

7.1 服务器类

7.2 服务类

7.3 Jenkins 直接构建

7.4 前端自动部署

7.5 后端自动部署

7.6 一体化项目

7.7 命令执行

8. 高级用户参考：模块与工具名对应关系

9. 常见问题

9.1 为什么 Codex 会先返回选项，而不是直接执行

9.2 为什么有些操作需要明确确认

9.3 为什么前端和后端流程不一样

9.4 为什么同样是部署，有时直接继续，有时会停下来问

10. 推荐给团队的统一说法

11. 附录

5.7.1 `all` 模式会发生什么