ssh-licco 0.2.1__tar.gz

ssh_licco-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ssh_licco-0.2.1/PKG-INFO

@@ -0,0 +1,512 @@
+Metadata-Version: 2.4
+Name: ssh-licco
+Version: 0.2.1
+Summary: SSH Model Context Protocol Server - Enable SSH functionality for AI models
+Author-email: SSH LICCO Team <contact@ssh-licco.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/Echoqili/ssh-licco
+Project-URL: Repository, https://github.com/Echoqili/ssh-licco
+Keywords: mcp,ssh,model-context-protocol,ai,security,devops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: asyncssh>=2.17.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.7.0; extra == "dev"
+Dynamic: license-file
+
+# 🚀 SSH LICCO
+
+[![PyPI version](https://badge.fury.io/py/ssh-licco.svg)](https://badge.fury.io/py/ssh-licco)
+[![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**让 AI 帮你操作服务器！**
+
+SSH LICCO 是一个基于 Model Context Protocol (MCP) 的 SSH 服务器，让 AI 助手（Trae、Cursor、Claude Desktop 等）能够直接连接和管理你的 SSH 服务器。通过自然语言对话，AI 可以帮你执行命令、管理文件、查看日志、部署应用等。
+
+## ✨ 核心特性
+
+- 🎯 **自然语言控制** - 直接用对话方式操作服务器
+- 🔐 **多种认证方式** - 支持密码、密钥、Agent 转发
+- 🔗 **长连接支持** - 自动保活，避免频繁连接导致账户锁定
+- 📦 **多客户端支持** - Paramiko、Fabric、AsyncSSH 可插拔
+- 🛡️ **完善的异常处理** - 统一的异常体系和错误处理
+- 📊 **会话管理** - 支持多个并发 SSH 会话
+- 📁 **SFTP 文件传输** - 上传、下载、列出目录
+- 🔑 **密钥管理** - 生成、保存和管理 SSH 密钥对
+- 📝 **详细日志记录** - 支持多级日志和文件输出
+- 🚀 **高性能异步** - 基于 asyncio 的异步架构
+- 🔌 **连接池** - 高性能连接复用
+- 📊 **批量执行** - 多主机并行命令执行
+- 📝 **审计日志** - 完整操作审计记录
+
+### 技术栈
+- Python 3.10 - 3.13
+- MCP SDK 1.0+
+- AsyncSSH 2.17.0+
+- Pydantic 2.0+
+- asyncio 异步架构
+
+## 📦 安装
+
+### 方式一：pip 安装（推荐）
+
+```bash
+pip install ssh-licco
+```
+
+### 方式二：从源码安装
+
+```bash
+git clone https://github.com/Echoqili/ssh-licco.git
+cd ssh-licco
+pip install -e .
+```
+
+### 开发环境安装
+
+```bash
+git clone https://github.com/Echoqili/ssh-licco.git
+cd ssh-licco
+pip install -e ".[dev]"
+```
+
+**Python 版本要求：**
+- ✅ Python 3.10, 3.11, 3.12, 3.13
+- ❌ Python 3.9 及以下版本不支持
+- ❌ Python 3.14 及以上版本未测试
+
+## 🚀 快速开始
+
+### 1. 配置 MCP 服务器
+
+#### 在 Trae / Cursor 中使用
+
+打开设置 → MCP → 添加新服务器：
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "ssh-licco"
+    }
+  }
+}
+```
+
+#### 在 Claude Desktop 中使用
+
+配置文件位置：
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "ssh-licco"
+    }
+  }
+}
+```
+
+### 2. 配置 SSH 主机（可选但推荐）
+
+#### 方式 1：使用配置文件
+
+```bash
+cp config/hosts.json.example config/hosts.json
+```
+
+编辑 `config/hosts.json`：
+
+```json
+{
+  "ssh_hosts": [
+    {
+      "name": "生产服务器",
+      "host": "192.168.1.100",
+      "port": 22,
+      "username": "root",
+      "password": "your_password",
+      "timeout": 30
+    },
+    {
+      "name": "测试服务器",
+      "host": "192.168.1.101",
+      "port": 2222,
+      "username": "admin",
+      "password": "test123"
+    }
+  ]
+}
+```
+
+#### 方式 2：直接在 MCP 配置中指定
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "ssh-licco",
+      "env": {
+        "SSH_HOST": "192.168.1.100",
+        "SSH_USER": "root",
+        "SSH_PASSWORD": "your_password",
+        "SSH_KEEPALIVE_INTERVAL": "30",
+        "SSH_SESSION_TIMEOUT": "7200",
+        "SSH_CLIENT_TYPE": "asyncssh"
+      }
+    }
+  }
+}
+```
+
+### 3. 开始使用
+
+重启 AI 应用后，直接用自然语言对话：
+
+**示例 1：查看服务器状态**
+```
+帮我看看服务器的负载情况
+```
+
+**示例 2：执行命令**
+```
+在服务器上执行 docker ps 查看运行中的容器
+```
+
+**示例 3：管理文件**
+```
+列出 /var/log 目录下的所有文件
+```
+
+**示例 4：安装软件**
+```
+在服务器上安装 nginx
+```
+
+**示例 5：上传文件**
+```
+把本地的 config.yaml 上传到服务器的 /etc 目录
+```
+
+## 🔥 长连接功能（避免账户锁定）
+
+频繁连接 SSH 服务器可能导致账户被锁定。SSH LICCO 默认启用长连接和自动保活：
+
+- **自动保活**：每 30 秒发送心跳包，保持连接活跃
+- **持久会话**：默认保持 2 小时，避免频繁重连
+- **可配置**：根据需求调整保活间隔和会话时长
+
+### 配置参数
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "ssh-licco",
+      "env": {
+        "SSH_HOST": "43.143.207.242",
+        "SSH_USER": "root",
+        "SSH_PASSWORD": "your-password",
+        "SSH_KEEPALIVE_INTERVAL": "30",
+        "SSH_SESSION_TIMEOUT": "7200"
+      }
+    }
+  }
+}
+```
+
+## 🔌 连接池（高性能）
+
+SSH LICCO 支持连接池功能，提供高效的连接复用：
+
+- **连接复用**：避免频繁建立连接的开销
+- **健康检查**：自动检测并回收无效连接
+- **线程安全**：支持并发访问
+- **配置灵活**：可调整最大连接数、空闲时间等
+
+### 连接池配置
+
+```python
+from ssh_mcp import ConnectionConfig, PoolConfig, ConnectionPool
+
+# 配置连接池
+pool_config = PoolConfig(
+    min_size=1,           # 最小连接数
+    max_size=10,          # 最大连接数
+    max_idle_time=300,    # 最大空闲时间（秒）
+    max_use_count=100,   # 单连接最大使用次数
+    acquire_timeout=30    # 获取连接超时（秒）
+)
+
+# 创建连接池
+config = ConnectionConfig(
+    host="192.168.1.100",
+    username="admin",
+    private_key_path="~/.ssh/id_rsa"
+)
+pool = ConnectionPool(config, pool_config)
+pool.initialize()
+
+# 使用连接池
+with pool.acquire() as client:
+    result = client.execute_command("ls -la")
+```
+
+## 📊 批量执行（多主机管理）
+
+支持批量并行执行命令，管理多台服务器：
+
+- **并行执行**：多主机同时执行命令
+- **失败隔离**：单主机异常不影响其他主机
+- **进度回调**：实时反馈执行进度
+- **异步支持**：AsyncBatchExecutor 实现高并发
+
+### 批量执行示例
+
+```python
+from ssh_mcp import (
+    ConnectionConfig, 
+    BatchExecutor, 
+    AsyncBatchExecutor
+)
+
+# 配置多台主机
+hosts = [
+    ConnectionConfig(host="192.168.1.100", username="admin", private_key_path="~/.ssh/id_rsa"),
+    ConnectionConfig(host="192.168.1.101", username="admin", private_key_path="~/.ssh/id_rsa"),
+    ConnectionConfig(host="192.168.1.102", username="admin", private_key_path="~/.ssh/id_rsa"),
+]
+
+# 同步批量执行
+executor = BatchExecutor(hosts, max_workers=10)
+result = executor.execute("uptime")
+
+print(f"成功: {result.success_count}, 失败: {result.failed_count}")
+for host_result in result.results:
+    print(f"{host_result.host}: {host_result.stdout}")
+
+# 异步批量执行
+async_executor = AsyncBatchExecutor(hosts, max_concurrent=50)
+result = await async_executor.execute("df -h")
+```
+
+## 📝 审计日志
+
+完整的操作审计日志，满足合规要求：
+
+- **结构化日志**：JSON 格式便于分析
+- **操作记录**：连接、执行命令、文件传输
+- **认证审计**：成功/失败认证记录
+
+### 使用审计日志
+
+```python
+from ssh_mcp import get_audit_logger, AuditEventType
+
+# 初始化审计日志
+audit = get_audit_logger("logs/audit.log")
+
+# 记录连接事件
+audit.log_connect(
+    username="admin",
+    host="192.168.1.100",
+    port=22,
+    client_type="asyncssh",
+    session_id="session-123"
+)
+
+# 记录命令执行
+audit.log_command(
+    username="admin",
+    host="192.168.1.100",
+    command="ls -la",
+    return_code=0,
+    stdout_length=1024,
+    stderr_length=0,
+    session_id="session-123"
+)
+```
+
+详细配置说明见 [CONFIG_GUIDE.md](CONFIG_GUIDE.md)
+
+## 🛠️ 可用工具
+
+| 工具 | 说明 | 示例 |
+|------|------|------|
+| `ssh_config` | 配置 SSH 连接信息 | 配置服务器地址、用户名、密码 |
+| `ssh_login` | 使用保存的配置登录 | 登录后执行命令 |
+| `ssh_connect` | 直接连接 SSH | 支持预配置主机或即时连接 |
+| `ssh_execute` | 执行命令 | 在会话中执行任意命令 |
+| `ssh_disconnect` | 断开连接 | 关闭指定会话 |
+| `ssh_list_sessions` | 列出活跃会话 | 查看所有 SSH 会话 |
+| `ssh_generate_key` | 生成 SSH 密钥 | 创建 RSA 或 ED25519 密钥对 |
+| `ssh_file_transfer` | SFTP 文件传输 | 上传、下载、列出目录 |
+
+详细使用说明见 [USAGE.md](USAGE.md)
+
+## 🏗️ 架构设计
+
+SSH LICCO 采用分层架构设计，遵循最佳实践：
+
+### 核心模块
+
+```
+ssh_mcp/
+├── clients/              # SSH 客户端层（可插拔）
+│   ├── interface.py     # 抽象接口定义
+│   ├── paramiko_client.py  # Paramiko 实现
+│   ├── additional_clients.py # 其他客户端实现
+│   └── factory.py       # 客户端工厂
+├── service.py           # 业务服务层
+├── session_manager.py   # 会话管理
+├── connection_config.py # 配置模型
+├── connection_pool.py  # 连接池管理
+├── batch_executor.py   # 批量执行器
+├── audit_logger.py     # 审计日志
+├── exceptions.py        # 统一异常体系
+├── logging_config.py    # 日志管理
+└── server.py           # MCP 服务端
+```
+
+### 设计模式
+
+- **工厂模式**：SSHClientFactory 动态创建客户端
+- **策略模式**：支持多种 SSH 客户端实现
+- **单例模式**：全局 SSHService 实例
+- **上下文管理器**：自动连接/断开管理
+
+### 客户端支持
+
+当前仅支持 **AsyncSSH** 客户端：
+
+| 客户端 | 类型 | 特点 | 安装 |
+|--------|------|------|------|
+| **AsyncSSH** | 异步 | 高并发性能，异步架构，默认且唯一 | `pip install asyncssh` |
+
+**说明：** 为了简化维护和优化性能，本项目目前仅支持 AsyncSSH 客户端。AsyncSSH 提供：
+- ✅ 异步架构，高并发性能
+- ✅ 低资源占用
+- ✅ 现代化的 API 设计
+- ✅ 活跃的社区支持
+
+### 配置客户端类型
+
+当前默认且仅支持 **AsyncSSH** 客户端，无需额外配置。
+
+如需指定（兼容性）：
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "ssh-licco",
+      "env": {
+        "SSH_CLIENT_TYPE": "asyncssh"
+      }
+    }
+  }
+}
+```
+
+详见 [🔌 客户端类型配置指南](docs/CLIENT_TYPES.md)
+
+## 🔒 安全注意事项
+
+⚠️ **重要提示：**
+
+1. **密码安全** - 密码仅本地存储，建议使用后清除配置文件
+2. **不要分享** - 不要在公开场合分享服务器密码
+3. **密钥认证** - 优先使用 SSH 密钥认证而非密码
+4. **普通用户** - 尽量使用普通用户而非 root 用户
+5. **文件权限** - 确保 `config/hosts.json` 文件权限设置为 600
+6. **环境变量** - 使用环境变量存储敏感信息更安全
+
+## 📚 文档
+
+- [📖 使用指南](USAGE.md) - 详细的工具使用说明
+- [⚙️ 配置指南](CONFIG_GUIDE.md) - 完整的配置选项说明
+- [🐳 Docker 超时问题](DOCKER_MCP_TIMEOUT.md) - Docker 构建相关问题
+- [📝 API 参考](docs/API_REFERENCE.md) - API 接口文档
+- [❓ 故障排除](docs/TROUBLESHOOTING.md) - 常见问题和解决方案
+
+## 💻 开发
+
+### 运行测试
+
+```bash
+pytest
+```
+
+### 代码检查
+
+```bash
+# 代码格式化
+ruff check ssh_mcp
+
+# 类型检查
+mypy ssh_mcp
+```
+
+### 构建文档
+
+```bash
+cd docs
+mkdocs build
+```
+
+## 🤝 贡献
+
+欢迎贡献代码、报告问题或提出建议！
+
+1. Fork 本仓库
+2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
+3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
+4. 推送到分支 (`git push origin feature/AmazingFeature`)
+5. 开启 Pull Request
+
+详见 [CONTRIBUTING.md](docs/CONTRIBUTING.md)
+
+## 📄 许可证
+
+本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件
+
+## 🙏 致谢
+
+- [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) - Model Context Protocol
+- [Paramiko](https://github.com/paramiko/paramiko) - SSH 库
+- [Fabric](https://github.com/fabric/fabric) - 高级 SSH 库
+- [AsyncSSH](https://github.com/ronf/asyncssh) - 异步 SSH 库
+
+## 📬 联系方式
+
+- **项目地址**: https://github.com/Echoqili/ssh-licco
+- **问题反馈**: https://github.com/Echoqili/ssh-licco/issues
+- **PyPI**: https://pypi.org/project/ssh-licco/
+
+---
+
+<div align="center">
+
+**Made with ❤️ by SSH LICCO Team**
+
+[![Star History Chart](https://api.star-history.com/svg?repos=Echoqili/ssh-licco&type=Date)](https://star-history.com/#Echoqili/ssh-licco&Date)
+
+</div>