内容
# SSH-Connect
一款基于 Rust 的 [模型上下文协议（Model Context Protocol）](https://modelcontextprotocol.io)（MCP）服务器，用于远程服务器管理和交互式网络设备/控制台管理，支持 **SSH、Telnet 和串行**，并附带一组技能和代理。
SSH-Connect 是 TypeScript `SSH-MCP` 工具的 Rust 继任者。它将两个早期的 Rust 项目合并为一个二进制文件：
- **服务器操作** — Linux/Ubuntu 管理（nginx、SSL/certbot、UFW、软件包、部署、systemd、MySQL/MariaDB、Redis、Docker、日志、进程、文件、cron）。每个命令都在自己的 SSH 通道上运行，并报告退出代码；文件传输使用 SFTP；可选的首次信任主机密钥检查可用。
- **交互式控制台** — 通过 SSH（PTY）、Telnet 和串行对交换机、路由器和控制台进行提示感知管理，具有分页处理、启用/登录流程和舰队命令。代理（Windows 命名管道/Unix 域套接字）允许多个 MCP 客户端共享一组实时会话和串行端口。
基于 `rmcp` MCP SDK 构建。SSH 完全使用 Rust via `russh`（无 OpenSSL/C 依赖）。
**下载：** Linux、macOS 和 Windows 的预编译二进制文件位于 [发布页面](https://github.com/mixelpixx/SSH-Connect/releases/latest) — 无需 Rust 工具链即可运行。
## 两种交互模式，一个服务器
| 目标 | 工具系列 | 连接方式 | 运行方式 |
|------|-------------|--------------|----------|
| 具有退出代码的 Linux/VPS 管理 | 服务器操作 | `ssh_connect` | `ssh_exec`、`vps_*`、`ubuntu_*` |
| 交换机、路由器、控制台、串行 | 交互式控制台 | `connect` | `run_command`、`enable`、`login` 等 |
两系列工具在同一进程中运行并共享代理，因此一个 MCP 客户端打开的会话可供另一个客户端使用。
## 工具
- **会话/发现（交互式）：** `connect`、`disconnect`、`list_sessions`、`list_com_ports`、`list_hosts`
- **交互式命令：** `run_command`、`run_commands`、`enable`、`login`、`expect_send`、`run_on_fleet`、`upload_config`、`download_config`
- **交换机便利：** `switch_backup_config`、`switch_network_diagnostics`
- **SSH 服务器操作：** `ssh_connect`、`ssh_exec`、`ssh_upload_file`、`ssh_download_file`、`ssh_list_files`、`ssh_disconnect`
- **VPS / Ubuntu：** `vps_system_stats`、`vps_logs`、`vps_process`、`vps_file_read`、`vps_file_ops`、`vps_cron`、`ubuntu_service_control`、`vps_nginx_config`、`ubuntu_nginx_control`、`ubuntu_update_packages`、`ubuntu_ssl_certificate`、`ubuntu_website_deployment`、`ubuntu_ufw_firewall`、`ubuntu_mysql`、`vps_redis`、`vps_docker`、`vps_health_check`
超时时，`ssh_exec`（和 `vps_*`/`ubuntu_*` 工具）返回错误并尝试终止远程命令。尝试不保证成功 — OpenSSH 可能忽略非 PTY 执行通道上的信号。`ubuntu_update_packages`、`ubuntu_ssl_certificate` 和 `vps_docker` 接受可选的 `timeoutMs`。对于可以运行数分钟的操作，请将其分离并轮询日志文件，而不是依赖长超时（请参阅 `vps-management` 技能）。
## 技能（`skills/`）
- **交换机管理** — 交换机/路由器的操作指南：供应商习惯、分页、启用/配置、保存、舰队操作、固件升级、控制台到 SSH 设置。
- **VPS 管理** — 安全更改规则和标准工作流程（补丁 + 重启、SSL/certbot 故障排除、服务恢复、长时间操作轮询）。
- **VPS 健康报告** — 标准化的 HTML 服务器健康报告（以及 JSON 边车和增量），由 `vps_health_check` 驱动。
- **健康报告** — 标准化的 HTML 网络设备健康报告（以及 JSON 边车）。
## 代理（`.claude/agents/`）
`vps-troubleshooter`、`switch-config-auditor`、`deployment-runner`、`fleet-health-reporter`、`vps-health-reporter`。
## 构建
需要最近的稳定 Rust 工具链。Rust 依赖项（包括 `rmcp = "1.8"`，来自 crates.io）由 Cargo 获取。
```sh
cargo build --release
# 二进制文件：target/release/ssh-connect （Windows 上为 ssh-connect.exe）
```
Windows 和 macOS 不需要系统软件包。在 **Linux** 上，`serialport` crate（用于 `list_com_ports` 和串行控制台访问）需要在构建时使用 `libudev`:
```sh
sudo apt-get install -y libudev-dev pkg-config # Debian/Ubuntu
```
如果您不想从源代码构建？Linux、macOS 和 Windows 的预编译二进制文件附在 [发布页面](https://github.com/mixelpixx/SSH-Connect/releases/latest) 的每个标记版本中（由 GitHub Actions 工作流 `release` 生成）。
## 注册到 MCP 客户端
克劳德代码:
```sh
claude mcp add ssh-connect --scope user -- /path/to/ssh-connect/target/release/ssh-connect
```
或在 MCP 设置文件中:
```json
{
"mcpServers": {
"ssh-connect": {
"command": "/path/to/ssh-connect/target/release/ssh-connect"
}
}
}
```
服务器通过 stdio 使用 MCP；所有日志记录都发送到 stderr（设置 `RUST_LOG=info` 以查看代理/角色消息）。
## 配置
- **库存：** 复制 `hosts.example.toml` 到 `hosts.toml` 并编辑。然后，`connect` 工具可以通过 `name` 单独访问设备。覆盖路径使用 `SSHCONNECT_HOSTS`。
- **机密：** 优先使用环境变量而不是提交密码。对于主机 `core-sw-01`，设置 `SSHCONNECT_CORE_SW_01_PASSWORD`（名称大写，非字母数字字符折叠为 `_`）；相同模式适用于 `USERNAME`、`HOST`、`PORT`、`KEY_PATH`。
- **主机密钥检查（服务器操作 SSH）：** 默认接受任何密钥。设置 `SSHCONNECT_HOST_KEY_CHECK=tofu`（遗留的 `VPS_HOST_KEY_CHECK` 也被接受）以启用对 `~/.ssh-connect/known_hosts` 的信任首次使用，这拒绝后来的密钥不匹配。
## 代理（多实例会话共享）
第一个实例成为每个机器的汇聚端点的所有者 — Windows 上的命名管道 (`\\.\pipe\ssh-connect-broker-v1`)，或 Linux/macOS 上的 Unix 域套接字（在 `$XDG_RUNTIME_DIR` 下，退回到临时目录）— 并持有实时连接和 COM 端口。后续实例充当代理，将 `tools/call` 转发给所有者，以便在一个客户端中打开的会话可供另一个客户端使用，并且两个客户端不能在同一个串行端口上发生冲突。工具模式由每个实例在本地提供。在没有可用传输的平台上，每个实例都是一个独立的所有者。
限制：如果所有者进程退出，现有的代理当前不会在会话中间重新选举新的所有者 — 重新启动受影响的客户端。新启动的实例始终能正确选举（并清除陈旧的套接字）。
## 测试
```sh
cargo test --bin ssh-connect
```
单元测试涵盖了 telnet IAC 解析器、提示/ANSI 输出处理、主机库存、串行端口探测和旧 SSH 算法集。通过向二进制文件发送 `initialize` + `tools/list` 序列并运行两个实例以确认所有者/代理选举来检查协议和代理行为。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
