host-execution-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,330 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-07-27
+
+First public release of **`host-execution-mcp`** (new npm package name; continues the Access → HostExecutionContext → Runtime line formerly developed as `bastion-k8s-mcp`).
+
+### Added
+
+- Access shapes: `ACCESS_KIND=ssh` (landing / jump+`TARGET_*`) and `ACCESS_KIND=paradi-gateway`
+- Paradi `ACCESS_PARADI_AUTH=auto|slash|compound` (default `auto`): try slash then compound on AUTH_FAILED; pin winner for the MCP process lifetime
+- `access_check` may include `paradiAuth` after a successful Paradi connect
+- Tools: `access_check`, `shell_exec`, `context_derive` / `context_probe`, `k8s_*`, `docker_*`, `remote_*` / `remote_copy_*`
+
+### Notes
+
+- Install: `npx -y host-execution-mcp@1.0.0` (or `@latest`)
+- Env: `ACCESS_*` / `TARGET_*` only (no `BASTION_*` / `REMOTE_SSH_*` aliases)
+
+## [6.0.0] - 2026-07-23
+
+### Breaking
+
+- Package / MCP server rename: `bastion-k8s-mcp` → `host-execution-mcp`
+- Source / index paths: `packages/mcp/bastion-k8s` → `packages/mcp/host-execution`, `mcp/bastion-k8s` → `mcp/host-execution`
+- Internal rename: `BastionClient` → `AccessClient` (`access-client.ts` / `access-errors.ts` / `access-sftp.ts`)
+- Removed CLI bin alias `bastion-k8s-mcp` (bin: `host-execution-mcp` only)
+
+### Changed
+
+- Paradi Zod fail-fast: `remote_*` / `remote_copy_*` schemas omit `target=context`; shell/docker omit `contextKey` under `ACCESS_KIND=paradi-gateway`
+- Copy guard rejects Paradi `target=context` (and `host`) before materialize
+- Agent-facing tool descriptions drop Hop1/Hop2 jargon; docs aligned to ACCESS/Context naming + 5.1 backlog
+
+## [5.0.0] - 2026-07-23
+
+### Breaking
+
+- Tool renames: `bastion_check` → `access_check`, `bastion_exec` → `shell_exec` (optional `contextKey`)
+- New tool: `context_derive` (returns `contextKey`; unavailable under `ACCESS_KIND=paradi-gateway`)
+- Error rename: `BASTION_UNAVAILABLE` → `ACCESS_UNAVAILABLE`; `BastionUnavailableError` → `AccessUnavailableError`
+- Remote schemas: `target=bastion` → `target=landing`; removed agent-facing `target=host`; added `target=context` with `contextKey`
+- `docker_*` / `context_probe`: `host`/`useTarget` removed — use `contextKey` only (omit for landing)
+- `ssh_exec` response includes `contextKey` + command result fields
+- Removed env alias `BASTION_COPY_JOB_ROOT` — use `ACCESS_COPY_JOB_ROOT` only
+- Removed deprecated `shellOnAccess` alias on `AccessRuntime`
+
+### Changed
+
+- Copy engine internal target `bastion` → `landing`; `target=context` materializes in copy handlers before execute
+- Instructions / AGENT_GUIDE / README tool table aligned to 5.0.0 naming (no deferred renames)
+- Instructions: ssh_exec = reuse-only derive+shell shortcut; shell_exec never creates Context; omit contextKey = AccessTransport landing; remote target=context defined; Paradi derive soft-worded; k8s_* notes contextKey not exposed yet; drop redundant Prefer-ssh_exec / Host-level duplication
+- Instructions (MMR consensus): ssh_exec = plain derive+shell shortcut; Paradi derive = unsupported by transport; k8s_* landing-only by design; slim system prompt (cookbook → AGENT_GUIDE)
+
+## [4.0.0] - 2026-07-22
+
+### Breaking
+
+- Removed env aliases: `BASTION_HOST`/`USER`/`PORT`/`PASSWORD`/`PRIVATE_KEY_PATH`, `REMOTE_SSH_USER`/`PASSWORD`. Use `ACCESS_*` / `TARGET_*` only; leftover old names throw with rename hints.
+- Policy: prefer `ACCESS_POLICY_ALLOWED_NAMESPACES` (`ALLOWED_NAMESPACES` still accepted as policy-only short name).
+
+### Changed
+
+- Docs / README / SECURITY / `.env.example` aligned to ACCESS_* only
+- Phase 4 cleanup complete per PARADI_ACCESS_PLAN
+- Post-review hardening: Paradi-aware MCP instructions & tool descriptions; forbid `remote_copy` `target=host` under Paradi (sync + async start); derived `cwd` uses bash single-quote; derive context key hashes password; `ACCESS_COPY_JOB_ROOT`; probe exitCode handling; tool-description UTF-8 arrows; `remote_read`/`remote_ps`/`remote_copy_start` Paradi notes; SECURITY.md 4.0
+- Instructions converge on Access/Runtime/derive (drop Hop1/Hop2); `current Context` wording; honest `docker_*(host/useTarget)` = derive convenience; hide Paradi username encoding; rename to `buildDerivedHostAuthGuidance` (no Hop2 alias); remove static `SERVER_INSTRUCTIONS`
+- Remove unused internals: `AccessRuntime.deriveToHost` / `shellOnContext`, `remoteHop2FilePathEndpointSchema`, unused `remoteCopy*ResultSchema`
+- Instruction v3 (text): Access-layer selectors vs Runtime; host-entry split; no Legacy wording; K8s probe on landing Context; Never reuse ACCESS_USER; Paradi “not available under this ACCESS_KIND” (not forever-disabled); capabilities not shared across Contexts
+
+## [3.3.0] - 2026-07-22
+
+### Added
+
+- `ACCESS_KIND=paradi-gateway`: ParadiAccessTransport → landing Context on TARGET; Hop1 SSH username `ACCESS_USER/TARGET_HOST/TARGET_USER`
+- Declared capabilities: `sftp: "degraded"`, `channelOpenSensitive: true` (preserved across probe)
+- `ssh_exec` / derive / `useTarget` rejected under paradi (already on TARGET)
+
+### Changed
+
+- `AccessClient` / Hop1 SFTP use `resolveAccessSshIdentity` (paradi-aware username)
+- CONFIGURATION documents Paradi shape; `TARGET_PASSWORD` ignored for paradi auth
+
+## [3.2.0] - 2026-07-22
+
+### Added
+
+- `context_probe`: probe Context capabilities (`docker` / `kubectl` CLI); tri-state true|false|unknown
+- `docker_ps` / `docker_exec` / `docker_logs`: Docker Runtime via SessionPool (ACCESS default; `host` / `useTarget` to derive)
+- Auto-probe `capabilities.docker` before docker_* when still unknown; fail if false
+
+### Changed
+
+- Server instructions: unknown ≠ true; docker_* vs k8s_exec selection
+
+## [3.1.0] - 2026-07-22
+
+### Breaking
+
+- Prefer `ACCESS_*` / `TARGET_*` env names (see CONFIGURATION.md). Legacy `BASTION_*` / `REMOTE_SSH_*` still accepted as temporary aliases.
+- `TARGET_HOST` requires `TARGET_USER` (no fallback to `ACCESS_USER`).
+- `ACCESS_KIND=paradi-gateway` rejected until Phase 3.
+
+### Added
+
+- Access layer: `HostExecutionContext` (no session) + `SessionPool` + `SshAccessTransport`
+- `ssh_exec` ≡ `deriveContext` + shell via `AccessRuntime` (optional host uses `TARGET_HOST`)
+- Capabilities: `exec` + `docker`/`kubectl` = `"unknown"` until probe (Phase 2)
+
+### Changed
+
+- Config / instructions / client examples document three Access shapes; Runtime not in mcp.json
+
+## [3.0.4] - 2026-07-22
+
+### Fixed
+
+- Hop2 auth guidance: password-only (`REMOTE_SSH_PASSWORD` without `REMOTE_SSH_USER`) now says omit password but **still pass user** (was incorrectly "omit user/password")
+
+### Changed
+
+- Slim Hop2 `REMOTE_SSH_*` agent guidance; drop redundant `bastion_check.remoteHostAuth` and `ssh_exec` Auth prose (server instructions + short schema remain)
+- First-session handshake: `kubectl cluster-info` only for Kubernetes ops
+- Clarify `k8s_logs` as stdout+stderr log stream; copy `skipIfComplete`/`verify`/`totalTimeoutMs` as all-hop copy rules; `bastion_check` hints in JSON message (other tools' `BASTION_UNAVAILABLE` hints in stderr)
+
+## [3.0.3] - 2026-07-22
+
+### Fixed
+
+- Agent guidance: when `REMOTE_SSH_USER` / `REMOTE_SSH_PASSWORD` are set in MCP env, server instructions and `ssh_exec` descriptions now say defaults are **active** — omit credentials and **do not ask the human** (runtime already applied env; agents were still prompted by old "provide user" wording)
+
+### Changed
+
+- `buildServerInstructions(config)` injects Hop2 auth status at startup (exposes default username, not password)
+- `bastion_check` returns `remoteHostAuth` (`userConfigured`, `user`, `passwordConfigured`, `hint`)
+- `hostFields` / `ssh_exec` parameter describes: omit when env defaults exist
+
+## [3.0.2] - 2026-07-21
+
+### Fixed
+
+- `buildSshRemoteCommand`: quote the entire `bash -lc '<cmd>'` as one ssh remote argv so OpenSSH space-join no longer truncates multi-word commands (`ssh_exec`, `remote_*` target=host)
+- `remote-copy` host post-copy `stat`: use `buildSshRemoteCommand` and pass the same password as scp (password-only hosts no longer fall back to BatchMode ssh)
+
+### Changed
+
+- Shared Hop2 host transport prefix (`buildHostTransportPrefix` / `hostSshBaseOpts`) for ssh and scp so `-o` / sshpass opts do not fork
+- Agent instructions + `AGENT_GUIDE`: shell metacharacters, non-TTY docker empty stdout, CRLF, `DOCKER_CONFIG`, `success=false` reads stdout; deferred `registry_check` noted in `TODO.md`
+
+### Tests
+
+- `shell-quote`: multi-word command, URL `&`, sshpass, double-wrap (`buildBashLcCommand(buildSshRemoteCommand(...))`)
+
+## [3.0.1] - 2026-07-17
+
+### Added
+
+- `BastionUnavailableError` (`code=BASTION_UNAVAILABLE`) with Chinese hints for VPN/network/auth failures
+- `bastion_check` tool: short-timeout Local→Bastion SSH probe (≤10s), structured `{ reachable, latencyMs, ... }`
+- `ensureAccessReady()` with positive/negative TTL on `exec` and Hop1 `uploadPath`/`downloadPath`
+
+### Changed
+
+- Network/auth **connect-phase** failures fail-fast (no 3× reconnect); stream-phase `ECONNRESET`/`EPIPE` remain briefly retryable
+- Probe/`bastion_check` use ephemeral SSH (do not sever in-flight exec/copy); transfer errors are not reclassified as bastion-down
+- Auth classification tightened to ssh2 auth phrases (file `Permission denied` excluded)
+- Server instructions / tool-selection prompt / descriptions: prefer `bastion_check` first; stop retrying on `BASTION_UNAVAILABLE`
+
+## [3.0.0] - 2026-07-16
+
+### Added
+
+- Hop1 directory copy (local↔bastion): walk + per-file SFTP via `ssh2-sftp-client` (independent TCP from exec)
+- `uploadPath` / `downloadPath` on AccessClient (file or directory)
+- `skipIfComplete` + result fields `skippedBytes` / `skipped` / `skipReason` (`size-match` | `hash-match`)
+- `resolveEffectiveVerify`: rejects `skipIfComplete` + `verify=none`
+- Job status `timeout`; `connectionTimeoutMs` for Hop1 SFTP connect
+
+### Changed
+
+- **BREAKING**: Removed Hop1 self-built stream engine and `.copy-meta.json` byte-offset resume
+- **BREAKING**: Removed `resume` (use `skipIfComplete`); removed `idleTimeoutMs`; renamed `resumedFrom` → `skippedBytes`
+- `remote_copy_file` remains sync-only; never auto-creates async jobs
+- Skip gate strength is explicitly `verify` (no auto-upgrade size→sha256)
+
+### Fixed
+
+- Hop1 upload `skipIfComplete`: verify fail after size match falls through to rewrite (aligned with download)
+- Directory skip accumulates `skippedBytes`; directory supports per-file `verify=size+sha256`
+
+### Removed
+
+- Stream upload/download, copy-meta helpers, `uploadFile`/`downloadFile` aliases, `resume` / `idleTimeoutMs` API surface
+
+## [2.2.1] - 2026-07-16
+
+### Fixed
+
+- Job terminal-state fence: cancel cannot overwrite success/failed; success cannot overwrite cancelled
+- Orphan reconcile on MCP start: leftover `queued|running` jobs → `failed` ("MCP restarted…")
+- Hop1 stream abort no longer `disconnect()`s the shared SSH client (avoids killing concurrent tools/jobs)
+- `exec` accepts `AbortSignal` and closes the channel (no 3× retry on abort/timeout)
+- Pipeline copies share one wall-clock `totalTimeoutMs` budget across hops; abort checked between hops
+- Upload fastPut / size-shortcut now run real verify; `verified: true` is no longer claimed without checks
+- Resume: same-size local without matching `.copy-meta.json` forces restart (no silent skip)
+- Stream idle timeout based on byte progress (+ write drain), not only read `data` events
+- Pre-aborted signal no longer hits `totalTimer` TDZ `ReferenceError`
+- Schema: `remote_copy_status` only accepts async `remote_copy_start` transferIds
+
+### Changed
+
+- Cancel messaging documents Hop2 best-effort abort
+- **Upload resume simplified**: no bastion-side meta / byte-offset append; `resume` only skips rewrite when remote size already matches + verify
+- Unified `withSftp` + single `verifyTransfer` for Hop1; removed unused `detach` and numeric timeout overload on upload/download
+- `throwIfAborted` lives in `copy-transfer` (shared)
+
+## [2.2.0] - 2026-07-16
+
+### Added
+
+- **Async copy jobs (M2)**: `remote_copy_start` / `remote_copy_status` / `remote_copy_cancel`
+- Job persistence under `~/.agent-compose/remote-copy/jobs/<transferId>.json` (override with `BASTION_COPY_JOB_ROOT`)
+- In-process worker runs the same Copy Engine as sync `remote_copy_file`; cancel via `AbortSignal` (Hop1 streams aborted; shared SSH kept)
+- Policy helpers: `shouldPreferAsyncCopy` (size>256MB or ETA>2min)
+- Docs: `docs/REMOTE_COPY_JOB_API.md` marked implemented
+
+### Changed
+
+- Server instructions / prompts recommend async tools for large or long-ETA copies
+- Hop1 stream upload/download honor `signal` for cooperative abort
+
+## [2.1.0] - 2026-07-16
+
+### Added
+
+- **`remote_copy_file` Hop1 SFTP resume**: optional `resume` with sibling `dest.copy-meta.json` (remote path/size/mtime) to prevent silent corruption
+- **Idle + total timeouts**: `idleTimeoutMs` (default 60s, resets on data) and `totalTimeoutMs` (wall clock); legacy `timeoutMs` maps to `totalTimeoutMs`
+- **Throttled progress**: `progressIntervalMs` (default 5s) + MCP `notifications/progress` when client provides `progressToken`
+- **Result fields**: `transferId`, `totalBytes`, `resumedFrom`, `verified`, `usedFastPath` (ready for future `remote_copy_status`)
+- **Verify modes**: `verify=none|size|size+sha256` (default `size`) for Hop1 transfers
+- Small files still use `fastGet`/`fastPut`; large files or `resume`/progress use streamed copy
+
+### Changed
+
+- `executeRemoteCopy` now takes an options object (breaking for direct JS callers; MCP schema remains backward compatible via optional fields)
+
+## [2.0.0] - 2026-07-06
+
+### Removed
+
+- **`remote_tail_file` tool** — use `remote_read_file` with `mode=tail` instead (breaking change)
+
+### Changed
+
+- Tool count reduced from 9 to 8; all docs/prompts/instructions updated
+
+## [1.4.0] - 2026-07-06
+
+### Added
+
+- `remote_read_file` unified file reading: `mode=head|tail`, shared `lines` parameter
+- Tail reads now include `totalLines` / `totalBytes` metadata (same as head)
+- `hop2PathUnion()` shared schema builder for bastion/pod/host targets (P0 refactor)
+- Tests for `resolveReadOptions`, `buildRemoteReadCommand`, deprecated tail alias
+
+### Changed
+
+- **`remote_tail_file` deprecated** — delegates to `remote_read_file` with `mode=tail`; kept for backward compatibility
+- `maxLines` on `remote_read_file` remains as deprecated alias for `lines` when `mode=head`
+
+## [1.2.0] - 2026-07-06
+
+### Added
+
+- **`remote_copy_file` `local` endpoint**: SFTP upload/download between MCP server machine and bastion
+- Chained routes: `local→pod`, `local→host`, `pod→local`, `host→local` (via bastion staging)
+
+## [1.1.0] - 2026-07-06
+
+### Added
+
+- **`remote_copy_file` tool**: copy files/directories between bastion, pod, and host; returns `{ success, bytes, message }` without file content
+- **`remote_read_file` metadata**: response includes `totalLines`, `totalBytes`, `truncatedByLines`, `truncatedByChars` for clearer truncation diagnosis
+- Unit tests for copy command builders and read-file metadata parsing
+
+### Changed
+
+- `remote_read_file` tool description documents default `maxLines=500` and `MAX_OUTPUT_CHARS` (65536) limits
+- Server instructions mention `remote_copy_file` and updated truncation guidance
+
+## [1.0.1] - 2026-07-03
+
+### Fixed
+
+- Bastion SSH auth: pass all configured methods (key, agent, password) to ssh2 instead of picking only the first — fixes empty SSH agent blocking `BASTION_PASSWORD` in IDE-launched MCP clients
+
+### Added
+
+- Unit tests: `truncateOutput`, `buildReadFileCommand` path escaping, `resolveSshAuthOptions` auth priority (injectable deps)
+- ESLint + Prettier, `CONTRIBUTING.md`
+- Expanded `SECURITY.md` (two-hop model, sshpass visibility, accept-new, ALLOWED_NAMESPACES scope)
+
+### Changed
+
+- Removed `parseRemoteTarget`; `remote_*` targets unified via `remote-schemas.ts` (`remoteInputToTarget` + `RemoteTarget` type)
+- `resolveSshAuthOptions` accepts optional deps for testability
+
+## [1.0.0] - 2026-07-02
+
+### Added
+
+- MCP server with 8 tools: `bastion_exec`, `k8s_list_pods`, `k8s_exec`, `k8s_logs`, `ssh_exec`, `remote_read_file`, `remote_tail_file`, `remote_ps`
+- Two-hop architecture: MCP client → SSH → bastion → kubectl / SSH / shell
+- Flexible bastion auth: SSH agent, default keys, `BASTION_PRIVATE_KEY_PATH`, or `BASTION_PASSWORD`
+- Remote host password support via `REMOTE_SSH_PASSWORD` / tool `password` (sshpass on bastion)
+- MCP prompts: `tool-selection`, `remote-debug-workflow`
+- Agent documentation (`docs/AGENT_GUIDE.md`) and configuration guide
+- Manual integration scripts under `scripts/manual/` (env-driven, not published to npm)
+- GitHub Actions CI (build + unit tests)
+
+### Security
+
+- Removed hardcoded credentials from manual scripts; use `scripts/manual/.env.local` instead
+- Added `SECURITY.md` with credential and sshpass guidance

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 host-execution-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# host-execution-mcp
+
+Generic [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for Access → HostExecutionContext → Runtime (shell / docker / kubectl via SSH jump or Paradi gateway).
+
+**Any MCP client** can connect (Cursor, Claude Desktop, VS Code, custom SDK) using stdio transport.
+
+## What it does
+
+```
+MCP Client → host-execution-mcp (local) → SSH → ACCESS landing Context → kubectl / docker / shell / optional derive → pods & hosts
+```
+
+Composable tools:
+
+| Tool | Purpose |
+|------|---------|
+| `access_check` | Short ACCESS SSH probe (`reachable` / `latencyMs`; not kubectl) |
+| `shell_exec` | Shell on landing Context (optional `contextKey`) |
+| `context_derive` | Derive child Context → `contextKey` (`ACCESS_KIND=ssh` only) |
+| `context_probe` | Probe docker/kubectl capabilities (unknown ≠ true) |
+| `docker_ps` / `docker_exec` / `docker_logs` | Docker Runtime on landing or derived Context (`contextKey`) |
+| `k8s_list_pods` | List pods (`kubectl get pods`) |
+| `k8s_exec` | Run command in pod container |
+| `k8s_logs` | Pod stdout/stderr (`kubectl logs`) |
+| `ssh_exec` | Derive + shell on remote host (`ACCESS_KIND=ssh`) |
+| `remote_read_file` | Read file head/tail (`mode=head\|tail`) on landing/pod/context |
+| `remote_copy_file` | Sync copy between local/landing/pod/context (SFTP for local↔landing; `skipIfComplete` / `totalTimeoutMs` / progress) |
+| `remote_copy_start` | Async copy job — returns `transferId` immediately (prefer for >256MB or ETA>2min) |
+| `remote_copy_status` | Poll async copy job progress |
+| `remote_copy_cancel` | Cancel async copy job |
+| `remote_ps` | List processes on landing/pod/context |
+
+Async job state: `~/.agent-compose/remote-copy/jobs/<transferId>.json` — see [docs/REMOTE_COPY_JOB_API.md](docs/REMOTE_COPY_JOB_API.md).
+
+No business logic, no hardcoded namespaces or paths.
+
+## Quick start
+
+### Option A — npx（推荐，无需 clone/build）
+
+Requires Node.js >= 18 only.
+
+```json
+{
+  "mcpServers": {
+    "host-execution": {
+      "command": "npx",
+      "args": ["-y", "host-execution-mcp@latest"],
+      "env": {
+        "ACCESS_HOST": "10.0.0.1",
+        "ACCESS_USER": "your-user"
+      }
+    }
+  }
+}
+```
+
+Pin a version for stability: `"args": ["-y", "host-execution-mcp@6.0.0"]`
+
+### Option B — 本地开发
+
+```bash
+cd packages/mcp/host-execution
+npm install
+npm run build
+```
+
+MCP config uses local path:
+
+```json
+"command": "node",
+"args": ["<ABS_PATH>/packages/mcp/host-execution/dist/index.js"]
+```
+
+### Minimal env
+
+Only `ACCESS_HOST` and `ACCESS_USER` are required. Configure any SSH auth you use (key path, default `~/.ssh` keys, SSH agent, and/or `ACCESS_PASSWORD`); the client tries each until one works. If your IDE exposes an empty SSH agent, set `ACCESS_PASSWORD` and it will be used after agent/key attempts fail. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
+
+## Publishing (maintainers)
+
+```bash
+npm run build && npm test
+npm publish          # or --registry for private npm
+```
+
+## Documentation
+
+- [使用教程（中文）](docs/USER_GUIDE.zh-CN.md) — Node.js 安装、MCP 配置、Agent 实用话术
+- [Agent usage guide](docs/AGENT_GUIDE.md) — for LLM agents after MCP handshake
+- [Configuration](docs/CONFIGURATION.md) — env vars, auth, client setup
+- [SECURITY.md](SECURITY.md) — trust boundaries, credentials, sshpass notes
+- [CHANGELOG.md](CHANGELOG.md)

package/SECURITY.md

@@ -0,0 +1,72 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 6.0.x   | Yes       |
+| 5.0.x   | Best effort |
+| 4.0.x   | Best effort |
+| < 4.0   | Best effort |
+
+## Reporting a vulnerability
+
+If you discover a security issue, please report it privately to the maintainers (do not open a public issue with exploit details).
+
+## Architecture and trust boundaries
+
+Operations follow **Access → HostExecutionContext → Runtime** (`access_check`, `shell_exec`, `context_*`, `k8s_*`, `docker_*`, `remote_*`):
+
+```
+MCP client → SSH → ACCESS_HOST (landing Context)
+                 → kubectl / docker / shell / optional derive(ssh) → Pod or host
+
+ACCESS_KIND=paradi-gateway: SSH username encodes TARGET; landing Context = TARGET (not the gateway OS).
+```
+
+There is **no direct path** from the MCP client machine to cluster pods or worker nodes. Treat compromise of the ACCESS landing (or Paradi gateway) as compromise of every target it can reach.
+
+## Credential storage
+
+| Credential | Typical location | Notes |
+|------------|------------------|-------|
+| ACCESS SSH key / agent | Local `~/.ssh`, `SSH_AUTH_SOCK`, or `ACCESS_PRIVATE_KEY_PATH` | Preferred over password; agent and password may both be configured — ssh2 tries each until one succeeds |
+| ACCESS password | MCP client env (`ACCESS_PASSWORD`) or `.env` | Dev only; never commit |
+| Target host password | MCP env (`TARGET_PASSWORD`) or per-tool `password` | Uses `sshpass` on ACCESS for derive (`ssh` kind) |
+| MCP client config | `.cursor/mcp.json`, Claude Desktop config, etc. | Often gitignored; treat as secret |
+
+**Never commit** `.env`, `scripts/manual/.env.local`, MCP configs with passwords, or private keys. Rotate credentials if they were ever committed or shared in chat logs.
+
+## sshpass and process visibility
+
+When `ssh_exec` / `context_derive` use a password (or `TARGET_PASSWORD`), the ACCESS landing runs:
+
+```bash
+sshpass -p '<password>' ssh ...
+```
+
+The password may appear in **`ps` / process listings on the landing** while the command runs. **Prefer SSH keys** for ACCESS→host derive. If passwords are unavoidable, restrict landing shell access and audit who can run MCP.
+
+## StrictHostKeyChecking=accept-new
+
+Remote host SSH uses `-o StrictHostKeyChecking=accept-new`. On first connect, unknown host keys are accepted automatically. This is intended for **controlled internal networks** where MITM risk is managed by network policy. For internet-facing hosts, pre-populate `known_hosts` on the bastion and consider key-based auth only.
+
+## ALLOWED_NAMESPACES scope
+
+`ALLOWED_NAMESPACES` restricts **kubectl tools only** (`k8s_list_pods`, `k8s_exec`, `k8s_logs`, and `remote_*` with `target=pod`). It does **not** restrict:
+
+- `shell_exec` — arbitrary shell on the ACCESS landing Context, including `kubectl` against any namespace
+- `ssh_exec` — SSH derive from ACCESS to any reachable host
+- `remote_*` with `target=landing` or materialized `target=context`
+
+For defense in depth, combine namespace whitelist with bastion RBAC, kubeconfig permissions, and limiting who can run the MCP server.
+
+## Operational risks
+
+- This server executes arbitrary shell commands on the bastion, in pods, and on remote hosts. There is no built-in command allowlist in v1.x.
+- Treat MCP access as equivalent to shell access on the bastion plus kubectl access in allowed namespaces.
+- Output is truncated at `MAX_OUTPUT_CHARS` (default 65536) to limit accidental large dumps.
+
+## Dependencies
+
+Run `npm audit` periodically and keep `@modelcontextprotocol/sdk`, `ssh2`, and `zod` updated.

package/dist/access/docker-runtime.d.ts

@@ -0,0 +1,38 @@
+import type { ExecOutput } from "../ssh/access-client.js";
+import type { SessionPool } from "./session-pool.js";
+import type { HostExecutionContext } from "./types.js";
+/** Docker Runtime — only consumes Context + SessionPool (Invariant B). */
+export declare function buildDockerPsCommand(options: {
+    all?: boolean;
+    quiet?: boolean;
+    filter?: string;
+}): string;
+export declare function buildDockerExecCommand(container: string, command: string, options?: {
+    interactive?: boolean;
+    workdir?: string;
+}): string;
+export declare function buildDockerLogsCommand(container: string, options?: {
+    tail?: number;
+    since?: string;
+    timestamps?: boolean;
+}): string;
+export declare function ensureDocker(pool: SessionPool, ctx: HostExecutionContext, timeoutMs?: number): Promise<void>;
+export declare function dockerPs(pool: SessionPool, ctx: HostExecutionContext, options?: {
+    all?: boolean;
+    quiet?: boolean;
+    filter?: string;
+    timeoutMs?: number;
+}): Promise<ExecOutput>;
+export declare function dockerExec(pool: SessionPool, ctx: HostExecutionContext, args: {
+    container: string;
+    command: string;
+    workdir?: string;
+    timeoutMs?: number;
+}): Promise<ExecOutput>;
+export declare function dockerLogs(pool: SessionPool, ctx: HostExecutionContext, args: {
+    container: string;
+    tail?: number;
+    since?: string;
+    timestamps?: boolean;
+    timeoutMs?: number;
+}): Promise<ExecOutput>;

package/dist/access/docker-runtime.js

@@ -0,0 +1,61 @@
+import { bashSingleQuote } from "../utils/shell-quote.js";
+import { assertCapability, probeCapabilities } from "./probe.js";
+/** Docker Runtime — only consumes Context + SessionPool (Invariant B). */
+export function buildDockerPsCommand(options) {
+    const parts = ["docker", "ps"];
+    if (options.all) {
+        parts.push("-a");
+    }
+    if (options.quiet) {
+        parts.push("-q");
+    }
+    if (options.filter?.trim()) {
+        parts.push("--filter", bashSingleQuote(options.filter.trim()));
+    }
+    // Prefer stable columns for agents (skip format when quiet)
+    if (!options.quiet) {
+        parts.push("--format", bashSingleQuote("table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}"));
+    }
+    return parts.join(" ");
+}
+export function buildDockerExecCommand(container, command, options = {}) {
+    const parts = ["docker", "exec"];
+    if (options.workdir?.trim()) {
+        parts.push("-w", bashSingleQuote(options.workdir.trim()));
+    }
+    parts.push(bashSingleQuote(container.trim()));
+    // Run via bash -lc so pipelines/redirection work like other Runtimes
+    parts.push("bash", "-lc", bashSingleQuote(command));
+    return parts.join(" ");
+}
+export function buildDockerLogsCommand(container, options = {}) {
+    const parts = ["docker", "logs"];
+    if (options.timestamps) {
+        parts.push("-t");
+    }
+    if (options.since?.trim()) {
+        parts.push("--since", bashSingleQuote(options.since.trim()));
+    }
+    parts.push("--tail", String(options.tail ?? 200));
+    parts.push(bashSingleQuote(container.trim()));
+    return parts.join(" ");
+}
+export async function ensureDocker(pool, ctx, timeoutMs) {
+    if (ctx.capabilities.docker === "unknown") {
+        await probeCapabilities(pool, ctx, timeoutMs);
+    }
+    assertCapability(ctx, "docker");
+}
+export async function dockerPs(pool, ctx, options = {}) {
+    await ensureDocker(pool, ctx, options.timeoutMs);
+    return pool.exec(ctx, buildDockerPsCommand(options), options.timeoutMs);
+}
+export async function dockerExec(pool, ctx, args) {
+    await ensureDocker(pool, ctx, args.timeoutMs);
+    return pool.exec(ctx, buildDockerExecCommand(args.container, args.command, { workdir: args.workdir }), args.timeoutMs);
+}
+export async function dockerLogs(pool, ctx, args) {
+    await ensureDocker(pool, ctx, args.timeoutMs);
+    return pool.exec(ctx, buildDockerLogsCommand(args.container, args), args.timeoutMs);
+}
+//# sourceMappingURL=docker-runtime.js.map

package/dist/access/docker-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-runtime.js","sourceRoot":"","sources":["../../src/access/docker-runtime.ts"],"names":[],"mappings":"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"}