@xiaoyankonling/ssh-mcp 2.0.0

package/build/ssh/connection-manager.js

@@ -0,0 +1,371 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { Client } from 'ssh2';
+import { DEFAULT_TIMEOUT_MS, escapeCommandForShell } from './command-utils.js';
+export class SSHConnectionManager {
+    conn = null;
+    sshConfig;
+    isConnecting = false;
+    connectionPromise = null;
+    suShell = null;
+    suPromise = null;
+    isElevated = false;
+    constructor(config) {
+        this.sshConfig = config;
+    }
+    async connect() {
+        if (this.conn && this.isConnected()) {
+            return;
+        }
+        if (this.isConnecting && this.connectionPromise) {
+            return this.connectionPromise;
+        }
+        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);
+            this.conn.on('ready', async () => {
+                clearTimeout(timeoutId);
+                this.isConnecting = false;
+                this.connectionPromise = null;
+                if (this.sshConfig.suPassword && !process.env.SSH_MCP_TEST) {
+                    try {
+                        await this.ensureElevated();
+                    }
+                    catch {
+                        // Intentionally swallow: non-elevated fallback is still valid.
+                    }
+                }
+                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', () => {
+                this.conn = null;
+                this.isConnecting = false;
+                this.connectionPromise = null;
+            });
+            this.conn.on('close', () => {
+                this.conn = null;
+                this.isConnecting = false;
+                this.connectionPromise = null;
+            });
+            this.conn.connect(this.sshConfig);
+        });
+        return this.connectionPromise;
+    }
+    isConnected() {
+        return this.conn !== null && Boolean(this.conn._sock) && !this.conn._sock.destroyed;
+    }
+    getSudoPassword() {
+        return this.sshConfig.sudoPassword;
+    }
+    setSudoPassword(password) {
+        this.sshConfig.sudoPassword = password;
+    }
+    getSuPassword() {
+        return this.sshConfig.suPassword;
+    }
+    async setSuPassword(pwd) {
+        this.sshConfig.suPassword = pwd;
+        if (!pwd) {
+            if (this.suShell) {
+                try {
+                    this.suShell.end();
+                }
+                catch {
+                    // no-op
+                }
+            }
+            this.suShell = null;
+            this.isElevated = false;
+            return;
+        }
+        try {
+            await this.ensureElevated();
+        }
+        catch {
+            // no-op; command execution can fall back without elevation.
+        }
+    }
+    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();
+            const timeoutId = setTimeout(() => {
+                this.suPromise = null;
+                reject(new McpError(ErrorCode.InternalError, 'su elevation timed out'));
+            }, 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}`));
+                    return;
+                }
+                let buffer = '';
+                let passwordSent = false;
+                const cleanup = () => {
+                    try {
+                        stream.removeAllListeners('data');
+                    }
+                    catch {
+                        // no-op
+                    }
+                };
+                const onData = (data) => {
+                    const text = data.toString();
+                    buffer += text;
+                    if (!passwordSent && /password[: ]/i.test(buffer)) {
+                        passwordSent = true;
+                        stream.write(this.sshConfig.suPassword + '\n');
+                    }
+                    if (passwordSent && /#/.test(buffer)) {
+                        clearTimeout(timeoutId);
+                        cleanup();
+                        this.suShell = stream;
+                        this.isElevated = true;
+                        this.suPromise = null;
+                        resolve();
+                        return;
+                    }
+                    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'));
+                    }
+                };
+                stream.on('data', onData);
+                stream.on('close', () => {
+                    clearTimeout(timeoutId);
+                    if (!this.isElevated) {
+                        this.suPromise = null;
+                        reject(new McpError(ErrorCode.InternalError, 'su shell closed before elevation completed'));
+                    }
+                });
+                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;
+    }
+    getSuShell() {
+        return this.suShell;
+    }
+    close() {
+        if (!this.conn)
+            return;
+        if (this.suShell) {
+            try {
+                this.suShell.end();
+            }
+            catch {
+                // no-op
+            }
+            this.suShell = null;
+            this.isElevated = false;
+        }
+        this.conn.end();
+        this.conn = null;
+    }
+}
+export async function execSshCommandWithConnection(manager, command, timeoutMs = DEFAULT_TIMEOUT_MS, stdin) {
+    return new Promise((resolve, reject) => {
+        let timeoutId;
+        let isResolved = false;
+        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`));
+            }
+        }, timeoutMs);
+        if (shell) {
+            let buffer = '';
+            const dataHandler = (data) => {
+                const text = data.toString();
+                buffer += text;
+                if (!/#/.test(buffer))
+                    return;
+                if (!isResolved) {
+                    isResolved = true;
+                    clearTimeout(timeoutId);
+                    const lines = buffer.split('\n');
+                    const output = lines.slice(1, -1).join('\n');
+                    resolve({
+                        content: [{
+                                type: 'text',
+                                text: output + (output ? '\n' : ''),
+                            }],
+                    });
+                }
+                shell.removeListener('data', dataHandler);
+            };
+            shell.on('data', dataHandler);
+            shell.write(command + '\n');
+            return;
+        }
+        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 {
+                    // no-op
+                }
+            }
+            try {
+                stream.end();
+            }
+            catch {
+                // no-op
+            }
+            stream.on('data', (data) => {
+                stdout += data.toString();
+            });
+            stream.stderr.on('data', (data) => {
+                stderr += data.toString();
+            });
+            stream.on('close', (code) => {
+                if (isResolved)
+                    return;
+                isResolved = true;
+                clearTimeout(timeoutId);
+                if (stderr) {
+                    reject(new McpError(ErrorCode.InternalError, `Error (code ${code}):\n${stderr}`));
+                    return;
+                }
+                resolve({
+                    content: [{
+                            type: 'text',
+                            text: stdout,
+                        }],
+                });
+            });
+        });
+    });
+}
+export async function execSshCommand(sshConfig, command, stdin, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const conn = new Client();
+        let timeoutId;
+        let isResolved = false;
+        timeoutId = setTimeout(() => {
+            if (isResolved)
+                return;
+            isResolved = true;
+            const abortTimeout = setTimeout(() => {
+                conn.end();
+            }, 5000);
+            conn.exec(`timeout 3s pkill -f '${escapeCommandForShell(command)}' 2>/dev/null || true`, (_err, abortStream) => {
+                if (abortStream) {
+                    abortStream.on('close', () => {
+                        clearTimeout(abortTimeout);
+                        conn.end();
+                    });
+                    return;
+                }
+                clearTimeout(abortTimeout);
+                conn.end();
+            });
+            reject(new McpError(ErrorCode.InternalError, `Command execution timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        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 && stdin.length > 0) {
+                    try {
+                        stream.write(stdin);
+                    }
+                    catch {
+                        // no-op
+                    }
+                }
+                try {
+                    stream.end();
+                }
+                catch {
+                    // no-op
+                }
+                let stdout = '';
+                let stderr = '';
+                stream.on('close', (code) => {
+                    if (isResolved)
+                        return;
+                    isResolved = true;
+                    clearTimeout(timeoutId);
+                    conn.end();
+                    if (stderr) {
+                        reject(new McpError(ErrorCode.InternalError, `Error (code ${code}):\n${stderr}`));
+                        return;
+                    }
+                    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)
+                return;
+            isResolved = true;
+            clearTimeout(timeoutId);
+            reject(new McpError(ErrorCode.InternalError, `SSH connection error: ${err.message}`));
+        });
+        conn.connect(sshConfig);
+    });
+}

package/build/tools/exec.js

@@ -0,0 +1,39 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { execSshCommandWithConnection, } from '../ssh/connection-manager.js';
+import { sanitizeCommand } from '../ssh/command-utils.js';
+function appendDescription(command, description) {
+    if (!description)
+        return command;
+    return `${command} # ${description.replace(/#/g, '\\#')}`;
+}
+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 }) => {
+        const runtime = deps.getRuntimeOptions();
+        const sanitizedCommand = sanitizeCommand(command, runtime.maxChars);
+        try {
+            const manager = await deps.getConnectionManager();
+            await manager.ensureConnected();
+            if (manager.getSuPassword()) {
+                try {
+                    await Promise.race([
+                        manager.ensureElevated(),
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('Elevation timeout')), 5000)),
+                    ]);
+                }
+                catch {
+                    // Intentionally swallow and fall back to normal execution.
+                }
+            }
+            return await execSshCommandWithConnection(manager, appendDescription(sanitizedCommand, description), runtime.timeoutMs);
+        }
+        catch (err) {
+            if (err instanceof McpError)
+                throw err;
+            throw new McpError(ErrorCode.InternalError, `Unexpected error: ${err?.message ?? err}`);
+        }
+    });
+}

