141 lines
4.9 KiB
Markdown
141 lines
4.9 KiB
Markdown
# Automatic File Transfer Improvements
|
|
|
|
## Summary
|
|
|
|
Enhanced the cremote MCP server to automatically handle file transfers between the host machine and the container, eliminating the need for separate manual file transfer steps in most common workflows.
|
|
|
|
## Changes Made
|
|
|
|
### 1. Automatic File Upload for Web Forms
|
|
|
|
**Tool:** `web_interact_cremotemcp` with action "upload"
|
|
|
|
**Before:**
|
|
```yaml
|
|
# Step 1: Manually upload file to container
|
|
file_upload_cremotemcp:
|
|
local_path: "/home/user/document.pdf"
|
|
container_path: "/tmp/document.pdf"
|
|
|
|
# Step 2: Upload to web form using container path
|
|
web_interact_cremotemcp:
|
|
action: "upload"
|
|
selector: "input[type='file']"
|
|
value: "/tmp/document.pdf"
|
|
```
|
|
|
|
**After:**
|
|
```yaml
|
|
# Single step - automatic transfer!
|
|
web_interact_cremotemcp:
|
|
action: "upload"
|
|
selector: "input[type='file']"
|
|
value: "/home/user/document.pdf" # Local path - auto-transferred
|
|
```
|
|
|
|
**How it works:**
|
|
- Detects if the file path is a local host path (doesn't start with `/tmp/` or `/var/`)
|
|
- Automatically uploads the file to the container using `UploadFileToContainer`
|
|
- Then performs the web form upload using the container path
|
|
- Falls back gracefully if the path is already a container path
|
|
|
|
### 2. Automatic Screenshot Download
|
|
|
|
**Tools:**
|
|
- `web_screenshot_cremotemcp`
|
|
- `web_screenshot_element_cremotemcp`
|
|
- `web_screenshot_enhanced_cremotemcp`
|
|
|
|
**Before:**
|
|
```yaml
|
|
# Step 1: Take screenshot in container
|
|
web_screenshot_cremotemcp:
|
|
output: "/tmp/screenshot.png"
|
|
|
|
# Step 2: Manually download from container
|
|
file_download_cremotemcp:
|
|
container_path: "/tmp/screenshot.png"
|
|
local_path: "/home/user/screenshots/screenshot.png"
|
|
```
|
|
|
|
**After:**
|
|
```yaml
|
|
# Single step - automatic download!
|
|
web_screenshot_cremotemcp:
|
|
output: "/home/user/screenshots/screenshot.png" # Local path - auto-downloaded
|
|
```
|
|
|
|
**How it works:**
|
|
- Detects if the output path is a local host path (doesn't start with `/tmp/` or `/var/`)
|
|
- Takes the screenshot in the container using a temporary path
|
|
- Automatically downloads the screenshot to the specified host path using `DownloadFileFromContainer`
|
|
- Returns the host path in the success message
|
|
|
|
### 3. Updated Documentation
|
|
|
|
**Files Updated:**
|
|
- `mcp/main.go` - Tool implementations
|
|
- `mcp/LLM_USAGE_GUIDE.md` - Usage examples and workflows
|
|
- `mcp/QUICK_REFERENCE.md` - Quick reference examples
|
|
- `docs/llm_instructions.md` - LLM agent instructions
|
|
|
|
**Key Documentation Changes:**
|
|
- Added notes about automatic file transfer capabilities
|
|
- Updated file upload workflow examples to show simplified approach
|
|
- Clarified when manual file transfer tools are still needed
|
|
- Updated tool descriptions to mention automatic transfer behavior
|
|
|
|
## Benefits
|
|
|
|
1. **Simplified Workflows**: Reduced multi-step operations to single-step operations
|
|
2. **Better UX**: Users can work with local paths directly without thinking about container paths
|
|
3. **Fewer Errors**: Eliminates the need to remember intermediate container paths
|
|
4. **Backward Compatible**: Still supports explicit container paths for advanced use cases
|
|
5. **Token Efficient**: Reduces the number of tool calls needed for common operations
|
|
|
|
## When to Use Manual File Transfer Tools
|
|
|
|
The manual file transfer tools (`file_upload_cremotemcp` and `file_download_cremotemcp`) are still useful for:
|
|
|
|
1. **Pre-staging files**: When you need to upload files to the container before using them
|
|
2. **Explicit control**: When you want to control the exact container path
|
|
3. **Bulk operations**: Using `file_operations_bulk_cremotemcp` for multiple files
|
|
4. **Browser downloads**: Files downloaded by the browser still need manual transfer
|
|
|
|
## Technical Implementation
|
|
|
|
### Path Detection Logic
|
|
|
|
```go
|
|
// For uploads and screenshots
|
|
if strings.HasPrefix(path, "/tmp/") || strings.HasPrefix(path, "/var/") {
|
|
// Treat as container path
|
|
containerPath = path
|
|
hostPath = generateDefaultHostPath(path)
|
|
} else {
|
|
// Treat as host path
|
|
hostPath = path
|
|
containerPath = generateTempContainerPath()
|
|
}
|
|
```
|
|
|
|
### Error Handling
|
|
|
|
- If automatic upload fails, the tool attempts to use the path as-is (might be a valid container path)
|
|
- If automatic download fails, returns an error message indicating the screenshot was taken but not downloaded
|
|
- Both approaches provide clear error messages to help users understand what went wrong
|
|
|
|
## Testing
|
|
|
|
Build successful with no compilation errors. The changes maintain backward compatibility with existing workflows while providing the new automatic transfer functionality.
|
|
|
|
## Future Enhancements
|
|
|
|
Potential improvements for future consideration:
|
|
|
|
1. **Browser Download Detection**: Automatically detect when the browser downloads a file and transfer it to the host
|
|
2. **Configurable Default Paths**: Allow users to configure default download directories
|
|
3. **Progress Indicators**: For large file transfers, show progress information
|
|
4. **Batch Screenshot Downloads**: Optimize multiple screenshot operations with batch downloads
|
|
|