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

alfresco_mcp_server/tools/search/search_content.py

@@ -0,0 +1,186 @@
+"""
+Content search tool for Alfresco MCP Server.
+Each tool is self-contained with its own validation, business logic, and env handling.
+"""
+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 search_content_impl(
+    search_query: str,
+    max_results: int = 25,
+    node_type: str = "cm:content",
+    ctx: Optional[Context] = None
+) -> str:
+    """Search for content in Alfresco repository.
+    
+    Args:
+        search_query: Search query string
+        max_results: Maximum number of results to return (default: 25)
+        node_type: Type of nodes to search for (default: "cm:content" - searches documents)
+        ctx: MCP context for progress reporting
+    
+    Returns:
+        Formatted search results
+    """
+    # Parameter validation and extraction
+    try:
+        # Extract parameters with fallback handling
+        if hasattr(search_query, 'value'):
+            actual_query = str(search_query.value)
+        else:
+            actual_query = str(search_query)
+            
+        if hasattr(max_results, 'value'):
+            actual_max_results = int(max_results.value)
+        else:
+            actual_max_results = int(max_results)
+            
+        if hasattr(node_type, 'value'):
+            actual_node_type = str(node_type.value)
+        else:
+            actual_node_type = str(node_type)
+        
+        # Default to cm:content if empty
+        if not actual_node_type.strip():
+            actual_node_type = "cm:content"
+        
+        # Clean and normalize for display (prevent Unicode encoding issues)
+        safe_query_display = safe_format_output(str(actual_query))
+        safe_node_type_display = safe_format_output(str(actual_node_type))
+        
+    except Exception as e:
+        logger.error(f"Parameter extraction error: {e}")
+        return safe_format_output(f"ERROR: Parameter error: {str(e)}")
+    
+    if not actual_query.strip():
+        return """Content Search Tool
+
+Usage: Provide a search query to search Alfresco repository content.
+
+Example searches:
+- admin (finds items with 'admin' in name or content)
+- name:test* (finds items with names starting with 'test')
+- modified:[2024-01-01 TO 2024-12-31] (finds items modified in 2024)
+- TYPE:"cm:content" (finds all documents)
+- TYPE:"cm:folder" (finds all folders)
+
+Search uses AFTS (Alfresco Full Text Search) syntax for flexible content discovery.
+By default, searches for documents (cm:content) unless a different type is specified.
+"""
+    
+    if ctx:
+        await ctx.info(safe_format_output(f"Content search for: '{safe_query_display}'"))
+        await ctx.report_progress(0.0)
+    
+    try:
+        # Get all clients that ensure_connection() already created
+        master_client = await ensure_connection()
+        
+        # Import search_utils
+        from python_alfresco_api.utils import search_utils
+        
+        # Access the search client that was already created
+        search_client = master_client.search
+        
+        logger.info(f"Content search for: '{safe_query_display}', type: '{safe_node_type_display}'")
+        
+        if ctx:
+            await ctx.report_progress(0.3)
+        
+        # Build search query to include node_type filter
+        final_query = actual_query
+        
+        # Add node_type filter if not already in query
+        has_type_in_query = "TYPE:" in final_query.upper()
+        if not has_type_in_query:
+            if final_query == "*":
+                final_query = f'TYPE:"{actual_node_type}"'
+            else:
+                final_query = f'({final_query}) AND TYPE:"{actual_node_type}"'
+        
+        # Use the correct working pattern: search_utils.simple_search with existing search_client
+        try:
+            search_results = search_utils.simple_search(search_client, final_query, max_items=actual_max_results)
+            
+            if search_results and hasattr(search_results, 'list_'):
+                entries_list = search_results.list_.entries if search_results.list_  else []
+                logger.info(f"Found {len(entries_list)} content search results")
+                
+                if ctx:
+                    await ctx.report_progress(1.0)
+                
+                if not entries_list:
+                    return "0"
+                
+                result_text = f"Found {len(entries_list)} item(s) matching the search query:\n\n"
+                
+                for i, entry in enumerate(entries_list, 1):
+                    # Debug: Log the entry structure
+                    logger.debug(f"Entry {i} type: {type(entry)}, content: {entry}")
+                    
+                    # Handle different possible entry structures
+                    node = None
+                    if isinstance(entry, dict):
+                        if 'entry' in entry:
+                            node = entry['entry']
+                        elif 'name' in entry:  # Direct node structure
+                            node = entry
+                        else:
+                            logger.warning(f"Unknown entry structure: {entry}")
+                            continue
+                    elif hasattr(entry, 'entry'):  # ResultSetRowEntry object
+                        node = entry.entry
+                    else:
+                        logger.warning(f"Entry is not a dict or ResultSetRowEntry: {type(entry)}")
+                        continue
+                    
+                    if node:
+                        # Handle both dict and ResultNode objects
+                        if isinstance(node, dict):
+                            name = str(node.get('name', 'Unknown'))
+                            node_id = str(node.get('id', 'Unknown'))
+                            node_type_actual = str(node.get('nodeType', 'Unknown'))
+                            created_at = str(node.get('createdAt', 'Unknown'))
+                        else:
+                            # ResultNode object - access attributes directly
+                            name = str(getattr(node, 'name', 'Unknown'))
+                            node_id = str(getattr(node, 'id', 'Unknown'))
+                            node_type_actual = str(getattr(node, 'node_type', 'Unknown'))
+                            created_at = str(getattr(node, 'created_at', 'Unknown'))
+                        
+                        # Clean JSON-friendly formatting (no markdown syntax)
+                        # Apply safe formatting to individual fields to prevent emoji encoding issues
+                        safe_name = safe_format_output(name)
+                        safe_node_id = safe_format_output(node_id)
+                        safe_node_type = safe_format_output(node_type_actual)
+                        safe_created_at = safe_format_output(created_at)
+                        
+                        result_text += f"{i}. {safe_name}\n"
+                        result_text += f"   - ID: {safe_node_id}\n"
+                        result_text += f"   - Type: {safe_node_type}\n"
+                        result_text += f"   - Created: {safe_created_at}\n\n"
+                
+                return safe_format_output(result_text)
+            else:
+                return safe_format_output(f"ERROR: Content search failed - invalid response from Alfresco")
+                
+        except Exception as e:
+            logger.error(f"Content search failed: {e}")
+            return safe_format_output(f"ERROR: Content search failed: {str(e)}")
+        
+    except Exception as e:
+        # Preserve Unicode characters in error messages
+        error_msg = f"ERROR: Content search failed: {str(e)}"
+        if ctx:
+            await ctx.error(safe_format_output(error_msg))
+        return safe_format_output(error_msg)
+
+    if ctx:
+        await ctx.info(safe_format_output("Content search completed!")) 

