# Linux SSH MCP - WindTerm 风格终端模拟器

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/badge/version-2.0.0-green.svg)](https://pypi.org/project/linux-ssh-mcp/)
[![MCP](https://img.shields.io/badge/MCP-2.0-purple.svg)](https://modelcontextprotocol.io/)

🚀 **WindTerm 风格的终端模拟器，通过 Model Context Protocol (MCP) 与 AI 助手集成**

通过自然语言管理多台 Linux 服务器：多标签页 SSH 会话、命令执行、文件传输、工作区持久化，全部暴露为 AI 助手可调用的 MCP 工具。

## 核心功能

### 🖥️ 多标签页 SSH 会话管理
- **多标签页**：像浏览器一样同时管理多台服务器的终端会话
- **会话切换**：在多个活跃会话间快速切换
- **工作区持久化**：把一组服务器会话保存为命名工作区，随时恢复

### 🤖 AI 助手集成（MCP 2.0）
- **17 个 MCP 工具**：终端管理、命令执行、文件传输、会话控制全覆盖
- **自然语言驱动**：用一句话创建会话、执行命令、传输文件
- **stdio 传输**：与 Claude Code 等 MCP 客户端无缝对接

### 📁 文件传输（SFTP）
- 上传 / 下载文件
- 直接读取远端文件内容

### ⚡ 跨平台
- 纯 `asyncssh` 实现，Windows / Linux / macOS 均可运行，无需本地 PTY

## 系统要求

- Python **3.9+**
- 可访问的 SSH 服务器

## 快速开始

### 安装

```bash
# 从 PyPI 安装
pip install linux-ssh-mcp

# 开发模式（克隆仓库后）
pip install -e ".[dev]"
```

### 接入 Claude Code

```bash
claude mcp add linux-ssh-mcp python -m linux_ssh_mcp.cli_v2
```

接入后，AI 助手即可通过自然语言操作你的服务器：

> "连接到 web-server，执行 `df -h` 查看磁盘空间"
> "把本地的 deploy.sh 上传到生产服务器的 /opt/app/"
> "保存当前所有会话为'日常巡检'工作区"

### 服务器配置（可选）

首次使用可生成示例配置：

```bash
linux-ssh-mcp init          # 生成 ~/.ssh-mcp/servers.json
linux-ssh-mcp check         # 检查配置并列出已配置服务器
```

配置文件 `servers.json` 示例：

```json
{
  "version": "2.0",
  "servers": {
    "web-server": {
      "id": "web-server",
      "host": "192.168.1.100",
      "port": 22,
      "username": "admin",
      "password": "your_password"
    }
  }
}
```

**配置文件搜索路径**（按优先级）：

1. `SSH_MCP_CONFIG_PATH` 环境变量
2. `~/.ssh-mcp/servers.json`
3. 平台特定目录：Windows `%APPDATA%/ssh-mcp/`、Linux/macOS `~/.config/ssh-mcp/`
4. 当前工作目录 `./servers.json`
5. 项目根目录 `servers.json`

## 命令行工具

```bash
# 启动 MCP 服务器（供 Claude Code 连接）
linux-ssh-mcp server
linux-ssh-mcp server --debug       # 调试日志

# 检查配置
linux-ssh-mcp check

# 创建示例配置
linux-ssh-mcp init

# 测试终端连接
linux-ssh-mcp test 192.168.1.100 admin --password your_password --port 22
```

也可通过 Python 模块运行：

```bash
python -m linux_ssh_mcp.cli_v2 server
python -m linux_ssh_mcp.mcp_server_v2
```

## MCP 工具清单

AI 助手通过以下 17 个工具操作终端（由 `WindTermMCPServer` 在 `mcp_server_v2.py` 中注册）：

| 分类 | 工具名 | 说明 |
|------|--------|------|
| **标签页** | `create_terminal_tab` | 创建并连接一个 SSH 终端标签页 |
| | `switch_terminal_tab` | 切换活跃标签页 |
| | `list_terminal_tabs` | 列出所有标签页 |
| | `close_terminal_tab` | 关闭标签页并断开 SSH |
| **交互** | `send_terminal_input` | 向终端发送命令（默认活跃标签页） |
| | `get_terminal_output` | 获取终端输出（支持增量读取） |
| | `resize_terminal` | 调整终端尺寸 |
| **会话/工作区** | `save_session_workspace` | 保存当前标签页为命名工作区 |
| | `restore_session_workspace` | 恢复已保存的工作区 |
| | `list_workspaces` | 列出已保存的工作区 |
| | `get_session_stats` | 获取会话统计信息 |
| **历史/控制** | `get_command_history` | 获取命令历史 |
| | `pause_terminal` | 暂停终端（拒绝新输入） |
| | `resume_terminal` | 恢复暂停的终端 |
| **文件（SFTP）** | `upload_file` | 上传本地文件到远端 |
| | `download_file` | 下载远端文件到本地 |
| | `read_remote_file` | 直接读取远端文件内容 |

> 未指定 `tab_id` 的工具默认作用于当前活跃标签页。

## Python API

```python
import asyncio
from linux_ssh_mcp.simple_terminal_manager import (
    SimpleTerminalSessionManager, ServerConfig,
)

async def main():
    manager = SimpleTerminalSessionManager()

    # 创建并连接一个终端会话
    config = ServerConfig(
        id="web-server",
        host="192.168.1.100",
        port=22,
        username="admin",
        password="your_password",
        timeout=30,
    )
    tab = await manager.create_tab(config, title="Web Server")

    # 执行命令并读取输出
    await tab.send_input("uptime")
    print("\n".join(tab.get_output(20)))

    # 保存为工作区，之后可恢复
    await manager.save_workspace("daily-check")

    await manager.shutdown()

asyncio.run(main())
```

包导出的主要符号（`linux_ssh_mcp`）：

- `SimpleTerminalSessionManager`、`SimpleTabSession`、`ServerConfig`、`TabStatus` — MCP 服务器实际使用的会话栈
- `TerminalSessionManager`、`PTYManager`、`TerminalProtocolHandler` — 完整 PTY 栈（真 PTY + 终端协议，尚未接入 MCP 服务器）
- `EnhancedSSHManager` — SSH 连接池管理
- `ScriptingEngine` — 脚本自动化引擎

## 架构说明

本项目包含**两套并行的会话实现**：

1. **Simple 栈（生产路径）** —— `WindTermMCPServer` → `SimpleTerminalSessionManager` → `asyncssh`
   直接通过 `asyncssh` 执行命令并把输出收集到内存缓冲。跨平台、零本地依赖，AI 助手调用的就是这条链路。适合命令式操作（占运维场景绝大多数）。

2. **Full PTY 栈** —— `TerminalSessionManager` → `terminal_emulator`（真 PTY + ANSI/VT100/xterm-256color）+ `EnhancedSSHManager`
   功能更完整，支持真正的交互式终端（如 `vim`、`top` 等全屏程序）。目前仅被 `test` 命令使用，**尚未接入 MCP 服务器**。

详见 `CLAUDE.md` 的架构章节。

## 开发

```bash
# 运行测试套件（生产路径 Simple 栈 + 终端模拟器）
python -m pytest tests/

# 运行单个测试
python -m pytest tests/test_simple_terminal_manager.py -v

# 代码质量
black src/ tests/        # 格式化（行宽 88）
mypy src/                # 类型检查
flake8 src/              # 风格检查
```

> Full 栈的 PTY+SSH 集成测试默认跳过；设置环境变量 `SSH_MCP_TEST_HOST` 指向一台可达的 SSH 服务器后才会运行。

### 构建发布

```bash
python -m build
python -m twine upload dist/*
```

## 入口点

| 命令 | 模块 |
|------|------|
| `linux-ssh-mcp` / `ssh-mcp` | `linux_ssh_mcp.cli_v2:main` |
| `linux-ssh-mcp-server` | `linux_ssh_mcp.mcp_server_v2:main` |

## 许可证

[MIT License](LICENSE)

---
[![M8ven Verified](https://m8ven.ai/badge/mcp/jindezhidiye-linux-ssh-mcp-1ky5az)](https://m8ven.ai/mcp/jindezhidiye-linux-ssh-mcp-1ky5az)
<!-- m8ven-verify: 4fe5c672463c5780478f3ae96beda888 -->
**Built with ❤️ for the Linux SSH management community**