sshoc 0.2.1

Lightweight SSH toolkit with optional MCP(stdio) JSON-RPC adapter

SSHOC

English | 简体中文

A lightweight, config-driven SSH toolkit (CLI + optional MCP stdio adapter).

• CLI: sshoc (list/run/upload/download/hostkey/..., plus prefix mode sshoc <profile>: <command...>)
• MCP (stdio): sshoc-mcp (line-delimited JSON-RPC, exposes ssh.* tools to MCP clients)
• Dependency: paramiko (SSH/SFTP)

Goal: strict, predictable, easy to embed (especially for automation / AI workflows).

---

Quick start (pip users)

1. Install:

python -m pip install -U sshoc

Windows note: if sshoc is still “not recognized” after install, your Python scripts directory (where sshoc.exe is generated) is likely not on PATH. Print the scripts directory and add it to PATH, then reopen your terminal:

python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

2. Initialize config (recommended: per-user config directory):

# Password auth (recommended: store password in an env var)
sshoc init demo --ssh "ssh -p 22 user@host" --password-env SSHOC_DEMO_PASSWORD

# Or: key auth
sshoc init demo --ssh "ssh -p 22 user@host" --key-path ~/.ssh/id_ed25519

3. Set the password env var (only needed for password_env):

$env:SSHOC_DEMO_PASSWORD="your_password"

export SSHOC_DEMO_PASSWORD="your_password"

4. First connection (known_hosts):

Default known_hosts_policy=strict. If the host key is not present in your local known_hosts, the first connection will fail. Recommended: write the host key first (optionally verify a trusted fingerprint):

sshoc hostkey ensure demo
# Strongly recommended (if you can get a trusted fingerprint from your provider/admin):
# sshoc hostkey ensure demo --expected-fingerprint "SHA256:..."

5. Run a command:

sshoc demo: uname -a
# Or
sshoc run demo --cmd "uname -a"

---

Installation (development)

Install from source (recommended: create a venv in this directory):

cd "SSH_Operation_Component (MCP)"
python -m venv .venv
.venv\\Scripts\\activate
python -m pip install -U pip
python -m pip install -e .

---

Configuration

Where is the config file (and which one is in use)?

sshoc config path

Practical tip: pin the config path with SSHOC_CONFIG

$env:SSHOC_CONFIG="C:\\path\\to\\sshoc.config.json"

export SSHOC_CONFIG="/path/to/sshoc.config.json"

Key fields (cheatsheet)

• servers.<profile>: profile name (recommended: A-Za-z0-9_-)
• servers.<profile>.ssh_command: common form ssh -p <port> user@host
• auth.type:
  • password: password or password_env
  • key: private_key_path (optional private_key_passphrase_env)
• known_hosts_policy:
  • strict: default; unknown host keys fail fast (safer)
  • accept_new: auto-write to known_hosts_path on first connect (TOFU)
• known_hosts_path: OpenSSH known_hosts path (template default: ~/.ssh/known_hosts)
• default_shell: default bash -lc (set to null if the remote has no bash)

---

CLI

Common commands

sshoc list
sshoc demo: "ls -la /root"
sshoc run demo --cmd "python -V"
sshoc upload demo --local ./local.txt --remote /tmp/local.txt --overwrite
sshoc download demo --remote /tmp/local.txt --local ./downloaded.txt --overwrite

Host key / known_hosts

These commands print JSON (friendly for scripts/CI/automation).

# Scan the remote host key (no auth)
sshoc hostkey scan demo

# Check whether the host is present in known_hosts
sshoc hostkey is-known demo

# Scan + write into known_hosts (optional fingerprint verification)
sshoc hostkey ensure demo
sshoc hostkey ensure demo --expected-fingerprint "SHA256:..."

# Manually add a key (if you already have key_type + base64)
sshoc hostkey add demo --key-type ssh-ed25519 --public-key-base64 "<BASE64>"

# Precise removal: remove one key type, or remove all key types for the host
sshoc hostkey remove demo --key-type ssh-ed25519
sshoc hostkey remove demo --all-types

---

MCP (stdio) server

Start:

sshoc-mcp

Tools:

• ssh.init_config — create sshoc.config.json (call this first if no config exists; the AI can self-configure)
• ssh.list_profiles
• ssh.scan_host_key
• ssh.is_known_host
• ssh.add_known_host
• ssh.ensure_known_host
• ssh.run — run a command synchronously (blocks until done, default 120s timeout)
• ssh.upload
• ssh.download
• ssh.run_async — submit a command for background execution, returns a task_id immediately (ideal for long-running tasks)
• ssh.task_status — query the status and output of a background task
• ssh.task_kill — terminate a running background task

Zero-config startup: sshoc-mcp starts even without a config file. Tools that need a config will return a CONFIG_NOT_FOUND error with a suggestion to call ssh.init_config. This lets MCP clients (e.g. AI assistants) discover the tools first, then create the config on demand.

Background tasks (v0.2.0+)

ssh.run is synchronous with a default 120s timeout, which is not suitable for long-running tasks (builds, deployments, training, etc.). The background task tools provide async execution:

1. ssh.run_async   {profile, command}         → returns {task_id, status: "running"} immediately
2. ssh.task_status {task_id}                   → returns {status, exit_code, stdout, stderr, ...}
3. ssh.task_kill   {task_id}                   → terminates the task

• ssh.run_async has no timeout by default (optionally pass timeout_sec)
• stdout/stderr are buffered in real time; ssh.task_status can read partial output while the task is still running
• task_id is a session-scoped incrementing integer ("1", "2", ...), reset when the MCP server restarts

Generic stdio config blueprint (for MCP clients)

Different MCP clients may use different config formats, but the essentials are usually: command / args / env / cwd. Below is a generic blueprint (field names are for reference—adapt to your client):

{
  "mcpServers": {
    "sshoc": {
      "command": "sshoc-mcp",
      // args/env are optional; the AI can call ssh.init_config to create the config.
      // If you prefer to pin a config file, use:
      // "args": ["--config", "<ABS_CONFIG_PATH>"],
      "env": {
        "SSHOC_DEMO_PASSWORD": "your_password",
        "SSHOC_DEBUG": "0"
      }
    }
  }
}

---

Security notes (strongly recommended)

• Never commit plaintext passwords; prefer password_env
• accept_new is TOFU (trust on first use); safer: verify with --expected-fingerprint
• This tool effectively gives automation/AI a remote execution entry point—use it only in environments you trust

---

License

Apache-2.0 (see LICENSE)