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

alfresco_mcp_server/__init__.py

@@ -0,0 +1,27 @@
+"""
+MCP Server for Alfresco
+
+Model Context Protocol server for Alfresco Content Services.
+Provides AI-native access to Alfresco content management and search operations.
+"""
+
+__version__ = "1.1.0"
+__title__ = "MCP Server for Alfresco"
+__description__ = "Model Context Protocol server for Alfresco Content Services"
+
+from .config import AlfrescoConfig, load_config
+
+# Import subpackages to make them available
+from . import tools
+from . import resources  
+from . import prompts
+from . import utils
+
+__all__ = [
+    "AlfrescoConfig", 
+    "load_config",
+    "tools",
+    "resources", 
+    "prompts",
+    "utils",
+] 

alfresco_mcp_server/config.py

@@ -0,0 +1,104 @@
+"""
+Configuration management for MCP Server for Alfresco.
+"""
+
+import os
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class AlfrescoConfig(BaseModel):
+    """Configuration for MCP Server for Alfresco."""
+    
+    # Alfresco server connection
+    alfresco_url: str = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_URL", "http://localhost:8080"),
+        description="Alfresco server URL"
+    )
+    
+    # Authentication
+    username: str = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_USERNAME", "admin"),
+        description="Alfresco username"
+    )
+    
+    password: str = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_PASSWORD", "admin"),
+        description="Alfresco password"
+    )
+    
+    # Connection settings
+    verify_ssl: bool = Field(
+        default_factory=lambda: os.getenv("ALFRESCO_VERIFY_SSL", "false").lower() == "true",
+        description="Verify SSL certificates"
+    )
+    
+    timeout: int = Field(
+        default_factory=lambda: int(os.getenv("ALFRESCO_TIMEOUT", "30")),
+        description="Request timeout in seconds"
+    )
+    
+    # MCP Server settings
+    server_name: str = Field(
+        default="python-alfresco-mcp-server",
+        description="MCP server name"
+    )
+    
+    server_version: str = Field(
+        default="1.0.0",
+        description="MCP server version"
+    )
+    
+    # FastAPI settings (for HTTP transport)
+    fastapi_host: str = Field(
+        default_factory=lambda: os.getenv("FASTAPI_HOST", "localhost"),
+        description="FastAPI host"
+    )
+    
+    fastapi_port: int = Field(
+        default_factory=lambda: int(os.getenv("FASTAPI_PORT", "8000")),
+        description="FastAPI port"
+    )
+    
+    fastapi_prefix: str = Field(
+        default_factory=lambda: os.getenv("FASTAPI_PREFIX", "/mcp"),
+        description="FastAPI URL prefix"
+    )
+    
+    # Logging
+    log_level: str = Field(
+        default_factory=lambda: os.getenv("LOG_LEVEL", "INFO"),
+        description="Logging level"
+    )
+    
+    # Content settings
+    max_file_size: int = Field(
+        default_factory=lambda: int(os.getenv("MAX_FILE_SIZE", "100000000")),  # 100MB
+        description="Maximum file size for uploads in bytes"
+    )
+    
+    allowed_extensions: list[str] = Field(
+        default_factory=lambda: [
+            ".txt", ".pdf", ".doc", ".docx", ".xls", ".xlsx", 
+            ".ppt", ".pptx", ".jpg", ".jpeg", ".png", ".gif", 
+            ".zip", ".xml", ".json", ".csv"
+        ],
+        description="Allowed file extensions for uploads"
+    )
+    
+    class Config:
+        env_prefix = "ALFRESCO_"
+        case_sensitive = False
+        
+    def model_post_init(self, __context) -> None:
+        """Normalize URLs after initialization."""
+        if self.alfresco_url.endswith("/"):
+            self.alfresco_url = self.alfresco_url.rstrip("/")
+
+
+def load_config() -> AlfrescoConfig:
+    """Load configuration from environment variables and defaults."""
+    return AlfrescoConfig()
+
+# Global config instance for import
+config = load_config() 

alfresco_mcp_server/fastmcp_server.py

