@bingzi-233/ssh-mcp 1.2.0 → 1.4.0

package/README.md

@@ -1,109 +1,101 @@
 # ssh-mcp
 
-一个 MCP 服务器，让 Claude 通过 **SSH** 在多台远程服务器上执行命令、并通过 **SFTP** 传输大文件（支持 40GB+ 与断点续传）。每台服务器配一个 `name`，模型靠 `name` 区分目标机器。
+纯命令行 SSH/SFTP 工具：在多台远程服务器上执行命令、传输大文件（断点续传）、端口转发、文件管理。支持 CLI 模式和 MCP stdio 模式（`--mcp`）。
 
-## 工具
+[![NPM](https://img.shields.io/npm/v/@bingzi-233/ssh-mcp?color=CB3837&logo=npm)](https://www.npmjs.com/package/@bingzi-233/ssh-mcp)
+[![Node](https://img.shields.io/node/v/@bingzi-233/ssh-mcp?color=339933&logo=nodedotjs)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Stars](https://img.shields.io/github/stars/BingZi-233/ssh-mcp?color=EAC54F&logo=github)](https://github.com/BingZi-233/ssh-mcp/stargazers)
+[![License](https://img.shields.io/github/license/BingZi-233/ssh-mcp?color=4A90D9)](https://github.com/BingZi-233/ssh-mcp/blob/master/LICENSE)
+[![LINUX DO](https://img.shields.io/badge/LINUX_DO-社区认可-4A90D9?logo=discourse&logoColor=white)](https://linux.do)
 
-| 工具 | 作用 |
-|---|---|
-| `list_servers` | 列出所有已配置的服务器（name / 描述 / 地址 / 用户，**不含密码私钥**） |
-| `run_command` | 在指定 `name` 的服务器上执行一条命令，返回 stdout / stderr / 退出码 |
-| `open_session` | 建立到服务器的长连接会话，返回会话 id 供 `run_command` 复用 |
-| `close_session` | 关闭长连接会话 |
-| `list_sessions` | 列出当前所有活跃的长连接会话 |
-| `upload_file` | 上传本机文件到远程（后台任务，支持断点续传） |
-| `download_file` | 从远程下载文件到本机（后台任务，支持断点续传） |
-| `transfer_status` | 查询传输进度（已传字节、百分比、速度、ETA、状态） |
-| `cancel_transfer` | 取消一个进行中的传输（已传部分保留，可续传） |
-
-> - **长连接**：用 `open_session` 建立持久连接，`run_command` 传入 `session` 参数复用，省去重复握手和认证开销。即便复用了连接，每条命令仍在独立 channel 中执行，工作目录和环境变量不保留。
-> - **安全策略**：内置拦截 `rm -rf /`、`dd` 写块设备、`mkfs`、fork 炸弹等高危命令。可在 `servers.json` 的 `security.blocked_patterns` 中追加自定义正则。传入 `force=true` 可绕过。
-> - 命令在独立会话中执行，**命令之间不保留工作目录和环境变量**。需要保持上下文时自行串接，例如 `cd /var/www && git pull`。
-> - 大文件传输是**后台任务**：`upload_file`/`download_file` 立即返回一个传输 id，用 `transfer_status` 轮询进度，不阻塞。
-> - **断点续传**基于目标文件的实际大小：对同一对路径再次发起传输会自动从已传字节处继续，进程重启后依然有效。
-
----
-
-## 安装
-
-### 方式一：作为 Claude Code 插件（推荐）
-
-```shell
-/plugin marketplace add BingZi-233/ssh-mcp
-/plugin install ssh-mcp@bingzi-plugins
-```
-
-插件会通过 `npx` 拉起已发布的 npm 包，因此**需要先把包发布到 npm**（见下文「发布到 npm」）。
-
-### 方式二：作为 MCP 服务器手动注册
-
-```bash
-claude mcp add ssh -- npx -y @bingzi-233/ssh-mcp
-```
-
-需要自定义配置文件路径时：
+## CLI 快速上手
 
 ```bash
-claude mcp add ssh -e SSH_MCP_CONFIG=/path/to/servers.json -- npx -y @bingzi-233/ssh-mcp
+npm i -g @bingzi-233/ssh-mcp
+
+ssh-mcp list-servers                                     # 列出服务器
+ssh-mcp run-command -s prod-web -c "df -h /"             # 执行命令
+ssh-mcp batch --servers web1,web2,web3 -c "uptime"       # 批量执行
+ssh-mcp upload -s prod-web -l ./dist.tar.gz -r /tmp/     # 上传文件
+ssh-mcp ls -s prod-web -p /var/log                       # 列出目录
+ssh-mcp forward -s prod-web -L 8080:192.168.1.5:80       # 端口转发
 ```
 
-### 方式三：本地源码构建（开发用）
+## 命令一览
 
-```bash
-npm install
-npm run build
-claude mcp add ssh -- node /绝对路径/ssh-mcp/dist/index.js
-```
+| 子命令 | 用途 |
+|---|---|
+| `list-servers` | 列出所有已配置的服务器 |
+| `run-command` | 在远程服务器上执行命令 |
+| `batch` | 在多台服务器上批量执行同一命令 |
+| `open-session` / `close-session` / `list-sessions` | 长连接会话管理 |
+| `upload` / `download` | 大文件传输（后台任务，断点续传） |
+| `transfer-status` / `cancel-transfer` | 传输进度与取消 |
+| `forward` / `list-forwards` / `close-forward` | SSH 端口转发（本地/远程） |
+| `ls` / `stat` | 列出远程目录、查看文件信息 |
+| `rm` / `mkdir` | 删除远程文件/目录、创建远程目录 |
 
----
+每个子命令运行 `ssh-mcp <子命令> --help` 查看详细用法。
 
-## 配置服务器
+## 配置 servers.json
 
-默认从**运行目录下的 `./servers.json`** 读取（即 Claude 启动 MCP 服务器时所在的工作目录，通常是你当前的项目根目录）。也可用环境变量 `SSH_MCP_CONFIG` 指定任意路径。参考 `servers.example.json`：
+默认从运行目录下 `./servers.json` 读取，或设置环境变量 `SSH_MCP_CONFIG`。
 
 ```json
 {
-  "security": {
-    "blocked_patterns": []
-  },
+  "security": { "blocked_patterns": [] },
   "servers": [
     {
       "name": "prod-web",
-      "description": "生产环境 Web 服务器",
+      "description": "生产环境",
       "host": "192.168.1.10",
       "port": 22,
       "username": "deploy",
       "privateKeyPath": "~/.ssh/id_rsa"
-    },
-    {
-      "name": "db",
-      "description": "数据库服务器",
-      "host": "db.example.com",
-      "username": "admin",
-      "password": "your-password"
     }
   ]
 }
 ```
 
-**鉴权优先级**（每台服务器独立选择）：
+鉴权优先级：私钥 → 密码 → ssh-agent。修改配置无需重启。
 
-1. `privateKeyPath`（+ 可选 `passphrase`）—— 私钥文件，支持 `~` 展开
-2. `password` —— 密码登录
-3. 都没配 → 回退到本机 `ssh-agent`（读 `SSH_AUTH_SOCK`）
+## 端口转发
 
-新增/修改服务器后**无需重启**——配置文件每次调用都会重新读取。
+```bash
+# 本地转发：本机 8080 → 经 SSH 服务器 → 内网 192.168.1.5:80
+ssh-mcp forward -s prod-web -L 8080:192.168.1.5:80
 
----
+# 远程转发：SSH 服务器 9000 → 回传到本机 localhost:3000
+ssh-mcp forward -s prod-web -R 9000:127.0.0.1:3000
+
+ssh-mcp list-forwards
+ssh-mcp close-forward -i f1
+```
+
+## 批量执行
+
+```bash
+ssh-mcp batch --servers prod-web,prod-api,prod-worker -c "systemctl status nginx"
+```
 
-## ⚠️ 安全提示
+## 安全策略
+
+内置拦截高危命令：`rm -rf /`、`dd` 写块设备、`mkfs`、fork 炸弹。在 `servers.json` 的 `security.blocked_patterns` 中追加自定义正则。传 `--force` 跳过检查。
+
+## MCP 模式
+
+以 MCP stdio 服务运行（供 Claude Code 等 AI 客户端调用）：
+
+```bash
+claude mcp add ssh -- npx -y @bingzi-233/ssh-mcp --mcp
+/plugin marketplace add BingZi-233/ssh-mcp
+/plugin install ssh-mcp@bingzi-plugins
+```
 
-这个工具允许模型在你的服务器上执行**任意命令**、读写文件。请仅指向你拥有/授权的机器：
+## 社区
 
-- `servers.json` 含明文凭据，已在 `.gitignore` 中排除，**切勿提交到仓库**。
-- 优先用私钥或 `ssh-agent`，尽量不在配置里写明文密码。
-- 给 SSH 账号最小权限；高危机器考虑用受限账号。
-- 内置命令安全策略会拦截 `rm -rf /`、`dd` 写块设备、`mkfs`、fork 炸弹等高危模式。可在 `security.blocked_patterns` 中追加自定义正则（JSON 字符串，需双重转义，如 `"rm\\\\s.*-rf?\\\\s+/\\\\*"`）。传 `force=true` 可绕过。
+本项目由 [LINUX DO](https://linux.do) 社区孵化并认可。
 
 ## License
 

package/dist/forward.js

@@ -0,0 +1,108 @@
+import { createServer, Socket } from "node:net";
+import { createConnection } from "./ssh.js";
+const forwards = new Map();
+/** 存活的本地 net.Server / SSH 连接，用于关闭 */
+const resources = new Map();
+let counter = 0;
+function track(id, conn, server) {
+    resources.set(id, { conn, server });
+    conn.on("close", () => {
+        const f = forwards.get(id);
+        if (f)
+            f.state = "stopped";
+        server?.close();
+    });
+    conn.on("error", () => {
+        const f = forwards.get(id);
+        if (f)
+            f.state = "stopped";
+        server?.close();
+    });
+}
+/**
+ * 启动端口转发。
+ *
+ * type=local: 监听本机 localPort，流量经 SSH 服务器转发到 remoteHost:remotePort。
+ * type=remote: SSH 服务器监听 remotePort，流量经本机转发到 localHost:localPort。
+ */
+export async function startForward(cfg, type, localHost, localPort, remoteHost, remotePort) {
+    const conn = await createConnection(cfg, 20_000);
+    const id = `f${++counter}`;
+    if (type === "local") {
+        await new Promise((resolve, reject) => {
+            const server = createServer((socket) => {
+                conn.forwardOut(localHost, localPort, remoteHost, remotePort, (err, stream) => {
+                    if (err) {
+                        socket.destroy();
+                        return;
+                    }
+                    socket.pipe(stream).pipe(socket);
+                    stream.on("error", () => socket.destroy());
+                    socket.on("error", () => stream.destroy());
+                });
+            });
+            server.on("error", reject);
+            server.listen(localPort, localHost, () => {
+                server.removeListener("error", reject);
+                track(id, conn, server);
+                resolve();
+            });
+        });
+    }
+    else {
+        // remote: SSH 服务器暴露端口，转发回本机
+        await new Promise((resolve, reject) => {
+            conn.forwardIn(remoteHost, remotePort, (err) => {
+                if (err)
+                    reject(err);
+                else {
+                    track(id, conn);
+                    resolve();
+                }
+            });
+        });
+        // 处理来自远程的入站连接
+        conn.on("tcp connection", (info, accept) => {
+            const stream = accept();
+            const sock = new Socket();
+            sock.connect(remotePort, localHost, () => {
+                sock.pipe(stream).pipe(sock);
+                stream.on("error", () => sock.destroy());
+                sock.on("error", () => stream.destroy());
+            });
+            sock.on("error", () => stream.end());
+        });
+    }
+    const fwd = {
+        id,
+        server: cfg.name,
+        type,
+        localHost,
+        localPort,
+        remoteHost,
+        remotePort,
+        state: "running",
+        createdAt: Date.now(),
+    };
+    forwards.set(id, fwd);
+    return fwd;
+}
+export function getForward(id) {
+    return forwards.get(id);
+}
+export function listForwards() {
+    return [...forwards.values()];
+}
+export function closeForward(id) {
+    const fwd = forwards.get(id);
+    if (!fwd || fwd.state === "stopped")
+        return false;
+    fwd.state = "stopped";
+    const res = resources.get(id);
+    if (res) {
+        res.server?.close();
+        res.conn.end();
+        resources.delete(id);
+    }
+    return true;
+}