@lzm04521/ssh-mcp-server 1.1.5

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 SIE Operations and Maintenance Team
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+<div align="center">
+
+<img src="images/logo.png" alt="ssh-mcp-server logo" width="160">
+
+# SSH MCP Server
+
+**让 AI 客户端安全地操作你的服务器 —— 基于 SSH 的 MCP 服务器**
+
+通过标准化 MCP 工具在远端执行命令与传输文件，内置 Web 管理台。
+
+[![npm](https://img.shields.io/npm/v/@lzm04521/ssh-mcp-server)](https://www.npmjs.com/package/@lzm04521/ssh-mcp-server)
+
+</div>
+
+## 它能做什么
+
+把 Claude Code、Cursor 等支持 MCP 协议的 AI 客户端连到你的 SSH 服务器上，AI 就可以：
+
+- ⚙️ **执行命令** —— 远程运维、日志排查、服务管理
+- 📤 **上传 / 📥 下载文件** —— 配置分发、日志拉取、大文件断点续传
+- 🖥️ **多机管理** —— 项目 → 环境 → 主机三级树，一次配置处处可用
+
+多种使用形态，按需选择：
+
+| 形态 | 适合场景 |
+|------|---------|
+| **npx 一键使用**（推荐） | 一行配置接入任意 MCP 客户端，自动带起常驻服务与 Web 管理台 |
+| **纯 stdio / 全局安装** | 不需要管理台的极简场景，SSH 参数直连 |
+
+## ✨ 核心特性
+
+### 连接能力
+
+- 🔐 多种认证：密码 / 私钥（含加密私钥）/ SSH Agent / 键盘交互式 **2FA**
+- 🔗 SOCKS5 与 HTTP(S) 代理，穿透跳板网络
+- 🚄 双传输模式：
+  - `exec` —— 每命令一通道，标准 Linux 主机
+  - `shell` —— 持久会话 + 标记协议，适配**堡垒机 / 跳板机**
+- ⏱️ 连接 / 命令 / SFTP 三级超时独立可控；大文件走 fastPut/fastGet 分片并发
+
+### 安全策略
+
+- 命令白名单 / 黑名单（正则），主机级与全局级双层过滤
+- 本地与远端路径白名单，约束文件传输范围
+- 全量审计日志：命令、输出、传输记录可追溯
+
+### Web 管理台
+
+- 项目-环境-主机三级可视化管理，连接拖拽排序
+- 测试连接、JSON 批量导入导出、`~/.ssh/config` 自动复用
+- 定时备份快照与一键恢复；MCP 客户端（Claude Code 等）一键注册
+- 开机自启动：Windows 登录后常驻服务自动就绪（设置页一键开关）
+- 在线更新：对照 npm registry 自动检测并升级新版本
+- 明暗双主题，跟随系统切换
+
+## 📸 界面一览
+
+**连接管理** —— 三级树管理全部主机：
+
+<div align="center"><img src="docs/screenshots/connections.png" alt="连接管理界面" width="820"></div>
+
+## 🚀 快速开始
+
+### 方式一：npx 一键使用（推荐）
+
+MCP 客户端 JSON 配置（Claude Code、Cursor 等通用）：
+
+```json
+{
+  "mcpServers": {
+    "ssh-server": {
+      "command": "npx",
+      "args": ["-y", "@lzm04521/ssh-mcp-server@latest"]
+    }
+  }
+}
+```
+
+也可命令行注册：
+
+```bash
+claude mcp add ssh-server -- npx -y @lzm04521/ssh-mcp-server@latest
+```
+
+首次调用会自动拉起常驻服务，之后：
+
+- 🖥️ **Web 管理台**：浏览器打开 `http://127.0.0.1:61823/admin/`，可视化维护项目 → 环境 → 主机，保存即时生效，无需重启 MCP 会话
+- 🔁 **常驻复用**：MCP 客户端经 stdio 自动转发到常驻服务；客户端退出后服务继续驻留，下次会话秒级复用
+- 🔌 **自定义端口**：在 args 中加 `--admin-port <port>`（默认 61823）
+
+### 方式二：高级用法（全局安装 / 纯 stdio）
+
+配置中出现 SSH 参数或 `--config-file` 时自动回到传统 stdio 模式（不拉经常驻服务）：
+
+```json
+{
+  "mcpServers": {
+    "ssh-server": {
+      "command": "npx",
+      "args": ["-y", "@lzm04521/ssh-mcp-server@latest", "--host", "your.server.com", "--username", "root", "--password", "YOUR_PWD"]
+    }
+  }
+}
+```
+
+也可全局安装后直接使用二进制，两种形态任选：
+
+```bash
+npm install -g @lzm04521/ssh-mcp-server
+```
+
+- **常驻服务形态（持久使用推荐）**：`claude mcp add ssh-server -- ssh-mcp-server`。无参数运行自动拉起/复用常驻服务，全局安装路径稳定（升级不换路径，优于 npx 缓存）。在管理台「设置 → 服务」开启**开机自启动**后，登录 Windows 常驻服务自动就绪，管理台与 MCP 通道随开随用
+- **纯 stdio 直连**：`claude mcp add ssh-server -- ssh-mcp-server --host your.server.com --username root --password YOUR_PWD`，不拉起常驻服务
+
+其他开关：手动启动常驻管理台 `--admin`；强制传统 stdio `--stdio`。配置文件与多连接模式详见 [`docs/migration.md`](docs/migration.md) 与 CLI 帮助（`--help`）。
+
+### 方式三：源码构建
+
+```bash
+git clone https://github.com/lzm04521/ssh-mcp-server.git
+cd ssh-mcp-server && npm install
+
+npm run build                 # 构建 Node 版
+npm test                      # 运行测试
+npm --prefix admin-web install && npm --prefix admin-web run build   # 构建管理台前端
+```
+
+## 🧰 MCP 工具一览
+
+| 工具 | 说明 |
+|------|------|
+| `execute-command` | 远程执行命令，支持目录切换、超时与输出限制，受白/黑名单约束 |
+| `upload` / `download` | SFTP 文件传输，大文件分片并发，路径白名单校验 |
+| `list-servers` | 列出所有可用连接 |
+
+## 🏗️ 架构
+
+```
+┌─ 常驻服务（npx 自动拉起 / 全局安装无参数运行 / --admin 手动启动）──┐
+│                                                                  │
+│  SSH 连接池 ── MCP StreamableHTTP (/mcp)                         │
+│      │                                                           │
+│  Admin API (/admin/api/*) ── 内嵌静态站点 (/admin/)              │
+│                                                                  │
+└── MCP 客户端经 stdio proxy 转发接入；浏览器直达管理页 ────────────┘
+```
+
+关键模块：`src/services/ssh-connection-manager.ts`（SSH 核心）、`src/server/`（Fastify Admin 服务）、`admin-web/`（React 管理台）。
+
+## 📋 更多文档
+
+- [使用迁移指南](docs/migration.md) —— 各客户端接入配置
+- [更新日志](CHANGELOG.md)
+
+## 📄 许可证
+
+[ISC](LICENSE) © lzm04521 (fork of [SIE-Operations-and-Maintenance-Team/ssh-mcp-server](https://github.com/SIE-Operations-and-Maintenance-Team/ssh-mcp-server))