@aaarc/handfree-ssh-mcp 1.0.0

package/build/tools/help.js

@@ -0,0 +1,147 @@
+import { z } from "zod";
+const TOOL_HELP = {
+    "list-servers": `list-servers — Discover available SSH servers.
+
+Parameters:
+  refresh  (boolean, optional)  When true, re-collects live system status
+           (hostname, CPU, memory, disk, GPUs) from all enabled servers.
+           Without this, cached status from connection time is returned.
+
+Returns: JSON array of server objects with name, host, port, username,
+         connected, enabled, and optional status.
+
+Example:
+  list-servers                   → cached info
+  list-servers { refresh: true } → fresh system status`,
+    "execute-command": `execute-command — Run a shell command on a remote server.
+
+Parameters:
+  cmdString       (string, required)   The shell command to execute.
+  connectionName  (string, see below)  Target server name from list-servers.
+  stream          (boolean, optional)  Default true. Set false for short
+                  commands when you only need the final output.
+  timeout         (number, optional)   Max runtime in ms.
+                  Defaults: 300000 (stream) / 30000 (non-stream).
+
+connectionName rule:
+  • If only one server is enabled → optional (auto-selected).
+  • If multiple servers are enabled → REQUIRED.
+
+Examples:
+  execute-command { cmdString: "pwd" }
+  execute-command { cmdString: "docker ps -a", connectionName: "prod", stream: false }
+  execute-command { cmdString: "tail -f /var/log/syslog", stream: true, timeout: 600000 }`,
+    "show-whitelist": `show-whitelist — Show allowed/blocked command patterns for a server.
+
+Parameters:
+  connectionName  (string, see below)  Target server name from list-servers.
+
+connectionName rule:
+  • If only one server is enabled → optional (auto-selected).
+  • If multiple servers are enabled → REQUIRED.
+
+Returns: Whitelist patterns, blacklist patterns, and example commands.`,
+    "upload": `upload — Upload a single local file to a remote server over SFTP.
+
+Parameters:
+  localPath       (string, required)   File path on the MCP host.
+                  Must be inside the MCP working directory.
+  remotePath      (string, required)   Destination path on the remote server.
+  connectionName  (string, see below)  Target server name from list-servers.
+
+connectionName rule:
+  • If only one server is enabled → optional (auto-selected).
+  • If multiple servers are enabled → REQUIRED.
+
+Example:
+  upload { localPath: "data.csv", remotePath: "/tmp/data.csv" }`,
+    "download": `download — Download a single file from a remote server over SFTP.
+
+Parameters:
+  remotePath      (string, required)   File path on the remote server.
+  localPath       (string, required)   Destination on the MCP host.
+                  Must be inside the MCP working directory.
+  connectionName  (string, see below)  Target server name from list-servers.
+
+connectionName rule:
+  • If only one server is enabled → optional (auto-selected).
+  • If multiple servers are enabled → REQUIRED.
+
+Example:
+  download { remotePath: "/var/log/app.log", localPath: "app.log" }`,
+    "transfer": `transfer — Move files between hosts (single/recursive/cross-server).
+
+Modes:
+  upload    Push local → remote (single file or recursive directory).
+  download  Pull remote → local (single file or recursive directory).
+  relay     Stream a file from remote-A → remote-B via SFTP piping.
+            No temp file on the MCP host, no SCP, no authorized-key
+            exchange between the two servers. Each side uses its own
+            existing SSH session.
+
+Parameters for upload / download:
+  mode            (string, required)   "upload" or "download"
+  localPath       (string, required)   Path on the MCP host.
+  remotePath      (string, required)   Path on the remote server.
+  connectionName  (string, see below)  Target server name.
+  recursive       (boolean, optional)  True to transfer a whole directory tree.
+
+Parameters for relay:
+  mode              (string, required)   "relay"
+  sourceServer      (string, required)   Server name to read from.
+  sourceRemotePath  (string, required)   File path on source server.
+  destServer        (string, required)   Server name to write to.
+  destRemotePath    (string, required)   File path on dest server.
+
+connectionName rule (upload/download):
+  • If only one server is enabled → optional.
+  • If multiple servers are enabled → REQUIRED.
+
+Examples:
+  transfer { mode: "upload", localPath: "dist/", remotePath: "/opt/app/dist", recursive: true }
+  transfer { mode: "relay", sourceServer: "prod", sourceRemotePath: "/var/log/app.log",
+             destServer: "backup", destRemotePath: "/backup/app.log" }`,
+    "help": `help — Show detailed usage for one or all tools.
+
+Parameters:
+  tool  (string, optional)  Tool name to get help for.
+        If omitted, shows a summary of all available tools.
+
+Example:
+  help                           → overview of all tools
+  help { tool: "execute-command" } → detailed usage for execute-command`,
+};
+const TOOL_OVERVIEW = `Available tools (use help { tool: "<name>" } for details):
+
+  list-servers      Discover available SSH servers and their status.
+  execute-command   Run a shell command on a remote server.
+  show-whitelist    Show allowed/blocked command patterns.
+  upload            Upload a single file to a remote server.
+  download          Download a single file from a remote server.
+  transfer          Move files: single, recursive, or cross-server relay.
+  help              Show this help or detailed per-tool usage.
+
+Quick start:
+  1. list-servers → discover server names
+  2. show-whitelist { connectionName: "<name>" } → see what's allowed
+  3. execute-command { cmdString: "pwd", connectionName: "<name>" }`;
+/**
+ * Register help tool
+ */
+export function registerHelpTool(server) {
+    server.tool("help", "Show detailed usage instructions for one or all tools. Call with no arguments for an overview, or specify a tool name for full parameter docs and examples.", {
+        tool: z.string().optional().describe("Tool name to get detailed help for. Omit to see an overview of all tools."),
+    }, async ({ tool }) => {
+        if (tool) {
+            const text = TOOL_HELP[tool];
+            if (!text) {
+                return {
+                    content: [{ type: "text", text: `Unknown tool: "${tool}". ${TOOL_OVERVIEW}` }],
+                    isError: true,
+                };
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        return { content: [{ type: "text", text: TOOL_OVERVIEW }] };
+    });
+}

package/build/tools/index.js

@@ -0,0 +1,20 @@
+import { registerExecuteCommandTool } from "./execute-command.js";
+import { registerUploadTool } from "./upload.js";
+import { registerDownloadTool } from "./download.js";
+import { registerListServersTool } from "./list-servers.js";
+import { registerShowWhitelistTool } from "./show-whitelist.js";
+import { registerTransferTool } from "./transfer.js";
+import { registerHelpTool } from "./help.js";
+/**
+ * Register all tools
+ * @param server MCP server instance
+ */
+export function registerAllTools(server) {
+    registerExecuteCommandTool(server);
+    registerUploadTool(server);
+    registerDownloadTool(server);
+    registerListServersTool(server);
+    registerShowWhitelistTool(server);
+    registerTransferTool(server);
+    registerHelpTool(server);
+}

package/build/tools/list-servers.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
+import { Logger } from "../utils/logger.js";
+import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
+/**
+ * Register list-servers tool
+ */
+export function registerListServersTool(server) {
+    server.tool("list-servers", "List the SSH servers that were loaded from OpenSSH config and/or YAML and enabled for this MCP process. Use this first to discover valid connectionName values, confirm whether a server is enabled, and see basic connection state before calling other tools. Set refresh=true to collect live system status (hostname, CPU, memory, disk, GPUs) from connected servers.", {
+        refresh: z.boolean().optional().describe("When true, re-collects live system status from all enabled servers before returning. Without this, cached status from connection time is returned."),
+    }, async ({ refresh }) => {
+        try {
+            const sshManager = SSHConnectionManager.getInstance();
+            if (refresh) {
+                await sshManager.refreshStatus();
+            }
+            const servers = sshManager.getAllServerInfos();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(servers),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const toolError = toToolError(error, "INVALID_CONFIGURATION");
+            Logger.handleError(toolError, "Failed to list servers");
+            return {
+                content: [{ type: "text", text: formatToolErrorResponse(toolError) }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/show-whitelist.js

@@ -0,0 +1,216 @@
+import { z } from "zod";
+import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
+import { Logger } from "../utils/logger.js";
+import { ToolError, formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
+/**
+ * Register show-whitelist tool
+ *
+ * Allows the LLM to see what commands are allowed for a server.
+ */
+export function registerShowWhitelistTool(server) {
+    const sshManager = SSHConnectionManager.getInstance();
+    server.tool("show-whitelist", "Show the configured whitelist, blacklist, and SFTP path policy (allowedRemoteDirectories / allowedLocalDirectories) for a server. Use this before execute-command when you need to understand which commands are allowed, why a command may be rejected, or what command patterns are safe to try next. Also use it before upload / download / transfer to see which paths SFTP is permitted to touch.", {
+        connectionName: z
+            .string()
+            .optional()
+            .describe("Target server name from list-servers. Required when multiple servers are enabled; optional when only one server is enabled."),
+    }, async ({ connectionName }) => {
+        try {
+            const resolvedName = sshManager.resolveServer(connectionName);
+            const config = sshManager.getServerConfig(resolvedName);
+            if (!config) {
+                const toolError = new ToolError("INVALID_CONFIGURATION", `Server '${resolvedName}' not found or not enabled.`, false);
+                return {
+                    content: [{
+                            type: "text",
+                            text: formatToolErrorResponse(toolError)
+                        }],
+                    isError: true,
+                };
+            }
+            const whitelist = config.commandWhitelist || [];
+            const blacklist = config.commandBlacklist || [];
+            let output = `# Command Permissions for: ${config.name}\n\n`;
+            output += `Host: ${config.username}@${config.host}:${config.port}\n\n`;
+            // Whitelist
+            output += `## ✅ Allowed Commands (Whitelist)\n\n`;
+            if (whitelist.length === 0) {
+                output += `⚠️ No whitelist configured - using default safe commands.\n\n`;
+            }
+            else {
+                output += `${whitelist.length} patterns:\n\n`;
+                for (const pattern of whitelist) {
+                    const readable = patternToReadable(pattern);
+                    output += `- \`${pattern}\``;
+                    if (readable !== pattern) {
+                        output += ` → ${readable}`;
+                    }
+                    output += `\n`;
+                }
+                output += `\n`;
+            }
+            // Blacklist
+            if (blacklist.length > 0) {
+                output += `## ❌ Blocked Commands (Blacklist)\n\n`;
+                output += `${blacklist.length} patterns:\n\n`;
+                for (const pattern of blacklist) {
+                    const readable = patternToReadable(pattern);
+                    output += `- \`${pattern}\``;
+                    if (readable !== pattern) {
+                        output += ` → ${readable}`;
+                    }
+                    output += `\n`;
+                }
+                output += `\n`;
+            }
+            // SFTP path policy (upload / download / transfer tools only)
+            const allowedRemoteDirs = config.allowedRemoteDirectories ?? [];
+            const allowedLocalDirs = config.allowedLocalDirectories ?? [];
+            const mcpCwd = process.cwd();
+            output += `## 📂 SFTP Path Policy (upload / download / transfer)\n\n`;
+            // ----- Remote directories -----
+            output += `### Allowed remote directories\n\n`;
+            if (allowedRemoteDirs.length === 0) {
+                output += `⚠️ **\`allowedRemoteDirectories\` is NOT configured.** ` +
+                    `SFTP upload/download/transfer is **disabled** for this server — every call will be rejected with \`REMOTE_PATH_NOT_ALLOWED\`. ` +
+                    `To enable file transfer, add absolute POSIX directories under \`allowedRemoteDirectories\` in the server's YAML config.\n\n`;
+            }
+            else {
+                output += `${allowedRemoteDirs.length} entr${allowedRemoteDirs.length === 1 ? "y" : "ies"}:\n\n`;
+                for (const dir of allowedRemoteDirs) {
+                    output += `- \`${dir}\`\n`;
+                }
+                output += `\n`;
+            }
+            // ----- Local directories -----
+            output += `### Allowed local directories\n\n`;
+            output += `Always implicitly allowed: \`${mcpCwd}\` _(the MCP working directory)_\n\n`;
+            if (allowedLocalDirs.length === 0) {
+                output += `⚠️ **\`allowedLocalDirectories\` is NOT configured.** ` +
+                    `Only paths inside the MCP working directory above can be used as the local side of upload/download — any other path will be rejected with \`LOCAL_PATH_NOT_ALLOWED\`. ` +
+                    `To allow more locations, add absolute host paths under \`allowedLocalDirectories\` in the server's YAML config.\n\n`;
+            }
+            else {
+                output += `Additional entries (${allowedLocalDirs.length}):\n\n`;
+                for (const dir of allowedLocalDirs) {
+                    output += `- \`${dir}\`\n`;
+                }
+                output += `\n`;
+            }
+            // ----- Matching rules -----
+            output += `### Matching rules\n\n`;
+            output += `- A path is allowed iff it equals an entry above, or starts with \`<entry> + separator\`.\n`;
+            output += `- Remote paths must be absolute POSIX (\`/...\`); \`..\` segments and null bytes are rejected up-front.\n`;
+            output += `- Local paths are resolved on the MCP host first, then matched.\n`;
+            output += `- These path lists do **not** affect \`execute-command\`. They only restrict SFTP file transfers.\n\n`;
+            // ----- Output log policy (execute-command full-output persistence) -----
+            const outputLogRoot = sshManager.getOutputLogRoot();
+            const serverLogDir = `${outputLogRoot}/${config.name}/${config.username}`.replace(/\\/g, "/");
+            output += `## 📝 \`execute-command\` Output Logs\n\n`;
+            output += `Every \`execute-command\` call returns at most \`maxOutputBytes\` (default 65536) bytes per stream, tail-only. The FULL stdout/stderr is always persisted to disk:\n\n`;
+            output += `- Root: \`${outputLogRoot}\` _(override via the top-level \`outputLogDir:\` field in \`servers.yaml\`)_\n`;
+            output += `- This server's logs land under: \`${serverLogDir}/\`\n`;
+            output += `- File name: \`<timestamp>-<pid>-<rand>.log\` with \`=== META / STDOUT / STDERR / END ===\` markers.\n`;
+            output += `- When output is truncated, the response includes an \`[OUTPUT TRUNCATED]\` header with the on-disk log path.\n\n`;
+            // Quick examples
+            output += `## 💡 Example Commands\n\n`;
+            output += `Based on the whitelist, here are some commands you can likely use:\n\n`;
+            const examples = generateExamples(whitelist);
+            for (const ex of examples.slice(0, 10)) {
+                output += `- \`${ex}\`\n`;
+            }
+            return {
+                content: [{ type: "text", text: output }],
+            };
+        }
+        catch (error) {
+            const toolError = toToolError(error, "INVALID_CONFIGURATION");
+            Logger.handleError(toolError, "Failed to show whitelist");
+            return {
+                content: [{ type: "text", text: formatToolErrorResponse(toolError) }],
+                isError: true,
+            };
+        }
+    });
+}
+/**
+ * Convert regex pattern to human-readable description
+ */
+function patternToReadable(pattern) {
+    let readable = pattern;
+    readable = readable.replace(/^\^/, "").replace(/\$$/, "");
+    if (readable === "ls( .*)?")
+        return "ls, ls -la, ls /path, etc.";
+    if (readable === "cat .*")
+        return "cat <file>";
+    if (readable === "pwd")
+        return "pwd (current directory)";
+    if (readable === "whoami")
+        return "whoami (current user)";
+    if (readable === "hostname")
+        return "hostname";
+    if (readable === "date")
+        return "date (current time)";
+    if (readable === "docker ps.*")
+        return "docker ps, docker ps -a, etc.";
+    if (readable === "docker logs.*")
+        return "docker logs <container>";
+    if (readable === "git .*")
+        return "git <any subcommand>";
+    if (readable.includes(".*"))
+        return readable.replace(/\.\*/g, "<any>");
+    if (readable.includes(".+"))
+        return readable.replace(/\.\+/g, "<required>");
+    return readable;
+}
+/**
+ * Generate example commands based on whitelist patterns
+ */
+function generateExamples(whitelist) {
+    const examples = [];
+    for (const pattern of whitelist) {
+        if (pattern.includes("^ls"))
+            examples.push("ls -la");
+        if (pattern.includes("^cat"))
+            examples.push("cat /etc/hostname");
+        if (pattern.includes("^pwd"))
+            examples.push("pwd");
+        if (pattern.includes("^whoami"))
+            examples.push("whoami");
+        if (pattern.includes("^hostname"))
+            examples.push("hostname");
+        if (pattern.includes("^date"))
+            examples.push("date");
+        if (pattern.includes("^echo"))
+            examples.push("echo 'hello world'");
+        if (pattern.includes("^docker ps"))
+            examples.push("docker ps -a");
+        if (pattern.includes("^docker logs"))
+            examples.push("docker logs --tail 50 <container>");
+        if (pattern.includes("^git"))
+            examples.push("git status");
+        if (pattern.includes("^head"))
+            examples.push("head -n 20 <file>");
+        if (pattern.includes("^tail"))
+            examples.push("tail -n 50 <file>");
+        if (pattern.includes("^grep"))
+            examples.push("grep 'pattern' <file>");
+        if (pattern.includes("^find"))
+            examples.push("find . -name '*.log'");
+        if (pattern.includes("^df"))
+            examples.push("df -h");
+        if (pattern.includes("^du"))
+            examples.push("du -sh *");
+        if (pattern.includes("^ps"))
+            examples.push("ps aux");
+        if (pattern.includes("^uptime"))
+            examples.push("uptime");
+        if (pattern.includes("^free"))
+            examples.push("free -h");
+        if (pattern.includes("^curl"))
+            examples.push("curl -s https://example.com");
+        if (pattern.includes("systemctl status"))
+            examples.push("systemctl status <service>");
+    }
+    return [...new Set(examples)];
+}

package/build/tools/transfer.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
+import { Logger } from "../utils/logger.js";
+import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
+/**
+ * Register unified file transfer tool
+ *
+ * Supports three modes:
+ *   upload   — push a local file or directory to a remote server
+ *   download — pull a remote file or directory to the MCP host
+ *   relay    — relay a file between two remote servers through the MCP host
+ */
+export function registerTransferTool(server) {
+    const sshManager = SSHConnectionManager.getInstance();
+    server.tool("transfer", `Transfer files between the MCP host and remote servers, or between two remote servers.
+
+Modes:
+  upload   — push a local file or directory to a remote server.
+  download — pull a remote file or directory to the MCP host.
+  relay    — stream a file from one remote server to another via SFTP piping.
+             No temp file touches the MCP host disk. No SCP or authorized-key
+             exchange between the two servers is needed — each side uses its
+             own existing SSH session.
+
+Set recursive=true when transferring a directory (upload/download only).
+For relay mode, specify sourceServer, sourceRemotePath, destServer, destRemotePath.`, {
+        mode: z.enum(["upload", "download", "relay"]).describe("'upload' pushes local → remote. 'download' pulls remote → local. 'relay' copies remote-A → remote-B through the MCP host."),
+        localPath: z.string().optional().describe("(upload/download only) Path on the MCP host. Must be inside the MCP working directory or one of the server's allowedLocalDirectories."),
+        remotePath: z.string().optional().describe("(upload/download only) Absolute POSIX path on the remote server. Must live inside one of the server's allowedRemoteDirectories — call show-whitelist to discover the allowed paths."),
+        connectionName: z.string().optional().describe("(upload/download only) Target server name from list-servers. Required when multiple servers are enabled."),
+        sourceServer: z.string().optional().describe("(relay only) Server name to download the file from."),
+        sourceRemotePath: z.string().optional().describe("(relay only) Absolute POSIX file path on the source server. Must live inside the source server's allowedRemoteDirectories."),
+        destServer: z.string().optional().describe("(relay only) Server name to upload the file to."),
+        destRemotePath: z.string().optional().describe("(relay only) Absolute POSIX destination path on the target server. Must live inside the destination server's allowedRemoteDirectories."),
+        recursive: z.boolean().optional().describe("(upload/download only) When true, transfers an entire directory tree recursively. Default false."),
+        skipIfIdentical: z.boolean().optional().describe("When true (default), skip the transfer if the destination already matches the source. " +
+            "Upload: byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts (.sh / .bash / .zsh) ignore CRLF\u2194LF differences. " +
+            "Relay: size match + md5sum match on both servers (when available); falls back to transferring if md5sum is missing on either side. " +
+            "Download is never skipped. Set to false to force the transfer."),
+    }, async (params) => {
+        try {
+            const { mode } = params;
+            if (mode === "relay") {
+                const { sourceServer, sourceRemotePath, destServer, destRemotePath, skipIfIdentical } = params;
+                if (!sourceServer || !sourceRemotePath || !destServer || !destRemotePath) {
+                    return {
+                        content: [{ type: "text", text: "relay mode requires: sourceServer, sourceRemotePath, destServer, destRemotePath" }],
+                        isError: true,
+                    };
+                }
+                const result = await sshManager.transferBetweenServers(sourceServer, sourceRemotePath, destServer, destRemotePath, { skipIfIdentical: skipIfIdentical !== false });
+                return { content: [{ type: "text", text: result }] };
+            }
+            // upload or download
+            const { localPath, remotePath, connectionName, recursive, skipIfIdentical } = params;
+            if (!localPath || !remotePath) {
+                return {
+                    content: [{ type: "text", text: `${mode} mode requires: localPath, remotePath` }],
+                    isError: true,
+                };
+            }
+            const resolvedName = sshManager.resolveServer(connectionName);
+            const uploadOptions = { skipIfIdentical: skipIfIdentical !== false };
+            if (recursive) {
+                let files;
+                if (mode === "upload") {
+                    files = await sshManager.uploadDirectory(localPath, remotePath, resolvedName, uploadOptions);
+                }
+                else {
+                    files = await sshManager.downloadDirectory(remotePath, localPath, resolvedName);
+                }
+                const summary = `Recursive ${mode} complete. ${files.length} file(s) transferred.`;
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ summary, files }) }],
+                };
+            }
+            // Single file
+            if (mode === "upload") {
+                const result = await sshManager.upload(localPath, remotePath, resolvedName, uploadOptions);
+                return { content: [{ type: "text", text: result }] };
+            }
+            else {
+                const result = await sshManager.download(remotePath, localPath, resolvedName);
+                return { content: [{ type: "text", text: result }] };
+            }
+        }
+        catch (error) {
+            const toolError = toToolError(error, "SFTP_ERROR");
+            Logger.handleError(toolError, "File transfer failed");
+            return {
+                content: [{ type: "text", text: formatToolErrorResponse(toolError) }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/tools/upload.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
+import { Logger } from "../utils/logger.js";
+import { formatToolErrorResponse, toToolError } from "../utils/tool-error.js";
+/**
+ * Register file upload tool
+ */
+export function registerUploadTool(server) {
+    const sshManager = SSHConnectionManager.getInstance();
+    server.tool("upload", "Upload a local file from the MCP host to the remote server over SFTP. Use this when the file already exists locally and must be copied to the selected SSH server. The remote destination must live inside one of the server's allowedRemoteDirectories; call show-whitelist to discover the allowed paths. " +
+        "Shell scripts (.sh / .bash / .zsh) with CRLF line endings are auto-converted to LF before upload (the response notes when this happens). " +
+        "By default the upload is skipped if the remote file is already identical to the local one (byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts are compared in a line-ending-agnostic way so CRLF\u2194LF differences alone do not trigger a re-upload) \u2014 pass skipIfIdentical=false to force a re-upload.", {
+        localPath: z.string().describe("Path to a local file on the MCP host. Must be inside the MCP working directory or one of the server's allowedLocalDirectories."),
+        remotePath: z.string().describe("Destination path on the remote server. Must be an absolute POSIX path inside one of the server's allowedRemoteDirectories (e.g. /home/user/uploads/file.txt)."),
+        connectionName: z.string().optional().describe("Target server name from list-servers. Required when multiple servers are enabled; optional when only one server is enabled."),
+        skipIfIdentical: z.boolean().optional().describe("When true (default), skip the upload if the remote file is already identical (byte-compare for files \u2264 256 MiB, MD5 otherwise; shell scripts ignore CRLF\u2194LF differences). Set to false to force re-upload."),
+    }, async ({ localPath, remotePath, connectionName, skipIfIdentical }) => {
+        try {
+            const resolvedName = sshManager.resolveServer(connectionName);
+            const result = await sshManager.upload(localPath, remotePath, resolvedName, {
+                skipIfIdentical: skipIfIdentical !== false,
+            });
+            return {
+                content: [{ type: "text", text: result }],
+            };
+        }
+        catch (error) {
+            const toolError = toToolError(error, "SFTP_ERROR");
+            Logger.handleError(toolError, "Failed to upload file");
+            return {
+                content: [{ type: "text", text: formatToolErrorResponse(toolError) }],
+                isError: true,
+            };
+        }
+    });
+}

package/build/utils/logger.js

@@ -0,0 +1,27 @@
+/**
+ * Logger class
+ */
+export class Logger {
+    /**
+     * Log a message
+     * Note: All logging goes to stderr to avoid interfering with MCP stdio protocol (which uses stdout)
+     */
+    static log(message, level = "info") {
+        const timestamp = new Date().toISOString();
+        const formattedMessage = `[${timestamp}] [${level.toUpperCase()}] ${message}`;
+        // Always write to stderr to avoid corrupting MCP protocol messages on stdout
+        process.stderr.write(formattedMessage + '\n');
+    }
+    /**
+     * Handle error
+     */
+    static handleError(error, prefix = "", exit = false) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const fullMessage = prefix ? `${prefix}: ${errorMessage}` : errorMessage;
+        Logger.log(fullMessage, "error");
+        if (exit) {
+            process.exit(1);
+        }
+        return fullMessage;
+    }
+}

package/build/utils/output-collector.js

@@ -0,0 +1,76 @@
+export class OutputCollector {
+    chunks = [];
+    bufferedBytes = 0;
+    totalBytes = 0;
+    droppedBytes = 0;
+    maxBytes;
+    constructor(maxBytes) {
+        if (!Number.isFinite(maxBytes) || maxBytes < 0) {
+            throw new Error(`OutputCollector: maxBytes must be a non-negative finite number, got ${maxBytes}`);
+        }
+        this.maxBytes = Math.floor(maxBytes);
+    }
+    /**
+     * Push a chunk of bytes into the collector. Accepts strings or Buffers.
+     * Strings are interpreted as UTF-8.
+     */
+    push(chunk) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+        if (buf.length === 0)
+            return;
+        this.totalBytes += buf.length;
+        if (this.maxBytes === 0) {
+            this.droppedBytes += buf.length;
+            return;
+        }
+        this.chunks.push(buf);
+        this.bufferedBytes += buf.length;
+        this.trim();
+    }
+    /**
+     * Trim chunks from the head until bufferedBytes <= maxBytes.
+     * The most recent chunk may need to be partially sliced.
+     */
+    trim() {
+        while (this.bufferedBytes > this.maxBytes && this.chunks.length > 0) {
+            const head = this.chunks[0];
+            const overshoot = this.bufferedBytes - this.maxBytes;
+            if (head.length <= overshoot) {
+                this.chunks.shift();
+                this.bufferedBytes -= head.length;
+                this.droppedBytes += head.length;
+            }
+            else {
+                this.chunks[0] = head.subarray(overshoot);
+                this.bufferedBytes -= overshoot;
+                this.droppedBytes += overshoot;
+            }
+        }
+    }
+    /**
+     * Get the current tail snapshot. The returned Buffer is a fresh copy.
+     */
+    getSnapshot() {
+        const tail = this.chunks.length === 0
+            ? Buffer.alloc(0)
+            : Buffer.concat(this.chunks, this.bufferedBytes);
+        return {
+            tail,
+            totalBytes: this.totalBytes,
+            droppedBytes: this.droppedBytes,
+            truncated: this.droppedBytes > 0,
+        };
+    }
+    getTotalBytes() {
+        return this.totalBytes;
+    }
+    getDroppedBytes() {
+        return this.droppedBytes;
+    }
+    isTruncated() {
+        return this.droppedBytes > 0;
+    }
+    getMaxBytes() {
+        return this.maxBytes;
+    }
+}