host-execution-mcp 1.0.0

package/docs/PARADI_ACCESS_PLAN.md

@@ -0,0 +1,272 @@
+# Plan: Access / Runtime 分层 + Paradi 合入
+
+Status: **accepted · Phase 0 frozen** · Updated: 2026-07-22
+
+## 终态目标
+
+干净的远程执行 MCP：**用户只配置「如何获得 HostExecutionContext」**；shell / docker / kubectl 是 Runtime，由 Agent 按落点 `capabilities` 选择，**不进 mcp.json**。
+
+```text
+AccessTransport.createContext()
+        │
+        ▼
+HostExecutionContext（描述 + capabilities；无 session）
+        │
+        │  deriveContext(parent, host…)   ← 仅 ssh 第二跳，按需创建
+        ▼
+Runtime(context) → shell / docker_* / k8s_* / copy
+        │
+        └──► SessionPool.get(context.key)  ← 旁路：按 key 借还 SSH；不进 Context
+```
+
+### 三条硬标准
+
+1. **无 Runtime 配置污染** — 不设 `ENABLE_DOCKER`。  
+2. **无旧双轨** — Phase 4 删光死代码与旧 env 名。  
+3. **文档 = 代码**。
+
+---
+
+## Phase 1 前冻结的不变量（守住不推倒）
+
+| # | 不变量 | 反例（禁止） |
+|---|--------|--------------|
+| A | **Context 永远无 session** | `Context { sshClient }`；MCP request 间串会话 |
+| B | **Runtime 永远不创建 Access/SSH** | `docker_*(host=)` 内部再拼 ssh；Runtime 自己 `new Client()` |
+| C | **`TARGET_*` = 默认 derive 选择器，不是启动时自动建第二 Context** | init 预建 Context_TARGET；或「配了 TARGET 就默认落点已在 T」 |
+| D | **capabilities 诚实：登录成功 ≠ 有 docker/kubectl** | SSH ok 就写 `docker:true`；Agent 当 infallible |
+
+另：现场「三跳」= 口语（ssh→ssh→docker）。模型 = Access 链 + Runtime；勿写「三跳作废」。
+
+### 不变量 D — capabilities 生命周期
+
+```ts
+// createContext / 首次连通后（仅能确定的）
+capabilities: {
+  exec: true,           // 或 false：能跑 shell
+  docker: "unknown",
+  kubectl: "unknown",
+  // 可选 source: "declared" | "probed"
+}
+```
+
+- **禁止**用「SSH 成功」推断 Runtime 能力。  
+- **probe**（`which docker` / `kubectl version --client` 等）后改为 `true` | `false`；可懒探测（首次 docker_* / k8s_* 前）或显式 probe 工具。  
+- Agent：`unknown` → 先 probe 或试一次并处理失败；**不得**把 unknown 当 true。  
+- Phase 1 可只保证 `exec`；docker/kubectl 字段先占位 `unknown`，Phase 2+ 接 probe。
+
+### 命名冻结 — `TARGET_PASSWORD`
+
+保持 **`TARGET_PASSWORD`**，不用 `TARGET_SSH_PASSWORD`。  
+Access 已表明走何种 Transport；密码是「目标侧凭证」，未来可复用（ssh / paradi fallback / 其它），勿把协议钉进 env 名。
+
+---
+
+## 核心不变量（完整）
+
+1. AccessTransport **生产** Context；Runtime **只消费** Context。  
+2. docker / kubectl = Runtime，不是 Access 第二跳。  
+3. Context 无 session；**SessionPool** 按稳定 `context.key` 管连接（与 Context 分离）。  
+4. `ssh_exec` ≡ `deriveContext` + shell（仅 `ACCESS_KIND=ssh`）。  
+5. 帕拉迪 = `ParadiTransport.createContext()` → **普通** `HostExecutionContext`（无 ParadiContext 子类；Runtime 不知网关）。  
+6. Policy ≠ Access。  
+7. 用户形态按「几个 IP / 是否网关」分，不按「机器叫不叫跳板」分。
+
+---
+
+## 用户怎么配（真正三种）
+
+只认：`ACCESS_*` = 本机第一次连谁；`TARGET_*` = 默认第二跳选择器（按需 derive，非自动双 Context）。  
+**不要** `BASTION_*` / `REMOTE_*` / `PARADI_*` 分套变量。
+
+| # | 形态 | IP | KIND | TARGET_* | 启动时 Context |
+|---|------|-----|------|----------|----------------|
+| 1 | **单机** | 1 | `ssh`（可省略） | **不要** | 仅 ACCESS |
+| 2 | **跳板→目标** | 2 | `ssh` | **要**（HOST+USER） | **仍仅 ACCESS**；TARGET 供默认 derive |
+| 3 | **帕拉迪** | 2 | `paradi-gateway` | **要** | 一次 create → 落点已是 T |
+
+> **为何不拆 Direct / 仅跳板？** 用户都是「ssh 上一台」；机器职能不是 Access 种类。旧 `ssh-direct` / 无 TARGET 的 bastion KIND → **形态 1**。
+
+### 形态 1 — 单机
+
+```json
+{
+  "ACCESS_KIND": "ssh",
+  "ACCESS_HOST": "10.121.120.7",
+  "ACCESS_USER": "mccxadmin",
+  "ACCESS_PASSWORD": "<secret>"
+}
+```
+
+```text
+Client ──SSH──► Context0(ACCESS) ── Runtime
+```
+
+调用时仍可 `ssh_exec(另一台)` → derive；不必在 mcp.json 写 TARGET。
+
+### 形态 2 — 跳板 → 目标
+
+```json
+{
+  "ACCESS_KIND": "ssh",
+  "ACCESS_HOST": "10.121.120.7",
+  "ACCESS_USER": "mccxadmin",
+  "ACCESS_PASSWORD": "<secret>",
+  "TARGET_HOST": "10.121.35.68",
+  "TARGET_USER": "mccuseradmin",
+  "TARGET_PASSWORD": "<secret>"
+}
+```
+
+```text
+启动:  Client ──SSH──► Context0(ACCESS)          ← 只有这一个 Context
+按需:  Context0 ──derive──► Context1(TARGET) ── Runtime
+       （ssh_exec 省略 host 时可用默认 TARGET_*；也可覆盖到别的 host）
+```
+
+`TARGET_PASSWORD`：目标侧凭证（需要时）；不是 docker/registry 密码；**勿改名** `TARGET_SSH_PASSWORD`。  
+**禁止** init 时预建 Context1；多 TARGET 未来 = 多次 derive / 选择器，不是启动 N 个 Context。
+
+### 形态 3 — 帕拉迪
+
+```json
+{
+  "ACCESS_KIND": "paradi-gateway",
+  "ACCESS_HOST": "10.121.61.3",
+  "ACCESS_USER": "zhangyimingzgc",
+  "ACCESS_PASSWORD": "<secret>",
+  "TARGET_HOST": "10.121.35.68",
+  "TARGET_USER": "mccuseradmin"
+}
+```
+
+```text
+ParadiTransport.createContext() → Context0(endpoint=T, transport=paradi-gateway)
+Client ──SSH(身份编码目标)──► T ── Runtime   （Runtime 无帕拉迪分支）
+```
+
+实现细节（用户不配）：`sshUsername = ACCESS_USER/TARGET_HOST/TARGET_USER`。一般不配 `TARGET_PASSWORD`。
+
+---
+
+## Policy（与 Access 拆开）
+
+Access **不含** `ALLOWED_NAMESPACES`。另层例如 `ACCESS_POLICY`。Phase 1 可暂缓。
+
+---
+
+## loadConfig 校验
+
+| KIND | 规则 |
+|------|------|
+| `ssh`（默认） | ACCESS 必填；TARGET 可选；**若存在 `TARGET_HOST` → `TARGET_USER` 必填**（禁止 fallback 到 `ACCESS_USER`） |
+| `paradi-gateway` | ACCESS + TARGET_HOST + TARGET_USER 必填；忽略 TARGET_PASSWORD 默认认证 |
+
+`ACCESS_KIND` 仅：`ssh` | `paradi-gateway`。
+
+配置路径：`env → AccessTransport.createContext → Runtime(+ SessionPool)`；禁止 tool 直读 env。
+
+---
+
+## 形态 → Context → Runtime
+
+| 形态 | 启动 Context | derive | Runtime |
+|------|--------------|--------|---------|
+| 1 单机 | ACCESS | 调用时可选 | Agent × capabilities |
+| 2 跳板→目标 | **仅 ACCESS**；TARGET = 默认 derive 信息 | 按需 | 同上 |
+| 3 帕拉迪 | T（一次 create） | 无「再 SSH」derive | 同上；capabilities 诚实 |
+
+口语「三跳」≈ 形态 2 + docker Runtime（SSH×2 + docker），不是第三种 Access。
+
+---
+
+## HostExecutionContext
+
+```ts
+type Cap = true | false | "unknown"
+
+interface ContextCapabilities {
+  exec: Cap
+  docker: Cap
+  kubectl: Cap
+}
+
+interface HostExecutionContext {
+  key: string  // 稳定；禁止每次 random uuid
+  transport: AccessTransportKind  // ssh | paradi-gateway
+  endpoint: { host: string; user?: string }
+  parentKey?: string  // 仅 derive 出的子 Context
+  capabilities: ContextCapabilities  // 初值见不变量 D；probe 后更新
+  // 禁止: sshClient / session / stream
+}
+```
+
+```ts
+SessionPool.get(ctx.key) → SSH session   // Runtime/Transport 调用；生命周期归 Pool
+
+// ACCESS_KIND=ssh
+ssh_exec(host?, command) ≡
+  deriveContext(accessContext, host ?? defaultTargetFromConfig)
+  shellExec(derived, command)
+```
+
+---
+
+## 实施路线
+
+### Phase 0 — 文档
+
+- [x] 三种用户形态；KIND=`ssh`|`paradi-gateway`；Runtime 不进配置  
+- [x] 冻结不变量 A/B/C/D；`TARGET_PASSWORD` 命名；SessionPool 旁路；TARGET=默认 derive  
+- [x] CONFIGURATION / AGENT_GUIDE / USER_GUIDE / clients → ACCESS_*（与 Phase 1 同 PR）  
+
+### Phase 1 — Context + `ssh`
+
+- [x] `HostExecutionContext`（无 session）+ `SessionPool`（按 key）  
+- [x] `SshTransport.createContext` → 仅 Context0(ACCESS)；capabilities 初值 `exec` + docker/kubectl=`unknown`  
+- [x] loadConfig + TARGET 作 default derive；有 TARGET_HOST 则 TARGET_USER 必填；字段名 `TARGET_PASSWORD`  
+- [x] 入口 shell；**ssh_exec = derive+shell**；k8s_* 仍经 ACCESS（bastion）执行  
+- [x] CONFIGURATION / AGENT_GUIDE / USER_GUIDE / clients → ACCESS_*（legacy BASTION_* 薄别名）  
+- [x] 版本 3.1.0  
+
+**不做：** docker 产品面、Paradi、Policy 大改、工具大改名。
+
+### Phase 2 — docker Runtime + probe
+
+- [x] `docker_ps` / `docker_exec` / `docker_logs`（经 SessionPool，不自建 SSH）  
+- [x] `context_probe` + lazy probe 更新 `capabilities.docker`；AGENT_GUIDE/instructions：unknown ≠ true  
+- [x] 版本 3.2.0  
+
+### Phase 3 — `paradi-gateway`
+
+- [x] `ParadiTransport.createContext` → 普通 Context（endpoint=T）  
+- [x] capabilities 诚实（`sftp: degraded`、`channelOpenSensitive`）  
+- [x] loadConfig 接受 paradi；Hop1 身份编码；禁止 derive/`ssh_exec`  
+- [x] 版本 3.3.0  
+
+### Phase 4 — 清理
+
+- [x] 删 `BASTION_*` / `REMOTE_SSH_*` loadConfig 别名（残留则报错提示改名）  
+- [x] 文案 / README / CONFIGURATION / SECURITY / examples → ACCESS_* only  
+- [x] Policy：`ACCESS_POLICY_ALLOWED_NAMESPACES`（保留 `ALLOWED_NAMESPACES` 短名）  
+- [x] 版本 **4.0.0** breaking changelog  
+
+---
+
+## 明确不做
+
+- Context 持 session；Runtime 创建 SSH；init 预建 TARGET Context  
+- SSH 成功 → 写死 `docker`/`kubectl: true`；Agent 把 `unknown` 当 true  
+- `TARGET_SSH_PASSWORD`；`TARGET_USER` fallback `ACCESS_USER`  
+- `ParadiContext` 子类 / Runtime 内 `if (paradi)`  
+- 单机拆 Direct vs 仅跳板；配置写 docker/kubectl  
+- expect 菜单；`BASTION_*`/`REMOTE_*`/`PARADI_HOST`；用户 KIND=`ssh-direct`  
+- 写「三跳作废」（改用「口语三跳 = Access + Runtime」）  
+- 未验证 `@##@` 方式 B  
+
+---
+
+## 现网锚点（实现者）
+
+- `bastion-client.ts` · `hop1-sftp.ts` · `remote-executor.ts` → Phase1：derive + SessionPool  
+- 外围文档仅 ACCESS_* / TARGET_*（4.0.0 已删 BASTION_* 别名）。

