python-alfresco-mcp-server 1.1.0__py3-none-any.whl

alfresco_mcp_server/tools/core/checkout_document.py

@@ -0,0 +1,258 @@
+"""
+Checkout document tool implementation for Alfresco MCP Server.
+Handles document checkout with lock management and local file download.
+"""
+import logging
+import os
+import pathlib
+import json
+import httpx
+from datetime import datetime
+from fastmcp import Context
+from ...utils.connection import get_core_client
+from ...config import config
+from ...utils.json_utils import safe_format_output
+
+
+logger = logging.getLogger(__name__)
+
+
+async def checkout_document_impl(
+    node_id: str, 
+    download_for_editing: bool = True,
+    ctx: Context = None
+) -> str:
+    """Check out a document for editing using Alfresco REST API.
+    
+    Args:
+        node_id: Document node ID to check out
+        download_for_editing: If True, downloads file to checkout folder for editing (default, AI-friendly).
+                            If False, just creates working copy in Alfresco (testing mode)
+        ctx: MCP context for progress reporting
+    
+    Returns:
+        Checkout confirmation with file path and editing instructions if download_for_editing=True,
+        or working copy details if False
+    """
+    if ctx:
+        await ctx.info(safe_format_output(f">> Checking out document: {node_id}"))
+        await ctx.info(safe_format_output("Validating node ID..."))
+        await ctx.report_progress(0.1)
+    
+    if not node_id.strip():
+        return safe_format_output("❌ Error: node_id is required")
+    
+    try:
+        logger.info(f"Starting checkout: node {node_id}")
+        core_client = await get_core_client()
+        
+        if ctx:
+            await ctx.info(safe_format_output("Connecting to Alfresco..."))
+            await ctx.report_progress(0.2)
+        
+        # Clean the node ID (remove any URL encoding or extra characters)
+        clean_node_id = node_id.strip()
+        if clean_node_id.startswith('alfresco://'):
+            # Extract node ID from URI format
+            clean_node_id = clean_node_id.split('/')[-1]
+        
+        if ctx:
+            await ctx.info(safe_format_output("Getting node information..."))
+            await ctx.report_progress(0.3)
+        
+        # Get node information first to validate it exists using high-level core client
+        node_response = core_client.nodes.get(node_id=clean_node_id)
+        
+        if not hasattr(node_response, 'entry'):
+            return safe_format_output(f"❌ Failed to get node information for: {clean_node_id}")
+        
+        node_info = node_response.entry
+        filename = getattr(node_info, 'name', f"document_{clean_node_id}")
+        
+        if ctx:
+            await ctx.info(safe_format_output(">> Performing Alfresco lock using core client..."))
+            await ctx.report_progress(0.5)
+        
+        # Use core client directly since it inherits from AuthenticatedClient
+        lock_status = "unlocked"
+        try:
+            logger.info(f"Attempting to lock document: {clean_node_id}")
+            
+            # Use the high-level wrapper method that handles the body internally
+            logger.info(f"Using AlfrescoCoreClient versions.checkout method...")
+            
+            # Use the hierarchical API: versions.checkout 
+            lock_response = core_client.versions.checkout(
+                node_id=clean_node_id
+            )
+            logger.info(f"✅ Used lock_node_sync method successfully")
+            
+            if lock_response and hasattr(lock_response, 'entry'):
+                lock_status = "locked"
+            else:
+                lock_status = "locked"  # Assume success if no error
+            
+            logger.info(f"Document locked successfully: {clean_node_id}")
+                
+        except Exception as lock_error:
+            error_str = str(lock_error)
+            if "423" in error_str or "already locked" in error_str.lower():
+                logger.warning(f"Document already locked: {clean_node_id}")
+                return safe_format_output(f"❌ Document is already locked by another user: {error_str}")
+            elif "405" in error_str:
+                # Server doesn't support lock API - continue without locking
+                lock_status = "no-lock-api"
+                logger.warning(f"Server doesn't support lock API for {clean_node_id}")
+                if ctx:
+                    await ctx.info(safe_format_output("WARNING: Server doesn't support lock API - proceeding without lock"))
+            elif "multiple values for keyword argument" in error_str:
+                logger.error(f"Parameter conflict in lock_node_sync: {error_str}")
+                return safe_format_output(f"❌ Internal client error - parameter conflict: {error_str}")
+            else:
+                logger.error(f"Failed to lock document {clean_node_id}: {error_str}")
+                return safe_format_output(f"❌ Document cannot be locked: {error_str}")
+        
+        # Document is now locked, we'll download the current content
+        working_copy_id = clean_node_id  # With lock API, we work with the same node ID
+        
+        if ctx:
+            if lock_status == "locked":
+                await ctx.info(safe_format_output(f"SUCCESS: Document locked in Alfresco!"))
+            else:
+                await ctx.info(safe_format_output(f"Document prepared for editing (no lock support)"))
+            await ctx.report_progress(0.7)
+        
+        if download_for_editing:
+            try:
+                if ctx:
+                    await ctx.info(safe_format_output("Downloading current content..."))
+                    await ctx.report_progress(0.8)
+                
+                # Get content using authenticated HTTP client from core client (ensure initialization)
+                if not core_client.is_initialized:
+                    return safe_format_output("❌ Error: Alfresco server unavailable")
+                # Use httpx_client property directly on AlfrescoCoreClient
+                http_client = core_client.httpx_client
+                
+                # Build correct content URL based on config
+                if config.alfresco_url.endswith('/alfresco/api/-default-/public'):
+                    # Full API path provided
+                    content_url = f"{config.alfresco_url}/alfresco/versions/1/nodes/{clean_node_id}/content"
+                elif config.alfresco_url.endswith('/alfresco/api'):
+                    # Base API path provided
+                    content_url = f"{config.alfresco_url}/-default-/public/alfresco/versions/1/nodes/{clean_node_id}/content"
+                else:
+                    # Base server URL provided
+                    content_url = f"{config.alfresco_url}/alfresco/api/-default-/public/alfresco/versions/1/nodes/{clean_node_id}/content"
+                
+                response = http_client.get(content_url)
+                response.raise_for_status()
+                
+                # Save to Downloads/checkout folder
+                downloads_dir = pathlib.Path.home() / "Downloads"
+                checkout_dir = downloads_dir / "checkout"
+                checkout_dir.mkdir(parents=True, exist_ok=True)
+                
+                # Create unique filename with node ID
+                safe_filename = filename.replace(" ", "_").replace("/", "_").replace("\\", "_")
+                local_filename = f"{safe_filename}_{clean_node_id}"
+                local_path = checkout_dir / local_filename
+                
+                with open(local_path, 'wb') as f:
+                    f.write(response.content)
+
+                logger.info(f"Downloaded for editing: {filename} -> {local_path}")
+                # Update checkout tracking with actual working copy ID
+                checkout_manifest_path = checkout_dir / ".checkout_manifest.json"
+                checkout_data = {}
+                
+                if checkout_manifest_path.exists():
+                    try:
+                        with open(checkout_manifest_path, 'r') as f:
+                            checkout_data = json.load(f)
+                    except:
+                        checkout_data = {}
+                
+                if 'checkouts' not in checkout_data:
+                    checkout_data['checkouts'] = {}
+                
+                checkout_time = datetime.now().isoformat()
+                
+                checkout_data['checkouts'][clean_node_id] = {
+                    'original_node_id': clean_node_id,
+                    'locked_node_id': clean_node_id,  # Same as original since we lock, not checkout
+                    'local_file': local_filename,
+                    'checkout_time': checkout_time,
+                    'original_filename': filename
+                }
+                
+                # Save manifest
+                with open(checkout_manifest_path, 'w') as f:
+                    json.dump(checkout_data, f, indent=2)
+                
+                if ctx:
+                    await ctx.info(safe_format_output("SUCCESS: Checkout completed!"))
+                    await ctx.report_progress(1.0)
+                
+                # Format file size
+                file_size = len(response.content)
+                if file_size < 1024:
+                    size_str = f"{file_size} bytes"
+                elif file_size < 1024 * 1024:
+                    size_str = f"{file_size / 1024:.1f} KB"
+                else:
+                    size_str = f"{file_size / (1024 * 1024):.1f} MB"
+                
+                if lock_status == "locked":
+                    result = f"🔒 Document Checked Out Successfully!\n\n"
+                    result += f"📄 Name: {filename}\n"
+                    result += f"🆔 Node ID: {clean_node_id}\n"
+                    result += f"📏 Size: {size_str}\n"
+                    result += f"💾 Downloaded to: {local_path}\n"
+                    result += f"🔒 Lock Status: {lock_status}\n"
+                    result += f"🕒 Checkout Time: {checkout_time}\n\n"
+                    result += f"Next steps:\n"
+                    result += f"   1. Edit the document at: {local_path}\n"
+                    result += f"   2. Save your changes\n"
+                    result += f"   3. Use checkin_document tool to upload changes\n\n"
+                    result += f"The document is now locked in Alfresco to prevent conflicts.\n"
+                    result += f"Other users cannot edit it until you check it back in or cancel the checkout."
+                    
+                    return safe_format_output(result)
+                else:
+                                    result = f"📥 **Document downloaded for editing!**\n\n"
+                status_msg = "ℹ️ **Status**: Downloaded for editing (server doesn't support locks)"
+                important_msg = "ℹ️ **Note**: Server doesn't support locking - multiple users may edit simultaneously."
+                
+                result += f">> **Downloaded to**: `{local_path}`\n"
+                result += f">> **Original**: {filename}\n"
+                result += f">> **Size**: {size_str}\n"
+                result += f"{status_msg}\n"
+                result += f"🔗 **Node ID**: {clean_node_id}\n"
+                result += f"🕒 **Downloaded at**: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+                result += f">> **Instructions**:\n"
+                result += f"1. Open the file in your preferred application (Word, Excel, etc.)\n"
+                result += f"2. Make your edits and save the file\n"
+                result += f"3. When finished, use `checkin_document` to upload your changes\n\n"
+                result += f"{important_msg}"
+                
+                return safe_format_output(result)
+            except Exception as e:
+                error_msg = f"❌ Checkout failed: {str(e)}"
+                if ctx:
+                    await ctx.error(safe_format_output(error_msg))
+                logger.error(f"Checkout failed: {e}")
+                return safe_format_output(error_msg)
+        else:
+            # Testing mode - just return lock status
+            if lock_status == "locked":
+                return f"SUCCESS: Document locked successfully for testing. Node ID: {clean_node_id}, Status: LOCKED"
+            else:
+                return f"WARNING: Document prepared for editing (no lock support). Node ID: {clean_node_id}"
+        
+    except Exception as e:
+        error_msg = f"❌ Checkout failed: {str(e)}"
+        if ctx:
+            await ctx.error(safe_format_output(error_msg))
+        logger.error(f"Checkout failed: {e}")
+        return safe_format_output(error_msg) 