alfresco_mcp_server/utils/__init__.py

@@ -0,0 +1,34 @@
+# Utilities module for Alfresco MCP Server
+
+from .connection import (
+    get_alfresco_config,
+    get_connection,
+    get_search_utils,
+    get_node_utils,
+)
+
+from .file_type_analysis import (
+    detect_file_extension_from_content,
+    analyze_content_type,
+)
+
+from .json_utils import (
+    make_json_safe,
+    safe_format_output,
+    escape_unicode_for_json,
+)
+
+__all__ = [
+    # Connection utilities
+    "get_alfresco_config",
+    "get_connection", 
+    "get_search_utils",
+    "get_node_utils",
+    # File type analysis
+    "detect_file_extension_from_content",
+    "analyze_content_type",
+    # JSON utilities
+    "make_json_safe",
+    "safe_format_output",
+    "escape_unicode_for_json",
+] 

alfresco_mcp_server/utils/connection.py

@@ -0,0 +1,114 @@
+"""
+Connection utilities for Alfresco MCP Server.
+Handles client creation and connection management.
+"""
+import logging
+import os
+from typing import Optional
+
+
+logger = logging.getLogger(__name__)
+
+# Global connection cache
+_master_client = None
+_client_factory = None
+
+def get_alfresco_config() -> dict:
+    """Get Alfresco configuration from environment variables."""
+    return {
+        'alfresco_url': os.getenv('ALFRESCO_URL', 'http://localhost:8080'),
+        'username': os.getenv('ALFRESCO_USERNAME', 'admin'),
+        'password': os.getenv('ALFRESCO_PASSWORD', 'admin'),
+        'verify_ssl': os.getenv('ALFRESCO_VERIFY_SSL', 'false').lower() == 'true',
+        'timeout': int(os.getenv('ALFRESCO_TIMEOUT', '30'))
+    }
+
+
+async def ensure_connection():
+    """Ensure we have a working connection to Alfresco using python-alfresco-api."""
+    global _master_client, _client_factory
+    
+    if _master_client is None:
+        try:
+            # Import here to avoid circular imports
+            from python_alfresco_api import ClientFactory
+            
+            config = get_alfresco_config()
+            
+            logger.info(">> Creating Alfresco clients...")
+            
+            # Use ClientFactory to create authenticated client (original Sunday pattern)
+            factory = ClientFactory(
+                base_url=config['alfresco_url'],
+                username=config['username'],
+                password=config['password'],
+                verify_ssl=config['verify_ssl'],
+                timeout=config['timeout']
+            )
+            
+            # Store the factory globally for other functions to use
+            _client_factory = factory
+            
+            _master_client = factory.create_master_client()
+            logger.info("Master client created successfully")
+                        
+            # Test connection - use method that initializes and gets
+            try:
+                # Use ensure_httpx_client to initialize, then test simple call
+                _master_client.core.ensure_httpx_client()
+                logger.info("Connection test successful!")
+            except Exception as conn_error:
+                logger.warning(f"Connection test failed: {conn_error}")
+            
+        except Exception as e:
+            logger.error(f"ERROR: Failed to create clients: {str(e)}")
+            raise e
+    
+    return _master_client
+
+
+def get_connection():
+    """Get the cached connection without async (for sync operations)."""
+    return _master_client
+
+
+async def get_search_client():
+    """Get the search client for search operations (using master_client for auth compatibility)."""
+    master_client = await ensure_connection()
+    # Return master_client which has simple_search access and working authentication
+    return master_client
+
+
+async def get_core_client():
+    """Get the core client for core operations (using master_client for auth compatibility)."""
+    master_client = await ensure_connection()
+    # Return the actual core client that has nodes, folders, etc.
+    return master_client.core
+
+
+async def get_client_factory():
+    """Get the client factory for advanced operations."""
+    await ensure_connection()
+    if not _client_factory:
+        raise RuntimeError("Connection not initialized. Call ensure_connection() first.")
+    return _client_factory
+
+
+def get_search_utils():
+    """Get the search_utils module from python-alfresco-api."""
+    try:
+        from python_alfresco_api.utils import search_utils
+        return search_utils
+    except ImportError as e:
+        logger.error(f"Failed to import search_utils: {e}")
+        raise
+
+
+def get_node_utils():
+    """Get the node_utils module from python-alfresco-api."""
+    try:
+        from python_alfresco_api.utils import node_utils
+        return node_utils
+    except ImportError as e:
+        logger.error(f"Failed to import node_utils: {e}")
+        raise