package/docs/REMOTE_COPY_JOB_API.md

@@ -0,0 +1,92 @@
+# Remote Copy Job API (M2)
+
+Status: **implemented** (2.2.0+; Hop1 engine **3.0.0**) — tools: `remote_copy_start` / `remote_copy_status` / `remote_copy_cancel`.
+
+## Framing
+
+| Phase | Goal |
+|-------|------|
+| **M1 (done)** | Copy **Engine**: Hop1 via `ssh2-sftp-client` (file + directory), progress, `totalTimeoutMs`, `transferId`, `skipIfComplete` |
+| **M2 (done)** | Expose Engine as async Job API — **not** a spawn-and-forget wrapper around blocking `remote_copy_file` |
+| **M3** | Agent policy: auto-async when size **or** ETA exceeds threshold (helpers in `copy-job-types.ts`) — never auto-promote sync tool |
+
+```
+remote_copy_file (sync) ──► same Copy Engine ◄── remote_copy_start (async job)
+                                      │
+                                      ▼
+                            remote_copy_status / cancel
+```
+
+## Tools
+
+### `remote_copy_start`
+
+Create job → return immediately.
+
+- Input: same endpoints + options (`skipIfComplete`, `verify`, `totalTimeoutMs`, …)
+- Output: `transferId`, `status: running`, optional `estimatedSeconds`, `jobStorePath`, `message`
+
+### `remote_copy_status`
+
+- Input: `{ transferId }` — only async `remote_copy_start` ids
+- Output: status machine + `progress{ transferredBytes, totalBytes, percent, speedBps, etaSeconds, skippedBytes, currentHopIndex }`
+
+### `remote_copy_cancel`
+
+- Input: `{ transferId }`
+- Output: `{ transferId, status, message }` — aborts in-process worker via `AbortSignal`
+- Hop1 SFTP: independent SFTP session ended promptly (exec SSH client is **not** disconnected)
+- Hop2 kubectl/scp: best-effort — abort checked between hops; `exec` closes the SSH channel when signalled
+- Terminal statuses are fenced (cancel cannot overwrite success; success cannot overwrite cancelled)
+- On MCP restart, leftover `queued|running` jobs are reconciled to `failed`
+
+## State machine
+
+```
+queued → running → success
+                 → failed
+                 → cancelled
+                 → timeout
+```
+
+## Persistence (Scheme A)
+
+Do **not** store job state in Cursor conversation.
+
+```
+~/.agent-compose/remote-copy/jobs/<transferId>.json
+```
+
+Override root with env `BASTION_COPY_JOB_ROOT`.
+
+Record shape: `CopyJobRecord` in `src/utils/copy-job-types.ts`.
+
+## Executor abstraction
+
+One user-facing API; Engine routes hops:
+
+| Hop | Executor kind |
+|-----|---------------|
+| local ↔ bastion | `sftp` (`ssh2-sftp-client`, separate TCP from exec) |
+| pod ↔ bastion | `kubectl` |
+| host ↔ bastion | `scp` |
+| multi-hop | `pipeline` (staging on bastion) |
+
+## Alignment with M1
+
+| M1 field | M2 usage |
+|----------|----------|
+| `transferId` (`copy-…`) | Job primary key |
+| `CopyProgress` | Mapped via `engineProgressToJobProgress` |
+| `skipIfComplete` / `skipped` / `skipReason` / `skippedBytes` | Skip gate = verify (size\|size+sha256); none+skip rejected |
+| `totalTimeoutMs` | Wall-clock budget; async terminal status `timeout` |
+| Sync `remote_copy_file` | Short copies; long copies → `remote_copy_start` (never auto-async) |
+
+## Async threshold (policy)
+
+`shouldPreferAsyncCopy` in `copy-job-types.ts`:
+
+- size > 256 MiB **or**
+- estimatedSeconds > 120
+
+Use as agent guidance only; do not auto-switch inside `remote_copy_file`.