alfresco_mcp_server/tools/core/create_folder.py

@@ -0,0 +1,105 @@
+"""
+Create folder tool for Alfresco MCP Server.
+Self-contained tool for creating folders in Alfresco repository.
+"""
+import logging
+from typing import Optional
+from fastmcp import Context
+
+from ...utils.connection import ensure_connection
+from ...utils.json_utils import safe_format_output
+
+logger = logging.getLogger(__name__)
+
+
+async def create_folder_impl(
+    folder_name: str, 
+    parent_id: str = "-shared-", 
+    description: str = "",
+    ctx: Optional[Context] = None
+) -> str:
+    """Create a new folder in Alfresco.
+    
+    Args:
+        folder_name: Name of the new folder
+        parent_id: Parent folder ID (default: shared folder)
+        description: Folder description
+        ctx: MCP context for progress reporting
+    
+    Returns:
+        Folder creation confirmation with details
+    """
+    if ctx:
+        await ctx.info(f">> Creating folder '{folder_name}' in {parent_id}")
+        await ctx.info("Validating folder parameters...")
+        await ctx.report_progress(0.0)
+    
+    if not folder_name.strip():
+        return safe_format_output("❌ Error: folder_name is required")
+    
+    try:
+        # Ensure connection and get client factory (working pattern from test)
+        await ensure_connection()
+        from ...utils.connection import get_client_factory
+        
+        # Get client factory and create core client (working pattern from test)
+        client_factory = await get_client_factory()
+        core_client = client_factory.create_core_client()
+        
+        if ctx:
+            await ctx.info("Creating folder in Alfresco...")
+            await ctx.report_progress(0.5)
+        
+        logger.info(f"Creating folder '{folder_name}' in parent {parent_id}")
+        
+        # Prepare properties
+        properties = {"cm:title": folder_name}
+        if description:
+            properties["cm:description"] = description
+        
+        logger.info(f"Using high-level API: core_client.nodes.create_folder()")
+        
+        # Use the working high-level API pattern from test script
+        folder_response = core_client.nodes.create_folder(
+            name=folder_name,
+            parent_id=parent_id,
+            properties=properties
+        )
+        
+        if folder_response and hasattr(folder_response, 'entry'):
+            entry = folder_response.entry
+            logger.info("✅ Folder created successfully")
+            
+            # Extract folder details from response
+            folder_id = getattr(entry, 'id', 'Unknown')
+            folder_name_response = getattr(entry, 'name', folder_name)
+            created_at = getattr(entry, 'createdAt', 'Unknown')
+            node_type = getattr(entry, 'nodeType', 'cm:folder')
+        else:
+            raise Exception(f"Failed to create folder - invalid response from core client")
+        
+        if ctx:
+            await ctx.info("Processing folder creation response...")
+            await ctx.report_progress(0.9)
+        
+        if ctx:
+            await ctx.info("Folder created!")
+            await ctx.report_progress(1.0)
+            await ctx.info(f"SUCCESS: Folder '{folder_name_response}' created successfully")
+            
+        # Clean JSON-friendly formatting (no markdown syntax)
+        return safe_format_output(f"""✅ Folder Created Successfully!
+
+📁 Name: {folder_name_response}
+🆔 Folder ID: {folder_id}
+📍 Parent: {parent_id}
+📅 Created: {created_at}
+🏷️ Type: {node_type}
+📝 Description: {description or 'None'}""")
+        
+    except Exception as e:
+        error_msg = f"❌ Folder creation failed: {str(e)}"
+        if ctx:
+            await ctx.error(error_msg)
+        logger.error(f"Folder creation failed: {e}")
+        return safe_format_output(error_msg) 

alfresco_mcp_server/tools/core/delete_node.py

@@ -0,0 +1,88 @@
+"""
+Delete node tool for Alfresco MCP Server.
+Self-contained tool for deleting documents or folders from Alfresco repository.
+"""
+import logging
+from typing import Optional
+from fastmcp import Context
+
+from ...utils.connection import ensure_connection
+from ...utils.json_utils import safe_format_output
+
+logger = logging.getLogger(__name__)
+
+
+async def delete_node_impl(
+    node_id: str, 
+    permanent: bool = False,
+    ctx: Optional[Context] = None
+) -> str:
+    """Delete a document or folder from Alfresco.
+    
+    Args:
+        node_id: Node ID to delete
+        permanent: Whether to permanently delete (bypass trash)
+        ctx: MCP context for progress reporting
+    
+    Returns:
+        Deletion confirmation
+    """
+    if ctx:
+        delete_type = "permanently delete" if permanent else "move to trash"
+        await ctx.info(f"Preparing to {delete_type}: {node_id}")
+        await ctx.info("Validating deletion request...")
+        await ctx.report_progress(0.1)
+    
+    if not node_id.strip():
+        return safe_format_output("❌ Error: node_id is required")
+    
+    try:
+        await ensure_connection()
+        from ...utils.connection import get_client_factory
+        
+        # Get client factory and create core client (working pattern from test)
+        client_factory = await get_client_factory()
+        core_client = client_factory.create_core_client()
+        
+        # Clean the node ID (remove any URL encoding or extra characters)
+        clean_node_id = node_id.strip()
+        if clean_node_id.startswith('alfresco://'):
+            # Extract node ID from URI format
+            clean_node_id = clean_node_id.split('/')[-1]
+        
+        logger.info(f"Attempting to delete node: {clean_node_id}")
+        
+        if ctx:
+            await ctx.report_progress(0.7)
+        
+        # Get node information first to validate it exists (working pattern from test)
+        node_response = core_client.nodes.get(clean_node_id)
+        
+        if not hasattr(node_response, 'entry'):
+            return safe_format_output(f"❌ Failed to get node information for: {clean_node_id}")
+        
+        node_info = node_response.entry
+        filename = getattr(node_info, 'name', f"document_{clean_node_id}")
+        
+        # Use the working high-level API pattern from test script
+        core_client.nodes.delete(clean_node_id)
+        
+        status = "permanently deleted" if permanent else "moved to trash"
+        logger.info(f"✅ Node {status}: {filename}")
+        
+        if ctx:
+            await ctx.report_progress(1.0)
+        return safe_format_output(f"""✅ **Deletion Complete**
+
+📄 **Node**: {node_info.name}
+🗑️ **Status**: {status.title()}
+{"⚠️ **WARNING**: This action cannot be undone" if permanent else "ℹ️ **INFO**: Can be restored from trash"}
+
+🆔 **Node ID**: {clean_node_id}""")
+        
+    except Exception as e:
+        error_msg = f"ERROR: Deletion failed: {str(e)}"
+        if ctx:
+            await ctx.error(error_msg)
+        logger.error(f"Deletion failed: {e}")
+        return error_msg 

