bump

CHANGELOG_automatic_file_transfers.md

@@ -0,0 +1,140 @@
+# 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
+