package/docs/TODO.md

@@ -0,0 +1,66 @@
+# TODO — known gaps & follow-ups
+
+As of **5.0.0**. Items below are intentional or deferred; do not treat as regressions unless marked otherwise.
+
+## Done in 5.0 cleanup (this branch)
+
+- [x] Paradi Zod fail-fast: remote schemas omit `target=context` / `contextKey` under `ACCESS_KIND=paradi-gateway`
+- [x] Copy assert rejects Paradi `host` **and** `context` before materialize
+- [x] Agent-facing tool descriptions: drop Hop1/Hop2 jargon; docs aligned to ACCESS/Context naming
+
+## 5.1 backlog
+
+### 1. Remote endpoint API — remove `target=context` pollution (ssh)
+
+```ts
+// TODO(remote-endpoint-union): Split agent-facing copy/read endpoints:
+//   { target: landing|pod|local, path, ... }  vs  { contextKey, path }
+// Keep materialize internal; stop overloading target=context on the same union.
+```
+
+### 2. KubectlRunner → SessionPool, then optional `k8s_*(contextKey)`
+
+```ts
+// TODO(kubectl-session-pool): Route kubectl through SessionPool (same as shell/docker).
+// Then optionally expose k8s_*(contextKey?) for derived-host kubeconfig — doc honesty first in 5.0.
+```
+
+### 3. SessionPool TTL / LRU
+
+```ts
+// TODO(session-pool-eviction): Bound derived Context sessions (TTL + LRU) so long MCP
+// processes do not accumulate idle SSH sessions indefinitely.
+```
+
+### 4. sshpass password in argv (security debt)
+
+```ts
+// TODO(sshpass-argv): Password appears in ps on landing when using TARGET_PASSWORD / tool password.
+Prefer keys; longer-term: askpass / env-file / ControlMaster without -p in argv.
+See SECURITY.md.
+```
+
+### 5. Copy cancel on kubectl/scp is best-effort
+
+```ts
+// TODO(copy-cancel-runtime): remote_copy_cancel aborts the in-process worker via AbortSignal.
+// - local↔landing SFTP: independent ssh2-sftp-client session ended promptly; exec SSH kept.
+// - kubectl cp / scp on landing: channel close + abort between hops; in-flight process may continue.
+// Goal ("干净秒杀任意 hop") is NOT met for kubectl/scp yet.
+// Follow-ups: track PIDs / trap-kill wrapper; document partial files on cancel.
+```
+
+## Related (not blocking)
+
+```ts
+// TODO(m3-agent-policy): Wire shouldPreferAsyncCopy into stronger agent/tool
+// guidance (size>256MiB OR ETA>2min → remote_copy_start). Do NOT auto-promote sync→async.
+```
+
+```ts
+// TODO(registry-check): Optional structured registry_check tool (login + manifest probe).
+```
+
+## Access evolution (Paradi)
+
+See **[PARADI_ACCESS_PLAN.md](PARADI_ACCESS_PLAN.md)** — Phase1–4 complete (4.0.0); 5.0 renames + Paradi Zod fail-fast.

