ssh-mcp-dev

# SSH MCP Server Development Guide

## Project Overview

- **Project Name**: ssh-licco
- **Description**: SSH Model Context Protocol Server - Enable SSH functionality for AI models
- **Repository**: https://github.com/Echoqili/ssh-licco
- **Current Version**: 1.6.0 (stored in `ssh_mcp/__init__.py`)
- **Python**: >=3.10, <3.14
- **License**: MIT

## Project Structure

```
ssh-mcp/
├── ssh_mcp/                    # Main source code
│   ├── __init__.py            # Version info (main version file)
│   ├── server.py              # MCP server implementation (SSHMCPServer)
│   ├── service.py             # SSH service protocol & connection info
│   ├── config_manager.py      # Config file management (hosts.json)
│   ├── session_manager.py     # SSH session lifecycle management
│   ├── connection_config.py   # Pydantic connection config model
│   ├── connection_pool.py     # Connection pool with health check
│   ├── executor.py            # Thread pool executor (async bridge)
│   ├── batch_executor.py      # Batch command execution across hosts
│   ├── key_manager.py         # SSH key pair generation (RSA/Ed25519)
│   ├── security.py            # Multi-level security (command/path validation)
│   ├── audit_logger.py        # Structured audit logging
│   ├── logging_config.py      # Centralized logging (SSHLogger singleton)
│   ├── watchdog.py            # Task monitoring & health check
│   ├── exceptions.py         # Custom exception hierarchy
│   ├── cli.py                # Python entry point (simplified to only start server)
│   └── clients/               # SSH client implementations
│       ├── __init__.py        # Exports: SSHClientInterface, ClientType, etc.
│       ├── interface.py       # Abstract base class + data models
│       ├── factory.py         # Client factory with registration
│       ├── paramiko_client.py # Paramiko implementation
│       └── additional_clients.py  # AsyncSSH/Fabric/SSH2 (optional)
├── ssh-licco.js              # Node.js wrapper - auto-install + integrity check + startup
├── install.js                # npm postinstall script - incremental install
├── smart_install.py          # Standalone diagnostic installer with SSH test
├── config/                    # Runtime configuration
│   ├── hosts.json            # SSH host configurations
│   ├── mcp.user.config.json.example
│   ├── mcp.presets.json
│   └── ssh-hosts.example.json
├── .github/workflows/
│   ├── pypi.yml               # PyPI release workflow
│   └── mcp-registry.yml       # MCP Registry publish workflow
├── openspec/                   # OpenSpec specifications
│   └── specs/                  # Feature specs
├── docs/                       # Documentation
│   ├── API_REFERENCE.md
│   ├── CONTRIBUTING.md
│   └── skills/                # Skill documentation copies
├── pyproject.toml              # Package configuration
├── sync_version.py            # Version sync script
├── Dockerfile                 # Docker image build (multi-stage)
└── .trae/skills/              # Trae IDE skills
```

## Auto-Install System Architecture

The npx auto-install uses a **three-layer architecture**:

```
User → npx ssh-licco
           ↓
    ┌──── ssh-licco.js (Node Layer) ────┐
    │  ① Find Python 3.10+             │
    │  ② Detect Anaconda environment   │
    │  ③ Create/reuse ~/.ssh-licco-venv │
    │  ④ pip install dependencies      │
    │  ⑤ Verify dependency integrity   │
    └──────────┬────────────────────────┘
               ↓
    ┌── cli.py (Python Entry) ──────┐
    │  Only starts MCP server       │
    └──────────┬────────────────────┘
               ↓
    ┌── SSHMCPServer (MCP Service) ─┐
    │  SSH connect, execute, etc.   │
    └───────────────────────────────┘
```

### Key Design Decisions

1. **Node.js wrapper (`ssh-licco.js`) handles all environment prep** - Python finding, venv creation, dependency installation, integrity verification. This ensures the Python layer can focus purely on MCP logic.

2. **Incremental install (`install.js`)** - The postinstall script checks `venvHasInstallation()` first. If the venv already has valid dependencies, it skips deletion and does incremental `pip install -e .`. This makes re-installs nearly instant.

3. **cli.py is stripped down** - No duplicate install logic. Only 17 lines: imports `run_server()` and calls it.

4. **Dependency integrity check** - Every startup verifies `from ssh_mcp.server import SSHMCPServer; from ssh_mcp.session_manager import SessionManager` works. If not, auto-repairs.

5. **Anaconda detection** - Both `ssh-licco.js` and `install.js` detect Anaconda/Miniconda Python and log a warning, ensuring users know their conda environment won't be touched.

### Smart Install Features

| Feature | Description |
|---------|-------------|
| **Anaconda Auto-Detect** | Detects conda environment, uses isolated venv |
| **Dependency Integrity Check** | Verifies on startup, auto-repairs if missing |
| **Incremental Update** | Doesn't delete venv, `pip install -e .` only |
| **Auto-Repair** | Re-installs when deps corrupted |

## Git Workflow

### Always create a new branch for changes

```bash
git checkout master
git pull github master
git checkout -b feature/your-feature-name
```

### Branch Naming Conventions

| Type | Example | Use Case |
|------|---------|----------|
| `feat/` | `feat/add-server-management` | New features |
| `fix/` | `fix/password-display-issue` | Bug fixes |
| `docs/` | `docs/update-readme` | Documentation |
| `refactor/` | `refactor/improve-code` | Code improvements |

### Commit Message Format

```
<type>: <description>
```

Types: `feat`, `fix`, `docs`, `refactor`, `chore`, `test`, `style`

## Quick Commands

```bash
pip install -e .
python -m pytest
python -m build
python -m twine upload dist/* -u __token__ -p <TOKEN>
python -c "from ssh_mcp import __version__; print(__version__)"
```

## Version Management

```bash
python sync_version.py 0.5.6
```

### Version Files (sync automatically)
- `ssh_mcp/__init__.py` - Main version file