Terminal SSH MCP Server (v2)

基于 Rust 的 SSH MCP Server，为 Agent 提供稳定的远程 SSH 执行能力。

v2 目标

• 双轨执行模型：
  • ssh_exec：一次性命令执行
  • ssh_shell_open/write/read/exec：流式 shell + 精确退出码
• 结构化返回：统一 ok、error.code、error.message
• Host Key 策略：insecure / strict / accept_new
• 会话可观测：connected、shell_open、state、last_activity_at

工具列表

1. ssh_connect
2. ssh_exec
3. ssh_shell_open
4. ssh_shell_write
5. ssh_shell_read
6. ssh_shell_exec
7. ssh_shell_resize
8. ssh_shell_close
9. ssh_list_sessions
10. ssh_disconnect

推荐调用流程

一次性命令

1. ssh_connect
2. ssh_exec
3. ssh_disconnect

持久 shell

1. ssh_connect
2. ssh_shell_open
3. ssh_shell_write + ssh_shell_read（流式）
4. 或 ssh_shell_exec（单条命令+退出码）
5. ssh_shell_close
6. ssh_disconnect

连接参数（ssh_connect）

• host / port / username
• auth_method
  • {"type":"password","password":"..."}
  • {"type":"public_key","key_path":"~/.ssh/id_rsa","passphrase":null}
  • {"type":"agent"}
• host_key_policy（可选，默认 insecure）
  • insecure
  • strict
  • accept_new
• known_hosts_path（可选）
• connect_timeout_ms（可选）
• keepalive_interval_secs（可选）

ssh_shell_exec 说明

ssh_shell_exec 内部使用哨兵协议提取退出码，返回：

• output
• stdout
• stderr
• exit_code
• duration_ms
• timed_out
• truncated
• command_id

当传入 split_streams=true 时，stdout/stderr 会按流分离；否则 stderr 为空，output/stdout 为合并输出。

错误返回语义

失败时统一返回：

• ok: false
• error.code
• error.message
• error.category (auth / usage / timeout / transport / internal)
• error.retriable (布尔值，建议 agent 用于自动重试决策)

开发与测试

cargo clippy
cargo test

集成测试（需 SSH 容器环境）：

cargo test --test integration_ssh -- --ignored --nocapture

CI 中会覆盖：

• 密码认证端到端
• HostKey 策略（strict / accept_new）
• SSH Agent 认证端到端