alfresco_mcp_server/utils/file_type_analysis.py

@@ -0,0 +1,163 @@
+"""
+File type analysis utility for Alfresco MCP Server.
+Provides content type analysis and suggestions for different file types.
+"""
+import pathlib
+import mimetypes
+from typing import Dict, List, Optional
+
+
+def detect_file_extension_from_content(content: bytes) -> Optional[str]:
+    """Detect file type from content and return appropriate extension.
+    
+    Args:
+        content: Raw file content bytes
+        
+    Returns:
+        File extension (e.g., '.pdf', '.txt', '.jpg') or None if unknown
+    """
+    if not content:
+        return None
+    
+    # Check for common file signatures (magic numbers)
+    if content.startswith(b'%PDF'):
+        return '.pdf'
+    elif content.startswith(b'\xff\xd8\xff'):
+        return '.jpg'
+    elif content.startswith(b'\x89PNG\r\n\x1a\n'):
+        return '.png'
+    elif content.startswith(b'GIF87a') or content.startswith(b'GIF89a'):
+        return '.gif'
+    elif content.startswith(b'PK\x03\x04') or content.startswith(b'PK\x05\x06') or content.startswith(b'PK\x07\x08'):
+        # ZIP-based formats (could be .zip, .docx, .xlsx, .pptx, etc.)
+        # For simplicity, assume .zip unless we detect Office formats
+        if b'word/' in content[:1024] or b'xl/' in content[:1024] or b'ppt/' in content[:1024]:
+            # Likely Office document but hard to determine exact type
+            return '.zip'  # Conservative choice
+        return '.zip'
+    elif content.startswith(b'\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1'):
+        # Microsoft Office old format
+        return '.doc'  # Could also be .xls, .ppt but .doc is most common
+    elif content.startswith(b'<?xml') or content.startswith(b'\xef\xbb\xbf<?xml'):
+        return '.xml'
+    elif content.startswith(b'<!DOCTYPE html') or content.startswith(b'<html'):
+        return '.html'
+    elif content.startswith(b'{\n') or content.startswith(b'{"') or content.startswith(b'[\n') or content.startswith(b'[{'):
+        return '.json'
+    else:
+        # Try to detect if it's text content
+        try:
+            # Try to decode as UTF-8 text
+            text_content = content.decode('utf-8')
+            # Check if it contains mostly printable characters
+            printable_chars = sum(1 for c in text_content if c.isprintable() or c.isspace())
+            if len(text_content) > 0 and printable_chars / len(text_content) > 0.8:
+                return '.txt'
+        except (UnicodeDecodeError, UnicodeError):
+            pass
+    
+    # Unknown binary format
+    return None
+
+
+def analyze_content_type(filename: str, mime_type: str, content: bytes) -> dict:
+    """Analyze file type and provide relevant suggestions.
+    
+    Args:
+        filename: Name of the file
+        mime_type: MIME type of the file
+        content: File content as bytes
+        
+    Returns:
+        Dictionary with category, suggestions, and file_size
+    """
+    file_size = len(content)
+    
+    # Get case-insensitive filename for macOS/Windows compatibility
+    filename_lower = filename.lower()
+    
+    # Determine file category based on MIME type and extension
+    if mime_type.startswith('image/'):
+        category = 'images'
+        suggestions = [
+            "Can be used for thumbnails and previews",
+            "Consider image optimization for web use"
+        ]
+    elif mime_type.startswith('video/') or mime_type.startswith('audio/'):
+        category = 'media'
+        suggestions = [
+            "Large files may need streaming support",
+            "Consider format compatibility for playback"
+        ]
+    elif mime_type in ['application/pdf', 'application/msword', 
+                      'application/vnd.openxmlformats-officedocument.wordprocessingml.document']:
+        category = 'documents'
+        suggestions = [
+            "PDF files support full-text search",
+            ">> Consider using text extraction for searchable content",
+            "Can be previewed in most browsers"
+        ]
+    elif mime_type in ['application/vnd.ms-excel',
+                      'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet']:
+        category = 'documents'
+        suggestions = [
+            ">> Excel spreadsheet - can be opened with Excel or LibreOffice Calc",
+            ">> May contain tracked changes or comments"
+        ]
+    elif mime_type in ['application/vnd.ms-powerpoint',
+                      'application/vnd.openxmlformats-officedocument.presentationml.presentation']:
+        category = 'documents'
+        suggestions = [
+            "Presentation files support slide previews",
+            "Consider extracting slide content for search"
+        ]
+    elif mime_type.startswith('text/') or 'javascript' in mime_type or 'json' in mime_type:
+        if filename_lower.endswith(('.py', '.js', '.java', '.cpp', '.c', '.cs', '.php', '.rb')):
+            category = 'code'
+            suggestions = [
+                "Source code files support syntax highlighting",
+                ">> Check contents before extraction for security",
+                "Can be indexed for code search"
+            ]
+        else:
+            category = 'documents'
+            suggestions = [
+                ">> Review for security before execution",
+                ">> May require specific runtime environment"
+            ]
+    elif mime_type in ['application/zip', 'application/x-rar-compressed', 'application/gzip']:
+        category = 'archives'
+        suggestions = [
+            "Archive contents can be extracted and indexed",
+            ">> Check contents before extraction for security",
+            "May contain multiple file types"
+        ]
+    else:
+        category = 'other'
+        suggestions = [
+            "Unknown file type - review content manually",
+            "Consider file format documentation"
+        ]
+    
+    # Add size-based suggestions
+    if file_size > 100 * 1024 * 1024:  # > 100MB
+        suggestions.append("WARNING: Large file - consider network and storage impact")
+    
+    # Add security suggestions for executable files (case-insensitive for cross-platform)
+    executable_extensions = (
+        '.exe', '.bat', '.sh', '.com', '.scr',  # Windows & shell scripts
+        '.app', '.dmg', '.pkg',                 # macOS
+        '.deb', '.rpm', '.run', '.bin', '.appimage'  # Linux
+    )
+    if filename_lower.endswith(executable_extensions):
+        suggestions = [
+            "WARNING: Executable file - scan for security before running",
+            "Consider sandboxed execution environment"
+        ]
+        category = 'executable'
+    
+    return {
+        'category': category,
+        'suggestions': suggestions,
+        'file_size': file_size
+    } 

