@xiaoyankonling/ssh-mcp 2.0.0 → 2.1.0

package/LICENSE

@@ -1,6 +1,7 @@
-MIT License
-
-Copyright (c) 2025 Tufan Tunç
+MIT License
+
+Copyright (c) 2025 Tufan Tunç
+Copyright (c) 2026 xiaoyankonling
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -36,7 +36,7 @@
 - Execute shell commands on remote Linux and Windows systems
 - Secure authentication via password or SSH key
 - Local profile configuration via YAML/JSON files
-- Runtime profile management tools (`profiles-list/use/reload/note-update`)
+- Runtime profile management tools (`profiles-list/find/use/reload/note-update/profiles-test`)
 - Profile notes/tags for operational context
 - Built with TypeScript and the official MCP SDK
 - **Configurable timeout protection** with automatic process abortion
@@ -44,16 +44,18 @@
 
 ### 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:**
+- `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)
+    - `timeoutMs` (optional): Per-command timeout override in milliseconds
+  - **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)
+  - **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)
+    - `timeoutMs` (optional): Per-command timeout override in milliseconds
   - **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
@@ -70,6 +72,7 @@
 
 - `profiles-list`: List profile summaries (`id/name/host/port/note/tags/active`) with sensitive fields masked
 - `profiles-find`: Find profile candidates by keyword across `id/name/host/user/note/tags`
+- `profiles-test`: Test TCP connectivity, SSH handshake, and authentication for a profile
 - `profiles-use`: Switch active profile at runtime, persist `activeProfile`, and recreate SSH connection on next command
 - `profiles-reload`: Reload profile configuration from disk and validate active profile still exists
 - `profiles-create`: Create profile templates dynamically at runtime (note optional but recommended)
@@ -157,7 +160,9 @@ Notes:
    - by default, created profile is activated immediately
 2. Keep note short and precise:
    - if `note` is omitted, tool can derive a concise note from `contextSummary`
-3. Safe deletion (two-step):
+3. Validate target quickly:
+   - call `profiles-test` to verify TCP/SSH/auth before executing commands
+4. Safe deletion (two-step):
    - call `profiles-delete-prepare` first
    - review returned profile + backup path + confirmation text with user
    - only then call `profiles-delete-confirm`

package/build/index.js

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
-import { readFile } from 'fs/promises';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { determineStartupMode, parseArgv, resolveRuntimeOptions, } from './cli/args.js';
-import { resolveKeyPath } from './config/loader.js';
 import { ProfileManager } from './profile/profile-manager.js';
-import { DEFAULT_MAX_CHARS, DEFAULT_TIMEOUT_MS, sanitizeCommand, sanitizePassword, } from './ssh/command-utils.js';
+import { DEFAULT_MAX_CHARS, DEFAULT_TIMEOUT_MS, sanitizeCommand, } from './ssh/command-utils.js';
 import { SSHConnectionManager, execSshCommand, execSshCommandWithConnection, } from './ssh/connection-manager.js';
+import { buildSshConfigFromProfile } from './ssh/ssh-config.js';
 import { registerExecTool } from './tools/exec.js';
 import { registerProfileTools } from './tools/profiles.js';
 import { registerSudoExecTool } from './tools/sudo-exec.js';
@@ -17,7 +16,7 @@ const shouldBootServer = isCliEnabled || isTestMode;
 const argvConfig = shouldBootServer ? parseArgv() : {};
 const server = new McpServer({
     name: 'SSH MCP Server',
-    version: '1.5.0',
+    version: '2.0.0',
     capabilities: {
         resources: {},
         tools: {},
@@ -48,25 +47,7 @@ async function buildSshConfig(mode) {
         throw new McpError(ErrorCode.InternalError, 'Profile mode not initialized');
     }
     const profile = profileManager.getActiveProfile();
-    const sshConfig = {
-        host: profile.host,
-        port: profile.port,
-        username: profile.user,
-    };
-    if (profile.auth.type === 'password') {
-        sshConfig.password = sanitizePassword(profile.auth.password);
-    }
-    else {
-        const keyPath = resolveKeyPath(profile.auth.keyPath, profileManager.getConfigPath());
-        sshConfig.privateKey = await readFile(keyPath, 'utf8');
-    }
-    if (profile.suPassword !== undefined) {
-        sshConfig.suPassword = sanitizePassword(profile.suPassword);
-    }
-    if (profile.sudoPassword !== undefined) {
-        sshConfig.sudoPassword = sanitizePassword(profile.sudoPassword);
-    }
-    return sshConfig;
+    return buildSshConfigFromProfile(profile, profileManager.getConfigPath());
 }
 async function getConnectionManager() {
     if (!startupMode) {

package/build/profile/profile-manager.js

@@ -125,6 +125,9 @@ export class ProfileManager {
         }
         return profile;
     }
+    getProfileById(profileId) {
+        return this.getProfile(profileId);
+    }
     getDefaults() {
         const loaded = this.ensureLoaded();
         return loaded.config.defaults ?? {};

package/build/ssh/connection-manager.js

@@ -1,6 +1,44 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { Client } from 'ssh2';
+import net from 'net';
 import { DEFAULT_TIMEOUT_MS, escapeCommandForShell } from './command-utils.js';
+const DEFAULT_CONNECT_RETRY_DELAYS_MS = [200, 400];
+const DEFAULT_TEST_TIMEOUT_MS = 10000;
+const MAX_TEST_RETRIES = 5;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function toErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function isAuthFailure(err) {
+    const message = toErrorMessage(err).toLowerCase();
+    return message.includes('authentication') ||
+        message.includes('permission denied') ||
+        message.includes('all configured authentication methods failed') ||
+        message.includes('auth failed');
+}
+function isRetryableConnectionError(err) {
+    if (isAuthFailure(err))
+        return false;
+    const message = toErrorMessage(err).toLowerCase();
+    const code = err?.code;
+    if (code && ['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'ETIMEDOUT'].includes(code)) {
+        return true;
+    }
+    return message.includes('handshake') ||
+        message.includes('kex') ||
+        message.includes('timeout') ||
+        message.includes('timed out') ||
+        message.includes('connection closed') ||
+        message.includes('protocol');
+}
+export function formatTargetContext(config) {
+    const profileId = config.profileId ? config.profileId : 'unknown';
+    return `profileId=${profileId} host=${config.host} port=${config.port}`;
+}
 export class SSHConnectionManager {
     conn = null;
     sshConfig;
@@ -20,19 +58,48 @@ export class SSHConnectionManager {
             return this.connectionPromise;
         }
         this.isConnecting = true;
-        this.connectionPromise = new Promise((resolve, reject) => {
-            this.conn = new Client();
+        this.connectionPromise = this.connectWithRetry()
+            .finally(() => {
+            this.isConnecting = false;
+            this.connectionPromise = null;
+        });
+        return this.connectionPromise;
+    }
+    async connectWithRetry() {
+        let lastError;
+        for (let attempt = 0; attempt <= DEFAULT_CONNECT_RETRY_DELAYS_MS.length; attempt += 1) {
+            try {
+                await this.connectOnce();
+                return;
+            }
+            catch (err) {
+                lastError = err;
+                if (!isRetryableConnectionError(err) || attempt === DEFAULT_CONNECT_RETRY_DELAYS_MS.length) {
+                    throw this.wrapConnectionError(err);
+                }
+                await sleep(DEFAULT_CONNECT_RETRY_DELAYS_MS[attempt]);
+            }
+        }
+        throw this.wrapConnectionError(lastError);
+    }
+    getConnectConfig() {
+        const { profileId, ...config } = this.sshConfig;
+        return config;
+    }
+    async connectOnce() {
+        return new Promise((resolve, reject) => {
+            const client = new Client();
+            this.conn = client;
             const timeoutId = setTimeout(() => {
-                this.conn?.end();
-                this.conn = null;
-                this.isConnecting = false;
-                this.connectionPromise = null;
-                reject(new McpError(ErrorCode.InternalError, 'SSH connection timeout'));
+                client.end();
+                if (this.conn === client) {
+                    this.conn = null;
+                }
+                const timeoutError = Object.assign(new Error('SSH connection timeout'), { code: 'ETIMEDOUT' });
+                reject(timeoutError);
             }, 30000);
-            this.conn.on('ready', async () => {
+            client.on('ready', async () => {
                 clearTimeout(timeoutId);
-                this.isConnecting = false;
-                this.connectionPromise = null;
                 if (this.sshConfig.suPassword && !process.env.SSH_MCP_TEST) {
                     try {
                         await this.ensureElevated();
@@ -43,26 +110,30 @@ export class SSHConnectionManager {
                 }
                 resolve();
             });
-            this.conn.on('error', (err) => {
+            client.on('error', (err) => {
                 clearTimeout(timeoutId);
-                this.conn = null;
-                this.isConnecting = false;
-                this.connectionPromise = null;
-                reject(new McpError(ErrorCode.InternalError, `SSH connection error: ${err.message}`));
+                if (this.conn === client) {
+                    this.conn = null;
+                }
+                reject(err);
             });
-            this.conn.on('end', () => {
-                this.conn = null;
-                this.isConnecting = false;
-                this.connectionPromise = null;
+            client.on('end', () => {
+                if (this.conn === client) {
+                    this.conn = null;
+                }
             });
-            this.conn.on('close', () => {
-                this.conn = null;
-                this.isConnecting = false;
-                this.connectionPromise = null;
+            client.on('close', () => {
+                if (this.conn === client) {
+                    this.conn = null;
+                }
             });
-            this.conn.connect(this.sshConfig);
+            client.connect(this.getConnectConfig());
         });
-        return this.connectionPromise;
+    }
+    wrapConnectionError(err, targetOverride) {
+        const target = targetOverride ?? this.getTargetContext();
+        const message = toErrorMessage(err);
+        return new McpError(ErrorCode.InternalError, `SSH connection error (${target}): ${message}`);
     }
     isConnected() {
         return this.conn !== null && Boolean(this.conn._sock) && !this.conn._sock.destroyed;
@@ -105,17 +176,18 @@ export class SSHConnectionManager {
             return;
         if (this.suPromise)
             return this.suPromise;
+        const target = this.getTargetContext();
         this.suPromise = new Promise((resolve, reject) => {
             const conn = this.getConnection();
             const timeoutId = setTimeout(() => {
                 this.suPromise = null;
-                reject(new McpError(ErrorCode.InternalError, 'su elevation timed out'));
+                reject(new McpError(ErrorCode.InternalError, `su elevation timed out (${target})`));
             }, 10000);
             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}`));
