@jadchene/mcp-ssh-service 1.1.1 → 1.2.0

package/README.md

@@ -1,95 +1,188 @@
-# SSH MCP Service
-
-A production-ready, highly secure Model Context Protocol (MCP) server for remote server management. It features stateless connections, lazy loading, and a mandatory two-step confirmation flow for high-risk operations.
-
-## Core Features
-
-- **Stateless & Lazy Loading**: Connections are only established when a tool is called and closed immediately after execution. No persistent SSH tunnels.
-- **Security First**: 
-  - Mandatory manual confirmation for all "Write Actions" (e.g., `rm`, `restart`, `docker_stop`).
-  - Command blacklist (prevents `rm -rf /`, etc.).
-  - Restricted directory protection for safe deletions.
-- **Context Aware**: Supports directory aliases and path mapping via `list_working_directories`.
-- **Workflow Automation**: `execute_batch` allows running multiple commands in a single session with state (like `cd`) preserved between steps.
-
-## Tool List (45 Total)
-
-### 🛠️ Discovery & Core (8)
-- `list_servers`: List all configured SSH servers.
-- `ping_server`: Test connectivity to a specific server.
-- `list_working_directories`: View path mappings/aliases.
-- `check_dependencies`: Verify if required binaries (git, docker, etc.) are installed.
-- `get_system_info`: Get CPU, memory, and kernel details.
-- `pwd`: Show current remote path.
-- `cd`: Change directory (effective within `execute_batch`).
-- `execute_batch`: Run a sequence of tools in one session.
-
-### 💻 Shell & Basic (2)
-- `execute_command` (*): Run any arbitrary shell command.
-- `echo`: Print text or variables.
-
-### 📂 File Management (5)
-- `upload_file` (*): Transfer file from local to remote.
-- `download_file`: Transfer file from remote to local.
-- `ll`: Detailed directory listing.
-- `cat`: Read file content.
-- `edit_text_file` (*): Replace file content (Safe Base64 transfer).
-- `touch`: Create empty file or update timestamp.
-- `find`: Search for files in a directory hierarchy.
-
-### 🐳 Docker & Compose (18)
-- `docker_compose_up` (*), `docker_compose_down` (*), `docker_compose_stop` (*), `docker_compose_restart` (*)
-- `docker_compose_logs`: View compose logs.
-- `docker_ps`, `docker_images`
-- `docker_pull` (*), `docker_cp` (*), `docker_stop` (*), `docker_rm` (*), `docker_start` (*), `docker_rmi` (*), `docker_commit` (*)
-- `docker_logs`: Get container logs.
-- `docker_load` (*), `docker_save` (*)
-
-### ⚙️ System Services (4)
-- `systemctl_status`
-- `systemctl_start` (*), `systemctl_stop` (*), `systemctl_restart` (*)
-
-### 🌐 Network & Stats (8)
-- `ip_addr`: Show network interfaces.
-- `firewall_cmd` (*): Manage firewall rules.
-- `netstat`: Monitor ports and connections.
-- `nvidia_smi`: GPU status.
-- `ps`: Process snapshot.
-- `df_h`: Disk usage.
-- `du_sh`: Directory size estimation.
-
-> (*) Requires manual confirmation.
-
-## Confirmation Protocol
-
-For any tool marked with `(*)`, the service follows a two-step flow:
-1. **Request**: Call the tool with parameters. The server returns a `confirmationId` and `status: "pending"`.
-2. **Confirm**: Call the **same tool again** with `confirmExecution: true` and the provided `confirmationId`.
-
-## Configuration
-
-External configuration `config.json` allows defining multiple servers and their working directory aliases:
-
-```json
-{
-  "servers": {
-    "prod-web": {
-      "host": "192.168.1.100",
-      "user": "root",
-      "keyPath": "~/.ssh/id_rsa",
-      "workingDirectories": {
-        "app": { "path": "/var/www/html", "desc": "Web Root" },
-        "logs": { "path": "/var/log/nginx", "desc": "Nginx Logs" }
-      }
-    }
-  }
-}
-```
-
-## Installation
-
-```bash
-npm install
-npm run build
-node dist/index.js
+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 (50 Tools)
+
+### Discovery & Core (8)
+* `list_servers`
+* `ping_server`
+* `list_working_directories`
+* `check_dependencies`
+* `get_system_info`
+* `pwd`
+* `cd`
+* `execute_batch` [Auth Required if any sub-command is high-risk]
+
+### Shell & Basic (2)
+* `execute_command` [Auth Required]
+* `echo`
+
+### File Management (10)
+* `upload_file` [Auth Required]
+* `download_file`
+* `ll`
+* `cat`
+* `tail`
+* `grep`
+* `edit_text_file` [Auth Required]
+* `touch`
+* `rm_safe` [Auth Required]
+* `find`
+
+### Git (2)
+* `git_status`
+* `git_pull` [Auth Required]
+
+### Docker & Compose (17)
+* `docker_compose_up` [Auth Required]
+* `docker_compose_down` [Auth Required]
+* `docker_compose_stop` [Auth Required]
+* `docker_compose_logs`
+* `docker_compose_restart` [Auth Required]
+* `docker_ps`
+* `docker_images`
+* `docker_pull` [Auth Required]
+* `docker_cp` [Auth Required]
+* `docker_stop` [Auth Required]
+* `docker_rm` [Auth Required]
+* `docker_start` [Auth Required]
+* `docker_rmi` [Auth Required]
+* `docker_commit` [Auth Required]
+* `docker_logs`
+* `docker_load` [Auth Required]
+* `docker_save` [Auth Required]
+
+### Service & Network (7)
+* `systemctl_status`
+* `systemctl_restart` [Auth Required]
+* `systemctl_start` [Auth Required]
+* `systemctl_stop` [Auth Required]
+* `ip_addr`
+* `firewall_cmd` [Auth Required]
+* `netstat`
+
+### Stats & Process (4)
+* `nvidia_smi`
+* `ps`
+* `df_h`
+* `du_sh`
+
+Total: 50 tools.
+
+---
+
+## 🔐 The Confirmation Workflow
+
+1.  **Request**: AI calls `execute_command({ command: 'systemctl restart nginx' })`.
+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 `execute_command` 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/tools/definitions.js

@@ -115,6 +115,16 @@ export const toolDefinitions = [
         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: 'grep',
+        description: 'Pattern search: Search for a regex pattern in a file.',
+        inputSchema: baseParams({ filePath: { type: 'string' }, pattern: { type: 'string' }, ignoreCase: { type: 'boolean' } }, ['filePath', 'pattern'])
+    },
     {
         name: 'edit_text_file',
         description: 'File creation/overwrite: Completely replaces file content. REQUIRES CONFIRMATION.',
@@ -129,11 +139,27 @@ export const toolDefinitions = [
         description: 'Timestamp/File creation: Updates access time or creates empty file.',
         inputSchema: baseParams({ filePath: { type: 'string' } }, ['filePath'])
     },
+    {
+        name: 'rm_safe',
+        description: 'File deletion: Removes file or directory. REQUIRES CONFIRMATION.',
+        inputSchema: baseParams({ path: { type: 'string' }, recursive: { type: 'boolean' }, ...confirmationParams }, ['path'])
+    },
     {
         name: 'find',
         description: 'Search for files in a directory hierarchy.',
         inputSchema: baseParams({ path: { type: 'string' }, name: { type: 'string' }, ...grepParam }, ['path'])
     },
+    // --- 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 })
+    },
     // --- Docker & Compose (Requirements) ---
     {
         name: 'docker_compose_up',

package/dist/tools/handlers.js

@@ -4,6 +4,8 @@ const WRITE_TOOLS = [
     'execute_command',
     'upload_file',
     'edit_text_file',
+    'rm_safe',
+    'git_pull',
     'docker_compose_up',
     'docker_compose_down',
     'docker_compose_stop',
@@ -68,12 +70,21 @@ export class ToolHandlers {
             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 'grep': return `grep ${params.ignoreCase ? '-inE' : '-nE'} "${params.pattern.replace(/"/g, '\\"')}" ${params.filePath}`;
             case 'edit_text_file':
                 const edB64 = Buffer.from(params.content).toString('base64');
                 return `echo "${edB64}" | base64 -d > ${params.filePath}`;
             case 'touch': return `touch ${params.filePath}`;
+            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 'echo': return `echo "${params.text}"`;
             case 'find': return `find ${params.path} -name "${params.name}"`;
+            case 'git_status': return 'git status';
+            case 'git_pull': return 'git pull --no-edit';
             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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jadchene/mcp-ssh-service",
-  "version": "1.1.1",
+  "version": "1.2.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",