mcp-ssh-session 0.1.0__tar.gz

mcp_ssh_session-0.1.0/.github/workflows/publish.yaml

@@ -0,0 +1,37 @@
+name: Publish package to PyPI
+
+on:
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/mcp-ssh-session/
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

mcp_ssh_session-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Local test files
+test_local.py

mcp_ssh_session-0.1.0/CLAUDE.md

@@ -0,0 +1,198 @@
+# MCP SSH Session
+
+An MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions, allowing them to execute commands on remote hosts while maintaining connection state.
+
+## Overview
+
+This MCP server provides tools for AI agents to:
+- Establish persistent SSH connections to remote hosts
+- Execute commands within existing sessions
+- Manage multiple concurrent SSH sessions
+- Track and close active connections
+
+## Features
+
+- **Persistent Sessions**: SSH connections are reused across multiple command executions, reducing connection overhead
+- **SSH Config Support**: Automatically reads and uses settings from `~/.ssh/config`, including aliases, hosts, ports, users, and identity files
+- **Multi-host Support**: Manage connections to multiple hosts simultaneously
+- **Automatic Reconnection**: Dead connections are detected and automatically re-established
+- **Thread-safe**: Safe for concurrent operations
+- **Flexible Authentication**: Supports both password and key-based authentication
+- **Network Device Support**: Automatic enable mode handling for routers and switches (Cisco, Juniper, etc.)
+- **Sudo Support**: Automatic password handling for sudo commands on Unix/Linux hosts
+- **Interactive Shell Handling**: Detects and responds to password prompts automatically
+
+## Installation
+
+Using `uvx`:
+
+```bash
+uvx mcp-ssh-session
+```
+
+Using `uv`:
+
+```bash
+uv venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install -e .
+```
+
+## Usage
+
+### Running the Server
+
+```bash
+uvx mcp-ssh-session
+```
+
+### Available Tools
+
+#### `execute_command`
+Execute a command on an SSH host using a persistent session.
+
+The `host` parameter can be either a hostname/IP or an SSH config alias. If an SSH config alias is provided, configuration will be read from `~/.ssh/config`.
+
+**Parameters:**
+- `host` (str, required): Hostname, IP address, or SSH config alias (e.g., "myserver")
+- `command` (str, required): Command to execute
+- `username` (str, optional): SSH username (will use SSH config or current user if not provided)
+- `password` (str, optional): Password for authentication
+- `key_filename` (str, optional): Path to SSH private key file (will use SSH config if not provided)
+- `port` (int, optional): SSH port (will use SSH config or default 22 if not provided)
+- `enable_password` (str, optional): Password for enable mode on network devices (routers/switches)
+- `enable_command` (str, optional): Command to enter enable mode (default: "enable")
+- `sudo_password` (str, optional): Password for sudo commands on Unix/Linux hosts
+- `timeout` (int, optional): Timeout in seconds for command execution (default: 30)
+
+**Returns:** Command output including exit status, stdout, and stderr
+
+**Examples:**
+
+Using SSH config alias:
+```python
+# If ~/.ssh/config has an entry for "myserver"
+execute_command(
+    host="myserver",
+    command="ls -la /var/log"
+)
+```
+
+Using explicit parameters:
+```python
+execute_command(
+    host="example.com",
+    username="user",
+    command="ls -la /var/log",
+    key_filename="~/.ssh/id_rsa"
+)
+```
+
+Network device with enable mode (Cisco router/switch):
+```python
+execute_command(
+    host="router.example.com",
+    username="admin",
+    password="ssh_password",
+    enable_password="enable_password",
+    command="show running-config"
+)
+```
+
+Unix/Linux host with sudo:
+```python
+execute_command(
+    host="server.example.com",
+    username="user",
+    sudo_password="user_password",
+    command="systemctl restart nginx"  # Auto-prefixed with 'sudo'
+)
+```
+
+Custom enable command (Juniper):
+```python
+execute_command(
+    host="juniper-switch",
+    username="admin",
+    password="ssh_password",
+    enable_password="root_password",
+    enable_command="su -",
+    command="show configuration"
+)
+```
+
+#### `list_sessions`
+List all active SSH sessions.
+
+**Returns:** List of active sessions in format `username@host:port`
+
+#### `close_session`
+Close a specific SSH session.
+
+**Parameters:**
+- `host` (str): Hostname or IP address
+- `username` (str): SSH username
+- `port` (int, default=22): SSH port
+
+#### `close_all_sessions`
+Close all active SSH sessions.
+
+## Project Structure
+
+```
+mcp-ssh-session/
+├── mcp_ssh_session/
+│   ├── __init__.py
+│   ├── __main__.py          # Entry point
+│   ├── server.py            # MCP server and tool definitions
+│   └── session_manager.py   # SSH session management logic
+├── pyproject.toml
+└── CLAUDE.md
+```
+
+## Architecture
+
+### SSHSessionManager
+The core session management class that:
+- Loads and parses `~/.ssh/config` on initialization
+- Resolves SSH config aliases to actual connection parameters
+- Maintains a dictionary of active SSH connections keyed by `username@host:port`
+- Provides thread-safe access to sessions via a threading lock
+- Automatically detects and removes dead connections
+- Reuses existing connections when possible
+- Falls back to sensible defaults when config is not available
+- Handles interactive prompts for enable mode and sudo authentication
+- Tracks enable mode state per session to avoid re-authentication
+- Uses `exec_command()` for standard SSH hosts and `invoke_shell()` for interactive scenarios
+
+### MCP Server
+Built with FastMCP, exposing SSH functionality as MCP tools that can be called by AI agents.
+
+## Security Considerations
+
+- Uses Paramiko's `AutoAddPolicy` for host key verification (accepts new host keys automatically)
+- Passwords and keys are handled in memory only
+- Sessions are properly closed when no longer needed
+- Thread-safe operations prevent race conditions
+
+## Dependencies
+
+- `fastmcp`: MCP server framework
+- `paramiko>=3.4.0`: SSH protocol implementation
+
+## Development
+
+The project uses Python 3.10+ and is structured as a standard Python package.
+
+### Key Components
+
+- **[server.py](mcp_ssh_session/server.py)**: MCP tool definitions and request handling
+- **[session_manager.py](mcp_ssh_session/session_manager.py)**: Core SSH session lifecycle management
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for details.
+
+## Contributing
+
+[Add contribution guidelines]