+                    reject(new McpError(ErrorCode.InternalError, `Failed to start interactive shell for su (${target}): ${err.message}`));
                     return;
                 }
                 let buffer = '';
@@ -148,7 +220,7 @@ export class SSHConnectionManager {
                         clearTimeout(timeoutId);
                         cleanup();
                         this.suPromise = null;
-                        reject(new McpError(ErrorCode.InternalError, 'su authentication failed'));
+                        reject(new McpError(ErrorCode.InternalError, `su authentication failed (${target})`));
                     }
                 };
                 stream.on('data', onData);
@@ -156,7 +228,7 @@ export class SSHConnectionManager {
                     clearTimeout(timeoutId);
                     if (!this.isElevated) {
                         this.suPromise = null;
-                        reject(new McpError(ErrorCode.InternalError, 'su shell closed before elevation completed'));
+                        reject(new McpError(ErrorCode.InternalError, `su shell closed before elevation completed (${target})`));
                     }
                 });
                 stream.write('su -\n');
@@ -171,10 +243,13 @@ export class SSHConnectionManager {
     }
     getConnection() {
         if (!this.conn) {
-            throw new McpError(ErrorCode.InternalError, 'SSH connection not established');
+            throw new McpError(ErrorCode.InternalError, `SSH connection not established (${this.getTargetContext()})`);
         }
         return this.conn;
     }
