# SCP Feature Implementation Plan

## 1. Core Functionality
- [ ] Add SFTP client to `SSHSession` class using **Paramiko's SFTPClient** (already a dependency)
- [ ] Implement file transfer methods with enhanced safety:
  - `upload_file(local_path, remote_path)`
    - Check local file size before transfer
    - Verify remote filesystem capacity (using `df` command via SSH)
    - Default 1GB transfer limit (configurable)
    - Conflict resolution: auto-rename (default) / overwrite / fail options
  - `download_file(remote_path, local_path)`
    - Check remote file size first
    - Verify local disk space
    - Same conflict resolution options
  - `list_directory(remote_path)`
  - `remove_file(remote_path)`
  - `get_disk_usage()` - Helper for capacity checks

## 2. File Size Handling
- [ ] Pre-transfer validation:
  - Local: `os.stat()` for size
  - Remote: Execute `df -k` via SSH and parse output
- [ ] Configurable limits:
  - Max single file size (default: 1GB)
  - Min free space requirement (default: 2x file size)
- [ ] Graceful error handling for:
  - Insufficient space
  - Size limit exceeded
  - Transfer interruptions

## 3. Conflict Resolution
- [ ] Transfer modes:
  - `FAIL` (default): Raise error on existing file
  - `OVERWRITE`: Replace existing file
  - `RENAME`: Add timestamp suffix (e.g., `file(20250422).ext`)
- [ ] Configurable via:
  - Transfer parameters
  - Environment variables
  - Global defaults

## 4. API Endpoints
- [ ] Enhanced Pydantic models:
  ```python
  class FileTransferParams(BaseModel):
      local_path: str
      remote_path: str
      max_size: Optional[int] = None  # bytes
      on_conflict: Literal["FAIL", "OVERWRITE", "RENAME"] = "FAIL"
  ```

## 5. Testing Strategy
- [ ] Add test cases for:
  - Size limit enforcement
  - Disk space verification
  - Conflict resolution modes
  - Partial transfer recovery

## 6. Partial Transfer Handling
- [ ] **Automatic Resume:**
  - If feasible, support resuming interrupted transfers using SFTP partial file support (seek, append). If not supported, document this limitation clearly.
- [ ] **Cleanup of Incomplete Files:**
  - On transfer failure, automatically remove any partially transferred files (or move to a `.partial` or temp location). Provide a configuration option to retain or clean up partial files.
- [ ] **User Notification:**
  - Always return clear, explicit error status if a transfer does not complete successfully.
  - Include details such as bytes transferred, error message, and suggested next steps (retry, cleanup, etc.).
- [ ] **Testing:**
  - Add test cases for interrupted connections, disk full scenarios, and manual aborts to verify correct cleanup and notification.

## 7. Documentation
- [ ] Update README with new SCP capabilities
- [ ] Add example usage

## Implementation Steps
1. Extend `SSHSession` with SFTP support using Paramiko
2. Add new tool methods to `SSHServerMCP`
3. Implement tests for edge cases (size, conflicts, errors)
4. Update documentation

## Estimated Timeline
- Core implementation: 2 days
- Testing: 1 day
- Documentation: 0.5 day

---
**Notes:**
- SFTP operations will use Paramiko's `SFTPClient`.
- File size and free space will be checked before transfer on both local and remote filesystems.
- Conflict behavior (fail, overwrite, rename) is configurable per transfer.