alfresco_mcp_server/tools/core/download_document.py

@@ -0,0 +1,214 @@
+"""
+Download document tool for Alfresco MCP Server.
+Self-contained tool for downloading documents from Alfresco repository.
+"""
+import logging
+import httpx
+import base64
+import os
+import pathlib
+from datetime import datetime
+from typing import Optional
+from fastmcp import Context
+from ...utils.connection import get_core_client
+from ...config import config
+from ...utils.file_type_analysis import analyze_content_type
+from ...utils.json_utils import safe_format_output
+
+logger = logging.getLogger(__name__)
+
+
+async def download_document_impl(
+    node_id: str, 
+    save_to_disk: bool = True,
+    attachment: bool = True,
+    ctx: Optional[Context] = None
+) -> str:
+    """Download a document from Alfresco repository.
+    
+    Args:
+        node_id: Node ID of the document to download
+        save_to_disk: If True, saves file to Downloads folder (default, AI-friendly). 
+                     If False, returns base64 content (testing/debugging)
+        attachment: If True, downloads as attachment (default). If False, opens for preview in browser
+        ctx: MCP context for progress reporting
+    
+    Returns:
+        File path and confirmation if save_to_disk=True, or base64 content if False
+    """
+    if ctx:
+        await ctx.info(f"Downloading document: {node_id}")
+        await ctx.report_progress(0.0)
+    
+    try:
+        logger.info(f"Starting download: node {node_id}")
+        core_client = await get_core_client()
+        
+        if ctx:
+            await ctx.info("Getting node information...")
+            await ctx.report_progress(0.3)
+        
+        # Clean the node ID (remove any URL encoding or extra characters)
+        clean_node_id = node_id.strip()
+        if clean_node_id.startswith('alfresco://'):
+            # Extract node ID from URI format
+            clean_node_id = clean_node_id.split('/')[-1]
+        
+        # Get node information first to validate it exists and get filename
+        node_response = core_client.nodes.get(node_id=clean_node_id)
+        
+        if not hasattr(node_response, 'entry'):
+            return safe_format_output(f"❌ Failed to get node information for: {clean_node_id}")
+        
+        node_info = node_response.entry
+        filename = getattr(node_info, 'name', f"document_{clean_node_id}")
+        node_type = getattr(node_info, 'node_type', 'Unknown')
+        
+        # Check if it's actually a file
+        is_file = getattr(node_info, 'is_file', False)
+        if not is_file:
+            return safe_format_output(f"❌ Node {clean_node_id} is not a file (it's a {node_type})")
+        
+        # Clean filename - strip whitespace and remove invalid characters for file paths
+        filename = filename.strip()
+        # Remove newlines and other control characters
+        filename = filename.replace('\n', '').replace('\r', '').replace('\t', '')
+        # Remove or replace invalid Windows filename characters
+        invalid_chars = '<>:"|?*'
+        for char in invalid_chars:
+            filename = filename.replace(char, '_')
+        # Ensure filename is not empty
+        if not filename or filename == '_':
+            filename = f"document_{clean_node_id}"
+        
+        if ctx:
+            await ctx.info(f"Downloading content for: {filename}")
+            await ctx.report_progress(0.7)
+        
+        # Get file content using authenticated HTTP client from core client
+        # Build correct content URL based on config
+        if config.alfresco_url.endswith('/alfresco/api/-default-/public'):
+            # Full API path provided
+            content_url = f"{config.alfresco_url}/alfresco/versions/1/nodes/{clean_node_id}/content"
+        elif config.alfresco_url.endswith('/alfresco/api'):
+            # Base API path provided
+            content_url = f"{config.alfresco_url}/-default-/public/alfresco/versions/1/nodes/{clean_node_id}/content"
+        else:
+            # Base server URL provided
+            content_url = f"{config.alfresco_url}/alfresco/api/-default-/public/alfresco/versions/1/nodes/{clean_node_id}/content"
+        
+        # Use the authenticated HTTP client from core client (ensure initialization)
+        if not core_client.is_initialized:
+            return safe_format_output("❌ Error: Alfresco server unavailable")
+        # Use httpx_client property directly on AlfrescoCoreClient
+        http_client = core_client.httpx_client
+        
+        # Add attachment parameter if specified
+        params = {}
+        if not attachment:
+            params['attachment'] = 'false'
+        
+        logger.debug(f"Downloading content from: {content_url}")
+        response = http_client.get(content_url, params=params)
+        response.raise_for_status()
+        content_bytes = response.content
+        logger.info(f"Downloaded {len(content_bytes)} bytes for {filename}")
+        
+        if ctx:
+            await ctx.report_progress(0.9)
+        
+        file_size = len(content_bytes)
+        # Fix: ContentInfo object doesn't have .get() method - access mime_type attribute directly
+        mime_type = 'application/octet-stream'
+        if hasattr(node_info, 'content') and node_info.content:
+            mime_type = getattr(node_info.content, 'mime_type', 'application/octet-stream')
+        
+        if save_to_disk:
+            # AI-Client friendly: Save file to Downloads folder with content-aware handling
+            
+            # Create Downloads directory if it doesn't exist
+            downloads_dir = pathlib.Path.home() / "Downloads"
+            downloads_dir.mkdir(exist_ok=True)
+            
+            # Content-aware file handling
+            file_extension = pathlib.Path(filename).suffix.lower()
+            content_type_info = analyze_content_type(filename, mime_type, content_bytes)
+            
+            # Create smart filename with content type organization
+            if content_type_info['category'] != 'other':
+                category_dir = downloads_dir / content_type_info['category']
+                category_dir.mkdir(exist_ok=True)
+                downloads_dir = category_dir
+            
+            # Create unique filename with node ID to avoid conflicts
+            name_parts = filename.rsplit('.', 1)
+            if len(name_parts) == 2:
+                safe_filename = f"{name_parts[0]}_{clean_node_id}.{name_parts[1]}"
+            else:
+                safe_filename = f"{filename}_{clean_node_id}"
+            
+            file_path = downloads_dir / safe_filename
+            
+            # Write file to disk
+            with open(file_path, 'wb') as f:
+                f.write(content_bytes)
+            
+            logger.info(f"File saved: {filename} -> {file_path}")
+            if ctx:
+                await ctx.info(f"File saved to: {file_path}")
+                await ctx.report_progress(1.0)
+            
+            # Format file size
+            if file_size < 1024:
+                size_str = f"{file_size} bytes"
+            elif file_size < 1024 * 1024:
+                size_str = f"{file_size / 1024:.1f} KB"
+            else:
+                size_str = f"{file_size / (1024 * 1024):.1f} MB"
+            
+            download_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            
+            # Clean JSON-friendly formatting (no markdown syntax)
+            result = f"📥 Document Downloaded Successfully!\n\n"
+            result += f"📄 Name: {filename}\n"
+            result += f"🆔 Node ID: {clean_node_id}\n"
+            result += f"📏 Size: {size_str}\n"
+            result += f"📄 MIME Type: {mime_type}\n"
+            result += f"💾 Saved to: {file_path}\n"
+            result += f"📁 Directory: {downloads_dir}\n"
+            result += f"🕒 Downloaded: {download_time}\n\n"
+            result += f"File saved to your Downloads folder for easy access.\n"
+            result += f"You can now open, edit, or move the file as needed.\n"
+            
+            if content_type_info['category'] and content_type_info['category'].strip():
+                result += f"📝 **Content Type**: {content_type_info['category']}\n"
+            
+            # Content-aware suggestions
+            if content_type_info['suggestions']:
+                result += f"**Content-Aware Suggestions:**\n"
+                for suggestion in content_type_info['suggestions']:
+                    result += f"   {suggestion}\n"
+                result += "\n"
+            
+            result += f"**Organized in**: {content_type_info['category']} folder\n"
+            result += f"**Tip**: File is automatically organized by content type for easier management!"
+            
+            return safe_format_output(result)
+        else:
+            # Testing/debugging mode: Return base64 content
+            base64_content = base64.b64encode(content_bytes).decode('ascii')
+            
+            result = f"**Downloaded: {filename}**\n\n"
+            result += f"- **Node ID**: {clean_node_id}\n"
+            result += f"- **Size**: {file_size} bytes\n"
+            result += f"- **MIME Type**: {mime_type}\n\n"
+            result += f"**Base64 Content**:\n```\n{base64_content[:200]}{'...' if len(base64_content) > 200 else ''}\n```\n"
+            result += f"\n*Note: Content is base64 encoded. Full content length: {len(base64_content)} characters*"
+            
+            return safe_format_output(result)
+        
+    except Exception as e:
+        error_msg = f"❌ Failed to download document {node_id}: {str(e)}"
+        if ctx:
+            await ctx.error(error_msg)
+        return safe_format_output(error_msg)