SSH MCP Server

# Epic 5: File Transfer Operations ## Epic Intent Implement bidirectional file transfer capabilities between local and remote systems through SSH sessions, enabling efficient code synchronization and development file operations. ## Story 1: Single File Upload Operations As a developer using Claude Code, I want to upload individual files to remote servers so that I can transfer specific files for testing or deployment. ### Acceptance Criteria - **Given** an active SSH session and a local file exists - **When** I upload a file to the remote server - **Then** the file is transferred using SFTP protocol through the SSH session - **And** the remote directory is created if it doesn't exist - **And** file permissions are preserved during transfer - **And** file modification times are preserved - **And** transfer progress is reported for large files (>1MB) - **And** existing remote files are overwritten with confirmation - **And** transfer errors provide specific failure reasons - **And** partial transfers are cleaned up on failure **Performance Requirements:** - Transfer rate must achieve at least 1MB/s on standard connections - Progress updates every 10% for files larger than 1MB - Transfer timeout of 5 minutes per 100MB ## Story 2: Single File Download Operations As a developer using Claude Code, I want to download individual files from remote servers so that I can retrieve logs, configuration files, or generated artifacts. ### Acceptance Criteria - **Given** an active SSH session and a remote file exists - **When** I download a file from the remote server - **Then** the file is retrieved using SFTP protocol through the SSH session - **And** the local directory is created if it doesn't exist - **And** file permissions are preserved during transfer - **And** file modification times are preserved - **And** transfer progress is reported for large files (>1MB) - **And** existing local files are overwritten with confirmation - **And** transfer errors provide specific failure reasons - **And** partial downloads are cleaned up on failure ## Story 3: Directory Upload Operations As a developer using Claude Code, I want to upload entire directories to remote servers so that I can deploy complete project structures or synchronize code bases. ### Acceptance Criteria - **Given** an active SSH session and a local directory exists - **When** I upload a directory to the remote server - **Then** the entire directory structure is transferred recursively - **And** subdirectories are created as needed on the remote server - **And** file permissions and timestamps are preserved for all files - **And** symbolic links are handled appropriately (followed or preserved) - **And** transfer progress shows overall progress and current file - **And** .gitignore files are respected to exclude unnecessary files - **And** hidden files and directories are included unless explicitly excluded - **And** transfer can be resumed if interrupted **Performance Requirements:** - Directory scanning completes within 10 seconds for 1000 files - Concurrent file transfers (up to 3 simultaneous files) - Overall progress reporting with ETA calculation ## Story 4: Directory Download Operations As a developer using Claude Code, I want to download entire directories from remote servers so that I can retrieve complete project backups or generated output directories. ### Acceptance Criteria - **Given** an active SSH session and a remote directory exists - **When** I download a directory from the remote server - **Then** the entire directory structure is retrieved recursively - **And** local subdirectories are created as needed - **And** file permissions and timestamps are preserved for all files - **And** symbolic links are handled appropriately - **And** transfer progress shows overall progress and current file - **And** large directories can be downloaded without memory exhaustion - **And** transfer can be resumed if interrupted - **And** empty directories are preserved in the download ## Story 5: File Transfer Progress and Monitoring As a developer transferring files, I want detailed progress information so that I can monitor transfer status and estimate completion times. ### Acceptance Criteria - **Given** file transfer operations are in progress - **When** transfers are active - **Then** current transfer progress is displayed as percentage complete - **And** transfer speed is calculated and displayed (MB/s) - **And** estimated time remaining is calculated and updated - **And** current file being transferred is shown for directory operations - **And** overall progress is shown for multi-file operations - **And** transfer can be cancelled cleanly without corrupting files - **And** progress information is available through monitoring interface **Progress Display Format:** ``` Uploading project/ to /remote/path/ [████████████░░░░░░░░] 65% - 3.2MB/s - ETA: 2m 15s Current: src/components/Button.tsx (847KB/1.2MB) Files: 23/35 complete ``` ## Story 6: File Synchronization Operations As a developer maintaining code synchronization, I want intelligent file synchronization so that only changed files are transferred between local and remote systems. ### Acceptance Criteria - **Given** local and remote directories exist with potentially different content - **When** I perform synchronization operations - **Then** file modification times are compared to identify changed files - **And** file sizes are compared as additional change detection - **And** only modified, new, or deleted files are processed - **And** bidirectional sync is supported (local→remote, remote→local, both) - **And** sync conflicts are detected and reported for manual resolution - **And** dry-run mode shows what changes would be made without executing - **And** sync operations can be configured to exclude patterns (.git/, node_modules/, etc.) **Sync Conflict Resolution:** - Newer timestamp wins (configurable) - Manual conflict resolution mode - Preserve both versions with suffix ## Story 7: Transfer Error Handling and Recovery As a developer performing file transfers, I want robust error handling so that transfer failures are handled gracefully with recovery options. ### Acceptance Criteria - **Given** file transfer operations may encounter errors - **When** transfer errors occur - **Then** specific error types are identified (permission denied, disk full, network error, etc.) - **And** partial transfers are detected and can be resumed - **And** corrupted transfers are detected using checksums - **And** network interruptions trigger automatic retry with exponential backoff - **And** file locking conflicts are detected and retried - **And** insufficient disk space is detected before transfer begins - **And** transfer logs capture detailed error information for troubleshooting **Error Recovery Strategies:** - Network errors: automatic retry up to 3 attempts - Permission errors: clear error message with suggested fixes - Disk space errors: cleanup suggestions and retry options - Corruption detection: automatic re-transfer of affected files ## Story 8: File Transfer Security and Validation As a security-conscious developer, I want secure file transfer operations so that file integrity is maintained and sensitive information is protected. ### Acceptance Criteria - **Given** file transfers contain potentially sensitive information - **When** transfer operations are performed - **Then** all transfers use encrypted SFTP protocol - **And** file checksums are calculated and verified for integrity - **And** temporary files are created with restrictive permissions (600) - **And** transfer logs do not contain file contents or sensitive paths - **And** file paths are validated to prevent directory traversal attacks - **And** large file transfers do not expose sensitive information in memory dumps - **And** cleanup removes all temporary transfer files **Security Measures:** - SFTP encryption mandatory - SHA-256 checksums for integrity verification - Secure temporary file handling - Path validation against directory traversal - Memory-safe handling of large files