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

alfresco_mcp_server/tools/__init__.py

@@ -0,0 +1,13 @@
+"""
+Tools module for Alfresco MCP Server.
+Contains core and search tools organized hierarchically.
+"""
+
+# Import subdirectories
+from . import core
+from . import search
+
+__all__ = [
+    "core",
+    "search",
+] 

alfresco_mcp_server/tools/core/__init__.py

@@ -0,0 +1,27 @@
+# Core tools module
+
+from . import (
+    browse_repository,
+    cancel_checkout,
+    checkin_document,
+    checkout_document,
+    create_folder,
+    delete_node,
+    download_document,
+    get_node_properties,
+    update_node_properties,
+    upload_document,
+)
+
+__all__ = [
+    "browse_repository",
+    "cancel_checkout",
+    "checkin_document", 
+    "checkout_document",
+    "create_folder",
+    "delete_node",
+    "download_document",
+    "get_node_properties",
+    "update_node_properties",
+    "upload_document",
+] 

alfresco_mcp_server/tools/core/browse_repository.py

@@ -0,0 +1,164 @@
+"""
+Browse repository tool for Alfresco MCP Server.
+Self-contained tool for browsing Alfresco repository structure.
+"""
+import logging
+from typing import Optional
+from fastmcp import Context
+
+from ...utils.connection import ensure_connection
+
+logger = logging.getLogger(__name__)
+
+
+async def browse_repository_impl(
+    parent_id: str = "-my-",
+    max_items: int = 25,
+    ctx: Optional[Context] = None
+) -> str:
+    """Browse the Alfresco repository structure.
+    
+    Args:
+        parent_id: Parent node ID to browse (default: user's personal space)
+        max_items: Maximum number of items to return (default: 25)
+        ctx: MCP context for progress reporting
+    
+    Returns:
+        Formatted listing of repository contents
+    """
+    # Parameter validation and extraction
+    try:
+        # Extract parameters with fallback handling
+        if hasattr(parent_id, 'value'):
+            actual_parent_id = str(parent_id.value)
+        else:
+            actual_parent_id = str(parent_id)
+            
+        if hasattr(max_items, 'value'):
+            actual_max_items = int(max_items.value)
+        else:
+            actual_max_items = int(max_items)
+        
+        # Clean and normalize for display (preserve Unicode characters)
+        safe_parent_id_display = str(actual_parent_id)
+        
+    except Exception as e:
+        logger.error(f"Parameter extraction error: {e}")
+        return f"ERROR: Parameter error: {str(e)}"
+    
+    if ctx:
+        await ctx.info(f"Browsing repository node: {safe_parent_id_display}")
+        await ctx.report_progress(0.0)
+    
+    try:
+        # Get all clients that ensure_connection() already created
+        master_client = await ensure_connection()
+        
+        # Access the core client that was already created
+        core_client = master_client.core
+        
+        # Try high-level API first, then use raw client property (NEW: cleaner access)
+        # Check if we can use high-level nodes.get_children()
+        try:
+            # Use high-level API for browsing (preferred approach)
+            children_result = core_client.nodes.get_children(actual_parent_id, max_items=actual_max_items)
+            if children_result and hasattr(children_result, 'list') and hasattr(children_result.list, 'entries'):
+                entries = children_result.list.entries
+                logger.info(f"Browse response via high-level API: {len(entries)} entries found")
+            else:
+                raise Exception("High-level API returned unexpected format")
+        except Exception as high_level_error:
+            logger.info(f"High-level API failed, using raw client: {high_level_error}")
+            # Fallback to raw client (ensure initialization)
+            if not core_client.is_initialized:
+                return safe_format_output("❌ Error: Alfresco server unavailable")
+            # Use httpx_client property directly on AlfrescoCoreClient
+            core_httpx = core_client.httpx_client
+        
+        logger.info(f"Browsing repository node: {safe_parent_id_display}")
+        logger.info(f"Max items: {actual_max_items}")
+        logger.info(f"Using URL: /nodes/{actual_parent_id}/children")
+        
+        if ctx:
+            await ctx.report_progress(0.3)
+        
+        # If high-level API didn't work, use HTTPx fallback
+        if 'entries' not in locals():
+            if ctx:
+                await ctx.report_progress(0.5)
+            
+            try:
+                # Use HTTPx client as fallback
+                url = f"/nodes/{actual_parent_id}/children"
+                if actual_max_items != 25:
+                    url += f"?maxItems={actual_max_items}"
+                
+                response = core_httpx.get(url)
+                
+                if response.status_code == 200:
+                    result_data = response.json()
+                    entries = result_data.get("list", {}).get("entries", [])
+                    logger.info(f"Browse response via HTTPx fallback: {len(entries)} entries found")
+                    
+                else:
+                    error_text = response.text if hasattr(response, 'text') else str(response)
+                    raise Exception(f"Browse failed with status {response.status_code}: {error_text}")
+                    
+            except Exception as browse_error:
+                raise Exception(f"Repository browse operation failed: {str(browse_error)}")
+        
+        # Check if we have entries
+        if not entries:
+            return f"Repository Browse Results\n\nNode: {safe_parent_id_display}\n\nNo child items found in this location."
+        
+        if ctx:
+            await ctx.report_progress(1.0)
+        
+        # Process final results
+        if entries:
+            logger.info(f"Found {len(entries)} repository items")
+            
+            # Clean JSON-friendly formatting (no markdown syntax)
+            result_text = f"Repository Browse Results\n\nNode: {safe_parent_id_display}\n\n"
+            result_text += f"Parent Node: {safe_parent_id_display}\n"
+            result_text += f"Found {len(entries)} item(s):\n\n"
+            
+            for i, entry_wrapper in enumerate(entries, 1):
+                # Handle JSON response structure correctly
+                if isinstance(entry_wrapper, dict) and 'entry' in entry_wrapper:
+                    entry = entry_wrapper['entry']
+                else:
+                    entry = entry_wrapper
+                
+                # Extract values from dictionary
+                name = str(entry.get('name', 'Unknown'))
+                node_id = str(entry.get('id', 'Unknown'))
+                node_type = str(entry.get('nodeType', 'Unknown'))
+                is_folder = entry.get('isFolder', False)
+                created_at = str(entry.get('createdAt', 'Unknown'))
+                
+                # Choose icon based on type
+                icon = "[FOLDER]" if is_folder else "[FILE]"
+                
+                result_text += f"{i}. {icon} {name}\n"
+                result_text += f"   - ID: {node_id}\n"
+                result_text += f"   - Type: {node_type}\n"
+                result_text += f"   - Created: {created_at}\n\n"
+            
+            result_text += f"Navigation help:\n"
+            result_text += "• Use the node ID to browse deeper: browse_repository(parent_id=\"<node_id>\")\n"
+            result_text += "• Common parent IDs: -root- (repository root), -shared- (shared folder), -my- (my files)\n"
+            
+            return result_text
+        else:
+            return f"Repository Browse Results\n\nNode: {safe_parent_id_display}\n\nNo child items found in this location."
+            
+    except Exception as e:
+        # Preserve Unicode characters in error messages
+        error_msg = f"ERROR: Repository browse failed: {str(e)}"
+        if ctx:
+            await ctx.error(error_msg)
+        return error_msg 
+
+    if ctx:
+        await ctx.info("Repository browse completed!") 

