@bingzi-233/ssh-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BingZi-233
+
+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.

package/README.md

@@ -0,0 +1,133 @@
+# ssh-mcp
+
+一个 MCP 服务器，让 Claude 通过 **SSH** 在多台远程服务器上执行命令、并通过 **SFTP** 传输大文件（支持 40GB+ 与断点续传）。每台服务器配一个 `name`，模型靠 `name` 区分目标机器。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `list_servers` | 列出所有已配置的服务器（name / 描述 / 地址 / 用户，**不含密码私钥**） |
+| `run_command` | 在指定 `name` 的服务器上执行一条命令，返回 stdout / stderr / 退出码 |
+| `upload_file` | 上传本机文件到远程（后台任务，支持断点续传） |
+| `download_file` | 从远程下载文件到本机（后台任务，支持断点续传） |
+| `transfer_status` | 查询传输进度（已传字节、百分比、速度、ETA、状态） |
+| `cancel_transfer` | 取消一个进行中的传输（已传部分保留，可续传） |
+
+> - 命令在独立会话中执行，**命令之间不保留工作目录和环境变量**。需要保持上下文时自行串接，例如 `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
+```
+
+需要自定义配置文件路径时：
+
+```bash
+claude mcp add ssh -e SSH_MCP_CONFIG=/path/to/servers.json -- npx -y @bingzi-233/ssh-mcp
+```
+
+### 方式三：本地源码构建（开发用）
+
+```bash
+npm install
+npm run build
+claude mcp add ssh -- node /绝对路径/ssh-mcp/dist/index.js
+```
+
+---
+
+## 配置服务器
+
+默认从 `~/.ssh-mcp/servers.json` 读取（可用环境变量 `SSH_MCP_CONFIG` 指定别的路径）。参考 `servers.example.json`：
+
+```json
+{
+  "servers": [
+    {
+      "name": "prod-web",
+      "description": "生产环境 Web 服务器",
+      "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"
+    }
+  ]
+}
+```
+
+**鉴权优先级**（每台服务器独立选择）：
+
+1. `privateKeyPath`（+ 可选 `passphrase`）—— 私钥文件，支持 `~` 展开
+2. `password` —— 密码登录
+3. 都没配 → 回退到本机 `ssh-agent`（读 `SSH_AUTH_SOCK`）
+
+新增/修改服务器后**无需重启**——配置文件每次调用都会重新读取。
+
+---
+
+## 发布到 npm（维护者）
+
+仓库已配置 GitHub Actions，推送 `vX.Y.Z` 形式的 tag 即自动发布到 npm。
+
+**一次性准备**：
+
+1. 在 npmjs.com 创建一个 **Automation** 类型的 Access Token。
+2. 把它加到仓库 Secrets：
+   ```bash
+   gh secret set NPM_TOKEN
+   ```
+   （或在 GitHub 网页 Settings → Secrets and variables → Actions 添加。）
+
+> 包名 scope `@bingzi-233` 必须是你拥有的 npm 用户名或组织。若不一致，改 `package.json` 的 `name` 与插件 `.mcp.json` 里的 `args`。
+
+**每次发版**：
+
+```bash
+# 1. 同步版本号（两处都改：npm 包与插件）
+#    - package.json 的 "version"
+#    - plugins/ssh-mcp/.claude-plugin/plugin.json 的 "version"
+# 2. 提交并打 tag
+git commit -am "release: v1.0.1"
+git tag v1.0.1
+git push && git push --tags
+```
+
+Actions 会自动 `npm ci && npm run build && npm publish`（带 provenance 来源证明）。
+
+---
+
+## ⚠️ 安全提示
+
+这个工具允许模型在你的服务器上执行**任意命令**、读写文件。请仅指向你拥有/授权的机器：
+
+- `servers.json` 含明文凭据，已在 `.gitignore` 中排除，**切勿提交到仓库**。
+- 优先用私钥或 `ssh-agent`，尽量不在配置里写明文密码。
+- 给 SSH 账号最小权限；高危机器考虑用受限账号。
+- `run_command` 默认每条命令 60s 超时，可用 `timeout_ms` 调整。
+
+## License
+
+MIT © BingZi-233

