host-execution-mcp

Generic Model Context Protocol (MCP) 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.

No business logic, no hardcoded namespaces or paths.

Quick start

Option A — npx（推荐，无需 clone/build）

Requires Node.js >= 18 only.

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

生产环境若要钉死版本，把 @latest 换成具体版本号即可。

Option B — 本地开发

cd packages/mcp/host-execution
npm install
npm run build

MCP config uses local path:

"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.

Publishing (maintainers)

npm run build && npm test
npm publish          # or --registry for private npm

Documentation

• 使用教程（中文） — Node.js 安装、MCP 配置、Agent 实用话术
• Agent usage guide — for LLM agents after MCP handshake
• Configuration — env vars, auth, client setup
• SECURITY.md — trust boundaries, credentials, sshpass notes
• CHANGELOG.md