@bingzi-233/ssh-mcp 1.3.0 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # ssh-mcp
 
-纯命令行 SSH/SFTP 工具：在多台远程服务器上执行命令、传输大文件（断点续传）。支持 CLI 模式和 MCP stdio 模式（`--mcp`）。
+纯命令行 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)
@@ -12,26 +12,14 @@
 ## CLI 快速上手
 
 ```bash
-# 安装
 npm i -g @bingzi-233/ssh-mcp
 
-# 查看帮助
-ssh-mcp --help
-
-# 列出服务器
-ssh-mcp list-servers
-
-# 执行远程命令
-ssh-mcp run-command -s prod-web -c "df -h /"
-
-# 上传文件（支持断点续传）
-ssh-mcp upload -s prod-web -l ./dist.tar.gz -r /tmp/dist.tar.gz
-
-# 下载文件
-ssh-mcp download -s prod-web -r /var/log/app.log -l ./logs/app.log
-
-# 传输进度
-ssh-mcp transfer-status
+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       # 端口转发
 ```
 
 ## 命令一览
@@ -40,13 +28,13 @@ ssh-mcp transfer-status
 |---|---|
 | `list-servers` | 列出所有已配置的服务器 |
 | `run-command` | 在远程服务器上执行命令 |
-| `open-session` | 打开长连接会话（复用 TCP 连接） |
-| `close-session` | 关闭长连接会话 |
-| `list-sessions` | 列出当前所有长连接会话 |
-| `upload` | 上传文件到远程（后台任务，断点续传） |
-| `download` | 从远程下载文件（后台任务，断点续传） |
-| `transfer-status` | 查看传输进度 |
-| `cancel-transfer` | 取消传输 |
+| `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` 查看详细用法。
 
@@ -56,24 +44,15 @@ ssh-mcp transfer-status
 
 ```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"
     }
   ]
 }
@@ -81,16 +60,24 @@ ssh-mcp transfer-status
 
 鉴权优先级：私钥 → 密码 → ssh-agent。修改配置无需重启。
 
-## 长连接会话
+## 端口转发
 
 ```bash
-SID=$(ssh-mcp open-session -s prod-web)
-ssh-mcp run-command -s prod-web --session $SID -c "hostname"
-ssh-mcp run-command -s prod-web --session $SID -c "uptime"
-ssh-mcp close-session -s $SID
+# 本地转发：本机 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
 ```
 
-复用 TCP 连接，省去重复握手和认证。注意每条命令仍在独立 channel 中执行，不保留工作目录。
+## 批量执行
+
+```bash
+ssh-mcp batch --servers prod-web,prod-api,prod-worker -c "systemctl status nginx"
+```
 
 ## 安全策略
 
@@ -101,10 +88,7 @@ ssh-mcp close-session -s $SID
 以 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
 ```

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;
+}

package/dist/index.js

@@ -5,6 +5,8 @@ import { z } from "zod";
 import { configPath, loadSecurity, loadServers, validateCommand } from "./config.js";
 import { closeSession, listSessions, openSession, runCommand, } from "./ssh.js";
 import { cancelTransfer, getTransfer, listTransfers, startTransfer, } from "./transfer.js";
