icon for mcp server

Alfresco

HTTP-SSE

Alfresco内容管理的AI原生MCP服务器

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

🚀 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 Configuration Guide 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 Examples Library for comprehensive usage patterns

🛠️ Available Tools

ToolDescriptionParameters
search_contentSearch documents and foldersquery (str), max_results (int)
download_documentDownload document contentnode_id (str)
upload_documentUpload new documentfilename (str), content_base64 (str), parent_id (str), description (str)
checkout_documentCheck out for editingnode_id (str)
checkin_documentCheck in after editingnode_id (str), comment (str), major_version (bool)
create_folderCreate new folderfolder_name (str), parent_id (str), description (str)
delete_nodeDelete document/foldernode_id (str), permanent (bool)
get_node_propertiesGet node metadatanode_id (str)
update_node_propertiesUpdate node metadatanode_id (str), properties (dict), name (str)

📖 See API Reference for detailed tool documentation

🔧 Configuration Options

Environment VariableDefaultDescription
ALFRESCO_URLhttp://localhost:8080Alfresco server URL
ALFRESCO_USERNAMEadminUsername for authentication
ALFRESCO_PASSWORDadminPassword for authentication
ALFRESCO_VERIFY_SSLfalseVerify SSL certificates
ALFRESCO_TIMEOUT30Request timeout (seconds)
FASTAPI_HOSTlocalhostFastAPI host
FASTAPI_PORT8000FastAPI port
LOG_LEVELINFOLogging level
MAX_FILE_SIZE100000000Max upload size (bytes)

⚙️ See Configuration Guide 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 Testing Guide 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:

💡 Examples

Real-world implementation patterns from beginner to enterprise:

🤝 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 LICENSE file for details.

🔗 Related Projects and References

🙋‍♂️ Support

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

MCP Now 重磅来袭，抢先一步体验