ssh-mcp2 1.5.0

package/README.md

@@ -0,0 +1,204 @@
+# SSH MCP Server
+
+[![NPM Version](https://img.shields.io/npm/v/ssh-mcp)](https://www.npmjs.com/package/ssh-mcp)
+[![Downloads](https://img.shields.io/npm/dm/ssh-mcp)](https://www.npmjs.com/package/ssh-mcp)
+[![Node Version](https://img.shields.io/node/v/ssh-mcp)](https://nodejs.org/)
+[![License](https://img.shields.io/github/license/tufantunc/ssh-mcp)](./LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/tufantunc/ssh-mcp?style=social)](https://github.com/tufantunc/ssh-mcp/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/tufantunc/ssh-mcp?style=social)](https://github.com/tufantunc/ssh-mcp/forks)
+[![Build Status](https://github.com/tufantunc/ssh-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/tufantunc/ssh-mcp/actions)
+[![GitHub issues](https://img.shields.io/github/issues/tufantunc/ssh-mcp)](https://github.com/tufantunc/ssh-mcp/issues)
+
+[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/tufantunc/ssh-mcp)](https://archestra.ai/mcp-catalog/tufantunc__ssh-mcp)
+
+**SSH MCP Server** is a local Model Context Protocol (MCP) server that exposes SSH control for Linux and Windows systems, enabling LLMs and other MCP clients to execute shell commands securely via SSH.
+
+## Contents
+
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Installation](#installation)
+- [Client Setup](#client-setup)
+- [Testing](#testing)
+- [Disclaimer](#disclaimer)
+- [Support](#support)
+
+## Quick Start
+
+- [Install](#installation) SSH MCP Server
+- [Configure](#configuration) SSH MCP Server
+- [Set up](#client-setup) your MCP Client (e.g. Claude Desktop, Cursor, etc)
+- Execute remote shell commands on your Linux or Windows server via natural language
+
+## Features
+
+- MCP-compliant server exposing SSH capabilities
+- Execute shell commands on remote Linux and Windows systems
+- Secure authentication via password or SSH key
+- Built with TypeScript and the official MCP SDK
+- **Configurable timeout protection** with automatic process abortion
+- **Graceful timeout handling** - attempts to kill hanging processes before closing connections
+
+### Tools
+
+- `exec`: Execute a shell command on the remote server
+  - **Parameters:**
+    - `command` (required): Shell command to execute on the remote SSH server
+    - `description` (optional): Optional description of what this command will do (appended as a comment)
+  - **Timeout Configuration:**
+
+- `sudo-exec`: Execute a shell command with sudo elevation
+  - **Parameters:**
+    - `command` (required): Shell command to execute as root using sudo
+    - `description` (optional): Optional description of what this command will do (appended as a comment)
+  - **Notes:**
+    - Requires `--sudoPassword` to be set for password-protected sudo
+    - Can be disabled by passing the `--disableSudo` flag at startup if sudo access is not needed or not available
+    - For persistent root access, consider using `--suPassword` instead which establishes a root shell
+    - Tool will not be available at all if server is started with `--disableSudo`
+  - **Timeout Configuration:**
+    - Timeout is configured via command line argument `--timeout` (in milliseconds)
+    - Default timeout: 60000ms (1 minute)
+    - When a command times out, the server automatically attempts to abort the running process before closing the connection
+  - **Max Command Length Configuration:**
+    - Max command characters are configured via `--maxChars`
+    - Default: `1000`
+    - No-limit mode: set `--maxChars=none` or any `<= 0` value (e.g. `--maxChars=0`)
+
+## Installation
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/tufantunc/ssh-mcp.git
+   cd ssh-mcp
+   ```
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+## Client Setup
+
+You can configure your IDE or LLM like Cursor, Windsurf, Claude Desktop to use this MCP Server.
+
+**Required Parameters:**
+- `host`: Hostname or IP of the Linux or Windows server
+- `user`: SSH username
+
+**Optional Parameters:**
+- `port`: SSH port (default: 22)
+- `password`: SSH password (or use `key` for key-based auth)
+- `key`: Path to private SSH key
+- `sudoPassword`: Password for sudo elevation (when executing commands with sudo)
+- `suPassword`: Password for su elevation (when you need a persistent root shell)
+- `timeout`: Command execution timeout in milliseconds (default: 60000ms = 1 minute)
+- `maxChars`: Maximum allowed characters for the `command` input (default: 1000). Use `none` or `0` to disable the limit.
+- `disableSudo`: Flag to disable the `sudo-exec` tool completely. Useful when sudo access is not needed or not available.
+
+
+```commandline
+{
+    "mcpServers": {
+        "ssh-mcp": {
+            "command": "npx",
+            "args": [
+                "ssh-mcp",
+                "-y",
+                "--",
+                "--host=1.2.3.4",
+                "--port=22",
+                "--user=root",
+                "--password=pass",
+                "--key=path/to/key",
+                "--timeout=30000",
+                "--maxChars=none"
+            ]
+        }
+    }
+}
+```
+
+### Claude Code
+
+You can add this MCP server to Claude Code using the `claude mcp add` command. This is the recommended method for Claude Code.
+
+**Basic Installation:**
+
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD
+```
+
+**Installation Examples:**
+
+**With Password Authentication:**
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=192.168.1.100 --port=22 --user=admin --password=your_password
+```
+
+**With SSH Key Authentication:**
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=example.com --user=root --key=/path/to/private/key
+```
+
+**With Custom Timeout and No Character Limit:**
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none
+```
+
+**With Sudo and Su Support:**
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y ssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --sudoPassword=sudo_pass --suPassword=root_pass
+```
+
+**Installation Scopes:**
+
+You can specify the scope when adding the server:
+
+- **Local scope** (default): For personal use in the current project
+  ```bash
+  claude mcp add --transport stdio ssh-mcp --scope local -- npx -y ssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD
+  ```
+
+- **Project scope**: Share with your team via `.mcp.json` file
+  ```bash
+  claude mcp add --transport stdio ssh-mcp --scope project -- npx -y ssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD
+  ```
+
+- **User scope**: Available across all your projects
+  ```bash
+  claude mcp add --transport stdio ssh-mcp --scope user -- npx -y ssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD
+  ```
+
+
+**Verify Installation:**
+
+After adding the server, restart Claude Code and ask Cascade to execute a command:
+```
+"Can you run 'ls -la' on the remote server?"
+```
+
+For more information about MCP in Claude Code, see the [official documentation](https://docs.claude.com/en/docs/claude-code/mcp).
+
+## Testing
+
+You can use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) for visual debugging of this MCP Server.
+
+```sh
+npm run inspect
+```
+
+## Disclaimer
+
+SSH MCP Server is provided under the [MIT License](./LICENSE). Use at your own risk. This project is not affiliated with or endorsed by any SSH or MCP provider.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](./CONTRIBUTING.md) for more information.
+
+## Code of Conduct
+
+This project follows a [Code of Conduct](./CODE_OF_CONDUCT.md) to ensure a welcoming environment for everyone.
+
+## Support
+
+If you find SSH MCP Server helpful, consider starring the repository or contributing! Pull requests and feedback are welcome. 

package/build/index.js

@@ -0,0 +1,812 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { Client } from 'ssh2';
+import { z } from 'zod';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { stat } from 'fs/promises';
+import path from 'path';
+// Example usage: node build/index.js --host=1.2.3.4 --port=22 --user=root --password=pass --key=path/to/key --timeout=5000 --disableSudo
+function parseArgv() {
+    const args = process.argv.slice(2);
+    const config = {};
+    for (const arg of args) {
+        if (arg.startsWith('--')) {
+            const equalIndex = arg.indexOf('=');
+            if (equalIndex === -1) {
+                // Flag without value
+                config[arg.slice(2)] = null;
+            }
+            else {
+                // Key=value pair
+                config[arg.slice(2, equalIndex)] = arg.slice(equalIndex + 1);
+            }
+        }
+    }
+    return config;
+}
+const isTestMode = process.env.SSH_MCP_TEST === '1';
+const isCliEnabled = process.env.SSH_MCP_DISABLE_MAIN !== '1';
+const argvConfig = (isCliEnabled || isTestMode) ? parseArgv() : {};
+const HOST = argvConfig.host;
+const PORT = argvConfig.port ? parseInt(argvConfig.port) : 22;
+const USER = argvConfig.user;
+const PASSWORD = argvConfig.password;
+const SUPASSWORD = argvConfig.suPassword;
+const SUDOPASSWORD = argvConfig.sudoPassword;
+const DISABLE_SUDO = argvConfig.disableSudo !== undefined;
+const KEY = argvConfig.key;
+const DEFAULT_TIMEOUT = argvConfig.timeout ? parseInt(argvConfig.timeout) : 60000; // 60 seconds default timeout
+// Max characters configuration:
+// - Default: 1000 characters
+// - When set via --maxChars:
+//   * a positive integer enforces that limit
+//   * 0 or a negative value disables the limit (no max)
+//   * the string "none" (case-insensitive) disables the limit (no max)
+const MAX_CHARS_RAW = argvConfig.maxChars;
+const MAX_CHARS = (() => {
+    if (typeof MAX_CHARS_RAW === 'string') {
+        const lowered = MAX_CHARS_RAW.toLowerCase();
+        if (lowered === 'none')
+            return Infinity;
+        const parsed = parseInt(MAX_CHARS_RAW);
+        if (isNaN(parsed))
+            return 1000;
+        if (parsed <= 0)
+            return Infinity;
+        return parsed;
+    }
+    return 1000;
+})();
+function validateConfig(config) {
+    const errors = [];
+    if (!config.host)
+        errors.push('Missing required --host');
+    if (!config.user)
+        errors.push('Missing required --user');
+    if (config.port && isNaN(Number(config.port)))
+        errors.push('Invalid --port');
+    if (errors.length > 0) {
+        throw new Error('Configuration error:\n' + errors.join('\n'));
+    }
+}
+if (isCliEnabled) {
+    validateConfig(argvConfig);
+}
+// Command sanitization and validation
+export function sanitizeCommand(command) {
+    if (typeof command !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'Command must be a string');
+    }
+    const trimmedCommand = command.trim();
+    if (!trimmedCommand) {
+        throw new McpError(ErrorCode.InvalidParams, 'Command cannot be empty');
+    }
+    // Length check
+    if (Number.isFinite(MAX_CHARS) && trimmedCommand.length > MAX_CHARS) {
+        throw new McpError(ErrorCode.InvalidParams, `Command is too long (max ${MAX_CHARS} characters)`);
+    }
+    return trimmedCommand;
+}
+function sanitizePassword(password) {
+    if (typeof password !== 'string')
+        return undefined;
+    // minimal check, do not log or modify content
+    if (password.length === 0)
+        return undefined;
+    return password;
+}
+// Escape command for use in shell contexts (like pkill)
+export function escapeCommandForShell(command) {
+    // Replace single quotes with escaped single quotes
+    return command.replace(/'/g, "'\"'\"'");
+}
+export class SSHConnectionManager {
+    conn = null;
+    sshConfig;
+    isConnecting = false;
+    connectionPromise = null;
+    suShell = null; // Store the elevated shell session
+    sftpSession = null;
+    suShellQueue = Promise.resolve();
+    suPromise = null;
+    isElevated = false; // Track if we're in su mode
+    constructor(config) {
+        this.sshConfig = config;
+    }
+    async connect() {
+        if (this.conn && this.isConnected()) {
+            return; // Already connected
+        }
+        if (this.isConnecting && this.connectionPromise) {
+            return this.connectionPromise; // Wait for ongoing connection
+        }
+        this.isConnecting = true;
+        this.connectionPromise = new Promise((resolve, reject) => {
+            this.conn = new Client();
+            const timeoutId = setTimeout(() => {
+                this.conn?.end();
+                this.conn = null;
+                this.isConnecting = false;
+                this.connectionPromise = null;
+                reject(new McpError(ErrorCode.InternalError, 'SSH connection timeout'));
+            }, 30000); // 30 seconds connection timeout
+            this.conn.on('ready', async () => {
+                clearTimeout(timeoutId);
+                this.isConnecting = false;
+                // In test mode, don't wait for su elevation during connection setup, as it
+                // may cause JSON-RPC server initialization to hang. Instead, elevation will
+                // be triggered on-demand when a command is executed.
+                // In production, elevation during connection is desirable for robustness.
+                if (this.sshConfig.suPassword && !process.env.SSH_MCP_TEST) {
+                    try {
+                        await this.ensureElevated();
+                    }
+                    catch (err) {
+                        // Do not reject the connection; just log the error. Subsequent commands
+                        // will either use the su shell if available or fall back to normal execution.
+                    }
+                }
+                resolve();
+            });
+            this.conn.on('error', (err) => {
+                clearTimeout(timeoutId);
+                this.conn = null;
+                this.isConnecting = false;
+                this.connectionPromise = null;
+                reject(new McpError(ErrorCode.InternalError, `SSH connection error: ${err.message}`));
+            });
+            this.conn.on('end', () => {
+                console.error('SSH connection ended');
+                this.conn = null;
+                this.isConnecting = false;
+                this.connectionPromise = null;
+            });
+            this.conn.on('close', () => {
+                console.error('SSH connection closed');
+                this.conn = null;
+                this.isConnecting = false;
+                this.connectionPromise = null;
+            });
+            this.conn.connect(this.sshConfig);
+        });
+        return this.connectionPromise;
+    }
+    isConnected() {
+        return this.conn !== null && this.conn._sock && !this.conn._sock.destroyed;
+    }
+    getSudoPassword() {
+        return this.sshConfig.sudoPassword;
+    }
+    getSuPassword() {
+        return this.sshConfig.suPassword;
+    }
+    async setSuPassword(pwd) {
+        this.sshConfig.suPassword = pwd;
+        if (pwd) {
+            try {
+                await this.ensureElevated();
+            }
+            catch (err) {
+                console.error('setSuPassword: failed to elevate to su shell:', err);
+            }
+        }
+        else {
+            // If clearing suPassword, drop any existing suShell
+            if (this.suShell) {
+                try {
+                    this.suShell.end();
+                }
+                catch (e) { /* ignore */ }
+                this.suShell = null;
+                this.isElevated = false;
+            }
+        }
+    }
+    async ensureElevated() {
+        if (this.isElevated && this.suShell)
+            return;
+        if (!this.sshConfig.suPassword)
+            return;
+        if (this.suPromise)
+            return this.suPromise;
+        this.suPromise = new Promise((resolve, reject) => {
+            const conn = this.getConnection();
+            // Add a safety timeout so elevation doesn't hang forever
+            const timeoutId = setTimeout(() => {
+                this.suPromise = null;
+                reject(new McpError(ErrorCode.InternalError, 'su elevation timed out'));
+            }, 10000); // 10 second timeout for elevation
+            conn.shell({ term: 'xterm', cols: 80, rows: 24 }, (err, stream) => {
+                if (err) {
+                    clearTimeout(timeoutId);
+                    this.suPromise = null;
+                    reject(new McpError(ErrorCode.InternalError, `Failed to start interactive shell for su: ${err.message}`));
+                    return;
+                }
+                let buffer = '';
+                let passwordSent = false;
+                const cleanup = () => {
+                    try {
+                        stream.removeAllListeners('data');
+                    }
+                    catch (e) { /* ignore */ }
+                };
+                const onData = (data) => {
+                    const text = data.toString();
+                    buffer += text;
+                    // If we haven't sent the password yet, look for the password prompt
+                    if (!passwordSent && /password[: ]/i.test(buffer)) {
+                        passwordSent = true;
+                        stream.write(this.sshConfig.suPassword + '\n');
+                        // Don't return; keep looking for root prompt
+                    }
+                    // After password is sent, look for any root indicator
+                    // Look for '#' which indicates root prompt (may be followed by spaces, escape codes, etc)
+                    if (passwordSent) {
+                        const cleanBuffer = buffer.replace(/\r/g, '').replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
+                        if (/]#\s*$/.test(cleanBuffer) || /\n#\s*$/.test(cleanBuffer) || /^#\s*$/.test(cleanBuffer)) {
+                            clearTimeout(timeoutId);
+                            cleanup();
+                            this.suShell = stream;
+                            this.isElevated = true;
+                            this.suPromise = null;
+                            resolve();
+                            return;
+                        }
+                    }
+                    // Detect authentication failure messages
+                    if (/authentication failure|incorrect password|su: .*failed|su: failure/i.test(buffer)) {
+                        clearTimeout(timeoutId);
+                        cleanup();
+                        this.suPromise = null;
+                        reject(new McpError(ErrorCode.InternalError, `su authentication failed: ${buffer}`));
+                        return;
+                    }
+                };
+                stream.on('data', onData);
+                stream.on('close', () => {
+                    clearTimeout(timeoutId);
+                    this.suShell = null;
+                    if (this.isElevated) {
+                        this.isElevated = false;
+                    }
+                    else {
+                        this.suPromise = null;
+                        reject(new McpError(ErrorCode.InternalError, 'su shell closed before elevation completed'));
+                    }
+                });
+                // Kick off the su command
+                stream.write('su -\n');
+            });
+        });
+        return this.suPromise;
+    }
+    async ensureConnected() {
+        if (!this.isConnected()) {
+            await this.connect();
+        }
+    }
+    getConnection() {
+        if (!this.conn) {
+            throw new McpError(ErrorCode.InternalError, 'SSH connection not established');
+        }
+        return this.conn;
+    }
+    async sftp() {
+        if (this.sftpSession) {
+            return this.sftpSession;
+        }
+        const conn = this.getConnection();
+        return new Promise((resolve, reject) => {
+            conn.sftp((err, sftp) => {
+                if (err)
+                    reject(new McpError(ErrorCode.InternalError, `SFTP error: ${err.message}`));
+                else {
+                    sftp.on('close', () => { this.sftpSession = null; });
+                    this.sftpSession = sftp;
+                    resolve(sftp);
+                }
+            });
+        });
+    }
+    close() {
+        if (this.sftpSession) {
+            try {
+                this.sftpSession.end();
+            }
+            catch (e) { /* ignore */ }
+            this.sftpSession = null;
+        }
+        if (this.conn) {
+            if (this.suShell) {
+                try {
+                    this.suShell.end();
+                }
+                catch (e) { /* ignore */ }
+                this.suShell = null;
+                this.isElevated = false;
+            }
+            this.conn.end();
+            this.conn = null;
+        }
+    }
+}
+let connectionManager = null;
+const server = new McpServer({
+    name: 'SSH MCP Server',
+    version: '1.5.0',
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+server.tool("exec", "Execute a shell command on the remote SSH server and return the output.", {
+    command: z.string().describe("Shell command to execute on the remote SSH server"),
+    description: z.string().optional().describe("Optional description of what this command will do"),
+}, async ({ command, description }) => {
+    // Sanitize command input
+    const sanitizedCommand = sanitizeCommand(command);
+    try {
+        // Initialize connection manager if not already done
+        if (!connectionManager) {
+            if (!HOST || !USER) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required host or username');
+            }
+            const sshConfig = {
+                host: HOST,
+                port: PORT,
+                username: USER,
+            };
+            if (PASSWORD) {
+                sshConfig.password = PASSWORD;
+            }
+            else if (KEY) {
+                const fs = await import('fs/promises');
+                sshConfig.privateKey = await fs.readFile(KEY, 'utf8');
+            }
+            if (SUPASSWORD !== null && SUPASSWORD !== undefined) {
+                sshConfig.suPassword = sanitizePassword(SUPASSWORD);
+            }
+            connectionManager = new SSHConnectionManager(sshConfig);
+        }
+        // Ensure connection is active (reconnect if needed)
+        await connectionManager.ensureConnected();
+        // If a suPassword was provided, explicitly wait for elevation before executing.
+        // This is critical: ensureElevated is idempotent and will return immediately if
+        // already elevated, so this ensures we have a su shell before we try to use it.
+        if (connectionManager.getSuPassword && connectionManager.getSuPassword()) {
+            try {
+                const elevationPromise = connectionManager.ensureElevated();
+                // Add a short timeout for elevation to complete
+                await Promise.race([
+                    elevationPromise,
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('Elevation timeout')), 5000))
+                ]);
+            }
+            catch (err) {
+                // Log but don't fail; fall back to non-elevated execution if elevation times out
+            }
+        }
+        // Append description as comment if provided
+        const commandWithDescription = description
+            ? `${sanitizedCommand} # ${description.replace(/#/g, '\\#')}`
+            : sanitizedCommand;
+        const result = await execSshCommandWithConnection(connectionManager, commandWithDescription);
+        return result;
+    }
+    catch (err) {
+        // Wrap unexpected errors
+        if (err instanceof McpError)
+            throw err;
+        throw new McpError(ErrorCode.InternalError, `Unexpected error: ${err?.message || err}`);
+    }
+});
+// Expose sudo-exec tool unless explicitly disabled
+if (!DISABLE_SUDO) {
+    server.tool("sudo-exec", "Execute a shell command on the remote SSH server using sudo. Will use sudo password if provided, otherwise assumes passwordless sudo.", {
+        command: z.string().describe("Shell command to execute with sudo on the remote SSH server"),
+        description: z.string().optional().describe("Optional description of what this command will do"),
+    }, async ({ command, description }) => {
+        const sanitizedCommand = sanitizeCommand(command);
+        try {
+            if (!connectionManager) {
+                if (!HOST || !USER) {
+                    throw new McpError(ErrorCode.InvalidParams, 'Missing required host or username');
+                }
+                const sshConfig = {
+                    host: HOST,
+                    port: PORT || 22,
+                    username: USER,
+                };
+                if (PASSWORD) {
+                    sshConfig.password = PASSWORD;
+                }
+                else if (KEY) {
+                    const fs = await import('fs/promises');
+                    sshConfig.privateKey = await fs.readFile(KEY, 'utf8');
+                }
+                if (SUPASSWORD !== null && SUPASSWORD !== undefined) {
+                    sshConfig.suPassword = sanitizePassword(SUPASSWORD);
+                }
+                if (SUDOPASSWORD !== null && SUDOPASSWORD !== undefined) {
+                    sshConfig.sudoPassword = sanitizePassword(SUDOPASSWORD);
+                }
+                connectionManager = new SSHConnectionManager(sshConfig);
+            }
+            await connectionManager.ensureConnected();
+            // If suPassword or sudoPassword were provided on this call but the
+            // existing connection manager was created earlier without them,
+            // update the manager's values so the subsequent sudo-exec call uses
+            // the latest passwords.
+            if (SUPASSWORD !== null && SUPASSWORD !== undefined) {
+                await connectionManager.setSuPassword(sanitizePassword(SUPASSWORD));
+            }
+            if (SUDOPASSWORD !== null && SUDOPASSWORD !== undefined) {
+                // update sudoPassword on the manager instance
+                connectionManager.sshConfig = { ...connectionManager.sshConfig, sudoPassword: sanitizePassword(SUDOPASSWORD) };
+            }
+            let wrapped;
+            const sudoPassword = connectionManager.getSudoPassword();
+            // Append description as comment if provided
+            const commandWithDescription = description
+                ? `${sanitizedCommand} # ${description.replace(/#/g, '\\#')}`
+                : sanitizedCommand;
+            if (!sudoPassword) {
+                // No password provided, use -n to fail if sudo requires a password
+                wrapped = `sudo -n sh -c '${commandWithDescription.replace(/'/g, "'\\''")}'`;
+            }
+            else {
+                // Password provided — pipe it into sudo using printf. This avoids complex
+                // PTY/stdin handling on the SSH channel and is simpler and more reliable.
+                const pwdEscaped = sudoPassword.replace(/'/g, "'\\''");
+                wrapped = `printf '%s\\n' '${pwdEscaped}' | sudo -p "" -S sh -c '${commandWithDescription.replace(/'/g, "'\\''")}'`;
+            }
+            return await execSshCommandWithConnection(connectionManager, wrapped);
+        }
+        catch (err) {
+            if (err instanceof McpError)
+                throw err;
+            throw new McpError(ErrorCode.InternalError, `Unexpected error: ${err?.message || err}`);
+        }
+    });
+}
+server.tool("upload_file", "Upload a local file to the remote server via SFTP.", {
+    localPath: z.string().describe("Absolute path to the local file"),
+    remotePath: z.string().describe("Destination path on the remote server"),
+    permissions: z.string().optional().describe("File permissions in octal, e.g. '0755'"),
+}, async ({ localPath, remotePath, permissions }) => {
+    try {
+        if (!path.isAbsolute(localPath)) {
+            throw new McpError(ErrorCode.InvalidParams, 'localPath must be an absolute path');
+        }
+        if (!path.isAbsolute(remotePath)) {
+            throw new McpError(ErrorCode.InvalidParams, 'remotePath must be an absolute path');
+        }
+        if (!connectionManager) {
+            if (!HOST || !USER) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required host or username');
+            }
+            const sshConfig = { host: HOST, port: PORT, username: USER };
+            if (PASSWORD) {
+                sshConfig.password = PASSWORD;
+            }
+            else if (KEY) {
+                const fs = await import('fs/promises');
+                sshConfig.privateKey = await fs.readFile(KEY, 'utf8');
+            }
+            if (SUPASSWORD !== null && SUPASSWORD !== undefined) {
+                sshConfig.suPassword = sanitizePassword(SUPASSWORD);
+            }
+            if (SUDOPASSWORD !== null && SUDOPASSWORD !== undefined) {
+                sshConfig.sudoPassword = sanitizePassword(SUDOPASSWORD);
+            }
+            connectionManager = new SSHConnectionManager(sshConfig);
+        }
+        await connectionManager.ensureConnected();
+        const sftp = await connectionManager.sftp();
+        const fileStat = await stat(localPath);
+        await new Promise((resolve, reject) => {
+            sftp.fastPut(localPath, remotePath, {
+                mode: permissions ? parseInt(permissions, 8) : undefined,
+            }, (err) => {
+                if (err)
+                    reject(new McpError(ErrorCode.InternalError, `Upload failed: ${err.message}`));
+                else
+                    resolve();
+            });
+        });
+        return {
+            content: [{ type: "text", text: `Uploaded ${localPath} → ${remotePath} (${fileStat.size} bytes)` }],
+        };
+    }
+    catch (err) {
+        if (err instanceof McpError)
+            throw err;
+        throw new McpError(ErrorCode.InternalError, `Unexpected error: ${err?.message || err}`);
+    }
+});
+server.tool("download_file", "Download a file from the remote server to local via SFTP.", {
+    remotePath: z.string().describe("Path to the file on the remote server"),
+    localPath: z.string().describe("Absolute destination path on the local machine"),
+}, async ({ remotePath, localPath }) => {
+    try {
+        if (!path.isAbsolute(remotePath)) {
+            throw new McpError(ErrorCode.InvalidParams, 'remotePath must be an absolute path');
+        }
+        if (!path.isAbsolute(localPath)) {
+            throw new McpError(ErrorCode.InvalidParams, 'localPath must be an absolute path');
+        }
+        if (!connectionManager) {
+            if (!HOST || !USER) {
+                throw new McpError(ErrorCode.InvalidParams, 'Missing required host or username');
+            }
+            const sshConfig = { host: HOST, port: PORT, username: USER };
+            if (PASSWORD) {
+                sshConfig.password = PASSWORD;
+            }
+            else if (KEY) {
+                const fs = await import('fs/promises');
+                sshConfig.privateKey = await fs.readFile(KEY, 'utf8');
+            }
+            if (SUPASSWORD !== null && SUPASSWORD !== undefined) {
+                sshConfig.suPassword = sanitizePassword(SUPASSWORD);
+            }
+            if (SUDOPASSWORD !== null && SUDOPASSWORD !== undefined) {
+                sshConfig.sudoPassword = sanitizePassword(SUDOPASSWORD);
+            }
+            connectionManager = new SSHConnectionManager(sshConfig);
+        }
+        await connectionManager.ensureConnected();
+        const sftp = await connectionManager.sftp();
+        await new Promise((resolve, reject) => {
+            sftp.fastGet(remotePath, localPath, (err) => {
+                if (err)
+                    reject(new McpError(ErrorCode.InternalError, `Download failed: ${err.message}`));
+                else
+                    resolve();
+            });
+        });
+        return {
+            content: [{ type: "text", text: `Downloaded ${remotePath} → ${localPath}` }],
+        };
+    }
+    catch (err) {
+        if (err instanceof McpError)
+            throw err;
+        throw new McpError(ErrorCode.InternalError, `Unexpected error: ${err?.message || err}`);
+    }
+});
+// New function that uses persistent connection
+export async function execSshCommandWithConnection(manager, command, stdin) {
+    const conn = manager.getConnection();
+    const shell = manager.suShell; // Use su shell if available
+    // If we have an active su shell, use it directly (commands run as root in session)
+    // Serialize through a queue to prevent concurrent-write corruption
+    if (shell) {
+        const result = manager.suShellQueue.then(() => {
+            return new Promise((resolve, reject) => {
+                let buffer = '';
+                let isResolved = false;
+                const timeoutId = setTimeout(() => {
+                    if (!isResolved) {
+                        isResolved = true;
+                        shell.removeListener('data', dataHandler);
+                        reject(new McpError(ErrorCode.InternalError, `Command execution timed out after ${DEFAULT_TIMEOUT}ms`));
+                    }
+                }, DEFAULT_TIMEOUT);
+                const dataHandler = (data) => {
+                    buffer += data.toString();
+                    // Strip \r and ANSI escape codes, then check for root prompt #
+                    const cleanBuffer = buffer.replace(/\r/g, '').replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
+                    if (/\n#\s*$/.test(cleanBuffer) || /^#\s*$/.test(cleanBuffer)) {
+                        if (!isResolved) {
+                            isResolved = true;
+                            clearTimeout(timeoutId);
+                            shell.removeListener('data', dataHandler);
+                            // Extract output: strip trailing # prompt and optional echoed command line
+                            let output = cleanBuffer.replace(/\n#\s*$/, '');
+                            const lines = output.split('\n');
+                            if (lines.length > 0 && lines[0].trim() === command.trim()) {
+                                lines.shift();
+                            }
+                            output = lines.join('\n').trimEnd();
+                            resolve({
+                                content: [{ type: 'text', text: output + (output ? '\n' : '') }],
+                            });
+                        }
+                    }
+                };
+                shell.on('data', dataHandler);
+                shell.write(command + '\n');
+            });
+        });
+        manager.suShellQueue = result.then(() => { }, () => { });
+        return await result;
+    }
+    // No persistent su shell; use normal exec with optional password piping
+    return new Promise((resolve, reject) => {
+        let timeoutId;
+        let isResolved = false;
+        timeoutId = setTimeout(() => {
+            if (!isResolved) {
+                isResolved = true;
+                reject(new McpError(ErrorCode.InternalError, `Command execution timed out after ${DEFAULT_TIMEOUT}ms`));
+            }
+        }, DEFAULT_TIMEOUT);
+        conn.exec(command, (err, stream) => {
+            if (err) {
+                if (!isResolved) {
+                    isResolved = true;
+                    clearTimeout(timeoutId);
+                    reject(new McpError(ErrorCode.InternalError, `SSH exec error: ${err.message}`));
+                }
+                return;
+            }
+            let stdout = '';
+            let stderr = '';
+            if (stdin && stdin.length > 0) {
+                try {
+                    stream.write(stdin);
+                }
+                catch (e) { /* ignore */ }
+            }
+            try {
+                stream.end();
+            }
+            catch (e) { /* ignore */ }
+            stream.on('data', (data) => {
+                stdout += data.toString();
+            });
+            stream.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            stream.on('close', (code, signal) => {
+                if (!isResolved) {
+                    isResolved = true;
+                    clearTimeout(timeoutId);
+                    if (stderr) {
+                        reject(new McpError(ErrorCode.InternalError, `Error (code ${code}):\n${stderr}`));
+                    }
+                    else {
+                        resolve({
+                            content: [{ type: 'text', text: stdout }],
+                        });
+                    }
+                }
+            });
+        });
+    });
+}
+// Keep the old function for backward compatibility (used in tests)
+export async function execSshCommand(sshConfig, command, stdin) {
+    return new Promise((resolve, reject) => {
+        const conn = new Client();
+        let timeoutId;
+        let isResolved = false;
+        // Set up timeout
+        timeoutId = setTimeout(() => {
+            if (!isResolved) {
+                isResolved = true;
+                // Try to abort the running command before closing connection
+                const abortTimeout = setTimeout(() => {
+                    // If abort command itself times out, force close connection
+                    conn.end();
+                }, 5000); // 5 second timeout for abort command
+                conn.exec('timeout 3s pkill -f \'' + escapeCommandForShell(command) + '\' 2>/dev/null || true', (err, abortStream) => {
+                    if (abortStream) {
+                        abortStream.on('close', () => {
+                            clearTimeout(abortTimeout);
+                            conn.end();
+                        });
+                    }
+                    else {
+                        clearTimeout(abortTimeout);
+                        conn.end();
+                    }
+                });
+                reject(new McpError(ErrorCode.InternalError, `Command execution timed out after ${DEFAULT_TIMEOUT}ms`));
+            }
+        }, DEFAULT_TIMEOUT);
+        conn.on('ready', () => {
+            conn.exec(command, (err, stream) => {
+                if (err) {
+                    if (!isResolved) {
+                        isResolved = true;
+                        clearTimeout(timeoutId);
+                        reject(new McpError(ErrorCode.InternalError, `SSH exec error: ${err.message}`));
+                    }
+                    conn.end();
+                    return;
+                }
+                // If stdin provided, write it to the stream and end stdin
+                if (stdin && stdin.length > 0) {
+                    try {
+                        stream.write(stdin);
+                    }
+                    catch (e) {
+                        // ignore
+                    }
+                }
+                try {
+                    stream.end();
+                }
+                catch (e) { /* ignore */ }
+                let stdout = '';
+                let stderr = '';
+                stream.on('close', (code, signal) => {
+                    if (!isResolved) {
+                        isResolved = true;
+                        clearTimeout(timeoutId);
+                        conn.end();
+                        if (stderr) {
+                            reject(new McpError(ErrorCode.InternalError, `Error (code ${code}):\n${stderr}`));
+                        }
+                        else {
+                            resolve({
+                                content: [{
+                                        type: 'text',
+                                        text: stdout,
+                                    }],
+                            });
+                        }
+                    }
+                });
+                stream.on('data', (data) => {
+                    stdout += data.toString();
+                });
+                stream.stderr.on('data', (data) => {
+                    stderr += data.toString();
+                });
+            });
+        });
+        conn.on('error', (err) => {
+            if (!isResolved) {
+                isResolved = true;
+                clearTimeout(timeoutId);
+                reject(new McpError(ErrorCode.InternalError, `SSH connection error: ${err.message}`));
+            }
+        });
+        conn.connect(sshConfig);
+    });
+}
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("SSH MCP Server running on stdio");
+    // Handle graceful shutdown
+    const cleanup = () => {
+        console.error("Shutting down SSH MCP Server...");
+        if (connectionManager) {
+            connectionManager.close();
+            connectionManager = null;
+        }
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    process.on('exit', () => {
+        if (connectionManager) {
+            connectionManager.close();
+        }
+    });
+}
+// Initialize server in test mode for automated tests
+if (isTestMode) {
+    const transport = new StdioServerTransport();
+    server.connect(transport).catch(error => {
+        console.error("Fatal error connecting server:", error);
+        process.exit(1);
+    });
+}
+// Start server in CLI mode
+else if (isCliEnabled) {
+    main().catch((error) => {
+        console.error("Fatal error in main():", error);
+        if (connectionManager) {
+            connectionManager.close();
+        }
+        process.exit(1);
+    });
+}
+export { parseArgv, validateConfig };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "ssh-mcp2",
+  "license": "MIT",
+  "version": "1.5.0",
+  "description": "MCP server exposing SSH control for Linux and Windows systems via Model Context Protocol.",
+  "type": "module",
+  "bin": {
+    "ssh-mcp": "build/index.js"
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc && shx chmod +x build/*.js",
+    "inspect": "npx @modelcontextprotocol/inspector node build/index.js",
+    "test": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run",
+    "test:watch": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest",
+    "coverage": "cross-env SSH_MCP_DISABLE_MAIN=1 vitest --run --coverage"
+  },
+  "files": [
+    "build"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "ssh2": "^1.17.0",
+    "zod": "3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "@types/ssh2": "^1.15.5",
+    "cross-env": "^7.0.3",
+    "shx": "^0.4.0",
+    "testcontainers": "^11.7.0",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "homepage": "https://github.com/xxd-169/ssh-mcp2#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xxd-169/ssh-mcp2.git"
+  },
+  "bugs": {
+    "url": "https://github.com/xxd-169/ssh-mcp2/issues"
+  },
+  "keywords": [
+    "ssh",
+    "mcp",
+    "model-context-protocol",
+    "server",
+    "windows",
+    "linux",
+    "automation",
+    "remote",
+    "cli",
+    "typescript"
+  ],
+  "author": "rock169",
+  "engines": {
+    "node": ">=18"
+  }
+}