+import { startForward, listForwards, closeForward, } from "./forward.js";
+import { listDirectory, statPath, removePath, makeDir, formatLsLong, formatLsShort, } from "./sftp-ops.js";
 const DEFAULT_TIMEOUT_MS = 60_000;
 function humanBytes(n) {
     if (n < 1024)
@@ -56,7 +58,7 @@ function formatTransfer(t) {
 // MCP server setup (--mcp mode)
 // ---------------------------------------------------------------------------
 function createMcpServer() {
-    const server = new McpServer({ name: "ssh-mcp", version: "1.3.0" });
+    const server = new McpServer({ name: "ssh-mcp", version: "1.4.0" });
     server.registerTool("list_servers", {
         title: "列出可用的 SSH 服务器",
         description: "列出所有已配置的远程服务器及其 name、描述、地址和登录用户。" +
@@ -284,6 +286,200 @@ function createMcpServer() {
             return { content: [{ type: "text", text: `未找到传输任务：${id}` }], isError: true };
         return { content: [{ type: "text", text: `已请求取消：\n${formatTransfer(t)}` }] };
     });
+    // ---- 端口转发 ----
+    server.registerTool("start_forward", {
+        title: "启动 SSH 端口转发",
+        description: "启动一个 SSH 端口转发隧道。本地转发（-L）：将本机端口流量经由 SSH 服务器转发到内网目标。" +
+            "远程转发（-R）：将 SSH 服务器端口流量回传到本机指定地址。" +
+            "返回转发 id，用 list_forwards 查看状态，close_forward 停止。",
+        inputSchema: {
+            server: z.string().describe("目标 SSH 服务器的 name"),
+            type: z.enum(["local", "remote"]).describe("转发类型：local 本地转发，remote 远程转发"),
+            local_host: z.string().default("127.0.0.1").describe("本机绑定地址，默认 127.0.0.1"),
+            local_port: z.number().int().positive().describe("本机端口号"),
+            remote_host: z.string().describe("远端目标地址（local 模式为内网主机，remote 模式为回传目标）"),
+            remote_port: z.number().int().positive().describe("远端端口号"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, async ({ server: serverName, type, local_host, local_port, remote_host, remote_port }) => {
+        try {
+            const servers = loadServers();
+            const cfg = servers.get(serverName);
+            if (!cfg)
+                return { content: [{ type: "text", text: `未找到服务器 "${serverName}"` }], isError: true };
+            const f = await startForward(cfg, type, local_host, local_port, remote_host, remote_port);
+            const dir = type === "local"
+                ? `${f.localHost}:${f.localPort} → ${f.remoteHost}:${f.remotePort}`
+                : `${f.remoteHost}:${f.remotePort} → ${f.localHost}:${f.localPort}`;
+            return { content: [{ type: "text", text: `转发已启动 [${f.id}] ${dir}\n类型: ${type}\n状态: ${f.state}` }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `启动转发失败：${e.message}` }], isError: true };
+        }
+    });
+    server.registerTool("list_forwards", {
+        title: "列出所有端口转发",
+        description: "列出当前活跃的端口转发隧道。",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => {
+        const all = listForwards();
+        if (all.length === 0)
+            return { content: [{ type: "text", text: "当前没有端口转发。" }] };
+        const lines = all.map((f) => f.type === "local"
+            ? `[${f.id}] ${f.server}  ${f.localHost}:${f.localPort} → ${f.remoteHost}:${f.remotePort}  (${f.state})`
+            : `[${f.id}] ${f.server}  ${f.remoteHost}:${f.remotePort} → ${f.localHost}:${f.localPort}  (${f.state})`);
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    });
+    server.registerTool("close_forward", {
+        title: "停止端口转发",
+        description: "停止一个端口转发隧道。",
+        inputSchema: { id: z.string().describe("转发 id") },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    }, async ({ id }) => {
+        const ok = closeForward(id);
+        if (!ok)
+            return { content: [{ type: "text", text: `转发 ${id} 不存在或已停止。` }], isError: true };
+        return { content: [{ type: "text", text: `转发 ${id} 已停止。` }] };
+    });
+    // ---- 批量执行 ----
+    server.registerTool("batch_run", {
+        title: "在多台服务器上批量执行命令",
+        description: "同时在多台服务器上执行同一条命令，并发执行、汇总结果。" +
+            "传入 servers 数组指定目标服务器 name 列表。",
+        inputSchema: {
+            servers: z.array(z.string()).describe("目标服务器 name 列表"),
+            command: z.string().describe("要执行的命令"),
+            timeout_ms: z.number().int().positive().optional().describe(`命令超时（毫秒），默认 ${DEFAULT_TIMEOUT_MS}`),
+            force: z.boolean().optional().describe("跳过安全策略检查"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, async ({ servers: serverNames, command, timeout_ms, force }) => {
+        let servers;
+        try {
+            servers = loadServers();
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `读取服务器配置失败：${e.message}` }], isError: true };
+        }
+        const missing = serverNames.filter((n) => !servers.has(n));
+        if (missing.length)
+            return { content: [{ type: "text", text: `未找到服务器：${missing.join(", ")}` }], isError: true };
+        if (!force) {
+            const security = loadSecurity();
+            const blocked = validateCommand(command, security.blocked_patterns ?? []);
+            if (blocked)
+                return { content: [{ type: "text", text: `${blocked}\n使用 force=true 可跳过安全检查。` }], isError: true };
+        }
+        const timeout = timeout_ms ?? DEFAULT_TIMEOUT_MS;
+        const results = await Promise.allSettled(serverNames.map((name) => runCommand(servers.get(name), command, timeout).then((r) => ({ server: name, result: r }))));
+        const lines = [];
+        for (const r of results) {
+            if (r.status === "rejected") {
+                lines.push(`--- ${r.reason?.server ?? "?"} FAILED ---\n${r.reason.message}`);
+            }
+            else {
+                const { server: sName, result } = r.value;
+                lines.push(`--- ${sName} (exit ${result.code}) ---`);
+                if (result.stdout)
+                    lines.push(result.stdout.trimEnd());
+                if (result.stderr)
+                    lines.push(`[stderr]\n${result.stderr.trimEnd()}`);
+            }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") || "（无输出）" }] };
+    });
+    // ---- SFTP 文件操作 ----
+    server.registerTool("list_directory", {
+        title: "列出远程目录内容",
+        description: "通过 SFTP 列出远程服务器上指定目录的文件和子目录。" +
+            "返回文件名、类型、大小、权限、修改时间等信息。",
+        inputSchema: {
+            server: z.string().describe("目标服务器 name"),
+            path: z.string().describe("远程目录路径"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ server: serverName, path }) => {
+        try {
+            const servers = loadServers();
+            const cfg = servers.get(serverName);
+            if (!cfg)
+                return { content: [{ type: "text", text: `未找到服务器 "${serverName}"` }], isError: true };
+            const entries = await listDirectory(cfg, path);
+            const lines = entries.map(formatLsLong);
+            return { content: [{ type: "text", text: `${path}:\n${lines.join("\n")}` }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `列出目录失败：${e.message}` }], isError: true };
+        }
+    });
+    server.registerTool("stat_file", {
+        title: "查看远程文件信息",
+        description: "通过 SFTP stat 查看远程文件的类型、大小、权限、修改时间。",
+        inputSchema: {
+            server: z.string().describe("目标服务器 name"),
+            path: z.string().describe("远程文件路径"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ server: serverName, path }) => {
+        try {
+            const servers = loadServers();
+            const cfg = servers.get(serverName);
+            if (!cfg)
+                return { content: [{ type: "text", text: `未找到服务器 "${serverName}"` }], isError: true };
+            const s = await statPath(cfg, path);
+            return { content: [{ type: "text", text: JSON.stringify(s, null, 2) }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `stat 失败：${e.message}` }], isError: true };
+        }
+    });
+    server.registerTool("remove_file", {
+        title: "删除远程文件或目录",
+        description: "通过 SFTP 删除远程服务器上的文件或目录。" +
+            "删除目录时需传入 recursive=true，将递归删除目录下所有内容。",
+        inputSchema: {
+            server: z.string().describe("目标服务器 name"),
+            path: z.string().describe("远程文件或目录路径"),
+            recursive: z.boolean().optional().describe("递归删除目录；默认 false"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, async ({ server: serverName, path, recursive }) => {
+        try {
+            const servers = loadServers();
+            const cfg = servers.get(serverName);
+            if (!cfg)
+                return { content: [{ type: "text", text: `未找到服务器 "${serverName}"` }], isError: true };
+            await removePath(cfg, path, recursive ?? false);
+            return { content: [{ type: "text", text: `已删除：${path}` }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `删除失败：${e.message}` }], isError: true };
+        }
+    });
+    server.registerTool("make_directory", {
+        title: "创建远程目录",
+        description: "通过 SFTP 在远程服务器上创建目录。" +
+            "传入 parents=true 可自动创建父目录（类似 mkdir -p）。",
+        inputSchema: {
+            server: z.string().describe("目标服务器 name"),
+            path: z.string().describe("远程目录路径"),
+            parents: z.boolean().optional().describe("自动创建父目录；默认 false"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, async ({ server: serverName, path, parents }) => {
+        try {
+            const servers = loadServers();
+            const cfg = servers.get(serverName);
+            if (!cfg)
+                return { content: [{ type: "text", text: `未找到服务器 "${serverName}"` }], isError: true };
+            await makeDir(cfg, path, parents ?? false);
+            return { content: [{ type: "text", text: `已创建目录：${path}` }] };
+        }
+        catch (e) {
+            return { content: [{ type: "text", text: `创建目录失败：${e.message}` }], isError: true };
+        }
+    });
     return server;
 }
 function parseArgs(raw) {
@@ -352,13 +548,14 @@ function die(msg) {
     process.exit(1);
 }
 function showHelp() {
-    process.stdout.write(`ssh-mcp — SSH/SFTP 远程服务器命令行工具  v1.2.0
+    process.stdout.write(`ssh-mcp — SSH/SFTP 远程服务器命令行工具  v1.4.0
 
 用法:  ssh-mcp <子命令> [选项]
 
 子命令:
   list-servers              列出所有已配置的服务器
   run-command               在远程服务器上执行命令
+  batch                     在多台服务器上批量执行同一命令
   open-session              打开到远程服务器的长连接会话
   close-session             关闭长连接会话
   list-sessions             列出当前所有长连接会话
@@ -366,6 +563,13 @@ function showHelp() {
   download                  从远程服务器下载文件（支持断点续传）
   transfer-status           查看文件传输进度
   cancel-transfer           取消文件传输
+  forward                   启动 SSH 端口转发（本地/远程）
+  list-forwards             列出当前所有端口转发
+  close-forward             停止端口转发
+  ls                        列出远程目录内容
+  stat                      查看远程文件信息
+  rm                        删除远程文件或目录
+  mkdir                     创建远程目录
 
 全局选项:
   --mcp                     以 MCP stdio 服务模式运行（供 AI 客户端调用）
@@ -696,6 +900,310 @@ async function cmdCancelTransfer(opts) {
         die(`未找到传输任务：${id}`);
     process.stdout.write(`已请求取消：\n${formatTransfer(t)}\n`);
 }
+// ---- 端口转发 CLI ----
+async function cmdForward(opts) {
+    if (optBool(opts, "help")) {
+        process.stdout.write(`用法: ssh-mcp forward --server <name> -L <本地端口>:<远端主机>:<远端端口>
+       ssh-mcp forward --server <name> -R <远端端口>:<本地主机>:<本地端口>
+
+选项:
+  --server, -s <name>   目标 SSH 服务器 name（必需）
+  -L <lport>:<rhost>:<rport>   本地端口转发
+  -R <rport>:<lhost>:<lport>   远程端口转发
+
+示例:
+  # 本地转发：本机 8080 → 经 prod-web → 内网 192.168.1.5:80
+  ssh-mcp forward -s prod-web -L 8080:192.168.1.5:80
+
+  # 远程转发：prod-web 的 9000 → 回传到本机 localhost:3000
+  ssh-mcp forward -s prod-web -R 9000:127.0.0.1:3000
+`);
+        return;
+    }
+    const serverName = optStr(opts, "server") ?? optStr(opts, "s");
+    if (!serverName)
+        die("缺少 --server");
+    const lFwd = optStr(opts, "L");
+    const rFwd = optStr(opts, "R");
+    if (!lFwd && !rFwd)
+        die("缺少 -L 或 -R。用法: ssh-mcp forward -s <name> -L lport:rhost:rport");
+    if (lFwd && rFwd)
+        die("不能同时指定 -L 和 -R");
+    const raw = (lFwd ?? rFwd);
+    const parts = raw.split(":");
+    if (parts.length !== 3)
+        die("转发格式错误：应为 -L lport:rhost:rport 或 -R rport:lhost:lport");
+    let type;
+    let localHost, localPort, remoteHost, remotePort;
+    if (lFwd) {
+        type = "local";
+        localPort = parseInt(parts[0], 10);
+        remoteHost = parts[1];
+        remotePort = parseInt(parts[2], 10);
+        localHost = "127.0.0.1";
+    }
+    else {
+        type = "remote";
+        remotePort = parseInt(parts[0], 10);
+        localHost = parts[1];
+        localPort = parseInt(parts[2], 10);
+        remoteHost = "0.0.0.0";
+    }
+    if (isNaN(localPort) || isNaN(remotePort))
+        die("端口号必须是数字");
+    try {
+        const servers = loadServers();
+        const cfg = servers.get(serverName);
+        if (!cfg)
+            die(`未找到服务器 "${serverName}"。可用：${[...servers.keys()].join(", ") || "（无）"}`);
+        const f = await startForward(cfg, type, localHost, localPort, remoteHost, remotePort);
+        const dir = type === "local"
+            ? `${f.localHost}:${f.localPort} → ${f.remoteHost}:${f.remotePort}`
+            : `${f.remoteHost}:${f.remotePort} → ${f.localHost}:${f.localPort}`;
+        process.stdout.write(`转发已启动 [${f.id}] ${dir}\n`);
+    }
+    catch (e) {
+        die(`启动转发失败：${e.message}`);
+    }
+}
+async function cmdListForwards(opts) {
+    if (optBool(opts, "help")) {
+        process.stdout.write(`用法: ssh-mcp list-forwards
+
+列出当前所有活跃的端口转发隧道。
+
+示例:
+  ssh-mcp list-forwards
+`);
+        return;
+    }
+    const all = listForwards();
+    if (all.length === 0) {
+        process.stdout.write("当前没有端口转发。\n");
+        return;
+    }
+    for (const f of all) {
+        const dir = f.type === "local"
+            ? `${f.localHost}:${f.localPort} → ${f.remoteHost}:${f.remotePort}`
+            : `${f.remoteHost}:${f.remotePort} → ${f.localHost}:${f.localPort}`;
+        process.stdout.write(`[${f.id}] ${f.server.padEnd(16)} ${dir.padEnd(32)} ${f.state}\n`);
+    }
+}
+async function cmdCloseForward(opts) {
+    if (optBool(opts, "help")) {
+        process.stdout.write(`用法: ssh-mcp close-forward --id <id>
+
+选项:
+  --id, -i <id>   要停止的转发 id（必需）
+
+示例:
+  ssh-mcp close-forward -i f1
+`);
+        return;
+    }
+    const id = optStr(opts, "id") ?? optStr(opts, "i");
+    if (!id)
+        die("缺少 --id");
+    if (!closeForward(id))
+        die(`转发 ${id} 不存在或已停止。`);
+    process.stdout.write(`转发 ${id} 已停止。\n`);
+}
+// ---- 批量执行 CLI ----
+async function cmdBatch(opts, positional) {
+    if (optBool(opts, "help")) {
+        process.stdout.write(`用法: ssh-mcp batch --servers <s1,s2,...> [选项] <命令...>
+
+选项:
+  --servers <names>     目标服务器 name 列表，逗号分隔（必需）
+  --timeout <ms>        命令超时毫秒数（默认 ${DEFAULT_TIMEOUT_MS}）
+  --force               跳过安全策略检查
+  --command, -c <cmd>   要执行的命令（也可直接放在选项之后）
+
+示例:
+  ssh-mcp batch --servers prod-web,prod-api -c "df -h /"
+  ssh-mcp batch --servers web1,web2,web3 "systemctl status nginx"
+`);
+        return;
+    }
+    const serversArg = optStr(opts, "servers");
+    if (!serversArg)
+        die("缺少 --servers。用法: ssh-mcp batch --servers s1,s2,... <命令>");
+    let command = optStr(opts, "command") ?? optStr(opts, "c");
+    if (!command)
+        command = positional.join(" ");
+    if (!command || command.trim() === "")
+        die("缺少命令");
+    const serverNames = serversArg.split(",").map((s) => s.trim()).filter(Boolean);
+    if (serverNames.length === 0)
+        die("--servers 格式错误");
+    const timeout = optNum(opts, "timeout") ?? DEFAULT_TIMEOUT_MS;
+    const force = optBool(opts, "force");
+    let servers;
+    try {
+        servers = loadServers();
+    }
+    catch (e) {
+        die(`读取配置失败：${e.message}`);
+    }
+    const missing = serverNames.filter((n) => !servers.has(n));
+    if (missing.length)
+        die(`未找到服务器：${missing.join(", ")}`);
+    if (!force) {
+        const security = loadSecurity();
+        const blocked = validateCommand(command, security.blocked_patterns ?? []);
+        if (blocked)
+            die(blocked + "\n使用 --force 可跳过安全检查。");
+    }
+    const results = await Promise.allSettled(serverNames.map((name) => runCommand(servers.get(name), command, timeout).then((r) => ({ server: name, result: r }))));
+    for (const r of results) {
+        if (r.status === "rejected") {
+            process.stderr.write(`=== ${r.reason?.server ?? "?"} FAILED ===\n${r.reason.message}\n`);
+        }
+        else {
+            const { server: sName, result } = r.value;
+            process.stdout.write(`=== ${sName} (exit ${result.code}) ===\n`);
+            if (result.stdout)
+                process.stdout.write(result.stdout.trimEnd() + "\n");
+            if (result.stderr)
+                process.stderr.write(`[stderr]\n${result.stderr.trimEnd()}\n`);
+        }
+    }
+}
+// ---- SFTP 文件操作 CLI ----
+async function cmdLs(opts) {
+    if (optBool(opts, "help")) {
+        process.stdout.write(`用法: ssh-mcp ls --server <name> --path <path> [--long]
+
+选项:
+  --server, -s <name>   目标服务器 name（必需）
+  --path, -p <path>     远程目录路径（必需）
+  --long, -l            详细列表模式（权限/大小/时间）
+
+示例:
+  ssh-mcp ls -s prod-web -p /var/log
+  ssh-mcp ls -s prod-web -p /tmp --long
+`);
+        return;
+    }
+    const serverName = optStr(opts, "server") ?? optStr(opts, "s");
+    const path = optStr(opts, "path") ?? optStr(opts, "p");
+    if (!serverName)
+        die("缺少 --server");
+    if (!path)
+        die("缺少 --path");
+    try {
+        const servers = loadServers();
+        const cfg = servers.get(serverName);
+        if (!cfg)
+            die(`未找到服务器 "${serverName}"`);
+        const entries = await listDirectory(cfg, path);
+        process.stdout.write(`${path}:\n`);
+        const long = optBool(opts, "long") || optBool(opts, "l");
+        for (const e of entries) {
+            process.stdout.write((long ? formatLsLong(e) : formatLsShort(e)) + "\n");
+        }
+        process.stdout.write(`\n${entries.length} 条\n`);
+    }
+    catch (e) {
+        die(`列出目录失败：${e.message}`);
+    }
+}
+async function cmdStat(opts) {
+    if (optBool(opts, "help")) {
+        process.stdout.write(`用法: ssh-mcp stat --server <name> --path <path>
+
+选项:
+  --server, -s <name>   目标服务器 name（必需）
+  --path, -p <path>     远程文件路径（必需）
+
+示例:
+  ssh-mcp stat -s prod-web -p /etc/nginx/nginx.conf
+`);
+        return;
+    }
+    const serverName = optStr(opts, "server") ?? optStr(opts, "s");
+    const path = optStr(opts, "path") ?? optStr(opts, "p");
+    if (!serverName)
+        die("缺少 --server");
+    if (!path)
+        die("缺少 --path");
+    try {
+        const servers = loadServers();
+        const cfg = servers.get(serverName);
+        if (!cfg)
+            die(`未找到服务器 "${serverName}"`);
+        const s = await statPath(cfg, path);
+        process.stdout.write(`类型: ${s.type}\n大小: ${s.size}\n权限: ${s.mode.toString(8)}\nuid: ${s.uid}\ngid: ${s.gid}\n修改: ${new Date(s.mtime * 1000).toISOString()}\n`);
+    }
+    catch (e) {
+        die(`stat 失败：${e.message}`);
+    }
+}
+async function cmdRm(opts) {
+    if (optBool(opts, "help")) {
+        process.stdout.write(`用法: ssh-mcp rm --server <name> --path <path> [--recursive]
+
+选项:
+  --server, -s <name>   目标服务器 name（必需）
+  --path, -p <path>     要删除的远程文件或目录（必需）
+  --recursive, -r       递归删除目录
+
+示例:
+  ssh-mcp rm -s prod-web -p /tmp/old.log
+  ssh-mcp rm -s prod-web -p /tmp/backup --recursive
+`);
+        return;
+    }
+    const serverName = optStr(opts, "server") ?? optStr(opts, "s");
+    const path = optStr(opts, "path") ?? optStr(opts, "p");
+    if (!serverName)
+        die("缺少 --server");
+    if (!path)
+        die("缺少 --path");
+    try {
+        const servers = loadServers();
+        const cfg = servers.get(serverName);
+        if (!cfg)
+            die(`未找到服务器 "${serverName}"`);
+        await removePath(cfg, path, optBool(opts, "recursive") || optBool(opts, "r"));
+        process.stdout.write(`已删除：${path}\n`);
+    }
+    catch (e) {
+        die(`删除失败：${e.message}`);
+    }
+}
+async function cmdMkdir(opts) {
+    if (optBool(opts, "help")) {
+        process.stdout.write(`用法: ssh-mcp mkdir --server <name> --path <path> [--parents]
+
+选项:
+  --server, -s <name>   目标服务器 name（必需）
+  --path, -p <path>     要创建的远程目录路径（必需）
+  --parents             自动创建父目录（类似 mkdir -p）
+
+示例:
+  ssh-mcp mkdir -s prod-web -p /opt/app/logs --parents
+`);
+        return;
+    }
+    const serverName = optStr(opts, "server") ?? optStr(opts, "s");
+    const path = optStr(opts, "path") ?? optStr(opts, "p");
+    if (!serverName)
+        die("缺少 --server");
+    if (!path)
+        die("缺少 --path");
+    try {
+        const servers = loadServers();
+        const cfg = servers.get(serverName);
+        if (!cfg)
+            die(`未找到服务器 "${serverName}"`);
+        await makeDir(cfg, path, optBool(opts, "parents"));
+        process.stdout.write(`已创建目录：${path}\n`);
+    }
+    catch (e) {
+        die(`创建目录失败：${e.message}`);
+    }
+}
 function loadServersOrDie() {
     try {
         return { servers: loadServers(), error: null };
@@ -727,6 +1235,7 @@ async function main() {
         }
         case "list-servers": return cmdListServers(options);
         case "run-command": return cmdRunCommand(options, positional);
+        case "batch": return cmdBatch(options, positional);
         case "open-session": return cmdOpenSession(options);
         case "close-session": return cmdCloseSession(options);
         case "list-sessions": return cmdListSessions(options);
@@ -734,6 +1243,13 @@ async function main() {
         case "download": return cmdDownload(options);
         case "transfer-status": return cmdTransferStatus(options);
         case "cancel-transfer": return cmdCancelTransfer(options);
+        case "forward": return cmdForward(options);
+        case "list-forwards": return cmdListForwards(options);
+        case "close-forward": return cmdCloseForward(options);
+        case "ls": return cmdLs(options);
+        case "stat": return cmdStat(options);
+        case "rm": return cmdRm(options);
+        case "mkdir": return cmdMkdir(options);
         default:
             die(`未知子命令: ${subcommand}\n运行 ssh-mcp --help 查看可用命令。`);
     }

package/dist/sftp-ops.js

@@ -0,0 +1,160 @@
+import { posix } from "node:path";
+import { createConnection } from "./ssh.js";
+function openSftp(conn) {
+    return new Promise((resolve, reject) => {
+        conn.sftp((err, sftp) => (err ? reject(err) : resolve(sftp)));
+    });
+}
+function classify(mode) {
+    const ifmt = mode & 0o170000;
+    if (ifmt === 0o040000)
+        return "directory";
+    if (ifmt === 0o100000)
+        return "file";
+    if (ifmt === 0o120000)
+        return "link";
+    return "other";
+}
+function formatMode(mode) {
+    const r = (mode & 0o4) ? "r" : "-";
+    const w = (mode & 0o2) ? "w" : "-";
+    const x = (mode & 0o1) ? "x" : "-";
+    return r + w + x;
+}
+function formatPerms(mode) {
+    const f = classify(mode);
+    const c = f === "directory" ? "d" : f === "link" ? "l" : f === "other" ? "?" : "-";
+    return c + formatMode(mode >> 6) + formatMode(mode >> 3) + formatMode(mode);
+}
+export function formatLsLong(e) {
+    return `${formatPerms(e.mode)}  ${String(e.uid).padStart(5)} ${String(e.gid).padStart(5)}  ${String(e.size).padStart(10)}  ${new Date(e.mtime * 1000).toISOString().replace("T", " ").replace(/\..*/, "")}  ${e.name}`;
+}
+export function formatLsShort(e) {
+    return e.name;
+}
+export async function listDirectory(cfg, path) {
+    const conn = await createConnection(cfg, 20_000);
+    try {
+        const sftp = await openSftp(conn);
+        return new Promise((resolve, reject) => {
+            sftp.readdir(path, (err, entries) => {
+                conn.end();
+                if (err)
+                    return reject(err);
+                resolve(entries.map((e) => ({
+                    name: e.filename,
+                    type: classify(e.attrs.mode),
+                    size: e.attrs.size,
+                    mode: e.attrs.mode,
+                    uid: e.attrs.uid,
+                    gid: e.attrs.gid,
+                    mtime: e.attrs.mtime,
+                    atime: e.attrs.atime,
+                    longname: e.longname,
+                })));
+            });
+        });
+    }
+    catch (e) {
+        conn.end();
+        throw e;
+    }
+}
+export async function statPath(cfg, path) {
+    const conn = await createConnection(cfg, 20_000);
+    try {
+        const sftp = await openSftp(conn);
+        return new Promise((resolve, reject) => {
+            sftp.stat(path, (err, s) => {
+                conn.end();
+                if (err)
+                    return reject(err);
+                resolve({
+                    type: classify(s.mode),
+                    size: s.size,
+                    mode: s.mode,
+                    uid: s.uid,
+                    gid: s.gid,
+                    mtime: s.mtime,
+                    atime: s.atime,
+                });
+            });
+        });
+    }
+    catch (e) {
+        conn.end();
+        throw e;
+    }
+}
+export async function removePath(cfg, path, recursive) {
+    const conn = await createConnection(cfg, 20_000);
+    try {
+        const sftp = await openSftp(conn);
+        // 先 stat 确定类型
+        const s = await new Promise((resolve, reject) => {
+            sftp.stat(path, (err, st) => {
+                if (err)
+                    return reject(err);
+                resolve({ type: classify(st.mode) });
+            });
+        });
+        if (s.type === "directory") {
+            if (!recursive)
+                throw new Error(`"${path}" 是目录，需要 --recursive 选项`);
+            // 递归删除目录内容
+            const entries = await new Promise((res, rej) => {
+                sftp.readdir(path, (err, e) => (err ? rej(err) : res(e)));
+            });
+            for (const e of entries) {
+                if (e.filename === "." || e.filename === "..")
+                    continue;
+                await removePath(cfg, posix.join(path, e.filename), true);
+            }
+            await new Promise((res, rej) => {
+                sftp.rmdir(path, (err) => (err ? rej(err) : res()));
+            });
+        }
+        else {
+            await new Promise((res, rej) => {
+                sftp.unlink(path, (err) => (err ? rej(err) : res()));
+            });
+        }
+        conn.end();
+    }
+    catch (e) {
+        conn.end();
+        throw e;
+    }
+}
+export async function makeDir(cfg, path, parents) {
+    const conn = await createConnection(cfg, 20_000);
+    try {
+        const sftp = await openSftp(conn);
+        if (parents) {
+            // 逐层创建
+            const parts = path.split("/").filter(Boolean);
+            let current = path.startsWith("/") ? "/" : "";
+            for (const p of parts) {
+                current = current ? posix.join(current, p) : p;
+                await new Promise((resolve, reject) => {
+                    sftp.mkdir(current, { mode: 0o755 }, (err) => {
+                        // 已存在不算错
+                        if (err && err.code !== 4)
+                            return reject(err);
+                        resolve();
+                    });
+                });
+            }
+        }
+        else {
+            await new Promise((res, rej) => {
+                sftp.mkdir(path, { mode: 0o755 }, (err) => (err ? rej(err) : res()));
+            });
+        }
+        conn.end();
+    }
+    catch (e) {
+        conn.end();
+        throw e;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bingzi-233/ssh-mcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "纯命令行 SSH/SFTP 工具：在多台远程服务器上执行命令、传输大文件（断点续传）。支持 CLI 模式和 MCP stdio 模式。",
   "type": "module",
   "bin": {