alfresco_mcp_server/utils/json_utils.py

@@ -0,0 +1,135 @@
+"""
+JSON utilities for Alfresco MCP Server.
+Handles proper Unicode emoji encoding for MCP protocol transport.
+"""
+import json
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+
+def make_json_safe(text: str) -> str:
+    """
+    Make text JSON-safe for MCP protocol transport.
+    Properly encodes Unicode emojis to prevent character map errors.
+    
+    Args:
+        text: Input text that may contain Unicode emojis
+        
+    Returns:
+        JSON-safe text with properly encoded Unicode characters
+    """
+    if not text:
+        return text
+        
+    try:
+        # Ensure proper Unicode normalization
+        import unicodedata
+        normalized = unicodedata.normalize('NFC', text)
+        
+        # Test if it can be safely JSON serialized
+        json.dumps(normalized)
+        return normalized
+        
+    except (UnicodeError, TypeError) as e:
+        logger.warning(f"Unicode encoding issue, falling back to ASCII: {e}")
+        # Fall back to ASCII-safe version with emoji descriptions
+        return text.encode('ascii', errors='ignore').decode('ascii')
+
+
+def safe_format_output(text: str) -> str:
+    """
+    Format output text to be safe for MCP JSON transport.
+    Replaces emojis with text equivalents to prevent character map errors.
+    
+    Args:
+        text: Text to format
+        
+    Returns:
+        Safely formatted text with emojis replaced
+    """
+    if not text:
+        return text
+        
+    try:
+        # Define emoji replacements for common ones used in the tools
+        emoji_replacements = {
+            '🔗': '[LINK]',
+            '🔓': '[UNLOCKED]', 
+            '📄': '[DOCUMENT]',
+            '🆔': '[ID]',
+            '📏': '[SIZE]',
+            '💾': '[SAVED]',
+            '🔒': '[LOCKED]',
+            '🕒': '[TIME]',
+            '📥': '[DOWNLOAD]',
+            'ℹ️': '[INFO]',
+            '⚠️': '[WARNING]',
+            '👤': '[USER]',
+            '✅': '[SUCCESS]',
+            '❌': '[ERROR]',
+            '🏷️': '[TAG]',
+            '🧩': '[MODULE]',
+            '📁': '[FOLDER]',
+            '📍': '[LOCATION]',
+            '📅': '[DATE]',
+            '📝': '[NOTE]',
+            '🔢': '[VERSION]',
+            '📊': '[SIZE]',
+            '🗑️': '[DELETE]',
+            '🔍': '[SEARCH]',
+            '📤': '[UPLOAD]',
+            '🧹': '[CLEANUP]',
+            '🏢': '[REPOSITORY]',
+            '🔧': '[TOOL]',
+            '📦': '[PACKAGE]'
+        }
+        
+        # Replace emojis with text equivalents
+        safe_text = text
+        for emoji, replacement in emoji_replacements.items():
+            safe_text = safe_text.replace(emoji, replacement)
+        
+        # Test if the result is JSON-safe
+        test_json = json.dumps(safe_text, ensure_ascii=True)
+        json.loads(test_json)
+        
+        return safe_text
+        
+    except Exception as e:
+        logger.warning(f"JSON formatting issue: {e}")
+        try:
+            # Ultimate fallback: remove all non-ASCII characters
+            ascii_text = text.encode('ascii', errors='ignore').decode('ascii')
+            return ascii_text
+        except Exception as fallback_error:
+            logger.error(f"ASCII fallback failed: {fallback_error}")
+            return "Error: Text encoding failed"
+
+
+def escape_unicode_for_json(text: str) -> str:
+    """
+    Alternative approach: explicitly escape Unicode characters for JSON.
+    Use this if the regular approach doesn't work.
+    
+    Args:
+        text: Input text with Unicode characters
+        
+    Returns:
+        Text with Unicode characters escaped for JSON
+    """
+    if not text:
+        return text
+        
+    try:
+        # Use json.dumps to properly escape Unicode, then remove the quotes
+        escaped = json.dumps(text, ensure_ascii=False)
+        # Remove the surrounding quotes added by json.dumps
+        if escaped.startswith('"') and escaped.endswith('"'):
+            escaped = escaped[1:-1]
+        return escaped
+        
+    except Exception as e:
+        logger.warning(f"Unicode escaping failed: {e}")
+        return text