89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# 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.
|