# ops-automation-mcp-ts

面向 Codex 的无状态运维 MCP，提供：

- SSH 命令预览、确认与执行
- Docker / K3s / Systemd 服务查询和启停
- Jenkins 项目、分支、构建与等待
- Nacos API 探测、命名空间/分组发现、配置读写
- Docker Compose / K3s 镜像直部署
- 显式参数的 HTTP/HTTPS 域名路由

## 接入

面向实际使用者的中文手册见：[docs/user-guide.zh-CN.md](docs/user-guide.zh-CN.md)。

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

也可以直接运行：

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

## 无状态参数模型

MCP 不读取、创建或维护 `~/.ops-automation`，不会访问本地 YAML，也不会根据环境名、服务器名、文档路径或固定默认值猜测目标。每次调用都传入完整连接信息：

- SSH：`{ host, port?, user, password?, privateKeyPath? }`
- Jenkins：`{ endpoint, auth: { username, token }, credentialsId? }`
- Nacos：`{ endpoint, auth?, apiVersion?, contextPath? }`

服务器清单、内部流程和账号可以自由写在 Markdown、YAML、JSON 或自然语言 Skill 的 `references/` 中，由 Agent 读取后映射到工具参数。参数缺失、冲突或存在多个安全目标时，工具返回选择信息，不自行延伸。

## Codex Skill

本包提供 Codex 标准 Skill：

```text
.codex/skills/ops-automation-mcp/
├── SKILL.md
├── agents/openai.yaml         # Codex 界面元数据，不承载业务规则
├── procedures/                 # 通用流程，随 npm 发布
└── references/                 # 用户本地资料，npm 包不包含
```

`SKILL.md` 是唯一入口；`agents/openai.yaml` 只提供 Codex 界面显示名称、简介和默认提示，不是第二套规则。`procedures/` 按场景提供通用流程；`references/` 是可选的用户本地资料，可以写成 Markdown、YAML、JSON 或自然语言，MCP 不读取或维护这些文件。

没有 `references/` 也可以调用 MCP，但 Agent 必须向用户索要本次所需的连接、目标、端口、路径、namespace、group 和流程参数。仓库不会在 MCP 启动时复制、创建或修改 Skill，也不会恢复旧的 `.ops-automation` 配置。

## 确认与敏感信息

所有远程副作用均采用“预览 -> 一次性审阅令牌 -> 仅令牌执行”步骤：受保护命令、服务启停、Jenkins 创建/构建、镜像运行环境初始化、部署文件写入/实际部署/NodePort、域名写入/应用和 Nacos 删除都必须使用相应 `*_execute`（Nacos 为 `nacos_do_delete`）工具。工具返回的 warning 或 `next_action` 不等于用户授权。

密码、Token、私钥路径只在当前进程使用，不落盘、不作为缓存键，也不会出现在响应、预览、日志或错误中。公开 npm 包只包含通用 Skill；公司私有服务器、凭证和流程请放在用户自己的 Skill 目录中。

## 常用入口

- `list_servers` / `query_servers`：传入 `targets` 数组查询服务器
- `service_find` / `service_list` / `service_status` / `service_logs`：每次显式传 `runtime`、`connection`、`service`
- `service_scan`：只扫描本次传入的 targets，不写本地服务目录
- `jenkins_menu`、`jenkins_ensure_project`、`jenkins_do_build`：返回创建/构建审阅令牌；用 `jenkins_ensure_project_execute` 或 `jenkins_do_build_execute` 执行
- `nacos_discover`、`nacos_list_namespaces`、`nacos_list_groups`：在未知版本/范围时先发现；单条配置的读取、发布与删除必须显式传入 namespace 和 group。发布/修改可直接执行，删除仍需令牌确认
- `deploy_image_auto`：显式传入带 tag/digest 的镜像、SSH 连接、runtime、部署目录、容器端口和对外端口；K3s 还必须明确 workload、Service 和每个挂载的存储策略；Git 地址继续使用 Jenkins 流程
- `configure_company_domain`：显式传入完整域名、协议、服务端口、路由拓扑和目标连接，并由 `configure_company_domain_execute` 分别写入、应用

## 使用边界

本包是通用执行内核，不包含任何公司服务器、Jenkins、Nacos、域名或中间件配置。公司环境信息应由私有 Skill/Agent 读取后逐项传入；缺少或冲突的信息必须先向用户确认。发布前请使用 `npm pack --dry-run` 和 `node scripts/check-public-package.mjs` 检查最终包内容。

旧版 `jenkins_find_project`、`service_id`、`config_init` 等入口已移除：Agent 读取资料后改用当前工具清单中的 `jenkins_menu`、`service_find`/`service_scan` 和显式连接参数。完整迁移表见 [功能清单](docs/feature-inventory.zh-CN.md)。