@jadchene/mcp-ssh-service 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jadch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+English | [简体中文](./README_zh.md)
+
+# 🚀 mcp-ssh
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
+[![MCP Ready](https://img.shields.io/badge/MCP-Ready-blue)](https://modelcontextprotocol.io/)
+
+A **production-grade** Model Context Protocol (MCP) server designed for secure, stateless SSH automation. This service empowers AI agents to manage remote infrastructure with **human-in-the-loop** safety and **semantic environment awareness**.
+
+---
+
+## 🌟 Key Pillars
+
+### 🔒 Uncompromising Security
+*   **Two-Step Confirmation**: High-risk operations (writes, deletes, restarts) return a `confirmationId`. Nothing happens until a human approves the specific transaction.
+*   **Command Blacklist**: Real-time regex interception for catastrophic commands like `rm -rf /` or `mkfs`.
+*   **Server-Level Read-Only**: Lock specific servers to a non-destructive mode at the configuration level.
+*   **Restricted File Deletion**: Hardcoded prevention of accidental deletion of system-critical paths like `/etc` or `/usr`.
+
+### 🧠 AI-Native Design
+*   **Semantic Infrastructure Discovery**: AI can list servers and understand their purposes via natural language descriptions.
+*   **Working Directory Aliases**: Map complex paths to simple aliases like `app-root` with descriptive metadata.
+*   **Contextual Pre-checks**: Built-in tools to verify dependencies (Docker, Git) before execution.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install globally via npm
+npm install -g @jadchene/mcp-ssh-service
+
+# Start the server with a config file
+mcp-ssh-service --config ./config.json
+```
+
+### Source Setup
+
+```bash
+git clone https://github.com/jadchene/mcp-ssh.git
+cd mcp-ssh
+npm install
+npm run build
+node dist/index.js --config ./config.json
+```
+
+---
+
+## ⚙️ Configuration Schema
+
+### Global Settings
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `logDir` | string | Directory for logs. Supports env vars like `${HOME}`. |
+| `commandBlacklist` | string[] | Prohibited command regex patterns (e.g., `["^rm -rf"]`). |
+| `defaultTimeout` | number | Command timeout in milliseconds (default: 60000). |
+| `servers` | object | Dictionary of server configs where key is the `serverAlias`. |
+
+### Server Object
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `host` | string | Remote IP or hostname. Supports env vars. |
+| `port` | number | SSH port (default: 22). |
+| `username` | string | SSH login user. |
+| `password` | string | SSH password. Use `${VAR}` for security. |
+| `privateKeyPath` | string | Path to private key file. |
+| `passphrase` | string | Passphrase for the private key. |
+| `readOnly` | boolean | Disables all write/modify tools for this server. |
+| `desc` | string | Server description shown in `list_servers`. |
+| `strictHostKeyChecking` | boolean | Set to `false` to bypass host key verification. |
+| `workingDirectories` | object | Semantic path mappings (Key: { path, desc }). |
+| `proxyJump` | object | Optional jump host (recursive server config). |
+
+---
+
+## ⚙️ Configuration Example
+
+```json
+{
+  "logDir": "./logs",
+  "defaultTimeout": 60000,
+  "commandBlacklist": ["^apt-get upgrade", "curl.*\\|.*sh"],
+  "servers": {
+    "prod-web": {
+      "desc": "Primary API Cluster",
+      "host": "10.0.0.5",
+      "username": "deploy",
+      "privateKeyPath": "~/.ssh/id_rsa",
+      "passphrase": "${SSH_KEY_PWD}",
+      "workingDirectories": {
+        "logs": { "path": "/var/log/nginx", "desc": "Nginx access logs" }
+      },
+      "proxyJump": {
+        "host": "bastion.example.com",
+        "username": "jumpuser"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ Integrated Toolset (45 Tools)
+
+### 📂 Discovery & Context
+*   `list_servers`: Discovery available hosts.
+*   `ping_server`: Test SSH connection & credentials.
+*   `list_working_directories`: Get semantic path mappings.
+*   `get_system_info`: CPU, Memory, and System Uptime.
+*   `check_dependencies`: Verify remote binaries.
+
+### 💻 Shell & Files
+*   `execute_command`*, `execute_batch`*: Run single or sequenced shell commands.
+*   `ll`, `cat`, `tail`, `grep`, `pwd`, `cd`: Browse and search remote files.
+*   `upload_file`*, `download_file`: Transfer data.
+*   `mkdir`*, `mv`*, `cp`*, `chmod`*, `rm_safe`*, `touch`*: File system management.
+
+### 🐳 DevOps & Services
+*   `docker_ps`, `docker_logs`, `docker_compose_up`*, `docker_compose_restart`*: Container orchestration.
+*   `systemctl_status`, `systemctl_restart`*: System service control.
+*   `git_status`, `git_pull`*: Version control.
+*   `ip_addr`, `ping`, `netstat`, `df_h`, `nvidia_smi`: Diagnostics.
+
+*\* High-risk: Requires `confirmationId` and `confirmExecution: true`.*
+
+---
+
+## 🔐 The Confirmation Workflow
+
+1.  **Request**: AI calls `rm_safe({ path: '/tmp/old' })`.
+2.  **Intercept**: Server returns `status: "pending"` with a `confirmationId`.
+3.  **Human Input**: You review the action in your chat client and approve.
+4.  **Execution**: AI calls `rm_safe` again with the `confirmationId` and `confirmExecution: true`.
+5.  **Verify**: Server ensures parameters match exactly and executes the SSH command.
+
+---
+
+## 📄 License
+Released under the [MIT License](./LICENSE).

package/dist/config.js

@@ -0,0 +1,123 @@
+import fs from 'fs';
+import path from 'path';
+import { logger, updateLogTransports } from './logger.js';
+export class ConfigManager {
+    configPath;
+    config;
+    watchTimeout = null;
+    constructor(configPath) {
+        this.configPath = path.resolve(configPath);
+        this.config = { servers: {} };
+        this.config = this.loadConfig();
+        this.watchConfig();
+    }
+    substituteEnvVars(val) {
+        return val.replace(/\${(\w+)}/g, (_, name) => process.env[name] || '');
+    }
+    processProxy(proxy) {
+        if (!proxy)
+            return undefined;
+        if (proxy.host)
+            proxy.host = this.substituteEnvVars(proxy.host);
+        if (proxy.username)
+            proxy.username = this.substituteEnvVars(proxy.username);
+        if (proxy.password)
+            proxy.password = this.substituteEnvVars(proxy.password);
+        if (proxy.passphrase)
+            proxy.passphrase = this.substituteEnvVars(proxy.passphrase);
+        if (proxy.privateKeyPath) {
+            proxy.privateKeyPath = this.substituteEnvVars(proxy.privateKeyPath);
+            try {
+                const keyPath = path.resolve(path.dirname(this.configPath), proxy.privateKeyPath);
+                proxy.privateKey = fs.readFileSync(keyPath, 'utf8');
+            }
+            catch (err) {
+                logger.error(`Failed to read proxy private key:`, err);
+            }
+        }
+        return proxy;
+    }
+    loadConfig() {
+        try {
+            if (!fs.existsSync(this.configPath)) {
+                logger.warn(`Config file not found at ${this.configPath}.`);
+                return { servers: {} };
+            }
+            const rawData = fs.readFileSync(this.configPath, 'utf8');
+            if (!rawData.trim())
+                return this.config;
+            const parsed = JSON.parse(rawData);
+            if (parsed.logDir)
+                updateLogTransports(this.substituteEnvVars(parsed.logDir));
+            const maskedConfig = JSON.parse(JSON.stringify(parsed)); // For logging
+            for (const key of Object.keys(parsed.servers || {})) {
+                const srv = parsed.servers[key];
+                const logSrv = maskedConfig.servers[key];
+                if (srv.host)
+                    srv.host = this.substituteEnvVars(srv.host);
+                if (srv.username)
+                    srv.username = this.substituteEnvVars(srv.username);
+                // Mask passwords/passphrases in log object
+                if (srv.password) {
+                    srv.password = this.substituteEnvVars(srv.password);
+                    logSrv.password = "********";
+                }
+                if (srv.passphrase) {
+                    srv.passphrase = this.substituteEnvVars(srv.passphrase);
+                    logSrv.passphrase = "********";
+                }
+                if (srv.proxyJump) {
+                    srv.proxyJump = this.processProxy(srv.proxyJump);
+                    if (logSrv.proxyJump.password)
+                        logSrv.proxyJump.password = "********";
+                    if (logSrv.proxyJump.passphrase)
+                        logSrv.proxyJump.passphrase = "********";
+                }
+                if (srv.privateKeyPath) {
+                    srv.privateKeyPath = this.substituteEnvVars(srv.privateKeyPath);
+                    try {
+                        const keyPath = path.resolve(path.dirname(this.configPath), srv.privateKeyPath);
+                        srv.privateKey = fs.readFileSync(keyPath, 'utf8');
+                    }
+                    catch (err) {
+                        logger.error(`Failed to read private key for server ${key}:`, err);
+                    }
+                }
+            }
+            logger.info('Configuration loaded successfully (sensitive data masked).');
+            return parsed;
+        }
+        catch (error) {
+            logger.error('Failed to load config:', error);
+            return this.config;
+        }
+    }
+    watchConfig() {
+        if (fs.existsSync(this.configPath)) {
+            fs.watch(this.configPath, () => {
+                if (this.watchTimeout)
+                    clearTimeout(this.watchTimeout);
+                this.watchTimeout = setTimeout(() => {
+                    this.config = this.loadConfig();
+                    logger.info('Config hot-reloaded.');
+                }, 100);
+            });
+        }
+    }
+    getServerConfig(alias) {
+        return this.config.servers[alias];
+    }
+    getAllServers() {
+        const result = {};
+        for (const [alias, srv] of Object.entries(this.config.servers)) {
+            result[alias] = { desc: srv.desc, host: srv.host };
+        }
+        return result;
+    }
+    getGlobalBlacklist() {
+        return this.config.commandBlacklist || [];
+    }
+    getDefaultTimeout() {
+        return this.config.defaultTimeout || 60000;
+    }
+}

package/dist/core/confirmation.js

@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+import { logger } from "../logger.js";
+const TTL_MS = 10 * 60 * 1000; // 10 minutes
+const MAX_PENDING = 500;
+export class ConfirmationManager {
+    pending = new Map();
+    createPending(toolName, serverAlias, args) {
+        // Cleanup expired first
+        this.cleanup();
+        if (this.pending.size >= MAX_PENDING) {
+            throw new Error("Too many pending confirmations. Please wait or confirm existing ones.");
+        }
+        const id = randomUUID();
+        this.pending.set(id, {
+            toolName,
+            serverAlias,
+            args,
+            expiresAt: Date.now() + TTL_MS
+        });
+        logger.info(`Action pending confirmation [${id}]: ${toolName} on ${serverAlias}`);
+        return id;
+    }
+    validateAndPop(id, toolName, serverAlias, args) {
+        const action = this.pending.get(id);
+        if (!action)
+            return false;
+        // Check expiration
+        if (Date.now() > action.expiresAt) {
+            this.pending.delete(id);
+            return false;
+        }
+        // Verify consistency: tool, server and essential args must match
+        const isToolMatch = action.toolName === toolName;
+        const isServerMatch = action.serverAlias === serverAlias;
+        // Deep compare essential args (excluding the confirmation fields themselves)
+        const { confirmationId: _1, confirmExecution: _2, ...currentArgs } = args;
+        const { confirmationId: _3, confirmExecution: _4, ...pendingArgs } = action.args;
+        const isArgsMatch = JSON.stringify(currentArgs) === JSON.stringify(pendingArgs);
+        if (isToolMatch && isServerMatch && isArgsMatch) {
+            this.pending.delete(id); // Use once
+            return true;
+        }
+        return false;
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [id, action] of this.pending.entries()) {
+            if (now > action.expiresAt) {
+                this.pending.delete(id);
+            }
+        }
+    }
+}
+export const confirmationManager = new ConfirmationManager();

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { MCPServer } from "./mcp.js";
+import { ConfigManager } from "./config.js";
+import { logger } from "./logger.js";
+import { VERSION } from "./version.js";
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("-v") || args.includes("--version")) {
+        console.log(`v${VERSION}`);
+        process.exit(0);
+    }
+    try {
+        let configPath = process.env.MCP_SSH_CONFIG || "config.json";
+        const configIdx = args.indexOf("--config");
+        if (configIdx !== -1 && args[configIdx + 1]) {
+            configPath = args[configIdx + 1];
+        }
+        const configManager = new ConfigManager(configPath);
+        const server = new MCPServer(configManager);
+        await server.start();
+    }
+    catch (error) {
+        logger.error("Failed to start MCP SSH server:", error);
+        process.exit(1);
+    }
+}
+main();

package/dist/logger.js

@@ -0,0 +1,42 @@
+import winston from 'winston';
+import path from 'path';
+import fs from 'fs';
+let currentLogDir = process.env.MCP_SSH_LOG_DIR || 'logs';
+export const logger = winston.createLogger({
+    level: 'info',
+    format: winston.format.combine(winston.format.timestamp({
+        format: 'YYYY-MM-DD HH:mm:ss',
+    }), winston.format.errors({ stack: true }), winston.format.splat(), winston.format.json()),
+    defaultMeta: { service: 'mcp-ssh' },
+    transports: [
+        new winston.transports.Console({
+            // MCP over stdio requires stdout to carry only protocol frames.
+            // Route all logs to stderr to avoid corrupting the MCP stream.
+            stderrLevels: ['error', 'warn', 'info', 'http', 'verbose', 'debug', 'silly'],
+            format: winston.format.combine(winston.format.colorize(), winston.format.simple())
+        })
+    ]
+});
+export function updateLogTransports(logDir) {
+    if (path.resolve(logDir) === path.resolve(currentLogDir)) {
+        return;
+    }
+    currentLogDir = logDir;
+    if (!fs.existsSync(logDir)) {
+        fs.mkdirSync(logDir, { recursive: true });
+    }
+    // Remove existing file transports
+    const fileTransports = logger.transports.filter(t => t instanceof winston.transports.File);
+    fileTransports.forEach(t => logger.remove(t));
+    // Add new file transports
+    logger.add(new winston.transports.File({
+        filename: path.join(logDir, 'error.log'),
+        level: 'error'
+    }));
+    logger.add(new winston.transports.File({
+        filename: path.join(logDir, 'mcp-ssh.log')
+    }));
+    logger.info(`Log directory updated to: ${logDir}`);
+}
+// Initialize with default or env var
+updateLogTransports(currentLogDir);

package/dist/mcp.js

@@ -0,0 +1,69 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { toolDefinitions } from "./tools/definitions.js";
+import { ToolHandlers } from "./tools/handlers.js";
+import { logger } from "./logger.js";
+import { NAME, VERSION } from "./version.js";
+export class MCPServer {
+    server;
+    handlers;
+    constructor(configManager) {
+        this.server = new Server({
+            name: NAME,
+            version: VERSION,
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        this.handlers = new ToolHandlers(configManager);
+        this.setupHandlers();
+        this.server.onerror = (error) => logger.error("[MCP Error]", error);
+        process.on("SIGINT", async () => {
+            await this.server.close();
+            process.exit(0);
+        });
+    }
+    setupHandlers() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: toolDefinitions,
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                if (!request.params.arguments) {
+                    throw new Error("No arguments provided");
+                }
+                logger.info(`Handling tool call: ${request.params.name}`, request.params.arguments);
+                const result = await this.handlers.handleTool(request.params.name, request.params.arguments);
+                // Ensure the result is a string for the MCP "text" content type
+                const textOutput = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: textOutput,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                logger.error(`Tool execution error: ${error.message}`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: ${error.message}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    async start() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        logger.info("MCP SSH Server running on stdio");
+    }
+}

package/dist/ssh.js

@@ -0,0 +1,142 @@
+import { Client } from 'ssh2';
+import { logger } from './logger.js';
+import fs from 'fs';
+import path from 'path';
+const MAX_OUTPUT_LENGTH = 30000;
+export class SSHClient {
+    static getBaseConnectConfig(srv) {
+        const config = {
+            host: srv.host,
+            port: srv.port || 22,
+            username: srv.username,
+            readyTimeout: 15000,
+        };
+        if (srv.privateKey) {
+            config.privateKey = srv.privateKey;
+            if (srv.passphrase)
+                config.passphrase = srv.passphrase;
+        }
+        else if (srv.password) {
+            config.password = srv.password;
+        }
+        return config;
+    }
+    static truncate(text) {
+        if (text.length <= MAX_OUTPUT_LENGTH)
+            return text;
+        return text.substring(0, MAX_OUTPUT_LENGTH) + `\n\n[... Output truncated (${text.length} chars) ...]`;
+    }
+    static async runSession(serverConfig, action) {
+        const mainConfig = this.getBaseConnectConfig(serverConfig);
+        // Support strictHostKeyChecking: false (standard automation practice)
+        if (serverConfig.strictHostKeyChecking === false) {
+            mainConfig.algorithms = { serverHostKey: ['ssh-rsa', 'ssh-dss', 'ecdsa-sha2-nistp256', 'ssh-ed25519'] };
+        }
+        return new Promise((resolve, reject) => {
+            const conn = new Client();
+            const connect = () => {
+                if (serverConfig.proxyJump) {
+                    const proxyConn = new Client();
+                    const pConfig = this.getBaseConnectConfig(serverConfig.proxyJump);
+                    proxyConn.on('ready', () => {
+                        logger.info(`Proxy connection ready to ${pConfig.host}`);
+                        proxyConn.forwardOut('127.0.0.1', 0, mainConfig.host, mainConfig.port, (err, stream) => {
+                            if (err) {
+                                proxyConn.end();
+                                return reject(new Error(`Proxy forwarding failed: ${err.message}`));
+                            }
+                            conn.connect({ ...mainConfig, sock: stream });
+                        });
+                    }).on('error', (err) => {
+                        proxyConn.end();
+                        reject(new Error(`Proxy connection error: ${err.message}`));
+                    }).connect(pConfig);
+                    // Ensure proxy closes when main connection closes
+                    conn.on('close', () => proxyConn.end());
+                }
+                else {
+                    conn.connect(mainConfig);
+                }
+            };
+            conn.on('ready', async () => {
+                logger.info(`SSH Session ready for ${serverConfig.host}`);
+                try {
+                    const result = await action(conn);
+                    conn.end();
+                    resolve(result);
+                }
+                catch (err) {
+                    conn.end();
+                    reject(err);
+                }
+            }).on('error', (err) => {
+                logger.error(`SSH Connection Error:`, err);
+                reject(err);
+            });
+            connect();
+        });
+    }
+    static async executeOnConn(conn, command, cwd, timeoutMs = 60000) {
+        return new Promise((resolve, reject) => {
+            let stdout = '';
+            let stderr = '';
+            const finalCommand = cwd ? `cd ${cwd} && ${command}` : command;
+            const timeout = setTimeout(() => {
+                conn.end();
+                reject(new Error(`Command timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            conn.exec(finalCommand, (err, stream) => {
+                if (err) {
+                    clearTimeout(timeout);
+                    return reject(err);
+                }
+                stream.on('close', (code, signal) => {
+                    clearTimeout(timeout);
+                    resolve({
+                        stdout: this.truncate(stdout),
+                        stderr: this.truncate(stderr),
+                        code,
+                        signal
+                    });
+                }).on('data', (data) => {
+                    stdout += data.toString();
+                }).stderr.on('data', (data) => {
+                    stderr += data.toString();
+                });
+            });
+        });
+    }
+    static async executeCommand(serverConfig, command, cwd, timeoutMs = 60000) {
+        return this.runSession(serverConfig, (conn) => this.executeOnConn(conn, command, cwd, timeoutMs));
+    }
+    static async uploadFile(serverConfig, localPath, remotePath) {
+        return this.runSession(serverConfig, (conn) => {
+            return new Promise((resolve, reject) => {
+                conn.sftp((err, sftp) => {
+                    if (err)
+                        return reject(err);
+                    const readStream = fs.createReadStream(path.resolve(localPath));
+                    const writeStream = sftp.createWriteStream(remotePath);
+                    writeStream.on('close', resolve).on('error', reject);
+                    readStream.pipe(writeStream);
+                });
+            });
+        });
+    }
+    static async downloadFile(serverConfig, remotePath, localPath) {
+        return this.runSession(serverConfig, (conn) => {
+            return new Promise((resolve, reject) => {
+                conn.sftp((err, sftp) => {
+                    if (err)
+                        return reject(err);
+                    sftp.fastGet(remotePath, path.resolve(localPath), (err) => {
+                        if (err)
+                            reject(err);
+                        else
+                            resolve();
+                    });
+                });
+            });
+        });
+    }
+}

package/dist/tools/definitions.js

@@ -0,0 +1,260 @@
+function baseParams(properties = {}, required = []) {
+    return {
+        type: 'object',
+        properties: {
+            serverAlias: { type: 'string', description: 'Unique server key from config.json. Use list_servers to find available keys.' },
+            ...properties
+        },
+        required: ['serverAlias', ...required]
+    };
+}
+const confirmationParams = {
+    confirmationId: { type: 'string', description: 'The ID returned from the first attempt of a high-risk tool.' },
+    confirmExecution: { type: 'boolean', description: 'Set to true to finalize execution after receiving a confirmationId.' }
+};
+const grepParam = { grep: { type: 'string', description: 'Filter output using regex pattern.' } };
+const cwdParam = { cwd: { type: 'string', description: 'Execution directory (supports aliases from list_working_directories).' } };
+export const toolDefinitions = [
+    // --- Discovery ---
+    {
+        name: 'list_servers',
+        description: 'Discovery tool: List all configured SSH servers, their hosts, and descriptions.',
+        inputSchema: { type: 'object', properties: {} }
+    },
+    {
+        name: 'ping_server',
+        description: 'Connection test: Verifies if the SSH configuration for a specific server is valid and reachable.',
+        inputSchema: baseParams()
+    },
+    {
+        name: 'list_working_directories',
+        description: 'Context tool: Retrieves path mappings for a specific server.',
+        inputSchema: baseParams()
+    },
+    {
+        name: 'check_dependencies',
+        description: 'Environmental pre-check: Verifies if specific binaries exist on the remote server.',
+        inputSchema: baseParams({ commands: { type: 'array', items: { type: 'string' } } }, ['commands'])
+    },
+    // --- System ---
+    {
+        name: 'get_system_info',
+        description: 'System health check: Returns current user, system uptime, kernel, and memory.',
+        inputSchema: baseParams()
+    },
+    {
+        name: 'pwd',
+        description: 'Current path: Returns the absolute path of the current directory on remote.',
+        inputSchema: baseParams(cwdParam)
+    },
+    {
+        name: 'cd',
+        description: 'Directory navigation: Changes the working directory (effective within batch).',
+        inputSchema: baseParams({ path: { type: 'string' } }, ['path'])
+    },
+    // --- Batch ---
+    {
+        name: 'execute_batch',
+        description: 'Workflow automation: Executes a sequence of multiple tools in a single persistent SSH session. REQUIRES CONFIRMATION if any sub-tool is high-risk.',
+        inputSchema: baseParams({
+            commands: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string' },
+                        arguments: { type: 'object' }
+                    },
+                    required: ['name', 'arguments']
+                }
+            },
+            ...cwdParam,
+            ...confirmationParams
+        }, ['commands'])
+    },
+    // --- Shell ---
+    {
+        name: 'execute_command',
+        description: 'Arbitrary execution: Runs any shell command via SSH. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({
+            command: { type: 'string' },
+            ...cwdParam,
+            ...confirmationParams
+        }, ['command'])
+    },
+    // --- Files ---
+    {
+        name: 'upload_file',
+        description: 'File transfer (Local -> Remote). REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({
+            localPath: { type: 'string' },
+            remotePath: { type: 'string' },
+            ...confirmationParams
+        }, ['localPath', 'remotePath'])
+    },
+    {
+        name: 'download_file',
+        description: 'File transfer (Remote -> Local).',
+        inputSchema: baseParams({
+            remotePath: { type: 'string' },
+            localPath: { type: 'string' }
+        }, ['remotePath', 'localPath'])
+    },
+    {
+        name: 'll',
+        description: 'Directory listing: Lists files in a directory with detailed information.',
+        inputSchema: baseParams({ ...cwdParam, ...grepParam })
+    },
+    {
+        name: 'cat',
+        description: 'File reading: Reads text file content.',
+        inputSchema: baseParams({ filePath: { type: 'string' }, ...grepParam }, ['filePath'])
+    },
+    {
+        name: 'tail',
+        description: 'Log inspection: Reads last N lines of a file.',
+        inputSchema: baseParams({ filePath: { type: 'string' }, lines: { type: 'number' }, ...grepParam }, ['filePath'])
+    },
+    {
+        name: 'edit_text_file',
+        description: 'File creation/overwrite: Completely replaces file content. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({
+            filePath: { type: 'string' },
+            content: { type: 'string' },
+            ...confirmationParams
+        }, ['filePath', 'content'])
+    },
+    {
+        name: 'append_text_file',
+        description: 'File appending: Adds text to end of file. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({
+            filePath: { type: 'string' },
+            content: { type: 'string' },
+            ...confirmationParams
+        }, ['filePath', 'content'])
+    },
+    {
+        name: 'mkdir',
+        description: 'Directory creation: Creates a directory (mkdir -p). REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ path: { type: 'string' }, ...confirmationParams }, ['path'])
+    },
+    {
+        name: 'chmod',
+        description: 'Permission management: Changes file or directory permissions. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ mode: { type: 'string' }, path: { type: 'string' }, ...confirmationParams }, ['mode', 'path'])
+    },
+    {
+        name: 'mv',
+        description: 'File movement/rename: Moves or renames files or directories. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ source: { type: 'string' }, destination: { type: 'string' }, ...confirmationParams }, ['source', 'destination'])
+    },
+    {
+        name: 'cp',
+        description: 'File copy: Copies files or directories. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({
+            source: { type: 'string' },
+            destination: { type: 'string' },
+            recursive: { type: 'boolean' },
+            ...confirmationParams
+        }, ['source', 'destination'])
+    },
+    {
+        name: 'rm_safe',
+        description: 'File deletion: Removes file or directory. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ path: { type: 'string' }, recursive: { type: 'boolean' }, ...confirmationParams }, ['path'])
+    },
+    {
+        name: 'touch',
+        description: 'Timestamp/File creation: Updates access time or creates empty file. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ filePath: { type: 'string' }, ...confirmationParams }, ['filePath'])
+    },
+    // --- Git ---
+    {
+        name: 'git_status',
+        description: 'Git status: Displays repository status.',
+        inputSchema: baseParams(cwdParam)
+    },
+    {
+        name: 'git_pull',
+        description: 'Git update: Pulls latest changes. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ ...cwdParam, ...confirmationParams })
+    },
+    {
+        name: 'git_log',
+        description: 'Git history: Shows commit logs.',
+        inputSchema: baseParams({ ...cwdParam, count: { type: 'number' } })
+    },
+    // --- Docker ---
+    {
+        name: 'docker_compose_up',
+        description: 'Deploy docker stack. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ ...cwdParam, ...confirmationParams }, ['cwd'])
+    },
+    {
+        name: 'docker_compose_down',
+        description: 'Remove docker stack. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ ...cwdParam, ...confirmationParams }, ['cwd'])
+    },
+    {
+        name: 'docker_compose_logs',
+        description: 'View compose logs.',
+        inputSchema: baseParams({ ...cwdParam, lines: { type: 'number' }, ...grepParam }, ['cwd'])
+    },
+    {
+        name: 'docker_compose_restart',
+        description: 'Restart compose stack. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ ...cwdParam, ...confirmationParams }, ['cwd'])
+    },
+    {
+        name: 'docker_ps',
+        description: 'List docker containers.',
+        inputSchema: baseParams(grepParam)
+    },
+    {
+        name: 'docker_logs',
+        description: 'Get container logs.',
+        inputSchema: baseParams({ container: { type: 'string' }, lines: { type: 'number' }, ...grepParam }, ['container'])
+    },
+    // --- Service & Network ---
+    {
+        name: 'systemctl_status',
+        description: 'Check systemd service status.',
+        inputSchema: baseParams({ service: { type: 'string' }, ...grepParam }, ['service'])
+    },
+    {
+        name: 'systemctl_restart',
+        description: 'Restart system service. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ service: { type: 'string' }, ...confirmationParams }, ['service'])
+    },
+    {
+        name: 'ip_addr',
+        description: 'Show network interface info.',
+        inputSchema: baseParams(grepParam)
+    },
+    {
+        name: 'ping',
+        description: 'Verify host accessibility.',
+        inputSchema: baseParams({ host: { type: 'string' }, count: { type: 'number' } }, ['host'])
+    },
+    {
+        name: 'netstat',
+        description: 'Monitor ports/connections.',
+        inputSchema: baseParams({ args: { type: 'string' }, ...grepParam })
+    },
+    // --- Stats ---
+    {
+        name: 'df_h',
+        description: 'System disk usage.',
+        inputSchema: baseParams(grepParam)
+    },
+    {
+        name: 'du_sh',
+        description: 'Directory size estimation.',
+        inputSchema: baseParams({ path: { type: 'string' }, ...grepParam }, ['path'])
+    },
+    {
+        name: 'nvidia_smi',
+        description: 'GPU utilization status.',
+        inputSchema: baseParams()
+    }
+];

package/dist/tools/handlers.js

@@ -0,0 +1,207 @@
+import { SSHClient } from '../ssh.js';
+import { confirmationManager } from '../core/confirmation.js';
+const WRITE_TOOLS = [
+    'execute_command',
+    'upload_file',
+    'edit_text_file',
+    'append_text_file',
+    'mkdir',
+    'chmod',
+    'mv',
+    'cp',
+    'rm_safe',
+    'touch',
+    'git_pull',
+    'docker_compose_up',
+    'docker_compose_down',
+    'docker_compose_restart',
+    'systemctl_restart'
+];
+const DEFAULT_BLACKLIST = [
+    /rm\s+-(rf|fr|r|f)\s+\//i,
+    /rm\s+-(rf|fr|r|f)\s+\*/i,
+    /mkfs/i,
+    /dd\s+if=/i,
+    />\s*\/dev\/sd[a-z]/i,
+    /shutdown/i,
+    /reboot/i
+];
+export class ToolHandlers {
+    configManager;
+    constructor(configManager) {
+        this.configManager = configManager;
+    }
+    getServerConfig(alias) {
+        const config = this.configManager.getServerConfig(alias);
+        if (!config) {
+            throw new Error(`Server alias '${alias}' not found in configuration.`);
+        }
+        return config;
+    }
+    resolveCwd(srv, cwd) {
+        if (!cwd)
+            return undefined;
+        if (srv.workingDirectories && srv.workingDirectories[cwd]) {
+            return srv.workingDirectories[cwd].path;
+        }
+        return cwd;
+    }
+    checkBlacklist(command) {
+        const userBlacklist = this.configManager.getGlobalBlacklist();
+        const combined = [...DEFAULT_BLACKLIST, ...userBlacklist.map(p => new RegExp(p, 'i'))];
+        for (const pattern of combined) {
+            if (pattern.test(command)) {
+                throw new Error(`Security Violation: Prohibited pattern: ${pattern.toString()}`);
+            }
+        }
+    }
+    getCommandForTool(name, params) {
+        switch (name) {
+            case 'get_system_info': return 'echo "USER: $(whoami)"; echo "UPTIME: $(uptime)"; echo "KERNEL: $(uname -a)"; echo "MEMORY:"; free -m';
+            case 'check_dependencies': return `for cmd in ${params.commands.join(' ')}; do which $cmd || echo "$cmd not found"; done`;
+            case 'pwd': return 'pwd';
+            case 'cd': return `cd ${params.path}`;
+            case 'll': return 'ls -l';
+            case 'cat': return `cat ${params.filePath}`;
+            case 'tail': return `tail -n ${params.lines || 50} ${params.filePath}`;
+            case 'mkdir': return `mkdir -p ${params.path}`;
+            case 'chmod': return `chmod ${params.mode} ${params.path}`;
+            case 'mv': return `mv -f ${params.source} ${params.destination}`;
+            case 'cp': return `cp -f ${params.recursive ? '-r' : ''} ${params.source} ${params.destination}`;
+            case 'rm_safe':
+                const restricted = ['/', '/etc', '/usr', '/bin', '/var', '/root', '/home'];
+                if (restricted.includes(params.path.trim()))
+                    throw new Error(`RM_SAFE: Denied for restricted directory.`);
+                return `rm ${params.recursive ? '-rf' : '-f'} ${params.path}`;
+            case 'touch': return `touch ${params.filePath}`;
+            case 'append_text_file':
+                const appB64 = Buffer.from(params.content).toString('base64');
+                return `echo "${appB64}" | base64 -d >> ${params.filePath}`;
+            case 'edit_text_file':
+                const edB64 = Buffer.from(params.content).toString('base64');
+                return `echo "${edB64}" | base64 -d > ${params.filePath}`;
+            case 'git_status': return 'git status';
+            case 'git_pull': return 'git pull --no-edit';
+            case 'git_log': return `git log -n ${params.count || 10} --oneline`;
+            case 'execute_command': return params.command;
+            case 'docker_compose_up': return 'docker-compose up -d';
+            case 'docker_compose_down': return 'docker-compose down --remove-orphans';
+            case 'docker_compose_logs': return `docker-compose logs -n ${params.lines || 100}`;
+            case 'docker_compose_restart': return 'docker-compose restart';
+            case 'docker_ps': return 'docker ps';
+            case 'docker_logs': return `docker logs -n ${params.lines || 100} ${params.container}`;
+            case 'systemctl_status': return `systemctl status ${params.service}`;
+            case 'systemctl_restart': return `systemctl restart ${params.service}`;
+            case 'ip_addr': return 'ip addr';
+            case 'ping': return `ping -c ${params.count || 4} ${params.host}`;
+            case 'netstat': return `netstat ${params.args || '-tuln'}`;
+            case 'df_h': return 'df -h';
+            case 'du_sh': return `du -sh ${params.path}`;
+            case 'nvidia_smi': return 'nvidia-smi';
+            default: return '';
+        }
+    }
+    async handleTool(name, args) {
+        if (name === 'list_servers') {
+            const servers = this.configManager.getAllServers();
+            if (Object.keys(servers).length === 0)
+                return "No servers configured.";
+            return "Available SSH Servers:\n" + Object.entries(servers)
+                .map(([alias, info]) => `- [${alias}] ${info.host}${info.desc ? ' (' + info.desc + ')' : ''}`)
+                .join('\n');
+        }
+        const { serverAlias, confirmationId, confirmExecution, ...params } = args;
+        const srv = this.getServerConfig(serverAlias);
+        const timeout = this.configManager.getDefaultTimeout();
+        if (name === 'ping_server') {
+            try {
+                await SSHClient.runSession(srv, async () => true);
+                return `Successfully connected to server '${serverAlias}' (${srv.host}). Configuration is valid.`;
+            }
+            catch (err) {
+                return `Connection failed for server '${serverAlias}': ${err.message}`;
+            }
+        }
+        // --- Confirmation Logic ---
+        const isWriteAction = WRITE_TOOLS.includes(name) || (name === 'execute_batch' && params.commands?.some((c) => WRITE_TOOLS.includes(c.name)));
+        if (isWriteAction) {
+            if (srv.readOnly)
+                throw new Error(`Server '${serverAlias}' is read-only.`);
+            if (confirmationId && confirmExecution === true) {
+                const isValid = confirmationManager.validateAndPop(confirmationId, name, serverAlias, args);
+                if (!isValid)
+                    throw new Error("Invalid or expired confirmationId. Please try again.");
+            }
+            else {
+                const newId = confirmationManager.createPending(name, serverAlias, args);
+                return {
+                    status: "pending",
+                    confirmationId: newId,
+                    message: `Manual confirmation required for high-risk tool: ${name}. Call this tool again with confirmExecution=true and the provided confirmationId.`,
+                    actionPreview: { tool: name, server: serverAlias, args: params }
+                };
+            }
+        }
+        // --- Execution Logic ---
+        if (name === 'execute_batch') {
+            const commands = params.commands;
+            let results = [];
+            let currentBatchCwd = this.resolveCwd(srv, params.cwd);
+            for (const cmd of commands) {
+                if (cmd.name === 'execute_command')
+                    this.checkBlacklist(cmd.arguments.command);
+            }
+            return await SSHClient.runSession(srv, async (conn) => {
+                for (const cmd of commands) {
+                    if (cmd.name === 'cd') {
+                        currentBatchCwd = cmd.arguments.path;
+                        results.push(`Directory changed to: ${currentBatchCwd}`);
+                        continue;
+                    }
+                    let cmdStr = this.getCommandForTool(cmd.name, cmd.arguments);
+                    if (!cmdStr) {
+                        results.push(`[${cmd.name}] Error: Not supported in batch.`);
+                        continue;
+                    }
+                    if (cmd.arguments.grep)
+                        cmdStr += ` | grep -E "${cmd.arguments.grep.replace(/"/g, '\\"')}"`;
+                    const res = await SSHClient.executeOnConn(conn, cmdStr, currentBatchCwd, timeout);
+                    results.push(`[${cmd.name}]\n${res.stdout}${res.stderr ? '\n[STDERR]\n' + res.stderr : ''}`);
+                }
+                return results.join('\n\n---\n\n');
+            });
+        }
+        if (name === 'execute_command')
+            this.checkBlacklist(params.command);
+        const cwd = this.resolveCwd(srv, params.cwd);
+        if (name === 'list_working_directories') {
+            if (!srv.workingDirectories || Object.keys(srv.workingDirectories).length === 0) {
+                return `No directory mappings for '${serverAlias}'.`;
+            }
+            return `Working Directories for [${serverAlias}]:\n` + Object.entries(srv.workingDirectories)
+                .map(([alias, info]) => `  - ${alias}: ${info.path} (${info.desc})`)
+                .join('\n');
+        }
+        if (name === 'upload_file') {
+            await SSHClient.uploadFile(srv, params.localPath, params.remotePath);
+            return `Successfully uploaded ${params.localPath} to ${params.remotePath}`;
+        }
+        if (name === 'download_file') {
+            await SSHClient.downloadFile(srv, params.remotePath, params.localPath);
+            return `Successfully downloaded ${params.remotePath} to ${params.localPath}`;
+        }
+        let commandToRun = this.getCommandForTool(name, params);
+        if (commandToRun) {
+            if (params.grep)
+                commandToRun += ` | grep -E "${params.grep.replace(/"/g, '\\"')}"`;
+            const res = await SSHClient.executeCommand(srv, commandToRun, cwd, timeout);
+            let out = res.stdout;
+            if (res.stderr)
+                out += `\n[STDERR]\n${res.stderr}`;
+            if (res.code !== 0 && res.code !== null && !params.grep)
+                out += `\n[Exited with code ${res.code}]`;
+            return out || 'Success (no output)';
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    }
+}

package/dist/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = resolve(__dirname, "../package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+export const VERSION = pkg.version || "0.0.0";
+export const NAME = pkg.name || "mcp-ssh";

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@jadchene/mcp-ssh-service",
+  "version": "1.0.0",
+  "description": "A production-ready, highly secure SSH MCP server featuring stateless connections, two-step operation confirmation, and comprehensive DevOps tool integration.",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "mcp-ssh-service": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "watch": "tsc -w",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "ssh",
+    "model context protocol",
+    "automation",
+    "stateless"
+  ],
+  "author": "jadchene",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jadchene/mcp-ssh.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jadchene/mcp-ssh/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "ssh2": "^1.15.0",
+    "winston": "^3.11.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/ssh2": "^1.11.19",
+    "typescript": "^5.3.3"
+  }
+}