# 🚀 ssh-pro-mcp: 生产级专业 SSH 运维管理 MCP 服务器

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-2.0-green.svg)](https://modelcontextprotocol.io/)

专为 AI Agent (Claude / Cursor / Antigravity) 与自动化运维场景打造的**生产级 SSH 智能管理与远程运维 MCP 服务**。内置长连接热复用池、AI 幻觉高危指令防火墙、多主机资产批量管理、长耗时异步后台作业跟踪、SFTP 完整文件流传输、一键 DevOps 系统画像体检与 SSH 端口转发隧道。

---

## 🌟 核心特性 (Key Features)

- ⚡ **连接池长连接热复用 (Connection Pooling)**：消除常规单次调用建立 SSH 握手的 1~3s 延迟，支持 Keepalive 心跳与连接断开自动恢复。
- 🛡️ **AI 智能高危防御与只读模式 (Safety & Guardrails)**：
  - 自动拦截 `rm -rf /`、格式化 `mkfs`、底层 `dd` 覆写、Fork 炸弹、清空防火墙等高危指令，必须显式传递 `force=True` 才能执行。
  - 支持主机级 `read_only=True` 强约束，彻底阻断任何写操作与文件修改。
  - 采用 SQLite 记录不可篡改的本地命令执行审计日志。
- 🏢 **多主机资产中心与跳板机穿透 (Host Inventory & JumpHost)**：
  - 支持密码、多算法私钥（RSA/Ed25519/ECDSA）、Passphrase、跳板机（ProxyJump）链路穿透。
  - 支持一键无损导入系统原生 `~/.ssh/config` 配置。
  - 敏感凭证多层脱敏返回，防止凭据泄露。
- 🔄 **多元化执行模式 (Multi-Mode Execution)**：
  - **同步命令 (`ssh_exec_command`)**：捕获标准输出/错误、退出码、执行耗时，自动剥离 ANSI 颜色码。
  - **多行脚本分发 (`ssh_exec_script`)**：一键下发 Bash/Python/Node 脚本并在远端安全执行与清理。
  - **跨机批量并发 (`ssh_exec_batch`)**：按多主机列表或标签（如 `tag:prod`）多线程并发执行并聚合输出。
  - **后台守护作业 (`ssh_job_*`)**：通过 nohup + PID 托管长耗时任务，支持实时日志抓取 (`logs`) 与生命周期控制 (`status`/`kill`)。
- 📂 **高性能 SFTP 文件流管理 (SFTP Stream)**：
  - 目录递归树浏览、分片分块大文件读写（支持 Base64）、原子覆盖写入安全保护、本地与远端文件夹递归双向同步。
- 🩺 **一键 DevOps 诊断与监控 (DevOps Diagnostics)**：
  - `ssh_ops_sysinfo`：全景系统画像（发行版、内核、CPU核心、虚拟化类型、运行负载）。
  - `ssh_ops_metrics`：实时 CPU/内存/Swap 占用率看板、各挂载点磁盘空间 `df -h`、网络 IP。
  - `ssh_ops_processes`：Top 资源消耗进程排行与关键字过滤。
  - `ssh_ops_service`：systemd 服务生命周期管控 (status/start/stop/restart/logs)。
  - `ssh_ops_docker`：Docker 容器与镜像一键检视与重启。
  - `ssh_ops_ports`：远程网络监听端口与关联进程扫描。
- 🔀 **SSH 端口转发隧道 (Port Forwarding)**：
  - 本地端口转发（如将远端 MySQL 3306 映射到本地 127.0.0.1:13306），后台线程安全维护与动态销毁。

---

## 🛠️ MCP 工具清单 (Tools Catalog)

| 分类 | 工具名称 | 功能描述 |
| :--- | :--- | :--- |
| **资产管理** | `ssh_host_add` | 注册或更新目标主机（支持 IP/端口/跳板机/标签/只读） |
| | `ssh_host_list` | 列出已配置主机清单（已脱敏） |
| | `ssh_host_get` | 获取单个主机脱敏详情 |
| | `ssh_host_remove` | 删除主机配置并断开连接 |
| | `ssh_host_import_ssh_config` | 一键解析导入系统 `~/.ssh/config` |
| | `ssh_host_ping` | 测试主机连通性与测量握手延迟 |
| **命令执行** | `ssh_exec_command` | 同步执行远程 Shell 命令（支持 sudo/PTY/工作目录） |
| | `ssh_exec_script` | 远程分发并执行多行脚本（Bash/Python/Node） |
| | `ssh_exec_batch` | 跨多台主机（或按 tag）多线程并发执行命令 |
| **后台作业** | `ssh_job_start` | 启动长耗时后台任务 (nohup+PID) |
| | `ssh_job_status` | 查看后台作业运行状态与尾部日志 |
| | `ssh_job_logs` | 抓取后台作业最新日志输出 |
| | `ssh_job_kill` | 终止后台作业进程 |
| **SFTP 文件** | `sftp_list_dir` | 浏览远端目录文件列表与元数据 |
| | `sftp_read_file` | 读取远端文件（支持大文件分片与 Base64） |
| | `sftp_write_file` | 创建或写入远端文件（支持原子写入保护） |
| | `sftp_mkdir` | 创建远程目录（支持递归 -p） |
| | `sftp_remove` | 删除远程文件或目录 |
| | `sftp_upload` | 递归上传本地文件/文件夹至远端 |
| | `sftp_download` | 递归下载远端文件/文件夹至本地 |
| **DevOps 诊断** | `ssh_ops_sysinfo` | 生成全景系统画像（发行版/内核/CPU/虚拟化） |
| | `ssh_ops_metrics` | 获取实时硬件指标（内存/Swap/磁盘/IP） |
| | `ssh_ops_processes` | Top 资源消耗进程排行与过滤 |
| | `ssh_ops_service` | systemd 服务管理与 journalctl 日志查看 |
| | `ssh_ops_docker` | Docker 容器状态、镜像统计与容器日志 |
| | `ssh_ops_ports` | 扫描开放监听端口 (TCP/UDP) 与绑定进程 |
| **端口隧道** | `ssh_tunnel_create` | 创建本地端口转发隧道 |
| | `ssh_tunnel_list` | 查看当前所有活跃隧道 |
| | `ssh_tunnel_close` | 关闭指定隧道并释放端口 |
| **安全审计** | `ssh_audit_logs` | 查询本地命令执行不可篡改审计记录 |

---

## 📦 安装与配置 (Installation & Configuration)

### 1. 安装依赖
```bash
pip install -r requirements.txt
```

### 2. 在 MCP 客户端中配置

在 Antigravity / Claude Desktop 的配置文件中添加：

```json
{
  "mcpServers": {
    "ssh-pro": {
      "command": "python",
      "args": [
        "C:/Users/baiyec/.gemini/antigravity/scratch/ssh-pro-mcp/mcp_server.py"
      ]
    }
  }
}
```

如需启动为 HTTP 模式：
```bash
python mcp_server.py --http --port 9022
```

---

## 🧪 自动化测试验证 (Testing)

项目采用纯 Python 标准库编写了全套自动化测试，无外部 Mock 库依赖：

```bash
python -m unittest discover -s tests -v
```

测试覆盖率包含：
- ✅ 高危指令拦截与只读防护测试
- ✅ SQLite 审计日志持久化测试
- ✅ 主机资产 CRUD 与 `~/.ssh/config` 导入测试
- ✅ 远程执行、超时、Sudo 提权与并发批量测试
- ✅ SFTP 读写、原子写入与递归遍历测试
- ✅ 系统全景画像、硬件指标与进程解析测试
- ✅ SSH 端口转发隧道生命周期测试
- ✅ MCP Server Tools 协议接口端到端调用测试

---

## 📄 开源许可证 (License)

本项目遵循 [MIT License](LICENSE) 开源协议。