alfresco_mcp_server/tools/core/cancel_checkout.py

@@ -0,0 +1,160 @@
+"""
+Cancel checkout tool implementation for Alfresco MCP Server.
+Handles canceling document checkout with cleanup and unlock management.
+"""
+import logging
+import pathlib
+import json
+from datetime import datetime
+from fastmcp import Context
+
+from ...utils.connection import get_core_client
+from ...utils.json_utils import safe_format_output
+
+logger = logging.getLogger(__name__)
+
+
+async def cancel_checkout_impl(
+    node_id: str,
+    ctx: Context = None
+) -> str:
+    """Cancel checkout of a document, discarding any working copy.
+    
+    Args:
+        node_id: Original node ID that was checked out
+        ctx: MCP context for progress reporting
+    
+    Returns:
+        Cancellation confirmation and cleanup status
+    """
+    if ctx:
+        await ctx.info(f"Cancelling checkout for: {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 cancel checkout: node {node_id}")
+        core_client = await get_core_client()
+        
+        # Clean the node ID
+        clean_node_id = node_id.strip()
+        if clean_node_id.startswith('alfresco://'):
+            clean_node_id = clean_node_id.split('/')[-1]
+        
+        if ctx:
+            await ctx.info("Checking node status...")
+            await ctx.report_progress(0.3)
+        
+        # Get node information to validate using high-level core client
+        node_response = core_client.nodes.get(node_id=clean_node_id)
+        
+        if not hasattr(node_response, 'entry'):
+            return f"ERROR: 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(">> Performing Alfresco unlock using high-level client...")
+            await ctx.report_progress(0.5)
+        
+        # Use high-level core client unlock method
+        try:
+            logger.info(f"Attempting to unlock document: {clean_node_id}")
+            unlock_response = core_client.versions.cancel_checkout(node_id=clean_node_id)
+            if unlock_response and hasattr(unlock_response, 'entry'):
+                api_status = "✅ Document unlocked in Alfresco"
+            else:
+                api_status = "✅ Document unlocked in Alfresco"
+            logger.info(f"Document unlocked successfully: {clean_node_id}")
+        except Exception as unlock_error:
+            error_str = str(unlock_error)
+            if "404" in error_str:
+                # Document might not be locked
+                api_status = "ℹ️ Document was not locked in Alfresco"
+                logger.info(f"Document was not locked: {clean_node_id}")
+            elif "405" in error_str:
+                # Server doesn't support lock/unlock APIs
+                api_status = "WARNING: Server doesn't support lock/unlock APIs (treating as unlocked)"
+                logger.warning(f"Server doesn't support unlock API for {clean_node_id}")
+            else:
+                api_status = f"WARNING: Alfresco unlock failed: {error_str}"
+                logger.error(f"Failed to unlock document {clean_node_id}: {error_str}")
+        
+        if ctx:
+            await ctx.info("Cleaning up local files...")
+            await ctx.report_progress(0.7)
+        
+        # Clean up local checkout tracking
+        downloads_dir = pathlib.Path.home() / "Downloads"
+        checkout_dir = downloads_dir / "checkout"
+        checkout_manifest_path = checkout_dir / ".checkout_manifest.json"
+        
+        checkout_data = {}
+        cleanup_status = [api_status]
+        
+        if checkout_manifest_path.exists():
+            try:
+                with open(checkout_manifest_path, 'r') as f:
+                    checkout_data = json.load(f)
+            except:
+                checkout_data = {}
+        
+        # Check if this node is tracked in local checkouts
+        if 'checkouts' in checkout_data and clean_node_id in checkout_data['checkouts']:
+            checkout_info = checkout_data['checkouts'][clean_node_id]
+            checkout_filename = checkout_info['local_file']
+            checkout_file_path = checkout_dir / checkout_filename
+            
+            # Remove local checkout file
+            try:
+                if checkout_file_path.exists():
+                    checkout_file_path.unlink()
+                    cleanup_status.append("🗑️ Local checkout file removed")
+                    logger.info(f"Removed local checkout file: {checkout_file_path}")
+                else:
+                    cleanup_status.append("ℹ️ Local checkout file already removed")
+            except Exception as e:
+                cleanup_status.append(f"WARNING: Could not remove local file: {e}")
+                logger.warning(f"Failed to remove local file {checkout_file_path}: {e}")
+            
+            # Remove from tracking
+            del checkout_data['checkouts'][clean_node_id]
+            
+            # Update manifest
+            try:
+                with open(checkout_manifest_path, 'w') as f:
+                    json.dump(checkout_data, f, indent=2)
+                cleanup_status.append(">> Checkout tracking updated")
+            except Exception as e:
+                cleanup_status.append(f"WARNING: Could not update tracking: {e}")
+        else:
+            cleanup_status.append("ℹ️ No local checkout tracking found")
+        
+        if ctx:
+            await ctx.info("Document unlocked!")
+            await ctx.report_progress(1.0)
+        
+        # Clean JSON-friendly formatting (no markdown syntax)
+        result = f"🔓 Document Unlocked\n\n"
+        result += f">> Document: {filename}\n"
+        result += f"ID: Node ID: {clean_node_id}\n"
+        result += f"🕒 Unlocked: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+        result += f"🧹 Cleanup Status:\n"
+        
+        for status in cleanup_status:
+            result += f"   {status}\n"
+        
+        result += f"\nINFO: Note: Document is now available for others to edit."
+        result += f"\nWARNING: Important: Any unsaved changes in the local file have been discarded."
+        
+        return safe_format_output(result)
+        
+    except Exception as e:
+        error_msg = f"❌ Cancel checkout failed: {str(e)}"
+        if ctx:
+            await ctx.error(error_msg)
+        logger.error(f"Cancel checkout failed: {e}")
+        return safe_format_output(error_msg) 