package/docs/USER_GUIDE.zh-CN.md

@@ -0,0 +1,93 @@
+# host-execution-mcp 使用教程
+
+**本机 Cursor → SSH（ACCESS / 帕拉迪网关）→ 落点 HostExecutionContext → kubectl / docker / shell**（笔记本不直连 Pod）。
+
+工具名：`access_check` / `shell_exec` / `context_*` / `k8s_*` / `docker_*` / `remote_*`。在 `ACCESS_KIND=ssh` 时落点是 ACCESS；在 `paradi-gateway` 时落点是 **TARGET**（不是网关机）。详见 [AGENT_GUIDE.md](AGENT_GUIDE.md) / [CONFIGURATION.md](CONFIGURATION.md)。
+
+---
+
+## 1. 安装 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。
+
+```json
+{
+  "mcpServers": {
+    "host-execution": {
+      "command": "npx",
+      "args": ["-y", "host-execution-mcp@latest"],
+      "env": {
+        "ACCESS_HOST": "10.121.120.7",
+        "ACCESS_USER": "your-user"
+      }
+    }
+  }
+}
+```
+
+`ACCESS_HOST` + `ACCESS_USER` 填你**本机能 SSH 直连的入口机**（跳板或目标机）即可。可选 `TARGET_HOST` / `TARGET_USER` / `TARGET_PASSWORD` 作为默认第二跳（见 CONFIGURATION.md）。
+
+保存后重启 MCP 服务。验证连通：
+
+> 先用 host-execution 跑 `access_check`。若要做 Kubernetes 相关操作，通过后再跑 `kubectl cluster-info --request-timeout=5s`（纯 ACCESS/主机 SSH 任务不必跑 cluster-info）。
+
+若提示 `ACCESS_UNAVAILABLE` / 无法连接：先检查本机 VPN 与 `ACCESS_HOST`，不要反复重试其他工具。
+
+---
+
+## 3. 怎么用
+
+对 Agent **用自然语言**说清：**命名空间、负载/Pod 名、文件路径**；需要时加「只读，不要改」。
+
+| 你想做的事 | 告诉 Agent |
+|-----------|-----------|
+| 找 Pod | 命名空间 + Deployment/负载名 |
+| 看日志 | Pod 名 + 日志**文件路径**（训练日志多在挂载盘，不是 stdout） |
+| 拷到本地 | 远程路径 + 本地目录（Agent 读取后写入本机） |
+| 排查故障 | 日志 / dmesg / core 路径 + 「只读分析」 |
+
+输出太大被截断时，让 Agent 用 `grep`、`tail` 缩小范围。
+
+---
+
+## 4. 示例话术
+
+**查负载**
+
+> `his-test` 命名空间，列出 `jd-joyvideo-test` 的 Pod 状态和 IP。
+
+**看训练日志**
+
+> Pod `jd-joyvideo-test-xxx`，tail `/mnt/code/.../log.65.10.121.33.74` 最后 200 行，看有没有 Killed 或 MUSA error。只读。
+
+**拷 log 到本地**
+
+> 把 Pod `jd-joyvideo-test-xxx` 上的 `/path/to/log` 和 `/path/to/core.mudmp` 拷到本地 `jd-joyvideo-logs/`，不要改远程文件。
+
+**分析训练失败**
+
+> 只读分析 Pod 上的 mudmp 和训练 log，启动脚本 `/mnt/code/0407/cluster/dist_run_fsdp8.sh`，说明失败原因。
+
+**批量检查**
+
+> 对 `his-test` 里所有 Running 的 `jd-joyvideo-test` Pod 跑 `mthreads-gmi -q | grep Bios`，汇总版本。
+
+---
+
+## 常见问题
+
+- **MCP 起不来**：检查 `node -v`、堡垒机地址账号、本机能否 `ssh user@10.121.120.7`
+- **k8s_logs 为空**：容器日志流（stdout+stderr）可能为空；日志在文件里时让 Agent 读挂载路径，不要只用 `k8s_logs`
+- **多个节点都 Killed**：先找第一个报 MUSA/SIGABRT 的 rank，其余可能是连锁退出
+
+更多配置见 [CONFIGURATION.md](./CONFIGURATION.md)。