mcp_ssh_session-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jon
+
+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_session-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: mcp-ssh-session
+Version: 0.1.0
+Summary: MCP server for managing persistent SSH sessions
+Project-URL: Homepage, https://github.com/devnullvoid/mcp-ssh-session
+Project-URL: Repository, https://github.com/devnullvoid/mcp-ssh-session
+Project-URL: Issues, https://github.com/devnullvoid/mcp-ssh-session/issues
+Author: Jon
+License: MIT License
+        
+        Copyright (c) 2024 Jon
+        
+        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.
+License-File: LICENSE
+Keywords: cli,fastmcp,mcp,ssh
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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.10
+Requires-Dist: fastmcp
+Requires-Dist: paramiko>=3.4.0
+Description-Content-Type: text/markdown
+
+# MCP SSH Session
+
+An MCP (Model Context Protocol) server that enables AI agents to establish and manage persistent SSH sessions.
+
+## Features
+
+- **Persistent Sessions**: SSH connections are reused across multiple command executions
+- **SSH Config Support**: Automatically reads and uses settings from `~/.ssh/config`
+- **Multi-host Support**: Manage connections to multiple hosts simultaneously
+- **Automatic Reconnection**: Dead connections are detected and automatically re-established
+- **Thread-safe**: Safe for concurrent operations
+- **Network Device Support**: Automatic enable mode handling for routers and switches
+- **Sudo Support**: Automatic password handling for sudo commands on Unix/Linux hosts
+- **File Operations**: Safe helpers to read and write remote files over SFTP
+
+## Installation
+
+### Using `uvx`
+
+```bash
+uvx mcp-ssh-session
+```
+
+### Using Claude Code
+
+Add to your `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "ssh-session": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-ssh-session"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Using MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector uvx mcp-ssh-session
+```
+
+### Development Installation
+
+```bash
+uv venv
+source .venv/bin/activate
+uv pip install -e .
+```
+
+## Usage
+
+### Available Tools
+
+#### `execute_command`
+Execute a command on an SSH host using a persistent session.
+
+**Using SSH config alias:**
+```json
+{
+  "host": "myserver",
+  "command": "uptime"
+}
+```
+
+**Using explicit parameters:**
+```json
+{
+  "host": "example.com",
+  "username": "user",
+  "command": "ls -la",
+  "key_filename": "~/.ssh/id_rsa",
+  "port": 22
+}
+```
+
+**Network device with enable mode:**
+```json
+{
+  "host": "router.example.com",
+  "username": "admin",
+  "password": "ssh_password",
+  "enable_password": "enable_password",
+  "command": "show running-config"
+}
+```
+
+**Unix/Linux with sudo:**
+```json
+{
+  "host": "server.example.com",
+  "username": "user",
+  "sudo_password": "user_password",
+  "command": "systemctl restart nginx"
+}
+```
+
+#### `list_sessions`
+List all active SSH sessions.
+
+#### `close_session`
+Close a specific SSH session.
+
+```json
+{
+  "host": "myserver"
+}
+```
+
+#### `close_all_sessions`
+Close all active SSH sessions.
+
+#### `read_file`
+Read the contents of a remote file via SFTP.
+
+```json
+{
+  "host": "myserver",
+  "remote_path": "/etc/nginx/nginx.conf",
+  "max_bytes": 131072
+}
+```
+
+- Uses persistent SSH sessions and opens short-lived SFTP channels
+- Enforces a 2 MB maximum per request (configurable per call up to that limit)
+- Returns truncated notice when the content size exceeds the requested limit
+
+#### `write_file`
+Write text content to a remote file via SFTP.
+
+```json
+{
+  "host": "myserver",
+  "remote_path": "/tmp/app.env",
+  "content": "DEBUG=true\n",
+  "append": true,
+  "make_dirs": true
+}
+```
+
+- Content larger than 2 MB is rejected for safety
+- Optional `append` mode to add to existing files
+- Optional `make_dirs` flag will create missing parent directories
+- Supports `permissions` to set octal file modes after write (e.g., `420` for `0644`)
+
+## SSH Config Support
+
+The server automatically reads `~/.ssh/config` and supports:
+- Host aliases
+- Hostname mappings
+- Port configurations
+- User specifications
+- IdentityFile settings
+
+Example `~/.ssh/config`:
+```
+Host myserver
+    HostName example.com
+    User myuser
+    Port 2222
+    IdentityFile ~/.ssh/id_rsa
+```
+
+Then simply use:
+```json
+{
+  "host": "myserver",
+  "command": "uptime"
+}
+```
+
+## Documentation
+
+See [CLAUDE.md](CLAUDE.md) for detailed documentation.
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for details.