stevereiner/python-alfresco-mcp-server

Python Alfresco MCP Server v1.0 🚀

Model Context Protocol server for Alfresco Content Services

A comprehensive MCP server that provides AI-native access to Alfresco content management through FastMCP 2.0, featuring complete documentation, examples, and deployment patterns.

🌟 What's New in v1.0 (First Release)

Complete FastMCP 2.0 Implementation

• Modern Architecture: Built entirely on FastMCP 2.0 framework
• Multiple Transport Options: STDIO, HTTP, and SSE with real-time streaming
• 73% Less Code: Revolutionary FastMCP 2.0 architecture with ~300 vs 1,098 lines
• Clean Codebase: Legacy MCP SDK code removed (main.py, server.py, tools.py, fastapi_transport.py)
• Live Testing: 84 comprehensive tests with 58 passing (including 18 live Alfresco integration tests)

Complete Documentation & Examples

• 📚 Complete Documentation: 6 comprehensive guides covering setup to deployment
• 💡 Real-World Examples: 6 practical examples from quick start to advanced patterns
• 🔧 Configuration Management: Environment variables, .env files, and command-line configuration
• 🏗️ Deployment Ready: Docker, systemd, and authentication patterns

Comprehensive Learning Resources

• 🚀 : 5-minute setup and first operations
• 📖 : Beginner to advanced implementation patterns
• 🔍 : Complete tool documentation with examples
• ⚙️ : Development to deployment
• 🧪 : Quality assurance and test development
• 🛠️ : Problem diagnosis and resolution

🚀 Features

Comprehensive Content Management Tools

• Search API: Advanced text search with AFTS query language
• Document Lifecycle: Upload, download, checkin, checkout, cancel checkout
• Version Management: Create major/minor versions with comments
• Folder Operations: Create and delete folders with metadata
• Property Management: Get and set document/folder properties and names
• Node Operations: Delete documents and folders (trash or permanent)

Modern Architecture

• FastMCP 2.0 Framework: Modern, high-performance MCP server implementation
• Multiple Transports:
  • STDIO (direct MCP protocol) - Default and fastest
  • HTTP (RESTful API) - Web services and testing
  • SSE (Server-Sent Events) - Real-time streaming updates
• Enterprise Security: OAuth 2.1, SSO, audit logging, and encrypted communications (optional)
• Type Safety: Full Pydantic v2 models and async support
• Advanced Testing: In-memory client testing with 10x faster execution
• Progress Reporting: Real-time operation progress and context logging
• Configuration: Environment variables, .env files, and CLI support
• Error Handling: Graceful error handling with detailed messages and recovery patterns

AI Integration

• MCP Tools: 9 comprehensive tools for content operations
• MCP Resources: Repository metadata and status information
• MCP Prompts: AI-friendly templates for common workflows

Alfresco Integration (Community & Enterprise)

• Authentication Compatibility: Works with basic auth, LDAP, SAML, and Kerberos authentication
• Permission Inheritance: Respects Alfresco's permission model and site-based security
• Content Classification: Integrates with Alfresco Governance Services (Enterprise) for compliance workflows
• Multi-Tenant Support: Compatible with Alfresco's multi-tenant architecture (Enterprise)
• Enterprise High Availability: Supports clustered Alfresco deployments with load balancing
• Version Control: Full integration with Alfresco's version management and workflow engine

FastMCP 2.0 Advantages

• 73% Less Code: ~300 lines vs 1,098 lines compared to legacy MCP SDK
• Revolutionary Testing: In-memory Client testing instead of FastAPI mocks
• Enhanced Developer Experience: Context logging, progress reporting, automatic schema generation
• Future-Proof Architecture: Ready for MCP protocol evolution and AI platform integrations
• Comprehensive Examples: Real-world patterns and best practices

📋 Requirements

• Python 3.8+
• Alfresco Content Services (Community or Enterprise)
• python-alfresco-api >= 1.0.0

Enterprise & Advanced Features

• SSO Integration: OAuth 2.1 providers (Azure AD, Okta, Auth0) for seamless authentication
• Enhanced Security: TLS 1.2+ for encrypted communications
• Compliance Support: Audit logging for regulatory requirements
• Enterprise Scalability: Load balancer support for high-availability deployments

🛠️ Installation

1. Install Dependencies

# Install MCP server
pip install -e .

# Or with development dependencies
pip install -e .[dev]

# Or with testing dependencies
pip install -e .[test]

# Or install everything
pip install -e .[all]

2. Configure Alfresco Connection

Option 1: Environment Variables

# Linux/Mac
export ALFRESCO_URL="http://localhost:8080"
export ALFRESCO_USERNAME="admin"
export ALFRESCO_PASSWORD="admin"
export ALFRESCO_VERIFY_SSL="false"

# Windows PowerShell
$env:ALFRESCO_URL="http://localhost:8080"
$env:ALFRESCO_USERNAME="admin"
$env:ALFRESCO_PASSWORD="admin"
$env:ALFRESCO_VERIFY_SSL="false"

# Windows Command Prompt
set ALFRESCO_URL=http://localhost:8080
set ALFRESCO_USERNAME=admin
set ALFRESCO_PASSWORD=admin
set ALFRESCO_VERIFY_SSL=false

Option 2: .env file (recommended - cross-platform):