+    getTargetContext() {
+        return formatTargetContext(this.sshConfig);
+    }
     getSuShell() {
         return this.suShell;
     }
@@ -199,12 +274,13 @@ export async function execSshCommandWithConnection(manager, command, timeoutMs =
     return new Promise((resolve, reject) => {
         let timeoutId;
         let isResolved = false;
+        const target = manager.getTargetContext();
         const conn = manager.getConnection();
         const shell = manager.getSuShell();
         timeoutId = setTimeout(() => {
             if (!isResolved) {
                 isResolved = true;
-                reject(new McpError(ErrorCode.InternalError, `Command execution timed out after ${timeoutMs}ms`));
+                reject(new McpError(ErrorCode.InternalError, `Command execution timed out after ${timeoutMs}ms (${target})`));
             }
         }, timeoutMs);
         if (shell) {
@@ -237,7 +313,7 @@ export async function execSshCommandWithConnection(manager, command, timeoutMs =
                 if (!isResolved) {
                     isResolved = true;
                     clearTimeout(timeoutId);
-                    reject(new McpError(ErrorCode.InternalError, `SSH exec error: ${err.message}`));
+                    reject(new McpError(ErrorCode.InternalError, `SSH exec error (${target}): ${err.message}`));
                 }
                 return;
             }
@@ -269,7 +345,7 @@ export async function execSshCommandWithConnection(manager, command, timeoutMs =
                 isResolved = true;
                 clearTimeout(timeoutId);
                 if (stderr) {
-                    reject(new McpError(ErrorCode.InternalError, `Error (code ${code}):\n${stderr}`));
+                    reject(new McpError(ErrorCode.InternalError, `Error (code ${code}) (${target}):\n${stderr}`));
                     return;
                 }
                 resolve({
@@ -287,6 +363,7 @@ export async function execSshCommand(sshConfig, command, stdin, timeoutMs = DEFA
         const conn = new Client();
         let timeoutId;
         let isResolved = false;
+        const target = formatTargetContext(sshConfig);
         timeoutId = setTimeout(() => {
             if (isResolved)
                 return;
@@ -305,7 +382,7 @@ export async function execSshCommand(sshConfig, command, stdin, timeoutMs = DEFA
                 clearTimeout(abortTimeout);
                 conn.end();
             });
-            reject(new McpError(ErrorCode.InternalError, `Command execution timed out after ${timeoutMs}ms`));
+            reject(new McpError(ErrorCode.InternalError, `Command execution timed out after ${timeoutMs}ms (${target})`));
         }, timeoutMs);
         conn.on('ready', () => {
             conn.exec(command, (err, stream) => {
@@ -313,7 +390,7 @@ export async function execSshCommand(sshConfig, command, stdin, timeoutMs = DEFA
                     if (!isResolved) {
                         isResolved = true;
                         clearTimeout(timeoutId);
-                        reject(new McpError(ErrorCode.InternalError, `SSH exec error: ${err.message}`));
+                        reject(new McpError(ErrorCode.InternalError, `SSH exec error (${target}): ${err.message}`));
                     }
                     conn.end();
                     return;
@@ -341,7 +418,7 @@ export async function execSshCommand(sshConfig, command, stdin, timeoutMs = DEFA
                     clearTimeout(timeoutId);
                     conn.end();
                     if (stderr) {
-                        reject(new McpError(ErrorCode.InternalError, `Error (code ${code}):\n${stderr}`));
+                        reject(new McpError(ErrorCode.InternalError, `Error (code ${code}) (${target}):\n${stderr}`));
                         return;
                     }
                     resolve({
@@ -366,6 +443,173 @@ export async function execSshCommand(sshConfig, command, stdin, timeoutMs = DEFA
             clearTimeout(timeoutId);
             reject(new McpError(ErrorCode.InternalError, `SSH connection error: ${err.message}`));
         });
-        conn.connect(sshConfig);
+        const { profileId, ...connectConfig } = sshConfig;
+        conn.connect(connectConfig);
+    });
+}
+function normalizeRetries(retries) {
+    if (retries === undefined || retries === null)
+        return 2;
+    if (!Number.isFinite(retries))
+        return 2;
+    const value = Math.max(0, Math.min(MAX_TEST_RETRIES, Math.floor(retries)));
+    return value;
+}
+async function testTcpConnection(host, port, timeoutMs) {
+    const start = Date.now();
+    return new Promise((resolve) => {
+        const socket = net.createConnection({ host, port });
+        let settled = false;
+        const finish = (ok, error) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                socket.destroy();
+            }
+            catch {
+                // no-op
+            }
+            resolve({
+                ok,
+                durationMs: Date.now() - start,
+                ...(error ? { error } : {}),
+            });
+        };
+        socket.setTimeout(timeoutMs, () => {
+            finish(false, 'TCP connection timeout');
+        });
+        socket.once('error', (err) => {
+            finish(false, err.message);
+        });
+        socket.once('connect', () => {
+            finish(true);
+        });
     });
 }
+async function testSshHandshakeAndAuth(sshConfig, timeoutMs) {
+    const start = Date.now();
+    return new Promise((resolve) => {
+        const client = new Client();
+        let settled = false;
+        let handshakeOk = false;
+        let authOk = false;
+        let handshakeDuration = 0;
+        let authDuration = 0;
+        let errorMessage;
+        let retryable = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                client.end();
+            }
+            catch {
+                // no-op
+            }
+            resolve({
+                handshake: {
+                    ok: handshakeOk,
+                    durationMs: handshakeDuration || Date.now() - start,
+                    ...(handshakeOk ? {} : { error: errorMessage ?? 'Handshake failed' }),
+                },
+                auth: {
+                    ok: authOk,
+                    durationMs: authDuration || Date.now() - start,
+                    ...(authOk ? {} : { error: errorMessage ?? 'Authentication failed' }),
+                },
+                retryable,
+            });
+        };
+        const timeoutId = setTimeout(() => {
+            errorMessage = 'SSH handshake timeout';
+            retryable = true;
+            finish();
+        }, timeoutMs);
+        client.on('banner', () => {
+            if (!handshakeOk) {
+                handshakeOk = true;
+                handshakeDuration = Date.now() - start;
+            }
+        });
+        client.on('ready', () => {
+            clearTimeout(timeoutId);
+            handshakeOk = true;
+            authOk = true;
+            if (!handshakeDuration) {
+                handshakeDuration = Date.now() - start;
+            }
+            authDuration = Date.now() - start;
+            finish();
+        });
+        client.on('error', (err) => {
+            clearTimeout(timeoutId);
+            errorMessage = err.message;
+            const authFailure = isAuthFailure(err);
+            if (authFailure) {
+                handshakeOk = true;
+                if (!handshakeDuration) {
+                    handshakeDuration = Date.now() - start;
+                }
+            }
+            retryable = !authFailure && isRetryableConnectionError(err);
+            finish();
+        });
+        const { profileId, ...connectConfig } = sshConfig;
+        client.connect(connectConfig);
+    });
+}
+export async function testSshConnection(sshConfig, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
+    const retries = normalizeRetries(options.retries);
+    const target = formatTargetContext(sshConfig);
+    const tcp = await testTcpConnection(sshConfig.host, sshConfig.port, timeoutMs);
+    if (!tcp.ok) {
+        return {
+            target,
+            attempts: 0,
+            tcp,
+            handshake: {
+                ok: false,
+                durationMs: 0,
+                error: 'Skipped due to TCP failure',
+            },
+            auth: {
+                ok: false,
+                durationMs: 0,
+                error: 'Skipped due to TCP failure',
+            },
+        };
+    }
+    let attempts = 0;
+    let lastHandshake = { ok: false, durationMs: 0, error: 'Not attempted' };
+    let lastAuth = { ok: false, durationMs: 0, error: 'Not attempted' };
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+        attempts += 1;
+        const result = await testSshHandshakeAndAuth(sshConfig, timeoutMs);
+        lastHandshake = result.handshake;
+        lastAuth = result.auth;
+        if (lastAuth.ok) {
+            return {
+                target,
+                attempts,
+                tcp,
+                handshake: lastHandshake,
+                auth: lastAuth,
+            };
+        }
+        if (!result.retryable || attempt === retries) {
+            break;
+        }
+        const delayMs = Math.min(200 * (2 ** attempt), 2000);
+        await sleep(delayMs);
+    }
+    return {
+        target,
+        attempts,
+        tcp,
+        handshake: lastHandshake,
+        auth: lastAuth,
+    };
+}

package/build/ssh/ssh-config.js

@@ -0,0 +1,31 @@
+import { readFile } from 'fs/promises';
+import { resolveKeyPath } from '../config/loader.js';
+import { sanitizePassword } from './command-utils.js';
+export async function buildSshConfigFromProfile(profile, configPath) {
+    const sshConfig = {
+        profileId: profile.id,
+        host: profile.host,
+        port: profile.port,
+        username: profile.user,
+    };
+    try {
+        if (profile.auth.type === 'password') {
+            sshConfig.password = sanitizePassword(profile.auth.password);
+        }
+        else {
+            const keyPath = resolveKeyPath(profile.auth.keyPath, configPath);
+            sshConfig.privateKey = await readFile(keyPath, 'utf8');
+        }
+        if (profile.suPassword !== undefined) {
+            sshConfig.suPassword = sanitizePassword(profile.suPassword);
+        }
+        if (profile.sudoPassword !== undefined) {
+            sshConfig.sudoPassword = sanitizePassword(profile.sudoPassword);
+        }
+    }
+    catch (err) {
+        const message = err?.message ?? String(err);
+        throw new Error(`Failed to load SSH credentials for profile "${profile.id}" (${profile.host}:${profile.port}): ${message}`);
+    }
+    return sshConfig;
+}

package/build/tools/exec.js

@@ -11,9 +11,16 @@ export function registerExecTool(server, deps) {
     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 }) => {
+        timeoutMs: z.number()
+            .int()
+            .positive()
+            .max(60 * 60 * 1000)
+            .optional()
+            .describe('Optional per-command timeout override in milliseconds'),
+    }, async ({ command, description, timeoutMs }) => {
         const runtime = deps.getRuntimeOptions();
         const sanitizedCommand = sanitizeCommand(command, runtime.maxChars);
+        const effectiveTimeoutMs = timeoutMs ?? runtime.timeoutMs;
         try {
             const manager = await deps.getConnectionManager();
             await manager.ensureConnected();
@@ -28,7 +35,7 @@ export function registerExecTool(server, deps) {
                     // Intentionally swallow and fall back to normal execution.
                 }
             }
-            return await execSshCommandWithConnection(manager, appendDescription(sanitizedCommand, description), runtime.timeoutMs);
+            return await execSshCommandWithConnection(manager, appendDescription(sanitizedCommand, description), effectiveTimeoutMs);
         }
         catch (err) {
             if (err instanceof McpError)

package/build/tools/profiles.js

@@ -1,5 +1,7 @@
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { buildSshConfigFromProfile } from '../ssh/ssh-config.js';
+import { testSshConnection } from '../ssh/connection-manager.js';
 import { asTextResult } from './result.js';
 function toMcpError(err) {
     if (err instanceof McpError)
@@ -74,6 +76,36 @@ export function registerProfileTools(server, deps) {
             throw toMcpError(err);
         }
     });
+    server.tool('profiles-test', 'Test TCP connectivity, SSH handshake, and authentication for a profile without executing commands.', {
+        profileId: z.string().min(1).optional().describe('Optional profile id; defaults to current active profile'),
+        timeoutMs: z.number()
+            .int()
+            .positive()
+            .max(60 * 1000)
+            .optional()
+            .describe('Optional timeout per attempt in milliseconds (default 10000)'),
+        retries: z.number()
+            .int()
+            .min(0)
+            .max(5)
+            .optional()
+            .describe('Retry count for handshake/network failures (default 2)'),
+    }, async ({ profileId, timeoutMs, retries }) => {
+        try {
+            const profile = profileId
+                ? deps.profileManager.getProfileById(profileId)
+                : deps.profileManager.getActiveProfile();
+            const sshConfig = await buildSshConfigFromProfile(profile, deps.profileManager.getConfigPath());
+            const result = await testSshConnection(sshConfig, { timeoutMs, retries });
+            return asTextResult({
+                profileId: profile.id,
+                result,
+            });
+        }
+        catch (err) {
+            throw toMcpError(err);
+        }
+    });
     server.tool('profiles-create', 'Create a new SSH profile template at runtime. Note is optional but recommended; if omitted, a short note is generated from context.', {
         id: z.string().min(1).describe('Unique profile id (stable key)'),
         name: z.string().min(1).describe('Human-readable profile name'),

package/build/tools/sudo-exec.js

@@ -11,9 +11,16 @@ export function registerSudoExecTool(server, deps) {
     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 }) => {
+        timeoutMs: z.number()
+            .int()
+            .positive()
+            .max(60 * 60 * 1000)
+            .optional()
+            .describe('Optional per-command timeout override in milliseconds'),
+    }, async ({ command, description, timeoutMs }) => {
         const runtime = deps.getRuntimeOptions();
         const sanitizedCommand = sanitizeCommand(command, runtime.maxChars);
+        const effectiveTimeoutMs = timeoutMs ?? runtime.timeoutMs;
         try {
             const manager = await deps.getConnectionManager();
             await manager.ensureConnected();
@@ -27,7 +34,7 @@ export function registerSudoExecTool(server, deps) {
                 const escapedPwd = sudoPassword.replace(/'/g, "'\\''");
                 wrapped = `printf '%s\\n' '${escapedPwd}' | sudo -p "" -S sh -c '${commandWithDescription.replace(/'/g, "'\\''")}'`;
             }
-            return await execSshCommandWithConnection(manager, wrapped, runtime.timeoutMs);
+            return await execSshCommandWithConnection(manager, wrapped, effectiveTimeoutMs);
         }
         catch (err) {
             if (err instanceof McpError)

package/package.json

@@ -1,15 +1,15 @@
 {
-  "name": "@xiaoyankonling/ssh-mcp",
-  "license": "MIT",
-  "version": "2.0.0",
+  "name": "@xiaoyankonling/ssh-mcp",
+  "license": "MIT",
+  "version": "2.1.0",
   "description": "MCP server exposing SSH control for Linux and Windows systems via Model Context Protocol.",
   "type": "module",
-  "bin": {
-    "ssh-mcp": "build/index.js"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
+  "bin": {
+    "ssh-mcp": "build/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "prepare": "npm run build",
     "build": "tsc && shx chmod +x build/*.js",
@@ -38,13 +38,13 @@
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },
-  "homepage": "https://github.com/Bianshumeng/ssh-mcp#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Bianshumeng/ssh-mcp.git"
-  },
+  "homepage": "https://github.com/Bianshumeng/ssh-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Bianshumeng/ssh-mcp.git"
+  },
   "bugs": {
-    "url": "https://github.com/Bianshumeng/ssh-mcp/issues"
+    "url": "https://github.com/Bianshumeng/ssh-mcp/issues"
   },
   "keywords": [
     "ssh",
@@ -58,7 +58,7 @@
     "cli",
     "typescript"
   ],
-  "author": "xiaoyankonling",
+  "author": "xiaoyankonling",
   "engines": {
     "node": ">=18"
   }