mcp-ssh-reloaded 0.1.0__tar.gz

mcp_ssh_reloaded-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright © 2025 Jon Rogers
+
+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.

mcp_ssh_reloaded-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: mcp-ssh-reloaded
+Version: 0.1.0
+Summary: MCP server for SSH sessions management.
+Author: Jon Rogers <devnullvoid>
+Author-email: AmritaConstant <admin@amritabot.com>
+License: Copyright © 2025 Jon Rogers
+        
+        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.
+Project-URL: Homepage, https://github.com/AmritaBot/mcp-ssh-reloaded
+Project-URL: Repository, https://github.com/AmritaBot/mcp-ssh-reloaded
+Project-URL: Issues, https://github.com/AmritaBot/mcp-ssh-reloaded/issues
+Keywords: mcp,ssh,fastmcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp>=3.2.0
+Requires-Dist: paramiko>=3.4.0
+Requires-Dist: pyte>=0.8.0
+Dynamic: license-file
+
+# MCP SSH Session
+
+An MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions.
+
+## Features
+
+- **Smart Command Execution** — auto-transitions to async mode if timeout is reached
+- **Persistent Sessions** — SSH connections reused across commands
+- **Async Commands** — non-blocking execution for long-running tasks
+- **SSH Config Support** — reads `~/.ssh/config` for aliases, ports, keys
+- **Multi-host** — manage connections to multiple hosts simultaneously
+- **Network Devices** — enable mode handling for Cisco, Juniper, MikroTik, etc.
+- **Sudo Support** — automatic password handling for Unix/Linux hosts
+- **File Operations** — read/write remote files via SFTP (sudo fallback)
+- **Command Interruption** — send Ctrl+C to stop running commands
+- **Thread-safe** — safe for concurrent operations
+
+## Quick Start
+
+### Install
+
+```bash
+uvx mcp-ssh-reloaded
+```
+
+### Development
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+```
+
+### CLI
+
+```bash
+# MCP server (default)
+mcp-ssh-reloaded serve mcp
+
+# Direct execution (no MCP)
+mcp-ssh-reloaded exec myserver "uname -a" -u admin
+
+# List / close sessions
+mcp-ssh-reloaded list
+mcp-ssh-reloaded close-all
+```
+
+### MCP Client Config
+
+**Claude Code / Desktop** (`~/.claude.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ssh-session": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-ssh-reloaded", "serve", "mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Quick Examples
+
+```json
+// SSH config alias
+{ "host": "myserver", "command": "uptime" }
+
+// Explicit params
+{ "host": "example.com", "username": "user", "command": "ls -la", "port": 2222 }
+
+// Network device (Cisco enable mode)
+{ "host": "router", "username": "admin", "enable_password": "secret", "command": "show run" }
+
+// Unix with sudo
+{ "host": "server", "username": "ops", "sudo_password": "secret", "command": "systemctl restart nginx" }
+```
+
+---
+
+> **Full API reference:** [API-DOCS.md](./API-DOCS.md) — all types, all methods, all MCP tools, error handling, server config tunables.
+
+## SSH Config
+
+`~/.ssh/config` is read automatically:
+
+```
+Host myserver
+    HostName example.com
+    User myuser
+    Port 2222
+    IdentityFile ~/.ssh/id_rsa
+```
+
+Then use `"host": "myserver"` — the rest is resolved for you.
+
+## Credential Hiding (OVRD\_\*)
+
+For production environments, store real credentials in env vars so AI agents only see aliases:
+
+| Variable                   | Description             |
+| -------------------------- | ----------------------- |
+| `OVRD_{alias}_HOST`        | Real hostname or IP     |
+| `OVRD_{alias}_PORT`        | SSH port                |
+| `OVRD_{alias}_USER`        | SSH username            |
+| `OVRD_{alias}_PASS`        | SSH password            |
+| `OVRD_{alias}_KEY`         | Path to SSH private key |
+| `OVRD_{alias}_SUDO_PASS`   | Sudo password           |
+| `OVRD_{alias}_ENABLE_PASS` | Enable password         |
+
+**Example config:**
+
+```json
+{
+  "mcpServers": {
+    "ssh-session": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-ssh-reloaded", "serve", "mcp"],
+      "env": {
+        "OVRD_prod_db_HOST": "192.168.1.100",
+        "OVRD_prod_db_USER": "admin",
+        "OVRD_prod_db_PASS": "secret123",
+        "OVRD_prod_db_SUDO_PASS": "sudopass"
+      }
+    }
+  }
+}
+```
+
+The agent uses `"host": "prod_db"` — never sees real IPs or passwords.
+
+## How It Works
+
+Commands run inside persistent interactive shells:
+
+- **Directory persists**: `cd /tmp` stays in `/tmp` for the next command
+- **Env vars persist**: `export FOO=bar` is visible across commands
+- **Prompt detection**: completion detected via captured prompt or idle timeout (2 s)
+- **Session recovery**: stuck shells auto-reset after repeated prompt-detection failures
+
+## Docs
+
+| Doc | Topic |
+|-----|-------|
+| [API-DOCS.md](./API-DOCS.md) | Full API reference — types, SSHService methods, MCP tools, error model |
+| [docs/ASYNC_COMMANDS.md](./docs/ASYNC_COMMANDS.md) | Smart execution & async command lifecycle |
+| [docs/INTERACTIVE_MODE.md](./docs/INTERACTIVE_MODE.md) | Terminal emulation, screen snapshots, key sending |
+| [docs/SAFETY_PROTECTIONS.md](./docs/SAFETY_PROTECTIONS.md) | Limits, timeouts, session recovery, error handling |
+| [docs/DOCKER.md](./docs/DOCKER.md) | Running via Docker |
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Fork
+
+Fork of [devnullvoid/mcp-ssh-session](https://github.com/devnullvoid/mcp-ssh-session) with significant refactoring by [AmritaConstant](https://github.com/AmritaBot).

mcp_ssh_reloaded-0.1.0/README.md

@@ -0,0 +1,160 @@
+# MCP SSH Session
+
+An MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions.
+
+## Features
+
+- **Smart Command Execution** — auto-transitions to async mode if timeout is reached
+- **Persistent Sessions** — SSH connections reused across commands
+- **Async Commands** — non-blocking execution for long-running tasks
+- **SSH Config Support** — reads `~/.ssh/config` for aliases, ports, keys
+- **Multi-host** — manage connections to multiple hosts simultaneously
+- **Network Devices** — enable mode handling for Cisco, Juniper, MikroTik, etc.
+- **Sudo Support** — automatic password handling for Unix/Linux hosts
+- **File Operations** — read/write remote files via SFTP (sudo fallback)
+- **Command Interruption** — send Ctrl+C to stop running commands
+- **Thread-safe** — safe for concurrent operations
+
+## Quick Start
+
+### Install
+
+```bash
+uvx mcp-ssh-reloaded
+```
+
+### Development
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+```
+
+### CLI
+
+```bash
+# MCP server (default)
+mcp-ssh-reloaded serve mcp
+
+# Direct execution (no MCP)
+mcp-ssh-reloaded exec myserver "uname -a" -u admin
+
+# List / close sessions
+mcp-ssh-reloaded list
+mcp-ssh-reloaded close-all
+```
+
+### MCP Client Config
+
+**Claude Code / Desktop** (`~/.claude.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ssh-session": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-ssh-reloaded", "serve", "mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Quick Examples
+
+```json
+// SSH config alias
+{ "host": "myserver", "command": "uptime" }
+
+// Explicit params
+{ "host": "example.com", "username": "user", "command": "ls -la", "port": 2222 }
+
+// Network device (Cisco enable mode)
+{ "host": "router", "username": "admin", "enable_password": "secret", "command": "show run" }
+
+// Unix with sudo
+{ "host": "server", "username": "ops", "sudo_password": "secret", "command": "systemctl restart nginx" }
+```
+
+---
+
+> **Full API reference:** [API-DOCS.md](./API-DOCS.md) — all types, all methods, all MCP tools, error handling, server config tunables.
+
+## SSH Config
+
+`~/.ssh/config` is read automatically:
+
+```
+Host myserver
+    HostName example.com
+    User myuser
+    Port 2222
+    IdentityFile ~/.ssh/id_rsa
+```
+
+Then use `"host": "myserver"` — the rest is resolved for you.
+
+## Credential Hiding (OVRD\_\*)
+
+For production environments, store real credentials in env vars so AI agents only see aliases:
+
+| Variable                   | Description             |
+| -------------------------- | ----------------------- |
+| `OVRD_{alias}_HOST`        | Real hostname or IP     |
+| `OVRD_{alias}_PORT`        | SSH port                |
+| `OVRD_{alias}_USER`        | SSH username            |
+| `OVRD_{alias}_PASS`        | SSH password            |
+| `OVRD_{alias}_KEY`         | Path to SSH private key |
+| `OVRD_{alias}_SUDO_PASS`   | Sudo password           |
+| `OVRD_{alias}_ENABLE_PASS` | Enable password         |
+
+**Example config:**
+
+```json
+{
+  "mcpServers": {
+    "ssh-session": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-ssh-reloaded", "serve", "mcp"],
+      "env": {
+        "OVRD_prod_db_HOST": "192.168.1.100",
+        "OVRD_prod_db_USER": "admin",
+        "OVRD_prod_db_PASS": "secret123",
+        "OVRD_prod_db_SUDO_PASS": "sudopass"
+      }
+    }
+  }
+}
+```
+
+The agent uses `"host": "prod_db"` — never sees real IPs or passwords.
+
+## How It Works
+
+Commands run inside persistent interactive shells:
+
+- **Directory persists**: `cd /tmp` stays in `/tmp` for the next command
+- **Env vars persist**: `export FOO=bar` is visible across commands
+- **Prompt detection**: completion detected via captured prompt or idle timeout (2 s)
+- **Session recovery**: stuck shells auto-reset after repeated prompt-detection failures
+
+## Docs
+
+| Doc | Topic |
+|-----|-------|
+| [API-DOCS.md](./API-DOCS.md) | Full API reference — types, SSHService methods, MCP tools, error model |
+| [docs/ASYNC_COMMANDS.md](./docs/ASYNC_COMMANDS.md) | Smart execution & async command lifecycle |
+| [docs/INTERACTIVE_MODE.md](./docs/INTERACTIVE_MODE.md) | Terminal emulation, screen snapshots, key sending |
+| [docs/SAFETY_PROTECTIONS.md](./docs/SAFETY_PROTECTIONS.md) | Limits, timeouts, session recovery, error handling |
+| [docs/DOCKER.md](./docs/DOCKER.md) | Running via Docker |
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+## Fork
+
+Fork of [devnullvoid/mcp-ssh-session](https://github.com/devnullvoid/mcp-ssh-session) with significant refactoring by [AmritaConstant](https://github.com/AmritaBot).

mcp_ssh_reloaded-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "mcp-ssh-reloaded"
+version = "0.1.0"
+description = "MCP server for SSH sessions management."
+requires-python = ">=3.10, <3.14"
+readme = "README.md"
+authors = [
+  { name = "Jon Rogers <devnullvoid>" },
+  { name = "AmritaConstant", email = "admin@amritabot.com" },
+]
+license = { file = "LICENSE" }
+keywords = ["mcp", "ssh", "fastmcp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: System :: Networking",
+  "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "fastmcp>=3.2.0",
+    "paramiko>=3.4.0",
+    "pyte>=0.8.0",
+]
+
+[project.scripts]
+mcp-ssh = "mcp_ssh_reloaded.__main__:main"
+mcp-ssh-reloaded = "mcp_ssh_reloaded.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/AmritaBot/mcp-ssh-reloaded"
+Repository = "https://github.com/AmritaBot/mcp-ssh-reloaded"
+Issues = "https://github.com/AmritaBot/mcp-ssh-reloaded/issues"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.411",
+    "pytest>=9.0.1",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.21",
+]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+[tool.ruff.lint]
+select = [
+  "F",     # Pyflakes
+  "W",     # pycodestyle warnings
+  "E",     # pycodestyle errors
+  "UP",    # pyupgrade
+  "ASYNC", # flake8-async
+  "C4",    # flake8-comprehensions
+  "T10",   # flake8-debugger
+  "PYI",   # flake8-pyi
+  "PT",    # flake8-pytest-style
+  "Q",     # flake8-quotes
+  "RUF",   # Ruff-specific rules
+  "I",     # isort
+  "PERF",  # pylint-performance
+]
+ignore = [
+  "E501",   # line-too-long
+  "UP037",  # quoted-annotation
+  "RUF001", # ambiguous-unicode-character-string
+  "RUF002", # ambiguous-unicode-character-docstring
+  "RUF003", # ambiguous-unicode-character-comment
+]
+
+
+[tool.pyright]
+typeCheckingMode = "standard"
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+typeCheckingMode = "basic"

mcp_ssh_reloaded-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_ssh_reloaded-0.1.0/src/mcp_ssh_reloaded/__init__.py

@@ -0,0 +1,32 @@
+"""MCP SSH Session server — persistent SSH sessions for AI agents."""
+
+from .api_types import (
+    CommandResult,
+    CommandStatus,
+    ConnectionParams,
+    DeviceFamily,
+    ErrorCategory,
+    FileContent,
+    ServerConfig,
+    SessionDiagnostics,
+    SessionInfo,
+    SSHError,
+)
+from .server import mcp
+from .services import SSHService
+
+__version__ = "0.3.0"
+__all__ = [
+    "CommandResult",
+    "CommandStatus",
+    "ConnectionParams",
+    "DeviceFamily",
+    "ErrorCategory",
+    "FileContent",
+    "SSHError",
+    "SSHService",
+    "ServerConfig",
+    "SessionDiagnostics",
+    "SessionInfo",
+    "mcp",
+]

mcp_ssh_reloaded-0.1.0/src/mcp_ssh_reloaded/__main__.py

@@ -0,0 +1,150 @@
+"""Entry point for mcp-ssh.
+
+Supports multiple modes:
+    mcp-ssh serve mcp          # MCP stdio server (default)
+    mcp-ssh serve http         # MCP Streamable HTTP server
+    mcp-ssh serve sse          # MCP SSE server
+    mcp-ssh exec <host> <cmd>  # Direct execution (no MCP)
+    mcp-ssh list               # List active sessions
+    mcp-ssh close <host>       # Close a session
+"""
+
+import argparse
+import sys
+
+from .api_types import ConnectionParams
+from .services import SSHService
+
+
+def main(argv: list[str] | None = None) -> None:
+    from .logging_manager import get_logger
+
+    _log = get_logger("cli")
+
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = argparse.ArgumentParser(
+        prog="mcp-ssh",
+        description="MCP SSH Session server",
+    )
+    sub = parser.add_subparsers(dest="mode")
+
+    # serve <sub-mode>
+    serve_p = sub.add_parser("serve", help="Start a server")
+    serve_sub = serve_p.add_subparsers(dest="serve_mode", required=True)
+    serve_sub.add_parser("mcp", help="MCP stdio server (default)")
+
+    http_p = serve_sub.add_parser("http", help="MCP Streamable HTTP server")
+    http_p.add_argument(
+        "--host", default="127.0.0.1", help="Listen host (default: 127.0.0.1)"
+    )
+    http_p.add_argument(
+        "--port", type=int, default=8000, help="Listen port (default: 8000)"
+    )
+
+    sse_p = serve_sub.add_parser("sse", help="MCP SSE server")
+    sse_p.add_argument(
+        "--host", default="127.0.0.1", help="Listen host (default: 127.0.0.1)"
+    )
+    sse_p.add_argument(
+        "--port", type=int, default=8000, help="Listen port (default: 8000)"
+    )
+
+    # exec <host> <command...>
+    exec_p = sub.add_parser("exec", help="Execute a command directly")
+    exec_p.add_argument("host")
+    exec_p.add_argument("command", nargs="+")
+    exec_p.add_argument("-u", "--user")
+    exec_p.add_argument("-p", "--port", type=int, default=22)
+    exec_p.add_argument("-k", "--key")
+    exec_p.add_argument("--sudo-password")
+    exec_p.add_argument("-t", "--timeout", type=int, default=30)
+
+    # list
+    sub.add_parser("list", help="List active sessions")
+
+    # close <host>
+    close_p = sub.add_parser("close", help="Close a session")
+    close_p.add_argument("host")
+    close_p.add_argument("-u", "--user")
+    close_p.add_argument("-p", "--port", type=int, default=22)
+
+    # close-all
+    sub.add_parser("close-all", help="Close all sessions")
+
+    args = parser.parse_args(argv)
+
+    if args.mode is None:
+        _run_mcp()
+    elif args.mode == "serve":
+        if args.serve_mode == "mcp":
+            _run_mcp()
+        elif args.serve_mode == "http":
+            _run_mcp(transport="streamable-http", host=args.host, port=args.port)
+        elif args.serve_mode == "sse":
+            _run_mcp(transport="sse", host=args.host, port=args.port)
+        else:
+            _run_mcp()
+    elif args.mode == "exec":
+        _run_exec(args)
+    elif args.mode == "list":
+        _run_list()
+    elif args.mode == "close":
+        _run_close(args)
+    elif args.mode == "close-all":
+        _run_close_all()
+    else:
+        _run_mcp()
+
+
+def _run_mcp(transport: str = "stdio", **kwargs: object) -> None:
+    from .server import mcp
+
+    mcp.run(transport=transport, **kwargs)  # type: ignore[arg-type]
+
+
+def _run_exec(args) -> None:
+    svc = SSHService()
+    conn = ConnectionParams(
+        host=args.host,
+        port=args.port,
+        username=args.user,
+        key_filename=args.key,
+        sudo_password=args.sudo_password,
+    )
+    cmd = " ".join(args.command)
+    result = svc.execute(conn, cmd, timeout=args.timeout)
+    if result.stdout:
+        sys.stdout.write(result.stdout)
+    if result.stderr:
+        sys.stderr.write(result.stderr)
+    sys.exit(result.exit_code)
+
+
+def _run_list() -> None:
+    svc = SSHService()
+    sessions = svc.list_sessions()
+    if not sessions:
+        print("No active SSH sessions")
+        return
+    for s in sessions:
+        print(f"  {s.session_key}")
+
+
+def _run_close(args) -> None:
+    svc = SSHService()
+    svc.close_session(
+        ConnectionParams(host=args.host, username=args.user, port=args.port)
+    )
+    print(f"Closed: {args.user or '(default)'}@{args.host}:{args.port}")
+
+
+def _run_close_all() -> None:
+    svc = SSHService()
+    svc.close_all()
+    print("All SSH sessions closed")
+
+
+if __name__ == "__main__":
+    main()