# Copy sample-dot-env.txt to .env and customize
cp sample-dot-env.txt .env

# Edit .env file with your settings
ALFRESCO_URL=http://localhost:8080
ALFRESCO_USERNAME=admin
ALFRESCO_PASSWORD=admin
ALFRESCO_VERIFY_SSL=false

Note: The .env file is not checked into git for security. Use sample-dot-env.txt as a template.

Why This Approach?

• ✅ Cross-platform: Works on Windows (PowerShell/CMD), Linux, Mac
• ✅ Simple: Single configuration method (environment variables only)
• ✅ Secure: .env files are git-ignored, sample file is checked in
• ✅ No Priority Confusion: Environment variables are the only source
• ✅ python-alfresco-api Compatible: May use its own config/env (see their docs)

📖 See for complete setup options

🚀 Usage

# Run MCP server with STDIO transport (default)
python-alfresco-mcp-server

# Or directly with module (also STDIO by default)
python -m alfresco_mcp_server.fastmcp_server

# HTTP transport for web services
python -m alfresco_mcp_server.fastmcp_server --transport http --host 127.0.0.1 --port 8001

# SSE transport for real-time streaming  
python -m alfresco_mcp_server.fastmcp_server --transport sse --host 127.0.0.1 --port 8003

MCP Client Example

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "alfresco_mcp_server.fastmcp_server"]
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # Search for documents
            result = await session.call_tool(
                "search_content", 
                arguments={"query": "important document", "max_results": 10}
            )
            print(result)

💡 See for comprehensive usage patterns

🛠️ Available Tools

📖 See for detailed tool documentation

🔧 Configuration Options

⚙️ See for advanced and enterprise deployment options

🏗️ Architecture

┌─────────────────────────────────────┐
│           MCP Client                │
│    (Claude, Custom App, etc.)       │
└─────────────┬───────────────────────┘
              │ stdio/HTTP/SSE
┌─────────────▼───────────────────────┐
│       FastMCP 2.0 MCP Server       │
│  ┌─────────────┬─────────────────┐  │
│  │ MCP Tools   │ MCP Resources   │  │
│  │ MCP Prompts │ HTTP/SSE API    │  │
│  └─────────────┴─────────────────┘  │
└─────────────┬───────────────────────┘
              │ python-alfresco-api
┌─────────────▼───────────────────────┐
│      Alfresco Content Services      │
│   (Community/Enterprise Edition)    │
└─────────────────────────────────────┘

🧪 Testing & Quality

Test Suite Overview

• 84 Total Tests: Comprehensive coverage of all functionality
• 58 Passing Tests: Including 18 live integration tests with Alfresco server
• 40 Unit Tests: Core functionality validated with mocking (FastMCP 2.0, tools, coverage)
• 18 Integration Tests: Live server testing (search, upload, download, workflows)
• Performance Validated: Search <1s, concurrent operations, resource access

Coverage Report (Post-Cleanup)

• FastMCP 2.0 Core: 84% coverage (392/414 lines) - Well tested
• Configuration Module: 93% coverage (24/25 lines) - Fully tested
• Package Initialization: 100% coverage (5/5 lines) - Complete
• Overall Project: 85% coverage focused on clean FastMCP 2.0 implementation

Run Tests

# Run full test suite
pytest

# Run with coverage report
pytest --cov=alfresco_mcp_server --cov-report=term-missing

# Run specific test categories
pytest -m "unit"           # Unit tests only
pytest -m "fastmcp"        # FastMCP 2.0 tests
pytest -m "integration"    # Integration tests (requires Alfresco)

🧪 See for detailed testing strategies

🧪 Development

Setup Development Environment

git clone <repository>
cd python-alfresco-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install development dependencies
pip install -e .[dev]

# Install python-alfresco-api (local development)
pip install -e ../python-alfresco-api

Code Quality

# Format code
black alfresco_mcp_server/

# Type checking
mypy alfresco_mcp_server/

# Linting
ruff check alfresco_mcp_server/

📚 Documentation & Examples

📖 Documentation

Comprehensive guides covering every aspect of deployment and usage:

• - Complete navigation and overview
• - 5-minute setup and first operations
• - Complete tool and resource documentation
• - Development to deployment
• - Quality assurance and test development
• - Problem diagnosis and resolution

💡 Examples

Real-world implementation patterns from beginner to enterprise:

• - Complete navigation and learning paths
• - 5-minute introduction and basic operations
• - Complete workflow demonstration
• - STDIO, HTTP, and SSE protocols
• - High-performance bulk processing
• - Resilience patterns
• - Comprehensive overview and statistics

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the Apache 2.0 License - see the file for details.

🔗 Related Projects and References

• Hyland Alfresco - Content management platform (Enterprise and Community editions)
• python-alfresco-api - The underlying Alfresco API library
• FastMCP 2.0 - Modern framework for building MCP servers
• Model Context Protocol - Official MCP specification and documentation

🙋‍♂️ Support

• 📚 Documentation: Complete guides in
• 💡 Examples: Implementation patterns in
• 🧪 Testing: Quality assurance in
• 🛠️ Troubleshooting: Problem solving in
• 🐛 Issues: GitHub Issues

🚀 MCP server built with python-alfresco-api and FastMCP 2.0