mcpssh/.note/scp_plan.md

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:

  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.