remote-admin-mcp 0.1.0__py3-none-any.whl

remote_admin_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: remote-admin-mcp
+Version: 0.1.0
+Summary: MCP Server for remote server administration via SSH — execute commands, manage files, edit configs, transfer files, control services. No agents needed on target servers.
+Project-URL: Homepage, https://github.com/intershopper/remote-admin-mcp
+Project-URL: Repository, https://github.com/intershopper/remote-admin-mcp
+Author-email: Frank Schaellert <intershopper@gmx.de>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: paramiko>=3.4.0
+Requires-Dist: pyjwt[crypto]>=2.12.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: starlette>=0.38.0
+Requires-Dist: uvicorn>=0.30.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SSH MCP Server
+
+MCP Server für SSH-basierte Server-Administration. Ermöglicht KI-Assistenten die Verwaltung von Remote-Servern via SSH.
+
+## Supported MCP Clients
+
+```mermaid
+graph LR
+    subgraph Getestet
+        K[Kiro CLI]
+        C[Claude Desktop]
+    end
+    subgraph Kompatibel
+        A[Alle MCP-fähigen Clients<br/>stdio + StreamableHTTP]
+    end
+    K --> MCP[SSH MCP Server]
+    C --> MCP
+    A --> MCP
+```
+
+| Client | Transport | Status |
+|--------|-----------|--------|
+| [Kiro CLI](https://github.com/aws/kiro) | stdio | ✅ getestet |
+| [Claude Desktop](https://claude.ai/download) | stdio | ✅ getestet |
+| Jeder MCP-Client | stdio / StreamableHTTP | ✅ kompatibel |
+
+## Features
+
+Verwalte Linux-Server per SSH — direkt aus dem KI-Assistenten heraus. Keine Agents, Daemons oder Tools auf den Zielservern nötig. Nur ein SSH-Zugang reicht.
+
+```mermaid
+graph LR
+    AI[KI-Assistent] -->|MCP| S[SSH MCP Server]
+    S -->|SSH/SFTP| R1[Server 1]
+    S -->|SSH/SFTP| R2[Server 2]
+    S -->|SSH/SFTP| RN[Server N]
+```
+
+- **Agentless**: Kein Setup auf den Zielservern — funktioniert mit jedem SSH-Zugang
+- **Remote Command Execution**: Einzelbefehle oder mehrzeilige Scripts ausführen
+- **Sudo Support**: Befehle mit `sudo` ausführen, ohne interaktives Passwort
+- **File Operations**: Dateien lesen (teilweise/komplett), schreiben, suchen, chirurgisch editieren
+- **File Transfer**: Upload/Download via SFTP
+- **Service Management**: Systemd Services starten, stoppen, restarten, Status prüfen
+- **Code Navigation**: Funktions-/Klassen-Übersicht aus Quelldateien extrahieren (grep-basiert, kein Language Server nötig)
+- **Multi-Server**: Beliebig viele Server parallel verwalten
+- **Connection Pooling**: SSH-Verbindungen werden 5 Minuten wiederverwendet
+- **User Approval**: Schreibende Operationen erfordern Bestätigung durch den Operator
+- **Audit Log**: Alle Aktionen werden protokolliert (Pfad konfigurierbar)
+
+## Installation
+
+### Von PyPI
+
+```bash
+pip install remote-admin-mcp
+```
+
+### Mit uv (empfohlen für Entwicklung)
+
+```bash
+# Virtuelle Umgebung erstellen und Abhängigkeiten installieren
+uv venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+### Mit pip
+
+```bash
+# Virtuelle Umgebung erstellen
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+
+# Abhängigkeiten installieren
+pip install -e ".[dev]"
+```
+
+## Konfiguration
+
+1. Kopiere `.env.example` zu `.env`:
+```bash
+cp .env.example .env
+```
+
+2. Bearbeite `.env` mit deinen Server-Zugangsdaten:
+```bash
+SSH_SERVER_1_NAME=production
+SSH_SERVER_1_HOST=prod.example.com
+SSH_SERVER_1_PORT=22
+SSH_SERVER_1_USER=admin
+SSH_SERVER_1_PASSWORD=your-password
+
+SSH_SERVER_2_NAME=staging
+SSH_SERVER_2_HOST=staging.example.com
+SSH_SERVER_2_PORT=22
+SSH_SERVER_2_USER=deploy
+SSH_SERVER_2_PASSWORD=your-password
+```
+
+## MCP Tools
+
+### list_servers
+Liste alle konfigurierten Server auf.
+
+### execute_command
+Führe einen Befehl auf einem Remote-Server aus.
+
+**Parameter:**
+- `server` (string): Server-Name
+- `command` (string): Auszuführender Befehl
+- `use_sudo` (boolean): Mit sudo ausführen
+
+### read_file
+Lese eine Datei vom Remote-Server.
+
+**Parameter:**
+- `server` (string): Server-Name
+- `path` (string): Dateipfad
+
+### write_file
+Schreibe eine Datei auf den Remote-Server.
+
+**Parameter:**
+- `server` (string): Server-Name
+- `path` (string): Dateipfad
+- `content` (string): Dateiinhalt
+
+### get_service_status
+Prüfe den Status eines systemd Services.
+
+**Parameter:**
+- `server` (string): Server-Name
+- `service` (string): Service-Name
+
+### manage_service
+Verwalte einen systemd Service (start/stop/restart/reload).
+
+**Parameter:**
+- `server` (string): Server-Name
+- `service` (string): Service-Name
+- `action` (string): Aktion (start/stop/restart/reload)
+
+## Verwendung mit KI-Assistenten
+
+### Kiro CLI / Claude Desktop (uvx — empfohlen)
+
+Kein manuelles Installieren nötig — `uvx` lädt und cached das Paket automatisch:
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "uvx",
+      "args": ["remote-admin-mcp"],
+      "env": {
+        "SSH_SERVER_1_NAME": "production",
+        "SSH_SERVER_1_HOST": "prod.example.com",
+        "SSH_SERVER_1_USER": "admin",
+        "SSH_SERVER_1_KEY_FILE": "~/.ssh/id_ed25519"
+      }
+    }
+  }
+}
+```
+
+### Alternative: Mit .env-Datei
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "uvx",
+      "args": ["--env-file", "/path/to/.env", "remote-admin-mcp"]
+    }
+  }
+}
+```
+
+### Alternative: Lokale Installation
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "/path/to/.venv/bin/ssh_mcp_server"
+    }
+  }
+}
+```
+
+## Beispiele
+
+**Log-Analyse:**
+```
+"Zeige mir die letzten 100 Zeilen vom nginx error log auf production"
+```
+
+**Service Restart:**
+```
+"Starte den nginx Service auf staging neu"
+```
+
+**Config ändern:**
+```
+"Lies die nginx.conf auf production und erhöhe worker_processes auf 4"
+```
+
+## Sicherheit
+
+- Schreibende Tools erfordern **User-Approval** durch den MCP Client
+- Lese-Tools (`list_servers`, `read_file`, `search_in_file`, `get_file_structure`) sind auto-approved
+- SSH-Key-Authentifizierung empfohlen (Passwort-Auth möglich)
+- `.env` sollte NICHT ins Git committed werden
+
+### Audit Log
+
+Alle Aktionen werden in ein Logfile geschrieben:
+
+```
+[2026-04-12 13:14:00] [production] execute: tail -100 /var/log/syslog
+[2026-04-12 13:14:05] [production] write_file: /etc/nginx/nginx.conf — Config update
+```
+
+Default: `~/.ssh-mcp-audit.log`. Konfigurierbar per Environment-Variable:
+
+```bash
+SSH_MCP_AUDIT_LOG=/var/log/ssh-mcp-audit.log
+```
+
+## Entwicklung
+
+```bash
+# Tests ausführen
+pytest -v
+
+# Linting
+ruff check src/
+```
+
+## Lizenz
+
+MIT — siehe [LICENSE](LICENSE)