package/docs/clients/claude-desktop.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "host-execution": {
+      "command": "node",
+      "args": ["<ABS_PATH>/packages/mcp/host-execution/dist/index.js"],
+      "env": {
+        "ACCESS_HOST": "10.0.0.1",
+        "ACCESS_USER": "your-user"
+      }
+    }
+  }
+}

package/docs/clients/cursor-npx.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "host-execution": {
+      "command": "npx",
+      "args": ["-y", "host-execution-mcp@latest"],
+      "env": {
+        "ACCESS_HOST": "10.0.0.1",
+        "ACCESS_USER": "your-user"
+      }
+    }
+  }
+}

package/docs/clients/cursor.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "host-execution": {
+      "command": "node",
+      "args": ["<ABS_PATH>/packages/mcp/host-execution/dist/index.js"],
+      "env": {
+        "ACCESS_HOST": "10.0.0.1",
+        "ACCESS_USER": "your-user"
+      }
+    }
+  }
+}

package/docs/clients/vscode.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "host-execution": {
+      "command": "node",
+      "args": ["<ABS_PATH>/packages/mcp/host-execution/dist/index.js"],
+      "env": {
+        "ACCESS_HOST": "10.0.0.1",
+        "ACCESS_USER": "your-user"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "host-execution-mcp",
+  "version": "1.0.0",
+  "description": "Access -> HostExecutionContext -> Runtime MCP for remote shell/docker/kubectl (SSH jump or Paradi gateway)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "host-execution-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "lint": "eslint src tests",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "host-execution",
+    "kubernetes",
+    "kubectl",
+    "ssh",
+    "paradi"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/host-execution-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/your-org/host-execution-mcp/issues"
+  },
+  "homepage": "https://github.com/your-org/host-execution-mcp#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ssh2": "^1.16.0",
+    "ssh2-sftp-client": "^12.1.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.23.0",
+    "@types/node": "^22.13.10",
+    "@types/ssh2": "^1.15.4",
+    "@types/ssh2-sftp-client": "^9.0.6",
+    "eslint": "^9.23.0",
+    "prettier": "^3.5.3",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.28.0"
+  }
+}