package/build/tools/profiles.js

@@ -0,0 +1,159 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { asTextResult } from './result.js';
+function toMcpError(err) {
+    if (err instanceof McpError)
+        return err;
+    const message = err?.message ?? String(err);
+    return new McpError(ErrorCode.InvalidParams, message);
+}
+export function registerProfileTools(server, deps) {
+    server.tool('profiles-list', 'List available SSH profiles with summary metadata. Use this first to identify target profile by id/host/note/tags.', {}, async () => {
+        try {
+            return asTextResult({
+                configPath: deps.profileManager.getConfigPath(),
+                activeProfile: deps.profileManager.getActiveProfileId(),
+                profiles: deps.profileManager.listProfiles(),
+            });
+        }
+        catch (err) {
+            throw toMcpError(err);
+        }
+    });
+    server.tool('profiles-use', 'Switch active SSH profile for subsequent command execution. The selected profile is persisted as activeProfile in config.', {
+        profileId: z.string().min(1).describe('Profile id to activate'),
+    }, async ({ profileId }) => {
+        try {
+            const profile = await deps.profileManager.setActiveProfile(profileId, true);
+            await deps.onTargetChanged();
+            return asTextResult({
+                activeProfile: deps.profileManager.getActiveProfileId(),
+                profile,
+            });
+        }
+        catch (err) {
+            throw toMcpError(err);
+        }
+    });
+    server.tool('profiles-reload', 'Reload profile configuration from local file and re-validate active profile.', {}, async () => {
+        try {
+            const result = await deps.profileManager.reload();
+            await deps.onTargetChanged();
+            return asTextResult(result);
+        }
+        catch (err) {
+            throw toMcpError(err);
+        }
+    });
+    server.tool('profiles-note-update', 'Update note field for a profile and persist it to local config file. Keep note short and precise so future matching stays accurate.', {
+        profileId: z.string().min(1).describe('Profile id to update'),
+        note: z.string().describe('New concise note text (recommended <= 120 chars)'),
+    }, async ({ profileId, note }) => {
+        try {
+            const profile = await deps.profileManager.updateNote(profileId, note);
+            return asTextResult({
+                updatedProfileId: profileId,
+                profile,
+            });
+        }
+        catch (err) {
+            throw toMcpError(err);
+        }
+    });
+    server.tool('profiles-find', 'Find profile candidates by keyword across id/name/host/user/note/tags. Use this to precisely locate the correct SSH target before switching or deleting.', {
+        query: z.string().describe('Search keyword, such as host fragment, role tag, or note keyword'),
+    }, async ({ query }) => {
+        try {
+            return asTextResult({
+                query,
+                activeProfile: deps.profileManager.getActiveProfileId(),
+                matches: deps.profileManager.findProfiles(query),
+            });
+        }
+        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'),
+        host: z.string().min(1).describe('SSH host or IP'),
+        port: z.number().int().min(1).max(65535).optional().describe('SSH port, default 22'),
+        user: z.string().min(1).describe('SSH username'),
+        authType: z.enum(['password', 'key']).describe('Authentication method'),
+        password: z.string().optional().describe('Required when authType=password; plain value or ${ENV_VAR}'),
+        keyPath: z.string().optional().describe('Required when authType=key; absolute or config-relative path'),
+        suPassword: z.string().optional().describe('Optional su password'),
+        sudoPassword: z.string().optional().describe('Optional sudo password'),
+        note: z.string().optional().describe('Optional concise note; recommended to describe role/purpose'),
+        contextSummary: z.string().optional().describe('Optional context used to auto-generate note when note is omitted'),
+        tags: z.array(z.string()).optional().describe('Optional tags for later matching'),
+        activate: z.boolean().optional().describe('Whether to activate this profile immediately, default true'),
+    }, async (input) => {
+        try {
+            let auth;
+            if (input.authType === 'password') {
+                if (!input.password || input.password.trim().length === 0) {
+                    throw new Error('password is required when authType=password');
+                }
+                auth = { type: 'password', password: input.password };
+            }
+            else {
+                if (!input.keyPath || input.keyPath.trim().length === 0) {
+                    throw new Error('keyPath is required when authType=key');
+                }
+                auth = { type: 'key', keyPath: input.keyPath };
+            }
+            const profile = await deps.profileManager.createProfile({
+                id: input.id,
+                name: input.name,
+                host: input.host,
+                port: input.port,
+                user: input.user,
+                auth,
+                suPassword: input.suPassword,
+                sudoPassword: input.sudoPassword,
+                note: input.note,
+                contextSummary: input.contextSummary,
+                tags: input.tags,
+                activate: input.activate,
+            });
+            if (input.activate ?? true) {
+                await deps.onTargetChanged();
+            }
+            return asTextResult({
+                createdProfileId: input.id,
+                activeProfile: deps.profileManager.getActiveProfileId(),
+                profile,
+            });
+        }
+        catch (err) {
+            throw toMcpError(err);
+        }
+    });
+    server.tool('profiles-delete-prepare', 'Prepare deletion for a profile. This step creates a backup and returns a deleteRequestId + confirmationText. Always show result to the user and ask explicit confirmation before calling profiles-delete-confirm.', {
+        profileId: z.string().min(1).describe('Exact profile id to delete'),
+    }, async ({ profileId }) => {
+        try {
+            const result = await deps.profileManager.prepareDeleteProfile(profileId);
+            return asTextResult(result);
+        }
+        catch (err) {
+            throw toMcpError(err);
+        }
+    });
+    server.tool('profiles-delete-confirm', 'Execute profile deletion after explicit user confirmation. Requires deleteRequestId and exact confirmationText from profiles-delete-prepare response.', {
+        deleteRequestId: z.string().min(1).describe('Delete request id returned by profiles-delete-prepare'),
+        profileId: z.string().min(1).describe('Exact profile id to delete'),
+        confirmationText: z.string().min(1).describe('Must exactly match the confirmationText returned by prepare step'),
+    }, async ({ deleteRequestId, profileId, confirmationText }) => {
+        try {
+            const result = await deps.profileManager.confirmDeleteProfile(deleteRequestId, profileId, confirmationText);
+            await deps.onTargetChanged();
+            return asTextResult(result);
+        }
+        catch (err) {
+            throw toMcpError(err);
+        }
+    });
+}

