mcp-win-stdio-ssh 0.2.4__py3-none-any.whl

mcp_win_stdio/ssh/__init__.py

@@ -0,0 +1,5 @@
+"""
+Advanced Multi-SSH Connection & Remote Management MCP Server for mcp-win-stdio.
+"""
+
+__version__ = "0.2.4"

mcp_win_stdio/ssh/__main__.py

@@ -0,0 +1,8 @@
+"""
+Direct execution entrypoint: python -m mcp_win_stdio.ssh
+"""
+
+from mcp_win_stdio.ssh.server import mcp
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

mcp_win_stdio/ssh/cli.py

@@ -0,0 +1,152 @@
+"""
+CLI entry point for mcp-win-stdio-ssh.
+"""
+
+import argparse
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import time
+
+# Ensure Windows console uses UTF-8 without crashing on cp1252
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except Exception:
+        pass
+
+from mcp_win_stdio.ssh import __version__
+from mcp_win_stdio.ssh.connection import (
+    SYSTEM_SSH_CONFIG,
+    get_all_registered_hosts,
+    get_active_host_name,
+    resolve_host_info,
+    get_cached_or_connect,
+)
+from mcp_win_stdio.ssh.guide import print_ssh_guide
+from mcp_win_stdio.ssh.server import mcp
+
+
+def cmd_run(args: argparse.Namespace) -> None:
+    """Run SSH MCP server over stdio."""
+    mcp.run()
+
+
+def cmd_doctor(args: argparse.Namespace) -> None:
+    """Run diagnostic checks on SSH drivers, Windows OpenSSH service, keys, and configs."""
+    print(f"\n=== mcp-win-stdio-ssh Doctor Diagnostic (v{__version__}) ===\n")
+    print(f"[OK] Python Runtime: {sys.version.split()[0]} ({sys.executable})")
+
+    # 1. Driver Checks
+    for dep in ("mcp", "paramiko", "cryptography"):
+        try:
+            mod = __import__(dep)
+            ver = getattr(mod, "__version__", "installed")
+            print(f"[OK] Python Module: {dep:<14} (v{ver})")
+        except ImportError:
+            print(f"[FAIL] Python Module: {dep:<14} (MISSING - run `pip install {dep}`)")
+
+    # 2. OpenSSH Windows client check
+    ssh_bin = shutil.which("ssh")
+    if ssh_bin:
+        print(f"[OK] System SSH CLI: {ssh_bin}")
+    else:
+        print(f"[INFO] System SSH CLI: Not on PATH (Optional: Paramiko native SSH client active)")
+
+    # 3. SSH Config & Keys
+    ssh_dir = Path.home() / ".ssh"
+    if ssh_dir.is_dir():
+        print(f"[OK] SSH Directory: {ssh_dir}")
+        if SYSTEM_SSH_CONFIG.exists():
+            print(f"[OK] SSH Config:    {SYSTEM_SSH_CONFIG}")
+        else:
+            print(f"[INFO] SSH Config:   No ~/.ssh/config found (can use add_host or create config)")
+
+        keys = [f.name for f in ssh_dir.iterdir() if f.is_file() and not f.name.endswith(".pub") and "id_" in f.name]
+        if keys:
+            print(f"[OK] Found Keys:     {', '.join(keys)}")
+        else:
+            print(f"[INFO] Found Keys:    No default id_* keys found in ~/.ssh/")
+    else:
+        print(f"[INFO] SSH Directory: {ssh_dir} not created yet.")
+
+    # 4. Registered Hosts
+    hosts = get_all_registered_hosts()
+    active = get_active_host_name()
+    print(f"\n--- Registered Hosts ({len(hosts)}) ---")
+    for name, h in hosts.items():
+        is_act = " (ACTIVE DEFAULT)" if name == active else ""
+        print(f" • {name:<16} -> {h.get('user')}@{h.get('hostname')}:{h.get('port')} [{h.get('source')}]{is_act}")
+
+    print("\nDiagnostic complete.\n")
+
+
+def cmd_test(args: argparse.Namespace) -> None:
+    """Test SSH connectivity and latency to configured hosts."""
+    target = args.host
+    hosts = get_all_registered_hosts()
+
+    if not hosts and not target:
+        print("\n[!] No SSH hosts configured. Use 'add_host' tool or configure ~/.ssh/config.\n")
+        return
+
+    targets = [target] if target else list(hosts.keys())
+
+    print(f"\n=== Testing SSH Connectivity ({len(targets)} host{'s' if len(targets) > 1 else ''}) ===\n")
+
+    for h_name in targets:
+        try:
+            h_info = resolve_host_info(h_name)
+            t_start = time.time()
+            client = get_cached_or_connect(h_info["name"], timeout=10)
+            lat_ms = round((time.time() - t_start) * 1000, 2)
+
+            stdin, stdout, stderr = client.exec_command("uname -srmo 2>/dev/null || ver", timeout=5)
+            os_info = stdout.read().decode("utf-8", errors="replace").strip()
+
+            print(f" [OK] {h_name:<16} -> {h_info.get('user')}@{h_info.get('hostname')}:{h_info.get('port')} ({lat_ms}ms) | {os_info}")
+        except Exception as e:
+            print(f" [FAIL] {h_name:<14} -> Error: {e}")
+
+    print("\nTest complete.\n")
+
+
+def cmd_guide(args: argparse.Namespace) -> None:
+    """Print guide and prompt recipes."""
+    print_ssh_guide()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="mcp-win-stdio-ssh",
+        description="Unified Multi-SSH Connection & Remote Management MCP Server CLI",
+    )
+    parser.add_argument("--version", "-v", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", help="Command to execute")
+
+    sub_guide = subparsers.add_parser("guide", help="View usage guide and recipes")
+    sub_guide.set_defaults(func=cmd_guide)
+
+    sub_doctor = subparsers.add_parser("doctor", help="Check SSH configuration and drivers")
+    sub_doctor.set_defaults(func=cmd_doctor)
+
+    sub_test = subparsers.add_parser("test", help="Test connectivity to configured hosts")
+    sub_test.add_argument("host", nargs="?", help="Specific host name to test")
+    sub_test.set_defaults(func=cmd_test)
+
+    sub_run = subparsers.add_parser("run", help="Run SSH MCP server over stdio")
+    sub_run.set_defaults(func=cmd_run)
+
+    args = parser.parse_args()
+    if hasattr(args, "func"):
+        args.func(args)
+    else:
+        # Default action is run
+        cmd_run(args)
+
+
+if __name__ == "__main__":
+    main()

mcp_win_stdio/ssh/connection.py

@@ -0,0 +1,369 @@
+"""
+SSH Connection Pool and Host Configuration Manager for mcp-win-stdio-ssh.
+Handles ~/.ssh/config auto-discovery, persistent host bookmarks, authentication resolution,
+bastion/jump host tunneling, and resilient connection pooling.
+"""
+
+import json
+import os
+from pathlib import Path
+import re
+import socket
+import sys
+import threading
+import time
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+import paramiko
+from paramiko.config import SSHConfig
+
+from mcp_win_stdio.core.config import INDALA_DIR, ensure_workspace_dirs
+
+SSH_CONFIG_DIR = INDALA_DIR
+HOSTS_CONFIG_FILE = SSH_CONFIG_DIR / "ssh_hosts.json"
+SSH_USER_DIR = Path.home() / ".ssh"
+SYSTEM_SSH_CONFIG = SSH_USER_DIR / "config"
+
+_ACTIVE_HOST: Optional[str] = None
+_CLIENT_POOL: Dict[str, paramiko.SSHClient] = {}
+_POOL_LOCK = threading.RLock()
+
+
+def _normalize_host_param(host: Any) -> Optional[str]:
+    """Normalize host parameter from LLM tool call, filtering out null/empty strings."""
+    if host is None:
+        return None
+    s = str(host).strip()
+    if s.lower() in ("", "null", "none", "undefined", "default"):
+        return None
+    return s
+
+
+def load_ssh_hosts() -> Dict[str, Any]:
+    """Load persistent SSH hosts from ~/.mcp-win-stdio/ssh_hosts.json."""
+    ensure_workspace_dirs()
+    if not HOSTS_CONFIG_FILE.exists():
+        return {}
+    try:
+        with open(HOSTS_CONFIG_FILE, "r", encoding="utf-8") as f:
+            data = json.load(f)
+            return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def save_ssh_hosts(data: Dict[str, Any]) -> None:
+    """Save persistent SSH hosts to ~/.mcp-win-stdio/ssh_hosts.json."""
+    ensure_workspace_dirs()
+    try:
+        with open(HOSTS_CONFIG_FILE, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+    except Exception as e:
+        sys.stderr.write(f"Warning: Failed to save ssh hosts: {e}\n")
+
+
+def get_active_host_name() -> Optional[str]:
+    """Get the currently active host name (memory or persistent)."""
+    global _ACTIVE_HOST
+    if _ACTIVE_HOST:
+        return _ACTIVE_HOST
+    data = load_ssh_hosts()
+    active = data.get("active_host")
+    if active:
+        _ACTIVE_HOST = active
+        return active
+    return None
+
+
+def set_active_host_name(name: Optional[str]) -> None:
+    """Set and persist the active host name."""
+    global _ACTIVE_HOST
+    _ACTIVE_HOST = name
+    data = load_ssh_hosts()
+    data["active_host"] = name
+    save_ssh_hosts(data)
+
+
+def parse_system_ssh_config() -> Dict[str, Dict[str, Any]]:
+    """Parse ~/.ssh/config and return a mapping of host aliases to connection configs."""
+    configs: Dict[str, Dict[str, Any]] = {}
+    if not SYSTEM_SSH_CONFIG.exists():
+        return configs
+
+    try:
+        ssh_cfg = SSHConfig()
+        with open(SYSTEM_SSH_CONFIG, "r", encoding="utf-8", errors="replace") as f:
+            ssh_cfg.parse(f)
+
+        # Iterate through host entries
+        for host in ssh_cfg.get_hostnames():
+            if host == "*":
+                continue
+            entry = ssh_cfg.lookup(host)
+            identity_files = entry.get("identityfile", [])
+            key_path = identity_files[0] if identity_files else None
+            
+            # Resolve ~ in key path
+            if key_path:
+                key_path = str(Path(key_path).expanduser())
+
+            configs[host] = {
+                "name": host,
+                "hostname": entry.get("hostname", host),
+                "user": entry.get("user", os.environ.get("USERNAME", "root")),
+                "port": int(entry.get("port", 22)),
+                "key_path": key_path,
+                "proxyjump": entry.get("proxyjump"),
+                "proxycommand": entry.get("proxycommand"),
+                "source": "ssh_config",
+            }
+    except Exception as e:
+        sys.stderr.write(f"Warning: Failed to parse system SSH config: {e}\n")
+
+    return configs
+
+
+def get_all_registered_hosts() -> Dict[str, Dict[str, Any]]:
+    """Merge SSH config hosts, persistent custom hosts, and env variables."""
+    all_hosts: Dict[str, Dict[str, Any]] = {}
+
+    # 1. System ~/.ssh/config
+    system_hosts = parse_system_ssh_config()
+    all_hosts.update(system_hosts)
+
+    # 2. Persistent ~/.mcp-win-stdio/ssh_hosts.json
+    saved_data = load_ssh_hosts()
+    hosts_dict = saved_data.get("hosts", {})
+    for name, host_data in hosts_dict.items():
+        if isinstance(host_data, dict):
+            entry = dict(host_data)
+            entry["name"] = name
+            entry["source"] = "saved_config"
+            all_hosts[name] = entry
+
+    # 3. Environment variable SSH_SERVERS (JSON format)
+    env_servers = os.environ.get("SSH_SERVERS")
+    if env_servers:
+        try:
+            parsed = json.loads(env_servers)
+            if isinstance(parsed, dict):
+                for name, cfg in parsed.items():
+                    if isinstance(cfg, dict):
+                        entry = dict(cfg)
+                        entry["name"] = name
+                        entry["source"] = "env"
+                        all_hosts[name] = entry
+        except Exception:
+            pass
+
+    return all_hosts
+
+
+def resolve_host_info(target_name: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Resolve connection parameters for a host by name or active default.
+    Supports user@host:port strings or registered aliases.
+    """
+    norm = _normalize_host_param(target_name)
+    host_name = norm or get_active_host_name()
+
+    registered = get_all_registered_hosts()
+
+    if host_name and host_name in registered:
+        return registered[host_name]
+
+    # Check if target is a direct user@hostname:port connection string
+    if host_name and ("@" in host_name or "." in host_name):
+        user = os.environ.get("USERNAME", "root")
+        host_str = host_name
+        port = 22
+
+        if "@" in host_str:
+            user, host_str = host_str.split("@", 1)
+
+        if ":" in host_str:
+            host_str, port_str = host_str.rsplit(":", 1)
+            try:
+                port = int(port_str)
+            except ValueError:
+                port = 22
+
+        return {
+            "name": host_name,
+            "hostname": host_str,
+            "user": user,
+            "port": port,
+            "key_path": None,
+            "source": "ad_hoc",
+        }
+
+    if not host_name:
+        if registered:
+            first_name = next(iter(registered.keys()))
+            set_active_host_name(first_name)
+            return registered[first_name]
+        raise ValueError(
+            "No SSH host specified and no active host is configured. "
+            "Use 'add_host' or provide 'host' parameter."
+        )
+
+    raise ValueError(f"SSH host '{host_name}' not found. Available hosts: {list(registered.keys())}")
+
+
+def _find_default_keys() -> List[str]:
+    """Find default SSH keys in ~/.ssh/ directory."""
+    keys = []
+    if SSH_USER_DIR.is_dir():
+        for key_name in ["id_ed25519", "id_rsa", "id_ecdsa", "id_dsa"]:
+            kp = SSH_USER_DIR / key_name
+            if kp.exists():
+                keys.append(str(kp))
+    return keys
+
+
+def create_ssh_client(
+    host_info: Dict[str, Any],
+    password: Optional[str] = None,
+    passphrase: Optional[str] = None,
+    timeout: int = 15,
+) -> paramiko.SSHClient:
+    """Instantiate and connect a paramiko.SSHClient based on host info."""
+    client = paramiko.SSHClient()
+    client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+
+    hostname = host_info.get("hostname", "localhost")
+    port = int(host_info.get("port", 22))
+    username = host_info.get("user") or os.environ.get("USERNAME", "root")
+    key_path = host_info.get("key_path")
+    pwd = password or host_info.get("password")
+    pass_phrase = passphrase or host_info.get("passphrase")
+
+    key_filename = None
+    if key_path and Path(key_path).expanduser().exists():
+        key_filename = str(Path(key_path).expanduser())
+    else:
+        # Check default keys
+        default_keys = _find_default_keys()
+        if default_keys:
+            key_filename = default_keys[0]
+
+    # Support JumpHost / Bastion if specified
+    sock = None
+    jump_host = host_info.get("jump_host") or host_info.get("proxyjump")
+    if jump_host:
+        jump_info = resolve_host_info(jump_host)
+        jump_client = get_cached_or_connect(jump_info["name"])
+        transport = jump_client.get_transport()
+        if transport and transport.is_active():
+            dest_addr = (hostname, port)
+            local_addr = ("127.0.0.1", 0)
+            sock = transport.open_channel("direct-tcpip", dest_addr, local_addr)
+
+    connect_kwargs: Dict[str, Any] = {
+        "hostname": hostname,
+        "port": port,
+        "username": username,
+        "timeout": timeout,
+        "allow_agent": True,
+        "look_for_keys": True,
+    }
+
+    if sock:
+        connect_kwargs["sock"] = sock
+    if pwd:
+        connect_kwargs["password"] = pwd
+    if key_filename:
+        connect_kwargs["key_filename"] = key_filename
+    if pass_phrase:
+        connect_kwargs["passphrase"] = pass_phrase
+
+    try:
+        client.connect(**connect_kwargs)
+        # Enable keepalive
+        transport = client.get_transport()
+        if transport:
+            transport.set_keepalive(30)
+        return client
+    except Exception as e:
+        client.close()
+        raise ConnectionError(
+            f"Failed to connect to SSH host '{host_info.get('name', hostname)}' ({username}@{hostname}:{port}): {e}"
+        )
+
+
+def get_cached_or_connect(
+    target_name: Optional[str] = None,
+    password: Optional[str] = None,
+    passphrase: Optional[str] = None,
+    timeout: int = 15,
+) -> paramiko.SSHClient:
+    """Retrieve an active SSH client from the pool or establish a new connection."""
+    host_info = resolve_host_info(target_name)
+    name = host_info["name"]
+
+    with _POOL_LOCK:
+        if name in _CLIENT_POOL:
+            client = _CLIENT_POOL[name]
+            transport = client.get_transport()
+            if transport and transport.is_active():
+                return client
+            # Drop dead connection
+            try:
+                client.close()
+            except Exception:
+                pass
+            del _CLIENT_POOL[name]
+
+        client = create_ssh_client(
+            host_info, password=password, passphrase=passphrase, timeout=timeout
+        )
+        _CLIENT_POOL[name] = client
+        return client
+
+
+def close_connection(target_name: Optional[str] = None) -> bool:
+    """Close connection for a specific host in the pool."""
+    norm = _normalize_host_param(target_name)
+    name = norm or get_active_host_name()
+    if not name:
+        return False
+
+    with _POOL_LOCK:
+        if name in _CLIENT_POOL:
+            try:
+                _CLIENT_POOL[name].close()
+            except Exception:
+                pass
+            del _CLIENT_POOL[name]
+            return True
+    return False
+
+
+def close_all_connections() -> int:
+    """Close all open SSH connections in the pool."""
+    closed = 0
+    with _POOL_LOCK:
+        for name, client in list(_CLIENT_POOL.items()):
+            try:
+                client.close()
+                closed += 1
+            except Exception:
+                pass
+        _CLIENT_POOL.clear()
+    return closed
+
+
+def get_pool_status() -> List[Dict[str, Any]]:
+    """Return status of all live connections in the pool."""
+    status = []
+    with _POOL_LOCK:
+        for name, client in _CLIENT_POOL.items():
+            transport = client.get_transport()
+            is_active = transport.is_active() if transport else False
+            status.append({
+                "name": name,
+                "isActive": is_active,
+                "remoteAddress": f"{transport.getpeername()}" if (transport and is_active) else "closed",
+                "isCurrentDefault": name == get_active_host_name(),
+            })
+    return status

mcp_win_stdio/ssh/guide.py

@@ -0,0 +1,94 @@
+"""
+Comprehensive guide, tool reference, and Claude prompt recipes for mcp-win-stdio-ssh.
+"""
+
+def print_ssh_guide() -> None:
+    """Print complete SSH MCP tool reference and workflow recipes."""
+    guide_text = """
+================================================================================
+ 🚀 mcp-win-stdio-ssh — Advanced Multi-SSH Connection & Remote Management
+================================================================================
+
+The SSH MCP server connects AI models directly to remote Linux, macOS, and Windows
+servers over standard SSH, SFTP, and interactive PTY channels.
+
+--------------------------------------------------------------------------------
+ 🌟 Key Architecture & Capabilities
+--------------------------------------------------------------------------------
+ • Multi-Host Pooling: Connect to multiple servers concurrently with connection reuse.
+ • Auto-Discovery: Automatically reads ~/.ssh/config aliases, identity files & proxy jumps.
+ • Sticky Context: 'use_host' sets the default target host across subsequent tool calls.
+ • Interactive PTY: Stateful terminal sessions for long-running processes, REPLs & prompts.
+ • Service & Health: Fast system metrics, systemd/docker/pm2 inspection, and log tailing.
+ • Full SFTP: Remote file reading/writing with token protection, directory recursion.
+ • Local Tunnels: Port forwarding to expose remote MySQL/Postgres/Web services locally.
+
+--------------------------------------------------------------------------------
+ 🛠️ Complete Tool Reference (27 Tools)
+--------------------------------------------------------------------------------
+
+ 1. Host & Connection Management
+    • list_hosts()                      -> List all discovered/saved SSH hosts & status
+    • use_host(host)                    -> Switch active sticky host context
+    • add_host(name, hostname, ...)     -> Save new host to ~/.mcp-win-stdio/ssh_hosts.json
+    • remove_host(name)                 -> Delete saved host configuration
+    • test_host(host=None)              -> Test SSH handshake, auth, latency, and remote OS
+    • list_active_connections()         -> Show live connections in the connection pool
+    • disconnect_host(host=None)        -> Close connection for specific or active host
+
+ 2. Command Execution & Background Jobs
+    • ssh_exec(command, cwd, env, ...)  -> Execute non-interactive command & return exit code
+    • ssh_exec_sudo(command, password)  -> Run command with sudo handling password prompt
+    • ssh_exec_script(script_content)   -> Upload and execute bash/python/sh script
+    • ssh_exec_background(command)      -> Run detached background job (nohup) & get PID
+    • ssh_check_job(job_id_or_pid)      -> Inspect status and logs of background job
+    • ssh_kill_job(pid, signal)         -> Terminate remote process by PID
+
+ 3. Interactive PTY / Shell
+    • ssh_pty_start(session_name)       -> Spawn interactive terminal session
+    • ssh_pty_send(session_name, text)  -> Send command/keystroke and read buffer
+    • ssh_pty_read(session_name)        -> Read output buffer from PTY session
+    • ssh_list_pty_sessions()           -> List open interactive PTY sessions
+    • ssh_pty_close(session_name)       -> Terminate PTY session
+
+ 4. Diagnostics & Remote Services
+    • ssh_system_overview()             -> CPU/RAM/Disk stats, OS distro, kernel, uptime
+    • ssh_list_services(type, filter)   -> List systemd units, docker containers, or pm2 apps
+    • ssh_service_action(name, action)  -> Manage service (status/start/stop/restart/reload)
+    • ssh_tail_logs(target, lines)      -> Tail log files (/var/log/...) or journalctl
+    • ssh_list_processes(sort_by)       -> Top processes by CPU or Memory
+    • ssh_list_packages(manager, ...)   -> Paginated installed packages (apt, dnf, pacman, pip, npm)
+
+ 5. SFTP File Management
+    • sftp_list_dir(remote_path)        -> List directory with permissions & sizes
+    • sftp_read_file(remote_path)       -> Read remote text file with line offset
+    • sftp_write_file(remote_path, ...) -> Write or append remote file
+    • sftp_stat(remote_path)            -> Get file/folder permissions & metadata
+    • sftp_mkdir(remote_path)           -> Create remote directory
+    • sftp_remove(remote_path)          -> Delete remote file or directory
+    • sftp_upload(local_path, remote)   -> Upload file or folder recursively
+    • sftp_download(remote, local_path) -> Download file or folder recursively
+
+ 6. Port Forwarding & Tunnels
+    • ssh_tunnel_open(local, remote)    -> Forward remote port to 127.0.0.1:<local_port>
+    • ssh_tunnel_list()                 -> List active local tunnels
+    • ssh_tunnel_close(tunnel_id)       -> Terminate active tunnel
+
+--------------------------------------------------------------------------------
+ 💡 Example Claude Workflows & Prompts
+--------------------------------------------------------------------------------
+
+ 1. Remote Diagnostics:
+    "Check the health and disk usage of production-server, then list any failed systemd services."
+
+ 2. Deploy Application & Check Logs:
+    "Upload ./dist to /var/www/my-app on web-01, restart the nginx service, and tail the error log."
+
+ 3. Database Tunneling:
+    "Open a local tunnel from port 15432 to remote Postgres port 5432 on db-cluster, then check table counts."
+
+ 4. Interactive Configuration:
+    "Start an interactive PTY session on staging-server and run the configuration script."
+================================================================================
+"""
+    print(guide_text)