package/dist/config.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** 把开头的 ~ 展开成用户主目录。 */
+export function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\"))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+/** 配置文件路径：优先环境变量 SSH_MCP_CONFIG，否则取 ~/.ssh-mcp/servers.json。 */
+export function configPath() {
+    const fromEnv = process.env.SSH_MCP_CONFIG;
+    return fromEnv ? expandHome(fromEnv) : join(homedir(), ".ssh-mcp", "servers.json");
+}
+/**
+ * 每次调用都从磁盘重新读取配置——配置文件就是唯一事实来源。
+ * 这样新增服务器后无需重启 MCP 服务器。读取或校验失败时抛错，由调用方处理。
+ */
+export function loadServers() {
+    const path = configPath();
+    const raw = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`配置文件 ${path} 不是合法 JSON：${e.message}`);
+    }
+    const list = parsed.servers;
+    if (!Array.isArray(list)) {
+        throw new Error(`配置文件 ${path} 缺少顶层 "servers" 数组`);
+    }
+    const map = new Map();
+    for (const item of list) {
+        if (!item.name || !item.host || !item.username) {
+            throw new Error(`配置文件中存在缺少 name/host/username 的服务器条目`);
+        }
+        if (map.has(item.name)) {
+            throw new Error(`配置文件中存在重复的服务器 name："${item.name}"`);
+        }
+        map.set(item.name, item);
+    }
+    return map;
+}