remote_admin_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ssh_mcp/__init__.py,sha256=esBcfCRGD4JEgjfCONycLLcS4pam5g_0JItsSlxQMTs,84
+ssh_mcp/audit.py,sha256=uayX6nMII6ScVkkb737_Brv65bwU7QCV9awQCnuXWbM,441
+ssh_mcp/config.py,sha256=7ZP4HCYmMYzx9uqYN1_nZnu7OfoIdmfF_G5rVv5mkC8,1092
+ssh_mcp/models.py,sha256=ur8fsk7Y6qDo9Yq-9xzrhd4i2mIVgwoaONrLlkQ3c1g,254
+ssh_mcp/server.py,sha256=ANA7eUCc31WIHb7FlYbWfaOrsa1vU89Wdz237EsvfCc,18998
+ssh_mcp/ssh_client.py,sha256=4NdQecel0w8bP_wTMlFcpn17YdqnhbUvHPTb8IquX74,10495
+remote_admin_mcp-0.1.0.dist-info/METADATA,sha256=xMCYCOzpCjIkQq6LUvjl2kga2781SF4Jl-bOXfdav0M,6771
+remote_admin_mcp-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+remote_admin_mcp-0.1.0.dist-info/entry_points.txt,sha256=Td4Be1QgN7xt2ocfxYqCNAdjSbRoPeVGQqmTC1MF6c0,57
+remote_admin_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=c4hjs6o_f9N3YnCBT35DQh-_RCkKQMEVznb8ycWQAJA,1073
+remote_admin_mcp-0.1.0.dist-info/RECORD,,

remote_admin_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

remote_admin_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+remote-admin-mcp = ssh_mcp.server:main

remote_admin_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frank Schaellert
+
+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.

