host-execution-mcp 1.0.1 → 2.0.0

package/docs/USER_GUIDE.zh-CN.md

@@ -1,140 +1,45 @@
 # host-execution-mcp 使用教程
 
-**使用场景：本地可以直连入口机（跳板 / 帕拉迪网关），再进入 K8s 集群或目标主机，AI 辅助分析代码、文件传输等等。**
+配置、`ACCESS_KIND`、怎么跟 Agent 说话，以 [GUIDE.md](./GUIDE.md) 为准（MCP Resource `host-execution://guides/user`）。本文只补 Codex 接法、旧包迁移和场景示例。
 
-**本机 Cursor → SSH（ACCESS）→ 落点 HostExecutionContext → kubectl / docker / shell / 再跳目标机**（这条路径上笔记本不直连 Pod）。
+建议配套 [k8s-multi-node-deploy](../../../skill/env/k8s-multi-node-deploy/) skill。
 
-> 包名已由 `bastion-k8s-mcp` 升级为 **`host-execution-mcp`**。环境变量统一为 `ACCESS_*` / `TARGET_*`（不再使用 `BASTION_*` / `REMOTE_SSH_*`）。
-
-:::
-建议配套 [**k8s-multi-node-deploy**](https://sh-code.mthreads.com/andy.wang/agent-compose/-/tree/master/skill/env/k8s-multi-node-deploy?ref_type=heads) skill 效果更佳~~~，无法访问联系我 $\color{#0089FF}{@Andy Wang}$
-:::
-
-## 1. 安装 Node.js
-
-MCP 需要运行在 Node.js 环境上，**Node.js >= 18**。官网 [nodejs.org](https://nodejs.org) 下载 LTS，安装后验证：
-
-```bash
-node -v
-```
-
-## 2. MCP 配置（Cursor 为例）
-
-配置文件：`.cursor/mcp.json`，或 Cursor → Settings → MCP → Edit Config。
-
-先问自己一句：**本机能不能用普通 `ssh user@ip` 直接登到要用的那台机器（或跳板）？** 答案决定 `ACCESS_KIND`。
-
-| `ACCESS_KIND` | 你的实际情况 | 一句话 |
-| --- | --- | --- |
-| **`ssh`**（默认） | 本机（通常开 VPN）能**正常 SSH** 到入口机 / 目标机，连上就是 bash，没有「选资产 / 选账号」菜单 | 普通 SSH 场景 |
-| **`paradi-gateway`** | **不能**对目标机直接 `ssh`；只能先连帕拉迪网关，再在网关里交互选资产、选登录账号，才能落到业务机 | 网关菜单穿透场景（见下图） |
-
-**`ssh` 长什么样：** 本机执行例如 `ssh mccxadmin@10.121.120.7`，输密码后直接进系统 shell —— 配 `ACCESS_KIND=ssh`（§2.1）。
-
-**`paradi-gateway` 长什么样：** 本机只能先 `ssh 网关账号@网关IP`，连上后出现「目标资产列表 / 登录帐号列表」，要手选数字才能进机器 —— **MCP 替你省掉这份交互**，用编码账号/密码直接落到目标机（§2.2）。真实终端示意：
+帕拉迪网关长什么样（先连网关，再选手选资产 / 账号）：
 
 ![帕拉迪网关：先连网关，再选资产与账号，才能进入目标机](./paradi-gateway-interactive.png)
 
-选好模式后，抄下面对应小节的 `env`。
-
-### 2.1 `ACCESS_KIND=ssh`：本机能正常 SSH（跳板 / K8s）
-
-:::
-**需要先验证本地机器通过 VPN 能登录到 `10.121.120.7` 才行（找四季青运维）**
-:::
-
-```json
-{
-  "mcpServers": {
-    "host-execution": {
-      "command": "npx",
-      "args": ["-y", "host-execution-mcp@latest"],
-      "env": {
-        "ACCESS_KIND": "ssh",
-        "ACCESS_HOST": "10.121.120.7",
-        "ACCESS_USER": "mccxadmin",
-        "ACCESS_PASSWORD": "mccxadminjd",
-        "ACCESS_PORT": "22",
-        "ALLOWED_NAMESPACES": "his-test"
-      }
-    }
-  }
-}
-```
+## Codex
 
-`ACCESS_HOST` + `ACCESS_USER` 填你**本机能 SSH 直连的入口机**地址和账号即可（MCP 会用同样的方式登录）。
+把 GUIDE §2 的 `env` 配进 Codex。不要把密码写进仓库或对话。
 
-可选：若常从跳板再 SSH 到某台目标机，可加默认第二跳：
+也可把 GUIDE 里的 JSON 交给 Codex，让它按 GUIDE 配。`~/.codex/config.toml` 示意：
 
-```json
-"TARGET_HOST": "10.121.32.69",
-"TARGET_USER": "mccxadmin",
-"TARGET_PASSWORD": "mccxadmin"
-```
+```toml
+[mcp_servers.host-execution]
+command = "npx"
+args = ["-y", "host-execution-mcp@latest"]
 
-### 2.2 `ACCESS_KIND=paradi-gateway`：不能直连目标机，经帕拉迪网关
-
-本机**无法**对业务机普通 SSH；只能连网关。客户只需配**网关账号** + **目标机 IP/系统用户**；**不要**手写三段用户名或 `@##@` 密码串（MCP 内部编码，效果等价于你在菜单里选好资产与账号）。默认 `ACCESS_PARADI_AUTH=auto`：先试 slash，失败再试 compound，成功后进程内钉死。
-
-```json
-{
-  "mcpServers": {
-    "host-execution-paradi": {
-      "command": "npx",
-      "args": ["-y", "host-execution-mcp@latest"],
-      "env": {
-        "ACCESS_KIND": "paradi-gateway",
-        "ACCESS_HOST": "10.121.61.10",
-        "ACCESS_PORT": "22",
-        "ACCESS_USER": "ellazj",
-        "ACCESS_PASSWORD": "<网关密码>",
-        "ACCESS_PARADI_AUTH": "auto",
-        "TARGET_HOST": "10.121.35.74",
-        "TARGET_USER": "mccuseradmin"
-      }
-    }
-  }
-}
+[mcp_servers.host-execution.env]
+ACCESS_KIND = "ssh"
+ACCESS_HOST = "<入口机 IP>"
+ACCESS_USER = "<入口机用户>"
+ACCESS_PASSWORD = "<入口机密码>"
+ACCESS_PORT = "22"
 ```
 
-运维可强制：`ACCESS_PARADI_AUTH` = `auto` | `slash` | `compound`（一般客户保持 **`auto`** 即可）。对照表：
-
-| 模式 | 用户名 | 密码 | 适合 | 实际场景（手动 SSH 等价） |
-| --- | --- | --- | --- | --- |
-| **auto**（默认） | 先按 slash，AUTH_FAILED 再按 compound；成功后进程内钉死赢家 | 同上 | 不确定网关开了哪种能力时 | 无需手选；`access_check` 可看 `paradiAuth` |
-| **slash** | `USER/HOST/OSUSER` | 网关密码 | 网关按三段用户名选资产 | `ssh zhangyimingzgc/10.121.35.68/mccuseradmin@10.121.61.3`，密码填网关密码（网关 `10.121.61.3` → `10.121.35.68` / `mccuseradmin`） |
-| **compound** | `USER` | `密码@##@HOST:SSH:22:OSUSER` | 网关已开程序穿透 | `ssh ellazj@10.121.61.10`，密码填 `网关密码@##@10.121.35.74:SSH:22:mccuseradmin`（网关 `10.121.61.10` → `10.121.35.74` / `mccuseradmin`） |
-
-mcp.json **不要**手写三段用户名或 `@##@` 串，由 MCP 按上表编码。
-
-保存后重启 MCP 服务。验证连通：
-
-> 用 host-execution 跑 `access_check`；若要做 K8s，再让 Agent 执行 `kubectl cluster-info --request-timeout=5s`
-
-若提示 `ACCESS_UNAVAILABLE`：先查 VPN / `ACCESS_HOST`，不要反复重试本 MCP 的其他工具。
-
----
-
-## 3. 怎么用
+> 使用时整个 vscode 窗口只能当作一个类似 Codex 桌面版 app，建议配合 terminal 使用。
 
-对 Agent **用自然语言**说清：**命名空间、负载/Pod 名、文件路径**；**需要时加「只读，不要改」**，可减少 AI 操作带来的不确定性风险（尤其破坏性操作）。
+## 与旧包对照（迁移）
 
-| 你想做的事 | 告诉 Agent |
+| 旧（bastion-k8s-mcp） | 新（host-execution-mcp） |
 | --- | --- |
-| 找 Pod | 命名空间 + Deployment/负载名 |
-| 看日志 | Pod 名 + 日志**文件路径**（训练日志多在挂载盘，不是 stdout） |
-| 拷到本地 | 远程路径 + 本地目录（Agent 读取后写入本机） |
-| 排查故障 | 日志 / dmesg / core 路径 + 「只读分析」 |
-| 上目标机 | 目标 IP + 用户（有 `TARGET_*` 时可省略，让 Agent `context_derive` / 跳板执行） |
-| 帕拉迪落点 | 已在目标机：直接 `shell_exec` / `docker_*`，不要再 derive |
-
-输出太大被截断时，让 Agent 用 `grep`、`tail` 缩小范围。
-
-常用工具（Agent 侧）：`access_check`、`shell_exec`、`context_derive`、`k8s_*`、`docker_*`、`remote_*` / `remote_copy_*`。
-
----
+| `bastion-k8s-mcp@3.x` | `host-execution-mcp@1.0.0` |
+| `BASTION_HOST` / `USER` / `PASSWORD` / `PORT` | `ACCESS_HOST` / `USER` / `PASSWORD` / `PORT` |
+| `REMOTE_SSH_USER` / `PASSWORD` | `TARGET_USER` / `TARGET_PASSWORD` |
+| `bastion_check` / `bastion_exec` | `access_check` / `shell_exec` |
+| — | `ACCESS_KIND=paradi-gateway` + `TARGET_*`（帕拉迪） |
 
-## 4. 示例
+## 场景示例
 
 1. MCP + SKILL → 让从零重新创建一个负载，然后拉 128 个节点
 
@@ -154,56 +59,4 @@ mcp.json **不要**手写三段用户名或 `@##@` 串，由 MCP 按上表编码
 
    ![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/4f8dc2c2-6445-44f8-b1d9-8aaf27d37ccc.png)
 
----
-
-## 常见问题
-
-* **MCP 起不来**：检查 `node -v`、入口机地址账号、本机能否 `ssh user@10.121.120.7`；确认 env 已改成 `ACCESS_*`（旧 `BASTION_*` 会被拒绝）
-* **仍配置 BASTION_***：会报错并提示改名；按上文 JSON 换成 `ACCESS_HOST` / `ACCESS_USER` / `ACCESS_PASSWORD`
-* **k8s_logs 为空**：日志在文件里，让 Agent 读挂载路径，不要只用 container stdout
-* **多个节点都 Killed**：先找第一个报 MUSA/SIGABRT 的 rank，其余可能是连锁退出
-* **帕拉迪连不上**：确认网关开了程序穿透（或 slash 可用）；可设 `ACCESS_PARADI_AUTH=compound` / `slash` 强制一种；`access_check` 成功后会带 `paradiAuth`
-
-更多配置见 [CONFIGURATION.md](./CONFIGURATION.md)。
-
----
-
-# 补充：
-
-## Codex 使用
-
-本地 vscode + codex 也可用。
-
-将上述《host-execution-mcp 使用教程》的配置拷贝给 codex 插件，直接让其根据该配置，自动本地配好 MCP server。
-
-配置好后大概如下：
-
-![image.png](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/AJdl65A66aVv7Oke/img/4286d40d-ca12-4bbd-94bf-beff93baefa7.png)
-
-也可以打开 `~/.codex/config.toml`（或本机 Codex 配置）增加配置如下：
-
-```toml
-[mcp_servers.host-execution]
-command = "npx"
-args = ["-y", "host-execution-mcp@latest"]
-
-[mcp_servers.host-execution.env]
-ALLOWED_NAMESPACES = "his-test"
-ACCESS_KIND = "ssh"
-ACCESS_HOST = "10.121.120.7"
-ACCESS_PASSWORD = "mccxadminjd"
-ACCESS_PORT = "22"
-ACCESS_USER = "mccxadmin"
-```
-
-> 使用时整个 vscode 窗口只能当作一个类似 Codex 桌面版 app，建议配合 terminal 使用。
-
-## 与旧包对照（迁移）
-
-| 旧（bastion-k8s-mcp） | 新（host-execution-mcp） |
-| --- | --- |
-| `bastion-k8s-mcp@3.x` | `host-execution-mcp@1.0.0` |
-| `BASTION_HOST` / `USER` / `PASSWORD` / `PORT` | `ACCESS_HOST` / `USER` / `PASSWORD` / `PORT` |
-| `REMOTE_SSH_USER` / `PASSWORD` | `TARGET_USER` / `TARGET_PASSWORD` |
-| `bastion_check` / `bastion_exec` | `access_check` / `shell_exec` |
-| — | `ACCESS_KIND=paradi-gateway` + `TARGET_*`（帕拉迪） |
+常见问题见 [GUIDE.md](./GUIDE.md)。更多环境变量见 [CONFIGURATION.md](./CONFIGURATION.md)。

package/docs/host-execution.yaml

@@ -0,0 +1,92 @@
+# host-execution 名册（对照 docs/GUIDE.md §2）
+# 路径写死：
+#   Linux/mac  ~/.agents/host-execution.yaml
+#   Windows    %USERPROFILE%\.agents\host-execution.yaml
+#
+# 一条链路 = GUIDE 里一份 mcp.json env。description 必填且唯一，写清场景用途（谁、干什么、哪台），不要只写「本机直连 + IP」。
+# 追加：在 links 下复制下面某一段示例，去掉行首 #，改 description 与账号。
+# 对话里出现新的 user+IP（新跳板/网关/账号，或同一 IP 换用户）→ 追加一条，不要只记在对话里。
+# 同一 ACCESS 且同一 TARGET_USER、只是多了一个目标 IP → 往该条 TARGET_HOSTS 加一项。
+# 同一 IP、不同用户（root vs mccxadmin）是两条链路，不要写进同一条 TARGET_HOSTS。
+# description 不准（场景变了、或「本机/跳板/生产」说错）→ 当场改名，随后按新名精确选用；不要把旧名当不可改主键。
+# 本轮对话一直指向某一条 → 一直用那条，不要因为本文件有多条（含同 IP 另一用户）就换。
+# 选用时 description 必须精确相等。不要 CIDR / 通配。
+# 帕拉迪：不要手写 USER/HOST/OSUSER 或 密码@##@… ，由 MCP 编码。
+
+links: []
+
+# --- GUIDE §2.1 最少：只上入口机 ---
+# - description: 入口机本机作业
+#   ACCESS_KIND: ssh                 # 可省，默认 ssh
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   ACCESS_PORT: 22                  # 可省
+
+# --- GUIDE §2.1 密钥代替密码 ---
+# - description: 入口机密钥登录
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PRIVATE_KEY_PATH: "<密钥路径>"
+
+# --- GUIDE §2.1 限制 kubectl 命名空间 ---
+#   ALLOWED_NAMESPACES: "his-test"
+
+# --- GUIDE §2.1 跳板 + 一台默认第二跳 ---
+# - description: 跳板再上训练机
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#   TARGET_USER: "<目标机用户>"
+#   TARGET_PASSWORD: "<目标机密码>"
+
+# --- GUIDE §2.1 跳板 + 多台已知 IP（同一账号）---
+# - description: 跳板再上多台训练机
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#     - "<目标机 IP>"
+#   TARGET_USER: "<目标机用户>"
+#   TARGET_PASSWORD: "<目标机密码>"
+
+# --- GUIDE §2.1 只留账号，对话里说 IP ---
+# - description: 跳板账号已配，目标 IP 对话指定
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_USER: "<目标机用户>"
+#   TARGET_PASSWORD: "<目标机密码>"
+
+# --- GUIDE §2.2 帕拉迪 ---
+# - description: 经网关上业务机
+#   ACCESS_KIND: paradi-gateway
+#   ACCESS_HOST: "<网关 IP>"
+#   ACCESS_PORT: 22
+#   ACCESS_USER: "<网关用户>"
+#   ACCESS_PASSWORD: "<网关密码>"
+#   ACCESS_PARADI_AUTH: auto         # auto | slash | compound
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#   TARGET_USER: "<目标机系统用户>"
+
+# --- 同一 IP、不同用户：两条链路 ---
+# - description: 业务机 mccxadmin
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#   TARGET_USER: "mccxadmin"
+#   TARGET_PASSWORD: "<该用户密码>"
+# - description: 业务机 root
+#   ACCESS_HOST: "<入口机 IP>"
+#   ACCESS_USER: "<入口机用户>"
+#   ACCESS_PASSWORD: "<入口机密码>"
+#   TARGET_HOSTS:
+#     - "<目标机 IP>"
+#   TARGET_USER: "root"
+#   TARGET_PASSWORD: "<该用户密码>"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "host-execution-mcp",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Access -> HostExecutionContext -> Runtime MCP for remote shell/docker/kubectl (SSH jump or Paradi gateway)",
   "type": "module",
   "main": "dist/index.js",
@@ -47,12 +47,14 @@
   "homepage": "https://github.com/your-org/host-execution-mcp#readme",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "js-yaml": "^5.4.2",
     "ssh2": "^1.16.0",
     "ssh2-sftp-client": "^12.1.1",
     "zod": "^3.24.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.23.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.13.10",
     "@types/ssh2": "^1.15.4",
     "@types/ssh2-sftp-client": "^9.0.6",