alfresco_mcp_server/tools/core/checkin_document.py

@@ -0,0 +1,264 @@
+"""
+Checkin document tool implementation for Alfresco MCP Server.
+Handles document checkin with versioning and cleanup management.
+"""
+import logging
+import os
+import pathlib
+import json
+import urllib.parse
+from io import BytesIO
+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
+from python_alfresco_api.raw_clients.alfresco_core_client.core_client.types import File
+from python_alfresco_api.raw_clients.alfresco_core_client.core_client.api.nodes.update_node_content import sync as update_node_content_sync
+
+logger = logging.getLogger(__name__)
+
+
+async def checkin_document_impl(
+    node_id: str, 
+    comment: str = "", 
+    major_version: bool = False,
+    file_path: str = "",
+    new_name: str = "",
+    ctx: Context = None
+) -> str:
+    """Check in a document after editing using Alfresco REST API.
+    
+    Args:
+        node_id: Original node ID to check in (not working copy)
+        comment: Check-in comment (default: empty)
+        major_version: Whether to create a major version (default: False = minor version)
+        file_path: Specific file path to upload (if empty, auto-detects from checkout folder)
+        new_name: Optional new name for the file during checkin (default: keep original name)
+        ctx: MCP context for progress reporting
+    
+    Returns:
+        Check-in confirmation with version details and cleanup status
+    """
+    if ctx:
+        await ctx.info(f"Checking in document: {node_id}")
+        await ctx.info("Validating parameters...")
+        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 checkin: node {node_id}")
+        core_client = await get_core_client()
+        
+        # Clean the node ID
+        clean_node_id = node_id.strip()
+        if clean_node_id.startswith('alfresco://'):
+            clean_node_id = clean_node_id.split('/')[-1]
+        
+        if ctx:
+            await ctx.info("Finding checkout file...")
+            await ctx.report_progress(0.2)
+        
+        # Find the file to upload
+        checkout_file_path = None
+        checkout_data = {}
+        working_copy_id = None
+        
+        if file_path:
+            # Use specific file path provided - handle quotes and path expansion
+            cleaned_file_path = file_path.strip().strip('"').strip("'")
+            
+            # Handle macOS/Unix path expansion (~/Documents, etc.)
+            if cleaned_file_path.startswith('~'):
+                cleaned_file_path = os.path.expanduser(cleaned_file_path)
+            
+            checkout_file_path = pathlib.Path(cleaned_file_path)
+            if not checkout_file_path.exists():
+                return safe_format_output(f"❌ Specified file not found: {cleaned_file_path} (cleaned from: {file_path})")
+            
+            # Linux-specific: Check file permissions
+            if not os.access(checkout_file_path, os.R_OK):
+                return safe_format_output(f"❌ File not readable (permission denied): {cleaned_file_path}")
+        else:
+            # Auto-detect from checkout folder
+            downloads_dir = pathlib.Path.home() / "Downloads"
+            checkout_dir = downloads_dir / "checkout"
+            checkout_manifest_path = checkout_dir / ".checkout_manifest.json"
+            
+            if checkout_manifest_path.exists():
+                try:
+                    with open(checkout_manifest_path, 'r') as f:
+                        checkout_data = json.load(f)
+                except:
+                    checkout_data = {}
+            
+            if 'checkouts' in checkout_data and clean_node_id in checkout_data['checkouts']:
+                checkout_info = checkout_data['checkouts'][clean_node_id]
+                checkout_filename = checkout_info['local_file']
+                locked_node_id = checkout_info.get('locked_node_id', clean_node_id)  # Updated for lock API
+                checkout_file_path = checkout_dir / checkout_filename
+                
+                if not checkout_file_path.exists():
+                    return safe_format_output(f"❌ Checkout file not found: {checkout_file_path}. File may have been moved or deleted.")
+            else:
+                return safe_format_output(f"❌ No locked document found for node {clean_node_id}. Use checkout_document first, or specify file_path manually.")
+        
+        if ctx:
+            await ctx.info(f"Uploading file: {checkout_file_path.name}")
+            await ctx.report_progress(0.4)
+        
+        # Read the file content
+        with open(checkout_file_path, 'rb') as f:
+            file_content = f.read()
+        
+        logger.info(f"Checkin file: {checkout_file_path.name} ({len(file_content)} bytes)")
+        # Get original node info 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
+        original_filename = getattr(node_info, 'name', f"document_{clean_node_id}")
+        
+        if ctx:
+            await ctx.info("Uploading new content with versioning using high-level API...")
+            await ctx.report_progress(0.7)
+        
+        # **USE HIGH-LEVEL API: update_node_content.sync()**
+        # Use new name if provided, otherwise keep original filename
+        final_filename = new_name.strip() if new_name.strip() else original_filename
+        
+        # Create File object with content
+        file_obj = File(
+            payload=BytesIO(file_content),
+            file_name=final_filename,
+            mime_type="application/octet-stream"
+        )
+        
+        # Use high-level update_node_content API instead of manual httpx
+        try:
+            version_type = "major" if major_version else "minor"
+            logger.info(f"Updating content for {clean_node_id} ({version_type} version)")
+            # Ensure raw client is initialized before using it
+            if not core_client.is_initialized:
+                return safe_format_output("❌ Error: Alfresco server unavailable")
+            # Use high-level update_node_content API
+            content_response = update_node_content_sync(
+                node_id=clean_node_id,
+                client=core_client.raw_client,
+                body=file_obj,
+                major_version=major_version,
+                comment=comment if comment else None,
+                name=new_name.strip() if new_name.strip() else None
+            )
+            
+            if not content_response:
+                return safe_format_output(f"❌ Failed to update document content using high-level API")
+            
+            logger.info(f"Content updated successfully for {clean_node_id}")
+            
+            # CRITICAL: Unlock the document after successful content update to complete checkin
+            try:
+                logger.info(f"Unlocking document after successful checkin: {clean_node_id}")
+                unlock_response = core_client.versions.cancel_checkout(node_id=clean_node_id)
+                logger.info(f"Document unlocked successfully after checkin: {clean_node_id}")
+            except Exception as unlock_error:
+                error_str = str(unlock_error)
+                if "404" in error_str:
+                    logger.info(f"Document was not locked (already unlocked): {clean_node_id}")
+                elif "405" in error_str:
+                    logger.warning(f"Server doesn't support unlock APIs: {clean_node_id}")
+                else:
+                    logger.error(f"Failed to unlock document after checkin: {clean_node_id} - {error_str}")
+                    # Don't fail the entire checkin if unlock fails - content was updated successfully
+                
+        except Exception as api_error:
+            return safe_format_output(f"❌ Failed to update document content: {str(api_error)}")
+        
+        # Get updated node info to show version details using high-level core client
+        updated_node_response = core_client.nodes.get(node_id=clean_node_id)
+        updated_node = updated_node_response.entry if hasattr(updated_node_response, 'entry') else {}
+        
+        # Extract version using multiple access methods (same as get_node_properties)
+        new_version = 'Unknown'
+        if hasattr(updated_node, 'properties') and updated_node.properties:
+            try:
+                # Try to_dict() method first
+                if hasattr(updated_node.properties, 'to_dict'):
+                    props_dict = updated_node.properties.to_dict()
+                    new_version = props_dict.get('cm:versionLabel', 'Unknown')
+                    logger.info(f"Version found via to_dict(): {new_version}")
+                # Try direct attribute access
+                elif hasattr(updated_node.properties, 'cm_version_label') or hasattr(updated_node.properties, 'cm:versionLabel'):
+                    new_version = getattr(updated_node.properties, 'cm_version_label', getattr(updated_node.properties, 'cm:versionLabel', 'Unknown'))
+                    logger.info(f"Version found via attributes: {new_version}")
+                # Try dict-like access
+                elif hasattr(updated_node.properties, '__getitem__'):
+                    new_version = updated_node.properties.get('cm:versionLabel', 'Unknown') if hasattr(updated_node.properties, 'get') else updated_node.properties['cm:versionLabel'] if 'cm:versionLabel' in updated_node.properties else 'Unknown'
+                    logger.info(f"Version found via dict access: {new_version}")
+                else:
+                    logger.warning(f"Version properties - type: {type(updated_node.properties)}, methods: {dir(updated_node.properties)}")
+            except Exception as version_error:
+                logger.error(f"Error extracting version: {version_error}")
+                new_version = 'Unknown'
+        else:
+            logger.warning("No properties found for version extraction")
+        
+        if ctx:
+            await ctx.info("Cleaning up checkout tracking...")
+            await ctx.report_progress(0.9)
+        
+        # Clean up checkout tracking
+        cleanup_status = "ℹ️  No checkout tracking to clean up"
+        if checkout_data and 'checkouts' in checkout_data and clean_node_id in checkout_data['checkouts']:
+            del checkout_data['checkouts'][clean_node_id]
+            
+            checkout_manifest_path = pathlib.Path.home() / "Downloads" / "checkout" / ".checkout_manifest.json"
+            with open(checkout_manifest_path, 'w') as f:
+                json.dump(checkout_data, f, indent=2)
+            
+            # Optionally remove the checkout file
+            try:
+                checkout_file_path.unlink()
+                cleanup_status = "🗑️  Local checkout file cleaned up"
+            except:
+                cleanup_status = "WARNING:  Local checkout file cleanup failed"
+        
+        if ctx:
+            await ctx.info("Checkin completed: Content updated + Document unlocked + Version created!")
+            await ctx.report_progress(1.0)
+        
+        # Format file size
+        file_size = len(file_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"
+        
+        # Clean JSON-friendly formatting (no markdown syntax)
+        return safe_format_output(f"""✅ Document checked in successfully!
+
+📄 Document: {final_filename}
+🔢 New Version: {new_version} ({version_type})
+📝 Comment: {comment if comment else '(no comment)'}
+📊 File Size: {size_str}
+🔗 Node ID: {clean_node_id}
+{f"📝 Renamed: {original_filename} → {final_filename}" if new_name.strip() else ""}
+
+{cleanup_status}
+
+Next Steps:
+🔓 Document is now UNLOCKED and available for others to edit
+✅ New version has been created with your changes
+✅ You can continue editing by using checkout_document again
+
+Status: Content updated → Document unlocked → Checkin complete!""")
+        
+    except Exception as e:
+        logger.error(f"Checkin failed: {str(e)}")
+        return safe_format_output(f"❌ Checkin failed: {str(e)}")