@@ -0,0 +1,259 @@
+"""
+MCP Server for Alfresco using FastMCP 2.0
+Modular implementation with separated concerns and self-contained tools
+"""
+import logging
+from fastmcp import FastMCP, Context
+
+# Search tools imports
+from .tools.search.search_content import search_content_impl
+from .tools.search.advanced_search import advanced_search_impl
+from .tools.search.search_by_metadata import search_by_metadata_impl
+from .tools.search.cmis_search import cmis_search_impl
+
+# Core tools imports
+from .tools.core.browse_repository import browse_repository_impl
+from .tools.core.upload_document import upload_document_impl
+from .tools.core.download_document import download_document_impl
+from .tools.core.create_folder import create_folder_impl
+from .tools.core.get_node_properties import get_node_properties_impl
+from .tools.core.update_node_properties import update_node_properties_impl
+from .tools.core.delete_node import delete_node_impl
+from .tools.core.checkout_document import checkout_document_impl
+from .tools.core.checkin_document import checkin_document_impl
+from .tools.core.cancel_checkout import cancel_checkout_impl
+
+# Resource imports
+from .resources.repository_resources import (
+    get_repository_info_impl
+)
+
+# Prompt imports
+from .prompts.search_and_analyze import search_and_analyze_impl
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+
+# Reduce verbosity of noisy loggers
+logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpcore").setLevel(logging.WARNING)
+
+logger = logging.getLogger(__name__)
+
+# Initialize MCP server
+mcp = FastMCP("MCP Server for Alfresco Content Services")
+
+# ================== SEARCH TOOLS ==================
+
+@mcp.tool
+async def search_content(
+    query: str, 
+    max_results: int = 25,
+    node_type: str = "",
+    ctx: Context = None
+) -> str:
+    """Search for content in Alfresco using AFTS query language."""
+    return await search_content_impl(query, max_results, node_type, ctx)
+
+@mcp.tool
+async def advanced_search(
+    query: str, 
+    sort_field: str = "cm:modified",
+    sort_ascending: bool = False,
+    max_results: int = 25,
+    ctx: Context = None
+) -> str:
+    """Advanced search with sorting and filtering capabilities."""
+    return await advanced_search_impl(query, sort_field, sort_ascending, max_results, ctx)
+
+@mcp.tool
+async def search_by_metadata(
+    term: str = "",
+    creator: str = "",
+    content_type: str = "",
+    max_results: int = 25,
+    ctx: Context = None
+) -> str:
+    """Search for content in Alfresco by metadata fields."""
+    return await search_by_metadata_impl(term, creator, content_type, max_results, ctx)
+
+@mcp.tool
+async def cmis_search(
+    cmis_query: str = "SELECT * FROM cmis:document WHERE cmis:contentStreamMimeType = 'application/pdf'",
+    max_results: int = 25,
+    ctx: Context = None
+) -> str:
+    """Search using CMIS SQL syntax. Default query searches for PDF documents."""
+    return await cmis_search_impl(cmis_query, max_results, ctx)
+
+# ================== CORE TOOLS ==================
+
+@mcp.tool
+async def browse_repository(
+    parent_id: str = "-my-",
+    max_items: int = 25,
+    ctx: Context = None
+) -> str:
+    """Browse the Alfresco repository structure."""
+    return await browse_repository_impl(parent_id, max_items, ctx)
+
+@mcp.tool
+async def upload_document(
+    file_path: str = "",
+    base64_content: str = "",
+    parent_id: str = "-shared-",
+    description: str = "",
+    ctx: Context = None
+) -> str:
+    """Upload a document to Alfresco."""
+    return await upload_document_impl(file_path, base64_content, parent_id, description, ctx)
+
+@mcp.tool
+async def download_document(
+    node_id: str, 
+    save_to_disk: bool = True,
+    attachment: bool = True,
+    ctx: Context = None
+) -> str:
+    """Download a document from Alfresco repository."""
+    return await download_document_impl(node_id, save_to_disk, attachment, ctx)
+
+@mcp.tool
+async def create_folder(
+    folder_name: str, 
+    parent_id: str = "-shared-", 
+    description: str = "",
+    ctx: Context = None
+) -> str:
+    """Create a new folder in Alfresco."""
+    return await create_folder_impl(folder_name, parent_id, description, ctx)
+
+@mcp.tool
+async def get_node_properties(node_id: str, ctx: Context = None) -> str:
+    """Get metadata and properties of a document or folder."""
+    return await get_node_properties_impl(node_id, ctx)
+
+@mcp.tool
+async def update_node_properties(
+    node_id: str,
+    name: str = "",
+    title: str = "",
+    description: str = "",
+    author: str = "",
+    ctx: Context = None
+) -> str:
+    """Update metadata and properties of a document or folder."""
+    return await update_node_properties_impl(node_id, name, title, description, author, ctx)
+
+@mcp.tool
+async def delete_node(
+    node_id: str, 
+    permanent: bool = False,
+    ctx: Context = None
+) -> str:
+    """Delete a document or folder from Alfresco."""
+    return await delete_node_impl(node_id, permanent, ctx)
+
+# ================== CHECKOUT/CHECKIN TOOLS ==================
+
+@mcp.tool
+async def checkout_document(
+    node_id: str, 
+    download_for_editing: bool = True,
+    ctx: Context = None
+) -> str:
+    """Check out a document for editing using Alfresco REST API."""
+    return await checkout_document_impl(node_id, download_for_editing, ctx)
+
+@mcp.tool
+async def checkin_document(
+    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."""
+    return await checkin_document_impl(node_id, comment, major_version, file_path, new_name, ctx)
+
+@mcp.tool
+async def cancel_checkout(
+    node_id: str,
+    ctx: Context = None
+) -> str:
+    """Cancel checkout of a document, discarding any working copy."""
+    return await cancel_checkout_impl(node_id, ctx)
+
+# ================== RESOURCES ==================
+
+@mcp.resource("alfresco://repository/info", description="📊 Live Alfresco repository information including version, edition, and connection status")
+async def repository_info() -> str:
+    """Get Alfresco repository information using Discovery Client."""
+    return await get_repository_info_impl()
+
+@mcp.tool
+async def get_repository_info_tool(ctx: Context = None) -> str:
+    """Get Alfresco repository information using Discovery Client (as tool instead of resource)."""
+    return await get_repository_info_impl()
+
+
+# ================== PROMPTS ==================
+
+@mcp.prompt(description="🔎 Generate comprehensive search and analysis steps for Alfresco documents with customizable analysis types")
+async def search_and_analyze(query: str, analysis_type: str = "summary") -> str:
+    """Generate comprehensive search and analysis prompts for Alfresco documents."""
+    return await search_and_analyze_impl(query, analysis_type)
+
+# ================== MAIN ENTRY POINT ==================
+
+def main():
+    """Main entry point for the FastMCP 2.0 Alfresco server."""
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="MCP Server for Alfresco 2.0")
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "http", "sse"],
+        default="stdio",
+        help="Transport method (default: stdio)"
+    )
+    parser.add_argument(
+        "--host",
+        default="localhost",
+        help="Host for HTTP/SSE transport (default: localhost)"
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port for HTTP/SSE transport (default: 8000)"
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default="INFO",
+        help="Logging level (default: INFO)"
+    )
+    
+    args = parser.parse_args()
+    
+    # Configure logging
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    
+    logger.info(">> Starting MCP Server for Alfresco")
+    logger.info(">> Hierarchical structure: tools/{core,search}, resources, prompts, utils")
+    
+    # Run server with specified transport
+    if args.transport == "stdio":
+        mcp.run(transport="stdio")
+    elif args.transport == "http":
+        mcp.run(transport="http", host=args.host, port=args.port)
+    elif args.transport == "sse":
+        mcp.run(transport="sse", host=args.host, port=args.port)
+
+if __name__ == "__main__":
+    main() 

alfresco_mcp_server/prompts/__init__.py

@@ -0,0 +1,7 @@
+# Prompts module
+
+from . import search_and_analyze
+
+__all__ = [
+    "search_and_analyze",
+] 

alfresco_mcp_server/prompts/search_and_analyze.py

@@ -0,0 +1,67 @@
+"""
+Search and analyze prompt for Alfresco MCP Server.
+Self-contained prompt for generating comprehensive search and analysis workflows.
+"""
+
+
+async def search_and_analyze_impl(query: str, analysis_type: str = "summary") -> str:
+    """Generate comprehensive search and analysis prompts for Alfresco documents.
+    
+    Args:
+        query: Search query for documents
+        analysis_type: Type of analysis (summary, detailed, trends, compliance)
+    
+    Returns:
+        Formatted prompt for document analysis workflow
+    """
+    base_prompt = f"""**Alfresco Document Analysis Request**
+
+Please search for documents matching "{query}" and provide a {analysis_type} analysis.
+
+**Step 1: Search**
+Use the `search_content` tool to find relevant documents.
+
+**Step 2: Analysis**
+Based on the search results, provide:
+"""
+    
+    if analysis_type == "summary":
+        base_prompt += """
+- Document count and types
+- Key themes and topics
+- Most relevant documents
+- Quick insights
+"""
+    elif analysis_type == "detailed":
+        base_prompt += """
+- Comprehensive document inventory
+- Metadata analysis (dates, authors, sizes)
+- Content categorization
+- Compliance status
+- Recommended actions
+- Related search suggestions
+"""
+    elif analysis_type == "trends":
+        base_prompt += """
+- Temporal patterns (creation/modification dates)
+- Document lifecycle analysis
+- Usage and access patterns
+- Version history insights
+- Storage optimization recommendations
+"""
+    elif analysis_type == "compliance":
+        base_prompt += """
+- Document retention analysis
+- Security classification review
+- Access permissions audit
+- Regulatory compliance status
+- Risk assessment
+- Remediation recommendations
+"""
+    
+    base_prompt += f"""
+**Step 3: Recommendations**
+Provide actionable insights and next steps based on the {analysis_type} analysis.
+"""
+    
+    return base_prompt 

alfresco_mcp_server/resources/__init__.py

@@ -0,0 +1,7 @@
+# Resources module
+
+from . import repository_resources
+
+__all__ = [
+    "repository_resources",
+] 

alfresco_mcp_server/resources/repository_resources.py

@@ -0,0 +1,205 @@
+"""
+Repository resources for Alfresco MCP Server.
+Self-contained resources for repository information, health, stats, and configuration.
+Returns data or indicates when unavailable.
+"""
+import json
+import logging
+import os
+
+from python_alfresco_api.client_factory import ClientFactory
+from ..utils.connection import ensure_connection, get_client_factory
+from ..utils.json_utils import safe_format_output
+    
+logger = logging.getLogger(__name__)
+
+
+async def get_repository_info_impl() -> str:
+    """Get Alfresco repository information using Discovery API.
+    Returns comprehensive repository details or connection status.
+    """
+    try:
+        await ensure_connection()
+        client_factory: ClientFactory = await get_client_factory()
+        
+        logger.info("Getting repository information via Discovery API")
+        
+        # Use the working pattern from test script - high-level API
+        discovery_client = client_factory.create_discovery_client()
+        
+        # Check if discovery client has the discovery attribute (working pattern from test)
+        if not hasattr(discovery_client, 'discovery'):
+            logger.warning("Discovery client does not have discovery attribute")
+            return safe_format_output(f"""⚠️ **Repository Information - Discovery Client Unavailable**
+
+**Status**: Discovery client initialization failed
+
+**Available Information**:
+🔗 **Server**: {os.getenv('ALFRESCO_URL', 'http://localhost:8080')}
+👤 **Connected as**: {os.getenv('ALFRESCO_USERNAME', 'admin')}
+❌ **Discovery API**: Client not available
+
+**Note**: This could indicate:
+- Authentication issues
+- Network connectivity problems
+- Server configuration issues
+
+**Recommendation**: Check connection settings and server status.""")
+        
+        # Get repository information using high-level Discovery API (working pattern from test)
+        repo_info = discovery_client.discovery.get_repository_information()
+        
+        # Handle None response (HTTP 501 - Discovery API disabled)
+        if repo_info is None:
+            logger.warning("Discovery API is disabled on this Alfresco instance (returned None)")
+            return safe_format_output(f"""⚠️ **Repository Information - Discovery API Disabled**
+
+**Status**: Discovery API is disabled on this Alfresco instance (HTTP 501)
+
+**Available Information**:
+🔗 **Server**: {os.getenv('ALFRESCO_URL', 'http://localhost:8080')}
+👤 **Connected as**: {os.getenv('ALFRESCO_USERNAME', 'admin')}
+✅ **Core API**: Available (connection successful)
+❌ **Discovery API**: Disabled by administrator
+
+**Note**: The Discovery API provides detailed repository information including:
+- Version and edition details
+- License information and entitlements  
+- Installed modules and their versions
+- Repository status and capabilities
+
+**Administrator Action Required**: To enable Discovery API, the Alfresco administrator needs to:
+1. Enable the Discovery API in the repository configuration
+2. Restart the Alfresco service
+3. Ensure proper permissions are configured
+
+**Alternative**: Use Core API tools for basic repository operations.""")
+        
+        if repo_info and hasattr(repo_info, 'entry'):
+            entry = repo_info.entry
+            repository = getattr(entry, 'repository', {})
+            
+            # Build comprehensive repository information
+            result = "🏢 **Alfresco Repository Information**\n\n"
+            
+            # Repository ID and Edition
+            repo_id = getattr(repository, 'id', 'Unknown')
+            edition = getattr(repository, 'edition', 'Unknown')
+            logger.info(f"✅ Retrieved repository info: {edition} edition")
+            result += f"🆔 **Repository ID**: {repo_id}\n"
+            result += f"🏷️ **Edition**: {edition}\n\n"
+            
+            # Version Information
+            version_info = getattr(repository, 'version', {})
+            if hasattr(version_info, 'major'):
+                result += "📦 **Version Details**:\n"
+                result += f"   • Major: {getattr(version_info, 'major', 'Unknown')}\n"
+                result += f"   • Minor: {getattr(version_info, 'minor', 'Unknown')}\n"
+                result += f"   • Patch: {getattr(version_info, 'patch', 'Unknown')}\n"
+                result += f"   • Hotfix: {getattr(version_info, 'hotfix', 'Unknown')}\n"
+                result += f"   • Schema: {getattr(version_info, 'schema', 'Unknown')}\n"
+                result += f"   • Label: {getattr(version_info, 'label', 'Unknown')}\n"
+                result += f"   • Display: {getattr(version_info, 'display', 'Unknown')}\n\n"
+            
+            # Repository Status
+            status_info = getattr(repository, 'status', {})
+            if hasattr(status_info, 'is_read_only'):
+                result += "STATUS **Repository Status**:\n"
+                result += f"   • Read Only: {'Yes' if getattr(status_info, 'is_read_only', False) else 'No'}\n"
+                result += f"   • Audit Enabled: {'Yes' if getattr(status_info, 'is_audit_enabled', False) else 'No'}\n"
+                result += f"   • Quick Share Enabled: {'Yes' if getattr(status_info, 'is_quick_share_enabled', False) else 'No'}\n"
+                result += f"   • Thumbnail Generation: {'Yes' if getattr(status_info, 'is_thumbnail_generation_enabled', False) else 'No'}\n\n"
+            
+            # License Information
+            license_info = getattr(repository, 'license', {})
+            if hasattr(license_info, 'issued_at'):
+                result += "📄 **License Information**:\n"
+                result += f"   • Issued At: {getattr(license_info, 'issued_at', 'Unknown')}\n"
+                result += f"   • Expires At: {getattr(license_info, 'expires_at', 'Unknown')}\n"
+                result += f"   • Remaining Days: {getattr(license_info, 'remaining_days', 'Unknown')}\n"
+                result += f"   • Holder: {getattr(license_info, 'holder', 'Unknown')}\n"
+                result += f"   • Mode: {getattr(license_info, 'mode', 'Unknown')}\n"
+                
+                # License Entitlements
+                entitlements = getattr(license_info, 'entitlements', {})
+                if hasattr(entitlements, 'max_users'):
+                    result += f"   • Max Users: {getattr(entitlements, 'max_users', 'Unknown')}\n"
+                    result += f"   • Max Documents: {getattr(entitlements, 'max_docs', 'Unknown')}\n"
+                    result += f"   • Cluster Enabled: {'Yes' if getattr(entitlements, 'is_cluster_enabled', False) else 'No'}\n"
+                    result += f"   • Cryptodoc Enabled: {'Yes' if getattr(entitlements, 'is_cryptodoc_enabled', False) else 'No'}\n"
+                result += "\n"
+            
+            # Modules Information
+            modules = getattr(repository, 'modules', [])
+            if modules and len(modules) > 0:
+                result += f"🧩 **Installed Modules** ({len(modules)} total):\n"
+                for i, module in enumerate(modules[:10], 1):  # Show first 10 modules
+                    module_id = getattr(module, 'id', 'Unknown')
+                    module_title = getattr(module, 'title', 'Unknown')
+                    module_version = getattr(module, 'version', 'Unknown')
+                    module_state = getattr(module, 'install_state', 'Unknown')
+                    result += f"   {i}. **{module_title}** (ID: {module_id})\n"
+                    result += f"      • Version: {module_version}\n"
+                    result += f"      • State: {module_state}\n"
+                    
+                    install_date = getattr(module, 'install_date', None)
+                    if install_date:
+                        result += f"      • Installed: {install_date}\n"
+                    result += "\n"
+                
+                if len(modules) > 10:
+                    result += f"   *... and {len(modules) - 10} more modules*\n\n"
+            
+            # Connection Details
+            result += "🔗 **Connection Details**:\n"
+            result += f"   • Server: {os.getenv('ALFRESCO_URL', 'http://localhost:8080')}\n"
+            result += f"   • Connected as: {os.getenv('ALFRESCO_USERNAME', 'admin')}\n"
+            result += f"   • Data Source: Discovery API (High-Level)\n"
+            
+            return safe_format_output(result)
+        
+    except Exception as discovery_error:
+        error_str = str(discovery_error)
+        
+        # Check if Discovery API is disabled (501 error)
+        if "501" in error_str or "Discovery is disabled" in error_str:
+            logger.warning("Discovery API is disabled on this Alfresco instance")
+            return safe_format_output(f"""WARNING: **Repository Information - Discovery API Disabled**
+
+**Status**: Discovery API is disabled on this Alfresco instance (HTTP 501)
+
+**Available Information**:
+🔗 **Server**: {os.getenv('ALFRESCO_URL', 'http://localhost:8080')}
+👤 **Connected as**: {os.getenv('ALFRESCO_USERNAME', 'admin')}
+✅ **Core API**: Available (connection successful)
+❌ **Discovery API**: Disabled by administrator
+
+**Note**: The Discovery API provides detailed repository information including:
+- Version and edition details
+- License information and entitlements  
+- Installed modules and their versions
+- Repository status and capabilities
+
+**Administrator Action Required**: To enable Discovery API, the Alfresco administrator needs to:
+1. Enable the Discovery API in the repository configuration
+2. Restart the Alfresco service
+3. Ensure proper permissions are configured
+
+**Alternative**: Use Core API tools for basic repository operations.""")
+        else:
+            # Other Discovery API errors
+            logger.error(f"Discovery API failed: {error_str}")
+            return safe_format_output(f"""ERROR: **Repository Information Unavailable**
+
+**Error**: Discovery API failed
+**Details**: {error_str}
+
+🔗 **Server**: {os.getenv('ALFRESCO_URL', 'http://localhost:8080')}
+👤 **Connected as**: {os.getenv('ALFRESCO_USERNAME', 'admin')}
+
+**Possible Causes**:
+- Discovery API endpoint not available
+- Insufficient permissions
+- Network connectivity issues
+- Repository service issues
+**Recommendation**: Check server logs and verify Discovery API availability.""")