package/dist/index.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { configPath, loadServers } from "./config.js";
+import { runCommand } from "./ssh.js";
+import { cancelTransfer, getTransfer, listTransfers, startTransfer, } from "./transfer.js";
+const DEFAULT_TIMEOUT_MS = 60_000;
+function humanBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    const units = ["KB", "MB", "GB", "TB"];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    return `${v.toFixed(2)} ${units[i]}`;
+}
+function humanDuration(sec) {
+    if (!isFinite(sec) || sec <= 0)
+        return "—";
+    const s = Math.round(sec);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${s % 60}s`;
+    const h = Math.floor(m / 60);
+    return `${h}h ${m % 60}m`;
+}
+function formatTransfer(t) {
+    const pct = t.totalBytes > 0 ? (t.transferredBytes / t.totalBytes) * 100 : 100;
+    const movedThisSession = t.transferredBytes - t.startOffset;
+    const elapsedSec = Math.max((t.updatedAt - t.startedAt) / 1000, 0.001);
+    const speed = movedThisSession / elapsedSec;
+    const remaining = t.totalBytes - t.transferredBytes;
+    const eta = t.state === "running" && speed > 0 ? remaining / speed : NaN;
+    const lines = [
+        `[${t.id}] ${t.direction === "upload" ? "上传" : "下载"} @ ${t.server} — ${t.state}`,
+        `  本地: ${t.localPath}`,
+        `  远程: ${t.remotePath}`,
+        `  进度: ${humanBytes(t.transferredBytes)} / ${humanBytes(t.totalBytes)} (${pct.toFixed(1)}%)`,
+    ];
+    if (t.startOffset > 0)
+        lines.push(`  续传起点: ${humanBytes(t.startOffset)}`);
+    if (t.state === "running") {
+        lines.push(`  速度: ${humanBytes(speed)}/s   预计剩余: ${humanDuration(eta)}`);
+    }
+    if (t.error)
+        lines.push(`  错误: ${t.error}`);
+    return lines.join("\n");
+}
+const server = new McpServer({
+    name: "ssh-mcp",
+    version: "1.0.0",
+});
+server.registerTool("list_servers", {
+    title: "列出可用的 SSH 服务器",
+    description: "列出所有已配置的远程服务器及其 name、描述、地址和登录用户。" +
+        "在使用 run_command 之前，先用本工具确认有哪些服务器以及对应的 name。" +
+        "（不会返回任何密码或私钥等敏感信息。）",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: false },
+}, async () => {
+    try {
+        const servers = loadServers();
+        const list = [...servers.values()].map((s) => ({
+            name: s.name,
+            description: s.description ?? "",
+            host: s.host,
+            port: s.port ?? 22,
+            username: s.username,
+        }));
+        const text = list.length > 0
+            ? JSON.stringify(list, null, 2)
+            : `没有已配置的服务器。请编辑配置文件：${configPath()}`;
+        return { content: [{ type: "text", text }] };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `读取服务器配置失败：${e.message}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool("run_command", {
+    title: "在远程服务器上执行命令",
+    description: "通过 SSH 在指定的远程服务器上执行一条 shell 命令，返回 stdout、stderr 和退出码。" +
+        "用 server 参数指定目标服务器的 name（可先用 list_servers 查看）。" +
+        "注意：每条命令在独立的会话中执行，命令之间不保留工作目录或环境变量；" +
+        "需要保持上下文时请自行串接，例如 `cd /var/www && git pull`。",
+    inputSchema: {
+        server: z
+            .string()
+            .describe("目标服务器的 name，必须与 list_servers 返回的某个 name 完全一致"),
+        command: z.string().describe("要在远程服务器上执行的 shell 命令"),
+        timeout_ms: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe(`命令超时时间（毫秒），默认 ${DEFAULT_TIMEOUT_MS}`),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+}, async ({ server: serverName, command, timeout_ms }) => {
+    let servers;
+    try {
+        servers = loadServers();
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `读取服务器配置失败：${e.message}` }],
+            isError: true,
+        };
+    }
+    const cfg = servers.get(serverName);
+    if (!cfg) {
+        const names = [...servers.keys()].join(", ") || "（无）";
+        return {
+            content: [
+                { type: "text", text: `未找到名为 "${serverName}" 的服务器。可用：${names}` },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        const r = await runCommand(cfg, command, timeout_ms ?? DEFAULT_TIMEOUT_MS);
+        const parts = [
+            `服务器: ${cfg.name} (${cfg.username}@${cfg.host}:${cfg.port ?? 22})`,
+            `退出码: ${r.code ?? "null"}${r.signal ? `  信号: ${r.signal}` : ""}`,
+        ];
+        if (r.stdout)
+            parts.push(`--- stdout ---\n${r.stdout.trimEnd()}`);
+        if (r.stderr)
+            parts.push(`--- stderr ---\n${r.stderr.trimEnd()}`);
+        if (!r.stdout && !r.stderr)
+            parts.push("（无输出）");
+        return { content: [{ type: "text", text: parts.join("\n") }] };
+    }
+    catch (e) {
+        return {
+            content: [{ type: "text", text: `执行失败：${e.message}` }],
+            isError: true,
+        };
+    }
+});
+function loadServersOrError() {
+    try {
+        return { servers: loadServers(), error: null };
+    }
+    catch (e) {
+        return { servers: null, error: e.message };
+    }
+}
+server.registerTool("upload_file", {
+    title: "上传文件到远程服务器",
+    description: "通过 SFTP 把本机文件上传到指定服务器，适用于大文件（40GB+）。" +
+        "这是后台任务：本工具立即返回一个传输 id，随后请用 transfer_status 轮询进度，不要阻塞等待。" +
+        "支持断点续传——对同一对路径再次调用会自动从远程已有字节处继续；" +
+        "若远程 remote_path 是已存在的目录，则自动在其下使用本地文件名。",
+    inputSchema: {
+        server: z.string().describe("目标服务器的 name（见 list_servers）"),
+        local_path: z.string().describe("本机要上传的文件路径（绝对路径）"),
+        remote_path: z.string().describe("远程目标路径（文件路径；若为已存在目录则自动追加文件名）"),
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("true 则忽略远程已有部分、从头覆盖；默认 false（自动断点续传）"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+}, async ({ server: serverName, local_path, remote_path, overwrite }) => {
+    const { servers, error } = loadServersOrError();
+    if (!servers)
+        return { content: [{ type: "text", text: `读取服务器配置失败：${error}` }], isError: true };
+    const cfg = servers.get(serverName);
+    if (!cfg) {
+        const names = [...servers.keys()].join(", ") || "（无）";
+        return { content: [{ type: "text", text: `未找到名为 "${serverName}" 的服务器。可用：${names}` }], isError: true };
+    }
+    try {
+        const t = await startTransfer(cfg, "upload", local_path, remote_path, overwrite ?? false);
+        const hint = t.state === "completed"
+            ? "\n（目标已是完整文件，无需传输。）"
+            : `\n传输已在后台开始，用 transfer_status({ id: "${t.id}" }) 查看进度。`;
+        return { content: [{ type: "text", text: formatTransfer(t) + hint }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `发起上传失败：${e.message}` }], isError: true };
+    }
+});
+server.registerTool("download_file", {
+    title: "从远程服务器下载文件",
+    description: "通过 SFTP 把指定服务器上的文件下载到本机，适用于大文件（40GB+）。" +
+        "这是后台任务：本工具立即返回一个传输 id，随后请用 transfer_status 轮询进度，不要阻塞等待。" +
+        "支持断点续传——对同一对路径再次调用会自动从本地已有字节处继续；" +
+        "若本地 local_path 是已存在的目录，则自动在其下使用远程文件名。",
+    inputSchema: {
+        server: z.string().describe("源服务器的 name（见 list_servers）"),
+        remote_path: z.string().describe("远程要下载的文件路径"),
+        local_path: z.string().describe("本机目标路径（文件路径；若为已存在目录则自动追加文件名）"),
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("true 则忽略本地已有部分、从头覆盖；默认 false（自动断点续传）"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+}, async ({ server: serverName, remote_path, local_path, overwrite }) => {
+    const { servers, error } = loadServersOrError();
+    if (!servers)
+        return { content: [{ type: "text", text: `读取服务器配置失败：${error}` }], isError: true };
+    const cfg = servers.get(serverName);
+    if (!cfg) {
+        const names = [...servers.keys()].join(", ") || "（无）";
+        return { content: [{ type: "text", text: `未找到名为 "${serverName}" 的服务器。可用：${names}` }], isError: true };
+    }
+    try {
+        const t = await startTransfer(cfg, "download", local_path, remote_path, overwrite ?? false);
+        const hint = t.state === "completed"
+            ? "\n（目标已是完整文件，无需传输。）"
+            : `\n传输已在后台开始，用 transfer_status({ id: "${t.id}" }) 查看进度。`;
+        return { content: [{ type: "text", text: formatTransfer(t) + hint }] };
+    }
+    catch (e) {
+        return { content: [{ type: "text", text: `发起下载失败：${e.message}` }], isError: true };
+    }
+});
+server.registerTool("transfer_status", {
+    title: "查看文件传输进度",
+    description: "查询后台文件传输任务的进度（已传字节、百分比、速度、预计剩余时间、状态）。" +
+        "传入 id 查看单个任务；不传则列出本次会话的全部任务。",
+    inputSchema: {
+        id: z.string().optional().describe("传输任务 id；不填则列出全部任务"),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+}, async ({ id }) => {
+    if (id) {
+        const t = getTransfer(id);
+        if (!t)
+            return { content: [{ type: "text", text: `未找到传输任务：${id}` }], isError: true };
+        return { content: [{ type: "text", text: formatTransfer(t) }] };
+    }
+    const all = listTransfers();
+    const text = all.length > 0 ? all.map(formatTransfer).join("\n\n") : "当前没有传输任务。";
+    return { content: [{ type: "text", text }] };
+});
+server.registerTool("cancel_transfer", {
+    title: "取消文件传输",
+    description: "取消一个正在进行的后台传输任务。已传输的部分文件会保留，之后可用同样的路径再次发起以断点续传。",
+    inputSchema: {
+        id: z.string().describe("要取消的传输任务 id"),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+}, async ({ id }) => {
+    const t = cancelTransfer(id);
+    if (!t)
+        return { content: [{ type: "text", text: `未找到传输任务：${id}` }], isError: true };
+    return { content: [{ type: "text", text: `已请求取消：\n${formatTransfer(t)}` }] };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // 日志走 stderr，避免污染 stdio 上的 MCP 协议数据。
+    console.error(`ssh-mcp 已启动，配置文件：${configPath()}`);
+}
+main().catch((e) => {
+    console.error("ssh-mcp 启动失败：", e);
+    process.exit(1);
+});

package/dist/ssh.js

@@ -0,0 +1,97 @@
+import { readFileSync } from "node:fs";
+import { Client } from "ssh2";
+import { expandHome } from "./config.js";
+/** 根据服务器配置组装 ssh2 的连接参数，挑选鉴权方式。 */
+export function buildConnectConfig(server, readyTimeoutMs) {
+    const conf = {
+        host: server.host,
+        port: server.port ?? 22,
+        username: server.username,
+        readyTimeout: readyTimeoutMs,
+    };
+    if (server.privateKeyPath) {
+        // 私钥登录优先级最高。
+        conf.privateKey = readFileSync(expandHome(server.privateKeyPath));
+        if (server.passphrase)
+            conf.passphrase = server.passphrase;
+    }
+    else if (server.password) {
+        // 其次是密码登录。
+        conf.password = server.password;
+    }
+    else if (process.env.SSH_AUTH_SOCK) {
+        // 最后退回到本机 ssh-agent。
+        conf.agent = process.env.SSH_AUTH_SOCK;
+    }
+    return conf;
+}
+/** 建立一条已就绪的 SSH 连接。命令执行和文件传输共用这一条连接路径。 */
+export function createConnection(server, readyTimeoutMs) {
+    return new Promise((resolve, reject) => {
+        const conn = new Client();
+        let settled = false;
+        conn.on("ready", () => {
+            if (!settled) {
+                settled = true;
+                resolve(conn);
+            }
+        });
+        conn.on("error", (err) => {
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        });
+        try {
+            conn.connect(buildConnectConfig(server, readyTimeoutMs));
+        }
+        catch (e) {
+            // 读取私钥失败等同步错误。
+            if (!settled) {
+                settled = true;
+                reject(e);
+            }
+        }
+    });
+}
+/**
+ * 在指定服务器上执行一条命令，收集 stdout/stderr/退出码后返回。
+ *
+ * 设计取舍：每次调用建立一条独立连接，执行完即断开。SSH 的 exec channel 本就
+ * 无状态，命令之间不会保留工作目录或环境变量——需要时请用 `cd x && cmd` 自行串接。
+ */
+export async function runCommand(server, command, timeoutMs) {
+    const conn = await createConnection(server, timeoutMs);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+            conn.end();
+        };
+        const timer = setTimeout(() => {
+            finish(() => reject(new Error(`命令执行超时（${timeoutMs}ms）`)));
+        }, timeoutMs);
+        conn.on("error", (err) => finish(() => reject(err)));
+        conn.exec(command, (err, stream) => {
+            if (err) {
+                finish(() => reject(err));
+                return;
+            }
+            let stdout = "";
+            let stderr = "";
+            stream.on("data", (d) => {
+                stdout += d.toString("utf8");
+            });
+            stream.stderr.on("data", (d) => {
+                stderr += d.toString("utf8");
+            });
+            stream.on("close", (code, signal) => {
+                finish(() => resolve({ stdout, stderr, code, signal }));
+            });
+        });
+    });
+}

package/dist/transfer.js

@@ -0,0 +1,179 @@
+import { createReadStream, createWriteStream, statSync } from "node:fs";
+import { basename } from "node:path";
+import { posix as posixPath } from "node:path";
+import { createConnection } from "./ssh.js";
+// 任务注册表只活在内存里。续传不依赖它——真正的事实来源是磁盘上文件的实际大小，
+// 所以即便进程重启、注册表清空，再次发起同一对路径的传输也能自动续上。
+const transfers = new Map();
+const handles = new Map();
+let counter = 0;
+function statRemote(sftp, path) {
+    return new Promise((resolve) => {
+        sftp.stat(path, (err, stats) => resolve(err ? null : stats));
+    });
+}
+function statLocal(path) {
+    try {
+        const s = statSync(path);
+        return { size: s.size, isDir: s.isDirectory() };
+    }
+    catch {
+        return null;
+    }
+}
+function openSftp(conn) {
+    return new Promise((resolve, reject) => {
+        conn.sftp((err, sftp) => (err ? reject(err) : resolve(sftp)));
+    });
+}
+/**
+ * 发起一次后台文件传输并立即返回任务记录。调用方应随后用 getTransfer/listTransfers 轮询进度。
+ *
+ * 续传逻辑：根据目标当前大小决定起始偏移量。overwrite=true 时从头覆盖。
+ * 若目标是已存在的目录，则自动在其下追加源文件名。
+ */
+export async function startTransfer(cfg, direction, localPath, remotePath, overwrite) {
+    const conn = await createConnection(cfg, 20_000);
+    let sftp;
+    try {
+        sftp = await openSftp(conn);
+    }
+    catch (e) {
+        conn.end();
+        throw e;
+    }
+    let totalBytes;
+    let startOffset;
+    let localFile = localPath;
+    let remoteFile = remotePath;
+    try {
+        if (direction === "upload") {
+            const lst = statLocal(localPath);
+            if (!lst)
+                throw new Error(`本地文件不存在：${localPath}`);
+            if (lst.isDir)
+                throw new Error(`本地路径是目录，请指定文件：${localPath}`);
+            totalBytes = lst.size;
+            const rst = await statRemote(sftp, remotePath);
+            if (rst?.isDirectory()) {
+                // 远程是目录 → 在其下追加本地文件名。
+                remoteFile = posixPath.join(remotePath, basename(localPath));
+                const r2 = await statRemote(sftp, remoteFile);
+                startOffset = overwrite ? 0 : r2?.size ?? 0;
+            }
+            else {
+                startOffset = overwrite ? 0 : rst?.size ?? 0;
+            }
+        }
+        else {
+            const rst = await statRemote(sftp, remotePath);
+            if (!rst)
+                throw new Error(`远程文件不存在：${remotePath}`);
+            if (rst.isDirectory())
+                throw new Error(`远程路径是目录，请指定文件：${remotePath}`);
+            totalBytes = rst.size;
+            const lst = statLocal(localPath);
+            if (lst?.isDir) {
+                // 本地是目录 → 在其下追加远程文件名。
+                localFile = posixPath.join(localPath, basename(remotePath));
+                const l2 = statLocal(localFile);
+                startOffset = overwrite ? 0 : l2?.size ?? 0;
+            }
+            else {
+                startOffset = overwrite ? 0 : lst?.size ?? 0;
+            }
+        }
+    }
+    catch (e) {
+        conn.end();
+        throw e;
+    }
+    if (startOffset > totalBytes) {
+        conn.end();
+        throw new Error(`目标已有 ${startOffset} 字节，超过源文件的 ${totalBytes} 字节，文件可能不一致。` +
+            `请用 overwrite=true 重新传输。`);
+    }
+    const id = `t${++counter}`;
+    const now = Date.now();
+    const t = {
+        id,
+        server: cfg.name,
+        direction,
+        localPath: localFile,
+        remotePath: remoteFile,
+        totalBytes,
+        startOffset,
+        transferredBytes: startOffset,
+        state: "running",
+        startedAt: now,
+        updatedAt: now,
+    };
+    transfers.set(id, t);
+    // 目标已经完整，无需传输。
+    if (startOffset === totalBytes) {
+        t.state = "completed";
+        t.updatedAt = Date.now();
+        conn.end();
+        return t;
+    }
+    const flags = overwrite ? "w" : "a";
+    const read = direction === "download"
+        ? sftp.createReadStream(remoteFile, { start: startOffset })
+        : createReadStream(localFile, { start: startOffset });
+    const write = direction === "download"
+        ? createWriteStream(localFile, { flags })
+        : sftp.createWriteStream(remoteFile, { flags });
+    const cleanup = () => {
+        read.destroy();
+        write.destroy();
+        conn.end();
+        handles.delete(id);
+    };
+    handles.set(id, () => {
+        read.destroy();
+        write.destroy();
+        conn.end();
+    });
+    read.on("data", (chunk) => {
+        t.transferredBytes += chunk.length;
+        t.updatedAt = Date.now();
+    });
+    const onError = (err) => {
+        if (t.state === "running") {
+            t.state = "failed";
+            t.error = err.message;
+            t.updatedAt = Date.now();
+        }
+        cleanup();
+    };
+    read.on("error", onError);
+    write.on("error", onError);
+    write.on("finish", () => {
+        if (t.state === "running") {
+            t.state = "completed";
+            t.transferredBytes = totalBytes;
+            t.updatedAt = Date.now();
+        }
+        cleanup();
+    });
+    read.pipe(write);
+    return t;
+}
+export function getTransfer(id) {
+    return transfers.get(id);
+}
+export function listTransfers() {
+    return [...transfers.values()];
+}
+export function cancelTransfer(id) {
+    const t = transfers.get(id);
+    if (!t)
+        return undefined;
+    if (t.state === "running") {
+        t.state = "cancelled";
+        t.updatedAt = Date.now();
+        handles.get(id)?.();
+        handles.delete(id);
+    }
+    return t;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@bingzi-233/ssh-mcp",
+  "version": "1.0.0",
+  "description": "通过 SSH/SFTP 让 AI 在多台远程服务器上执行命令并传输大文件（支持断点续传）的 MCP 服务器",
+  "type": "module",
+  "bin": {
+    "ssh-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ssh",
+    "sftp",
+    "remote",
+    "file-transfer",
+    "claude"
+  ],
+  "author": "BingZi-233",
+  "license": "MIT",
+  "homepage": "https://github.com/BingZi-233/ssh-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BingZi-233/ssh-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BingZi-233/ssh-mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "ssh2": "^1.16.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ssh2": "^1.15.0",
+    "typescript": "^5.6.0"
+  }
+}