DroidMind

Instructions

Implementation Reference

• droidmind/tools/file_operations.py:335-491 (handler)

  Main execution handler for the 'android-file' MCP tool. Decorated with @mcp.tool(name="android-file"), it dispatches file operations (list, push, pull, delete, etc.) based on the 'action' parameter to internal helper functions, using the connected Android device.
  @mcp.tool(name="android-file") async def file_operations( serial: str, action: FileAction, ctx: Context, path: str | None = None, local_path: str | None = None, device_path: str | None = None, content: str | None = None, max_size: int | None = 100000, # Default from original read_file ) -> str | bool: """ Perform file and directory operations on an Android device. This single tool consolidates various file system actions. The 'action' parameter determines the operation. Args: serial: Device serial number. action: The specific file operation to perform. See available actions below. ctx: MCP Context for logging and interaction. path (Optional[str]): General path argument on the device. Used by: list_directory, delete_file, create_directory, file_exists, file_stats. Can also be used by read_file and write_file as an alternative to 'device_path'. local_path (Optional[str]): Path on the DroidMind server machine. Used by: push_file (source), pull_file (destination). device_path (Optional[str]): Path on the Android device. Used by: push_file (destination), pull_file (source), read_file (source), write_file (destination). If 'path' is also provided for read/write, 'device_path' takes precedence. content (Optional[str]): Text content to write. Used by: write_file. max_size (Optional[int]): Maximum file size in bytes for read_file (default: 100KB). Used by: read_file. Returns: Union[str, bool]: A string message indicating the result or status for most actions. Returns a boolean for the 'file_exists' action. --- Available Actions and their specific argument usage: 1. `action="list_directory"`: Lists contents of a directory. - Requires: `path` (directory path on device). - Returns: Formatted string of directory contents. 2. `action="push_file"`: Uploads a file from the local server to the device. - Requires: `local_path` (source on server), `device_path` (destination on device). - Returns: String message confirming upload. 3. `action="pull_file"`: Downloads a file from the device to the local server. - Requires: `device_path` (source on device), `local_path` (destination on server). - Returns: String message confirming download. 4. `action="delete_file"`: Deletes a file or directory from the device. - Requires: `path` (path to delete on device). - Returns: String message confirming deletion. 5. `action="create_directory"`: Creates a directory on the device. - Requires: `path` (directory path to create on device). - Returns: String message confirming creation. 6. `action="file_exists"`: Checks if a file or directory exists on the device. - Requires: `path` (path to check on device). - Returns: `True` if exists, `False` otherwise. 7. `action="read_file"`: Reads the contents of a file from the device. - Requires: `device_path` (or `path`) for the file on device. - Optional: `max_size` (defaults to 100KB). - Returns: String containing file contents or error message. 8. `action="write_file"`: Writes text content to a file on the device. - Requires: `device_path` (or `path`) for the file on device, `content` (text to write). - Returns: String message confirming write. 9. `action="file_stats"`: Gets detailed statistics for a file or directory. - Requires: `path` (path on device). - Returns: Markdown-formatted string of file/directory statistics. --- """ # Declare here so it's always bound for exception logging _effective_device_path: str | None = None try: # Initialize _effective_device_path early for robust logging _effective_device_path = device_path if device_path is not None else path device = await get_device_manager().get_device(serial) if not device: if action == FileAction.FILE_EXISTS: logger.warning("Device %s not found for file_exists check.", serial) return False return f"❌ Error: Device {serial} not found or not connected." # Use device_path if provided, otherwise fall back to path for relevant actions # _effective_device_path assignment moved above if action == FileAction.LIST_DIRECTORY: if path is None: return "❌ Error: 'path' is required for list_directory." return await _list_directory_impl(device, path, ctx) if action == FileAction.PUSH_FILE: if local_path is None or device_path is None: return "❌ Error: 'local_path' and 'device_path' are required for push_file." return await _push_file_impl(device, local_path, device_path, ctx) if action == FileAction.PULL_FILE: if device_path is None or local_path is None: return "❌ Error: 'device_path' and 'local_path' are required for pull_file." return await _pull_file_impl(device, device_path, local_path, ctx) if action == FileAction.DELETE_FILE: if path is None: return "❌ Error: 'path' is required for delete_file." return await _delete_file_impl(device, path, ctx) if action == FileAction.CREATE_DIRECTORY: if path is None: return "❌ Error: 'path' is required for create_directory." return await _create_directory_impl(device, path, ctx) if action == FileAction.FILE_EXISTS: if path is None: return "❌ Error: 'path' is required for file_exists." return await _file_exists_impl(device, path, ctx) if action == FileAction.READ_FILE: if _effective_device_path is None: return "❌ Error: 'device_path' or 'path' is required for read_file." return await _read_file_impl(device, _effective_device_path, ctx, max_size or 100000) if action == FileAction.WRITE_FILE: if _effective_device_path is None or content is None: return "❌ Error: ('device_path' or 'path') and 'content' are required for write_file." return await _write_file_impl(device, _effective_device_path, content, ctx) if action == FileAction.FILE_STATS: if path is None: return "❌ Error: 'path' is required for file_stats." return await _file_stats_impl(device, path, ctx) # Default case for invalid actions valid_actions = ", ".join([act.value for act in FileAction]) logger.error("Invalid file action '%s' received. Valid actions are: %s", action, valid_actions) return f"❌ Error: Unknown file action '{action}'. Valid actions are: {valid_actions}." except ValueError as ve: logger.warning("ValueError during file operation %s for device %s: %s", action, serial, ve) if action == FileAction.FILE_EXISTS: return False return f"❌ Error: {ve}" except Exception as e: # Log with a fallback for _effective_device_path if necessary log_path_info = _effective_device_path if _effective_device_path is not None else "[path not determinable]" logger.exception( "Unexpected error during file operation %s on %s with path/device_path '%s': %s", action, serial, log_path_info, e, ) if action == FileAction.FILE_EXISTS: return False return f"❌ Error: An unexpected error occurred: {e!s}"
• droidmind/tools/file_operations.py:24-36 (schema)

  Type definition (Enum) for the 'action' parameter, defining all supported sub-operations of the android-file tool. Serves as input schema validation.
  class FileAction(str, Enum): """Defines the available sub-commands for the 'android-file' tool.""" LIST_DIRECTORY = "list_directory" PUSH_FILE = "push_file" PULL_FILE = "pull_file" DELETE_FILE = "delete_file" CREATE_DIRECTORY = "create_directory" FILE_EXISTS = "file_exists" READ_FILE = "read_file" WRITE_FILE = "write_file" FILE_STATS = "file_stats"
• droidmind/tools/file_operations.py:335-335 (registration)

  MCP tool registration decorator applied to the handler function, naming it 'android-file'.
  @mcp.tool(name="android-file")
• droidmind/tools/file_operations.py:116-143 (helper)

  Helper function for LIST_DIRECTORY action: lists and formats directory contents.
  async def _list_directory_impl(device: "Device", path: str, ctx: Context) -> str: """Implementation for listing directory contents.""" if ctx: await ctx.info(f"Listing directory {path}...") dir_resource = DirectoryResource(path, device) contents = await dir_resource.list_contents() formatted_output = f"# 📁 Directory: {path}\n\n" files = [item for item in contents if item.__class__.__name__ == "FileResource"] dirs = [item for item in contents if item.__class__.__name__ == "DirectoryResource"] formatted_output += f"**{len(files)} files, {len(dirs)} directories**\n\n" if dirs: formatted_output += "## Directories\n\n" for dir_item in sorted(dirs, key=lambda x: x.name): formatted_output += f"📁 `{dir_item.name}`\n" formatted_output += "\n" if files: formatted_output += "## Files\n\n" for file_item in sorted(files, key=lambda x: x.name): size_str = file_item.to_dict().get("size", "unknown") formatted_output += f"📄 `{file_item.name}` ({size_str})\n" return formatted_output
• droidmind/tools/file_operations.py:145-165 (helper)

  Helper function for PUSH_FILE action: uploads local file to device.
  async def _push_file_impl(device: "Device", local_path: str, device_path: str, ctx: Context) -> str: """Implementation for uploading a file.""" if not os.path.exists(local_path): return f"❌ Error: Local file {local_path} does not exist." size = os.path.getsize(local_path) size_str = format_file_size(size) if ctx: await ctx.info(f"Pushing file {os.path.basename(local_path)} ({size_str}) to {device_path}...") result = await device.push_file(local_path, device_path) return f""" # ✅ File Uploaded Successfully The file `{os.path.basename(local_path)}` ({size_str}) has been uploaded to `{device_path}` on device {device.serial}. **Details**: {result} """