package/build/tools/result.js

@@ -0,0 +1,8 @@
+export function asTextResult(payload) {
+    return {
+        content: [{
+                type: 'text',
+                text: `${JSON.stringify(payload, null, 2)}\n`,
+            }],
+    };
+}

package/build/tools/sudo-exec.js

@@ -0,0 +1,38 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { execSshCommandWithConnection, } from '../ssh/connection-manager.js';
+import { sanitizeCommand } from '../ssh/command-utils.js';
+function appendDescription(command, description) {
+    if (!description)
+        return command;
+    return `${command} # ${description.replace(/#/g, '\\#')}`;
+}
+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 }) => {
+        const runtime = deps.getRuntimeOptions();
+        const sanitizedCommand = sanitizeCommand(command, runtime.maxChars);
+        try {
+            const manager = await deps.getConnectionManager();
+            await manager.ensureConnected();
+            const commandWithDescription = appendDescription(sanitizedCommand, description);
+            const sudoPassword = manager.getSudoPassword();
+            let wrapped;
+            if (!sudoPassword) {
+                wrapped = `sudo -n sh -c '${commandWithDescription.replace(/'/g, "'\\''")}'`;
+            }
+            else {
+                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);
+        }
+        catch (err) {
+            if (err instanceof McpError)
+                throw err;
+            throw new McpError(ErrorCode.InternalError, `Unexpected error: ${err?.message ?? err}`);
+        }
+    });
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@xiaoyankonling/ssh-mcp",
+  "license": "MIT",
+  "version": "2.0.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"
+  },
+  "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",
+    "yaml": "^2.8.2",
+    "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/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"
+  },
+  "keywords": [
+    "ssh",
+    "mcp",
+    "model-context-protocol",
+    "server",
+    "windows",
+    "linux",
+    "automation",
+    "remote",
+    "cli",
+    "typescript"
+  ],
+  "author": "xiaoyankonling",
+  "engines": {
+    "node": ">=18"
+  }
+}