ssh_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""SSH MCP Server - Remote server administration via MCP."""
+
+__version__ = "0.1.0"

ssh_mcp/audit.py

@@ -0,0 +1,12 @@
+import os
+import datetime
+
+_log_path = os.getenv("SSH_MCP_AUDIT_LOG", os.path.join(os.path.expanduser("~"), ".ssh-mcp-audit.log"))
+
+
+def log(server: str, tool: str, detail: str, reason: str = "") -> None:
+    ts = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    reason_str = f" — {reason}" if reason else ""
+    line = f"[{ts}] [{server}] {tool}: {detail}{reason_str}\n"
+    with open(_log_path, "a") as f:
+        f.write(line)

ssh_mcp/config.py

@@ -0,0 +1,35 @@
+import os
+from dotenv import load_dotenv
+from .models import ServerConfig
+
+
+def load_servers() -> dict[str, ServerConfig]:
+    """Load server configurations from environment variables."""
+    load_dotenv()
+    
+    servers = {}
+    i = 1
+    
+    while True:
+        name = os.getenv(f"SSH_SERVER_{i}_NAME")
+        if not name:
+            break
+            
+        host = os.getenv(f"SSH_SERVER_{i}_HOST")
+        port = int(os.getenv(f"SSH_SERVER_{i}_PORT", "22"))
+        user = os.getenv(f"SSH_SERVER_{i}_USER")
+        password = os.getenv(f"SSH_SERVER_{i}_PASSWORD", "")
+        key_file = os.getenv(f"SSH_SERVER_{i}_KEY_FILE", "")
+        if key_file:
+            key_file = os.path.expanduser(key_file)
+        
+        if not all([host, user]) or not any([password, key_file]):
+            raise ValueError(f"Incomplete configuration for server {i} (need password or key_file)")
+        
+        servers[name] = ServerConfig(
+            name=name, host=host, port=port, user=user,
+            password=password, key_file=key_file,
+        )
+        i += 1
+    
+    return servers

ssh_mcp/models.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class ServerConfig:
+    name: str
+    host: str
+    port: int
+    user: str
+    password: str = ""
+    key_file: str = ""
+
+
+@dataclass
+class CommandResult:
+    stdout: str
+    stderr: str
+    exit_code: int

ssh_mcp/server.py

@@ -0,0 +1,393 @@
+from mcp.server import Server
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
+from mcp.types import Tool, TextContent
+from .config import load_servers
+from .ssh_client import SSHClient
+from . import audit
+import atexit
+
+server = Server("remote-admin-mcp")
+servers = {}
+ssh_client = None
+
+_use_streaming = True
+
+
+def _validate(arguments: dict, *keys: str) -> str | None:
+    for k in keys:
+        if k in arguments and not str(arguments[k]).strip():
+            return f"ERROR: '{k}' must not be empty"
+    return None
+
+
+def _init():
+    global servers, ssh_client
+    if ssh_client is None:
+        servers = load_servers()
+        ssh_client = SSHClient(servers)
+        atexit.register(ssh_client.close_all)
+
+
+def _truncate_json_lines(text: str, max_json_len: int = 300) -> str:
+    """Truncate lines that look like large JSON blobs."""
+    lines = text.split("\n")
+    out = []
+    for line in lines:
+        stripped = line.strip()
+        if (stripped.startswith("{") and stripped.endswith("}") and len(stripped) > max_json_len):
+            out.append(line[:max_json_len] + "... [JSON truncated]")
+        else:
+            out.append(line)
+    return "\n".join(out)
+
+
+def _format_result(result, server_name: str = "", command: str = "") -> str:
+    """Output with server/command context header."""
+    header = f"[{server_name}] $ {command}\n" if server_name and command else ""
+    parts = []
+    if result.stdout.strip():
+        parts.append(_truncate_json_lines(result.stdout.rstrip()))
+    if result.stderr.strip():
+        parts.append(f"STDERR: {result.stderr.rstrip()}")
+    if result.exit_code != 0:
+        parts.append(f"Exit code: {result.exit_code}")
+    body = "\n".join(parts) if parts else "(no output)"
+    return f"{header}{body}"
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name="list_servers",
+            description="List all configured SSH servers with their connection details. Call this first to discover available server names.",
+            inputSchema={"type": "object", "properties": {}}
+        ),
+        Tool(
+            name="execute",
+            description="Execute a command or multi-line script on a remote server via SSH. For single commands use `command`, for multi-line scripts use `script`. Requires approval.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "server": {"type": "string", "description": "Server name"},
+                    "command": {"type": "string", "description": "Single command to execute"},
+                    "script": {"type": "string", "description": "Multi-line bash script (alternative to command)"},
+                    "use_sudo": {"type": "boolean", "description": "Use sudo", "default": False},
+                    "timeout": {"type": "integer", "description": "Timeout in seconds (default: 30, max: 300)", "default": 30},
+                    "reason": {"type": "string", "description": "Human-readable explanation of what this command does and why (for audit log)"}
+                },
+                "required": ["server"]
+            }
+        ),
+        Tool(
+            name="read_file",
+            description="Read a file or specific line range from a remote server. For large files (>200 lines), always use lines+offset to read only the relevant section. Use tail=true to read from end (e.g. log files).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "server": {"type": "string", "description": "Server name"},
+                    "path": {"type": "string", "description": "File path"},
+                    "lines": {"type": "integer", "description": "Number of lines to read"},
+                    "offset": {"type": "integer", "description": "Line offset (skip N lines from start)", "default": 0},
+                    "tail": {"type": "boolean", "description": "Read from end of file", "default": False}
+                },
+                "required": ["server", "path"]
+            }
+        ),
+        Tool(
+            name="write_file",
+            description="Overwrite an entire file on remote server via SFTP. WARNING: replaces full file content. For surgical edits on large files, use replace_in_file instead. Requires approval.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "server": {"type": "string", "description": "Server name"},
+                    "path": {"type": "string", "description": "File path"},
+                    "content": {"type": "string", "description": "File content"},
+                    "reason": {"type": "string", "description": "Human-readable explanation of what is being written and why (for audit log)"}
+                },
+                "required": ["server", "path", "content"]
+            }
+        ),
+        Tool(
+            name="transfer_file",
+            description="Transfer a file between local machine and remote server via SFTP. Use direction=upload to send, direction=download to receive.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "server": {"type": "string", "description": "Server name"},
+                    "direction": {"type": "string", "enum": ["upload", "download"], "description": "Transfer direction"},
+                    "local_path": {"type": "string", "description": "Local file path"},
+                    "remote_path": {"type": "string", "description": "Remote file path"},
+                    "reason": {"type": "string", "description": "Human-readable explanation of what is being transferred and why (for audit log)"}
+                },
+                "required": ["server", "direction", "local_path", "remote_path"]
+            }
+        ),
+        Tool(
+            name="service",
+            description="Manage or query a systemd service. Use action=status to check, or start/stop/restart/reload to control. Actions other than status require sudo.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "server": {"type": "string", "description": "Server name"},
+                    "service": {"type": "string", "description": "Service name"},
+                    "action": {"type": "string", "enum": ["status", "start", "stop", "restart", "reload"], "description": "Action to perform"},
+                    "reason": {"type": "string", "description": "Human-readable explanation of why this service action is needed (for audit log)"}
+                },
+                "required": ["server", "service", "action"]
+            }
+        ),
+        Tool(
+            name="search_in_file",
+            description="Search for a text pattern in a remote file using grep. Returns matching lines with line numbers and surrounding context. Use this to locate code sections before editing.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "server": {"type": "string", "description": "Server name"},
+                    "path": {"type": "string", "description": "File path"},
+                    "pattern": {"type": "string", "description": "Grep regex pattern"},
+                    "context_lines": {"type": "integer", "description": "Lines of context around each match", "default": 3},
+                    "max_matches": {"type": "integer", "description": "Maximum number of matches", "default": 20}
+                },
+                "required": ["server", "path", "pattern"]
+            }
+        ),
+        Tool(
+            name="replace_in_file",
+            description="Replace a specific text passage in a remote file without loading the full content. Preferred over write_file for editing large files. Returns error if old_text not found. Supports dry_run preview.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "server": {"type": "string", "description": "Server name"},
+                    "path": {"type": "string", "description": "File path"},
+                    "old_text": {"type": "string", "description": "Exact text to find (multi-line supported)"},
+                    "new_text": {"type": "string", "description": "Replacement text"},
+                    "count": {"type": "integer", "description": "Max replacements (default: 1, 0 = all)", "default": 1},
+                    "dry_run": {"type": "boolean", "description": "Preview changes without applying", "default": False},
+                    "reason": {"type": "string", "description": "Human-readable explanation of what is being changed and why (for audit log)"}
+                },
+                "required": ["server", "path", "old_text", "new_text"]
+            }
+        ),
+        Tool(
+            name="get_file_structure",
+            description="Get an overview of functions, classes and key definitions in a source file. Returns symbol names with line numbers. Use this to understand a large file before reading or editing specific sections.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "server": {"type": "string", "description": "Server name"},
+                    "path": {"type": "string", "description": "File path"},
+                    "language": {"type": "string", "description": "Language hint (auto-detected from extension if omitted)"}
+                },
+                "required": ["server", "path"]
+            }
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    _init()
+
+    if name == "list_servers":
+        server_list = "\n".join(f"  {n}  {cfg.user}@{cfg.host}:{cfg.port}" for n, cfg in servers.items())
+        return [TextContent(type="text", text=server_list)]
+
+    elif name == "execute":
+        srv = arguments["server"]
+        command = arguments.get("command")
+        script = arguments.get("script")
+        use_sudo = arguments.get("use_sudo", False)
+        timeout = max(1, min(arguments.get("timeout", 30), 300))
+
+        if not command and not script:
+            return [TextContent(type="text", text="ERROR: Provide either 'command' or 'script'")]
+
+        # Script mode: write to temp file, execute, clean up
+        if script:
+            import uuid
+            tmp = f"/tmp/_mcp_{uuid.uuid4().hex[:8]}.sh"
+            ssh_client.write_file(srv, tmp, f"#!/bin/bash\n{script}\n")
+            try:
+                result = ssh_client.execute(srv, f"bash {tmp}", use_sudo, timeout)
+                audit.log(srv, "execute", f"script ({len(script)} chars)", arguments.get("reason", ""))
+                return [TextContent(type="text", text=_format_result(result, srv, "execute_script"))]
+            except TimeoutError:
+                return [TextContent(type="text", text=f"[{srv}] execute_script\nTIMEOUT after {timeout}s")]
+            finally:
+                ssh_client.execute(srv, f"rm -f {tmp}")
+
+        # Command mode with streaming
+        cmd = command
+        if _use_streaming:
+            try:
+                ctx = server.request_context
+                rid = ctx.request_id
+                log = ctx.session.send_log_message
+                output_lines, exit_code, stderr_data = [], 0, ""
+                async for line in ssh_client.execute_streaming(srv, cmd, use_sudo, timeout):
+                    if line.startswith("\0EXIT:"):
+                        parts = line[6:].split(":", 1)
+                        exit_code = int(parts[0])
+                        stderr_data = parts[1] if len(parts) > 1 else ""
+                    else:
+                        output_lines.append(line)
+                        await log(level="info", data=line, related_request_id=rid)
+                header = f"[{srv}] $ {cmd}\n"
+                result_parts = []
+                stdout = "\n".join(output_lines)
+                if stdout.strip():
+                    result_parts.append(_truncate_json_lines(stdout))
+                if stderr_data.strip():
+                    result_parts.append(f"STDERR: {stderr_data.rstrip()}")
+                if exit_code == 124:
+                    result_parts.append(f"TIMEOUT after {timeout}s")
+                elif exit_code != 0:
+                    result_parts.append(f"Exit code: {exit_code}")
+                body = "\n".join(result_parts) if result_parts else "(no output)"
+                audit.log(srv, "execute", cmd, arguments.get("reason", ""))
+                return [TextContent(type="text", text=f"{header}{body}")]
+            except Exception as e:
+                import sys
+                print(f"[ssh-mcp] Streaming failed, falling back to non-streaming: {e}", file=sys.stderr)
+
+        try:
+            result = ssh_client.execute(srv, cmd, use_sudo, timeout)
+            audit.log(srv, "execute", cmd, arguments.get("reason", ""))
+            return [TextContent(type="text", text=_format_result(result, srv, cmd))]
+        except TimeoutError:
+            return [TextContent(type="text", text=f"[{srv}] $ {cmd}\nTIMEOUT after {timeout}s. Retry with higher timeout (max 300s).")]
+
+    elif name == "read_file":
+        err = _validate(arguments, "server", "path")
+        if err: return [TextContent(type="text", text=err)]
+        srv = arguments["server"]
+        path = arguments["path"]
+        lines = arguments.get("lines")
+        offset = arguments.get("offset", 0)
+        tail = arguments.get("tail", False)
+        content = ssh_client.read_file(srv, path, lines=lines, offset=offset, tail=tail)
+        return [TextContent(type="text", text=f"[{srv}] {path}\n{content.rstrip()}")]
+
+    elif name == "write_file":
+        err = _validate(arguments, "server", "path")
+        if err: return [TextContent(type="text", text=err)]
+        ssh_client.write_file(arguments["server"], arguments["path"], arguments["content"])
+        audit.log(arguments["server"], "write_file", arguments["path"], arguments.get("reason", ""))
+        return [TextContent(type="text", text=f"[{arguments['server']}] Written: {arguments['path']}")]
+
+    elif name == "transfer_file":
+        srv = arguments["server"]
+        direction = arguments["direction"]
+        local_path = arguments["local_path"]
+        remote_path = arguments["remote_path"]
+        if direction == "upload":
+            ssh_client.upload_file(srv, local_path, remote_path)
+            audit.log(srv, "transfer_file", f"upload {local_path} → {remote_path}", arguments.get("reason", ""))
+            return [TextContent(type="text", text=f"[{srv}] Uploaded: {local_path} → {remote_path}")]
+        else:
+            ssh_client.download_file(srv, remote_path, local_path)
+            return [TextContent(type="text", text=f"[{srv}] Downloaded: {remote_path} → {local_path}")]
+
+    elif name == "service":
+        import re
+        srv = arguments["server"]
+        svc = arguments["service"]
+        action = arguments["action"]
+        if not re.match(r'^[a-zA-Z0-9_.\-@]+$', svc):
+            return [TextContent(type="text", text=f"ERROR: Invalid service name: {svc}")]
+        use_sudo = action != "status"
+        result = ssh_client.execute(srv, f"systemctl {action} {svc}", use_sudo=use_sudo)
+        if action != "status" and result.exit_code == 0:
+            audit.log(srv, "service", f"{action} {svc}", arguments.get("reason", ""))
+            status = ssh_client.execute(srv, f"systemctl status {svc}", use_sudo=False)
+            return [TextContent(type="text", text=f"[{srv}] {svc} → {action} OK\n{status.stdout.rstrip()}")]
+        return [TextContent(type="text", text=_format_result(result, srv, f"systemctl {action} {svc}"))]
+
+    elif name == "search_in_file":
+        err = _validate(arguments, "server", "path", "pattern")
+        if err: return [TextContent(type="text", text=err)]
+        srv = arguments["server"]
+        path = arguments["path"]
+        pattern = arguments["pattern"]
+        ctx_lines = arguments.get("context_lines", 3)
+        max_matches = arguments.get("max_matches", 20)
+        result = ssh_client.search_in_file(srv, path, pattern, ctx_lines, max_matches)
+        return [TextContent(type="text", text=f"[{srv}] grep '{pattern}' {path}\n{result}")]
+
+    elif name == "replace_in_file":
+        err = _validate(arguments, "server", "path")
+        if err: return [TextContent(type="text", text=err)]
+        srv = arguments["server"]
+        path = arguments["path"]
+        old_text = arguments["old_text"]
+        new_text = arguments["new_text"]
+        count = arguments.get("count", 1)
+        dry_run = arguments.get("dry_run", False)
+        result = ssh_client.replace_in_file(srv, path, old_text, new_text, count, dry_run)
+        action = "Preview" if dry_run else "Replaced"
+        if not dry_run:
+            audit.log(srv, "replace_in_file", path, arguments.get("reason", ""))
+        return [TextContent(type="text", text=f"[{srv}] {action} in {path}\n{result}")]
+
+    elif name == "get_file_structure":
+        err = _validate(arguments, "server", "path")
+        if err: return [TextContent(type="text", text=err)]
+        srv = arguments["server"]
+        path = arguments["path"]
+        language = arguments.get("language")
+        result = ssh_client.get_file_structure(srv, path, language)
+        return [TextContent(type="text", text=f"[{srv}] {path}\n{result}")]
+
+    raise ValueError(f"Unknown tool: {name}")
+
+
+async def _async_main_stdio():
+    from mcp.server.stdio import stdio_server
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+async def _async_main_http(host: str, port: int):
+    from starlette.applications import Starlette
+    from starlette.routing import Mount
+    import uvicorn
+    import contextlib
+
+    session_manager = StreamableHTTPSessionManager(app=server, json_response=False)
+
+    async def handle_mcp(scope, receive, send):
+        await session_manager.handle_request(scope, receive, send)
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app):
+        async with session_manager.run():
+            yield
+
+    app = Starlette(
+        routes=[Mount("/mcp", app=handle_mcp)],
+        lifespan=lifespan,
+    )
+    config = uvicorn.Config(app, host=host, port=port)
+    srv = uvicorn.Server(config)
+    await srv.serve()
+
+
+def main():
+    import argparse
+    import asyncio
+
+    parser = argparse.ArgumentParser(description="SSH MCP Server")
+    parser.add_argument("--transport", choices=["stdio", "http"], default="stdio")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8080)
+    args = parser.parse_args()
+
+    if args.transport == "http":
+        asyncio.run(_async_main_http(args.host, args.port))
+    else:
+        asyncio.run(_async_main_stdio())
+
+
+if __name__ == "__main__":
+    main()

ssh_mcp/ssh_client.py

@@ -0,0 +1,226 @@
+import time
+import shlex
+import re
+import paramiko
+from typing import AsyncIterator
+from .models import ServerConfig, CommandResult
+
+
+class SSHClient:
+    CONNECT_TIMEOUT = 10
+    POOL_TTL = 300  # reuse connections for 5 min
+
+    def __init__(self, servers: dict[str, ServerConfig]):
+        self.servers = servers
+        self._pool: dict[str, tuple[paramiko.SSHClient, float]] = {}
+
+    def _get_connection(self, server_name: str) -> paramiko.SSHClient:
+        if server_name not in self.servers:
+            raise ValueError(f"Unknown server: {server_name}")
+
+        # Check pool
+        if server_name in self._pool:
+            client, ts = self._pool[server_name]
+            if time.time() - ts < self.POOL_TTL:
+                try:
+                    transport = client.get_transport()
+                    if transport and transport.is_active():
+                        return client
+                except Exception:
+                    pass
+            # Stale — close and remove
+            try:
+                client.close()
+            except Exception:
+                pass
+            del self._pool[server_name]
+
+        cfg = self.servers[server_name]
+        client = paramiko.SSHClient()
+        client.load_system_host_keys()
+        client.set_missing_host_key_policy(paramiko.WarningPolicy())
+        connect_kwargs = dict(
+            hostname=cfg.host, port=cfg.port, username=cfg.user,
+            timeout=self.CONNECT_TIMEOUT, banner_timeout=self.CONNECT_TIMEOUT,
+            auth_timeout=self.CONNECT_TIMEOUT,
+        )
+        if cfg.key_file:
+            connect_kwargs["key_filename"] = cfg.key_file
+        if cfg.password:
+            connect_kwargs["password"] = cfg.password
+        client.connect(**connect_kwargs)
+        self._pool[server_name] = (client, time.time())
+        return client
+
+    def _exec(self, server_name: str, command: str, use_sudo: bool, timeout: int):
+        client = self._get_connection(server_name)
+        cmd = f"timeout {timeout} bash -c {shlex.quote(command)}"
+        if use_sudo:
+            cmd = f"sudo bash -c {shlex.quote(f'timeout {timeout} bash -c {shlex.quote(command)}')}"
+        channel = client.get_transport().open_session()
+        channel.exec_command(cmd)
+        return client, channel
+
+    def _drain(self, channel) -> tuple[str, str]:
+        out, err = [], []
+        while channel.recv_ready():
+            out.append(channel.recv(4096))
+        while channel.recv_stderr_ready():
+            err.append(channel.recv_stderr(4096))
+        return b"".join(out).decode(), b"".join(err).decode()
+
+    def execute(self, server_name: str, command: str, use_sudo: bool = False, timeout: int = 30) -> CommandResult:
+        client, channel = self._exec(server_name, command, use_sudo, timeout)
+        try:
+            out, err = [], []
+            while True:
+                if channel.recv_ready():
+                    out.append(channel.recv(4096))
+                if channel.recv_stderr_ready():
+                    err.append(channel.recv_stderr(4096))
+                if channel.exit_status_ready() and not channel.recv_ready() and not channel.recv_stderr_ready():
+                    break
+            extra_out, extra_err = self._drain(channel)
+            exit_code = channel.recv_exit_status()
+            stdout_data = b"".join(out).decode() + extra_out
+            stderr_data = b"".join(err).decode() + extra_err
+            if exit_code == 124:
+                raise TimeoutError(f"Command timed out after {timeout}s")
+            return CommandResult(stdout=stdout_data, stderr=stderr_data, exit_code=exit_code)
+        finally:
+            channel.close()
+
+    async def execute_streaming(self, server_name: str, command: str, use_sudo: bool = False, timeout: int = 30) -> AsyncIterator[str]:
+        import asyncio
+        client, channel = self._exec(server_name, command, use_sudo, timeout)
+        try:
+            buf, err_chunks = "", []
+            while True:
+                if channel.recv_stderr_ready():
+                    err_chunks.append(channel.recv_stderr(4096))
+                if channel.recv_ready():
+                    chunk = await asyncio.get_event_loop().run_in_executor(None, channel.recv, 4096)
+                    buf += chunk.decode()
+                    while "\n" in buf:
+                        line, buf = buf.split("\n", 1)
+                        yield line
+                elif channel.exit_status_ready():
+                    break
+                else:
+                    await asyncio.sleep(0.05)
+            while channel.recv_ready():
+                buf += channel.recv(4096).decode()
+            while channel.recv_stderr_ready():
+                err_chunks.append(channel.recv_stderr(4096))
+            if buf.strip():
+                yield buf.strip()
+            exit_code = channel.recv_exit_status()
+            yield f"\0EXIT:{exit_code}:{b''.join(err_chunks).decode()}"
+        finally:
+            channel.close()
+
+    def read_file(self, server_name: str, path: str, lines: int | None = None, offset: int = 0, tail: bool = False) -> str:
+        if lines and tail:
+            cmd = f"tail -n {lines} {shlex.quote(path)}"
+        elif lines:
+            start = offset + 1
+            end = offset + lines
+            cmd = f"sed -n '{start},{end}p' {shlex.quote(path)}"
+        else:
+            cmd = f"cat {shlex.quote(path)}"
+        result = self.execute(server_name, cmd)
+        if result.exit_code != 0:
+            raise RuntimeError(f"Failed to read file: {result.stderr}")
+        return result.stdout
+
+    def write_file(self, server_name: str, path: str, content: str) -> None:
+        client = self._get_connection(server_name)
+        sftp = client.open_sftp()
+        with sftp.file(path, 'w') as f:
+            f.write(content)
+        sftp.close()
+
+    def upload_file(self, server_name: str, local_path: str, remote_path: str) -> None:
+        client = self._get_connection(server_name)
+        sftp = client.open_sftp()
+        sftp.put(local_path, remote_path)
+        sftp.close()
+
+    def download_file(self, server_name: str, remote_path: str, local_path: str) -> None:
+        client = self._get_connection(server_name)
+        sftp = client.open_sftp()
+        sftp.get(remote_path, local_path)
+        sftp.close()
+
+    def search_in_file(self, server_name: str, path: str, pattern: str, context_lines: int = 3, max_matches: int = 20) -> str:
+        result = self.execute(server_name, f"test -f {shlex.quote(path)} && grep -n -C{context_lines} -m{max_matches} -- {shlex.quote(pattern)} {shlex.quote(path)}")
+        if result.exit_code == 1:
+            return "No matches found."
+        if result.exit_code != 0:
+            raise RuntimeError(f"Search failed: {result.stderr}")
+        return result.stdout
+
+    def replace_in_file(self, server_name: str, path: str, old_text: str, new_text: str, count: int = 1, dry_run: bool = False) -> str:
+        import base64
+        b64_old = base64.b64encode(old_text.encode()).decode()
+        b64_new = base64.b64encode(new_text.encode()).decode()
+        script = f"""import sys, base64, difflib
+path, count, dry_run = sys.argv[1], int(sys.argv[2]), sys.argv[3] == "1"
+old = base64.b64decode("{b64_old}").decode()
+new = base64.b64decode("{b64_new}").decode()
+content = open(path).read()
+if old not in content:
+    print("ERROR: old_text not found in file", file=sys.stderr); sys.exit(1)
+result = content.replace(old, new, count) if count > 0 else content.replace(old, new)
+n = content.count(old) if count == 0 else min(count, content.count(old))
+if dry_run:
+    diff = difflib.unified_diff(content.splitlines(), result.splitlines(), lineterm="", fromfile="before", tofile="after", n=3)
+    print("\\n".join(diff))
+else:
+    open(path, "w").write(result)
+    print(f"OK: {{n}} replacement(s) applied")
+"""
+        import uuid
+        tmp = f"/tmp/_mcp_replace_{uuid.uuid4().hex[:8]}.py"
+        try:
+            self.write_file(server_name, tmp, script)
+            result = self.execute(server_name, f"python3 {tmp} {shlex.quote(path)} {count} {'1' if dry_run else '0'}")
+            if result.exit_code != 0:
+                raise RuntimeError(result.stderr.strip())
+            return result.stdout.strip()
+        finally:
+            self.execute(server_name, f"rm -f {tmp}")
+
+    def get_file_structure(self, server_name: str, path: str, language: str | None = None) -> str:
+        if not language:
+            ext = path.rsplit(".", 1)[-1].lower() if "." in path else ""
+            lang_map = {"js": "js", "ts": "js", "tsx": "js", "jsx": "js", "mjs": "js", "py": "py", "go": "go", "rs": "rs", "java": "java", "sh": "sh", "bash": "sh", "zsh": "sh", "c": "c", "h": "c", "cpp": "c", "hpp": "c", "cc": "c", "rb": "rb", "php": "php"}
+            language = lang_map.get(ext, "generic")
+        patterns = {
+            "js": r'^\s*(export\s+)?(async\s+)?function\s|^\s*(export\s+)?(const|let|var)\s+\w+\s*=\s*(async\s+)?\(|^\s*(export\s+)?class\s|^\s*(export\s+)?interface\s|^\s*(export\s+)?type\s|^\s*(export\s+)?enum\s',
+            "py": r'^\s*(class |def |async def )',
+            "go": r'^(func |type )',
+            "rs": r'^\s*(pub\s+)?(fn |struct |enum |impl |trait |mod )',
+            "java": r'^\s*(public|private|protected)?\s*(static\s+)?(class |interface |enum |.*\s+\w+\s*\()',
+            "sh": r'^\s*(\w+\s*\(\)|function\s+\w+)',
+            "c": r'^\s*(static\s+)?(inline\s+)?(void|int|char|float|double|long|unsigned|struct|enum|typedef|#define)\s|^\w+.*\w+\s*\(',
+            "rb": r'^\s*(class |module |def )',
+            "php": r'^\s*(public|private|protected|static)?\s*(function |class |interface |trait )',
+            "generic": r'^\s*(function|class|def|async def|interface|type|struct|impl|pub fn|fn|enum|trait|mod)\s',
+        }
+        pat = patterns.get(language, patterns["generic"])
+        result = self.execute(server_name, f"wc -l < {shlex.quote(path)} && grep -n -E {shlex.quote(pat)} {shlex.quote(path)}")
+        if result.exit_code != 0:
+            raise RuntimeError(f"Failed: {result.stderr}")
+        lines = result.stdout.strip().split("\n")
+        total = lines[0].strip()
+        symbols = "\n".join(lines[1:]) if len(lines) > 1 else "(no symbols found)"
+        return f"({total} lines)\n{symbols}"
+
+    def close_all(self):
+        for name, (client, _) in self._pool.items():
+            try:
+                client.close()
+            except Exception:
+                pass
+        self._pool.clear()