portal_transfer
Transfer files securely between local and remote servers via SFTP. Supports single file, recursive directory sync, and batch transfers with optional checksum verification to skip unchanged files.
Instructions
Transfer files between local and remote via SFTP (binary-safe, atomic).
Modes
direction="upload": local_path → remote_path (single file). Example: portal_transfer(direction="upload", host="web01", local_path="/tmp/app.jar", remote_path="/opt/app/app.jar")
direction="download": remote_path → local_path (single file). Example: portal_transfer(direction="download", host="web01", remote_path="/var/log/syslog", local_path="/tmp/syslog")
direction="sync": recursively sync local_path directory → remote_path directory (upload). Files already present with a matching size+mtime (or sha256 when checksum=True) are skipped.
direction="mirror": recursively mirror remote_path directory → local_path directory (download); the remote→local counterpart of "sync". Example: portal_transfer(direction="mirror", host="web01", remote_path="/srv/www/", local_path="./www/")
direction="upload-list" / "download-list": transfer an explicit list of file pairs given in paths_json (an arbitrary local→remote mapping, not a whole directory). Each pair is skipped when already present with a matching size+mtime (or sha256 when checksum=True), so re-runs only move the changed files; a single pair's failure is collected in failed[] without aborting the batch. local_path / remote_path are ignored in these modes. Example: portal_transfer(direction="upload-list", host="web01", paths_json='[{"local":"/tmp/a.conf","remote":"/etc/app/a.conf"}, {"local":"/tmp/b.conf","remote":"/etc/app/b.conf"}]')
Args:
checksum: for the incremental modes (sync/mirror/upload-list/
download-list), compare files by sha256 instead of size+mtime
(slower, requires sha256sum on the remote; missing remote files or
an unavailable sha256sum force a re-transfer).
paths_json: JSON array of {"local": ..., "remote": ...} objects, required
by the upload-list / download-list modes (ignored otherwise).
Progress is reported to the MCP client during transfers.
Returns a JSON status dict. Single-file: {status, direction, host, bytes, duration_s, ...}. sync/mirror/upload-list/download-list: {status, uploaded|downloaded, skipped, failed[], bytes_total, bytes_transferred, duration_s}.
For text-only edits prefer portal_patch (hash-protected). Use portal_transfer when SFTP semantics are needed: binary files, large files, whole directory trees. Note: directory modes copy files only — symlinks and special files are skipped, and empty directories are not created on their own.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| host | Yes | ||
| checksum | No | ||
| direction | Yes | ||
| local_path | Yes | ||
| paths_json | No | ||
| remote_path | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |