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

🚀 Quick Start Guide: 5-minute setup and first operations
📖 Examples Library: Beginner to advanced implementation patterns
🔍 API Reference: Complete tool documentation with examples
⚙️ Configuration Guide: Development to deployment
🧪 Testing Guide: Quality assurance and test development
🛠️ Troubleshooting: 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 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

Tool	Description	Parameters
`search_content`	Search documents and folders	`query` (str), `max_results` (int)
`download_document`	Download document content	`node_id` (str)
`upload_document`	Upload new document	`filename` (str), `content_base64` (str), `parent_id` (str), `description` (str)
`checkout_document`	Check out for editing	`node_id` (str)
`checkin_document`	Check in after editing	`node_id` (str), `comment` (str), `major_version` (bool)
`create_folder`	Create new folder	`folder_name` (str), `parent_id` (str), `description` (str)
`delete_node`	Delete document/folder	`node_id` (str), `permanent` (bool)
`get_node_properties`	Get node metadata	`node_id` (str)
`update_node_properties`	Update node metadata	`node_id` (str), `properties` (dict), `name` (str)

📖 See API Reference for detailed tool documentation

🔧 Configuration Options

Environment Variable	Default	Description
`ALFRESCO_URL`	`http://localhost:8080`	Alfresco server URL
`ALFRESCO_USERNAME`	`admin`	Username for authentication
`ALFRESCO_PASSWORD`	`admin`	Password for authentication
`ALFRESCO_VERIFY_SSL`	`false`	Verify SSL certificates
`ALFRESCO_TIMEOUT`	`30`	Request timeout (seconds)
`FASTAPI_HOST`	`localhost`	FastAPI host
`FASTAPI_PORT`	`8000`	FastAPI port
`LOG_LEVEL`	`INFO`	Logging level
`MAX_FILE_SIZE`	`100000000`	Max 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:

📚 Documentation Hub - Complete navigation and overview
🚀 Quick Start Guide - 5-minute setup and first operations
🔍 API Reference - Complete tool and resource documentation
⚙️ Configuration Guide - Development to deployment
🧪 Testing Guide - Quality assurance and test development
🛠️ Troubleshooting Guide - Problem diagnosis and resolution

💡 Examples

Real-world implementation patterns from beginner to enterprise:

💡 Examples Library - Complete navigation and learning paths
🏃 Quick Start - 5-minute introduction and basic operations
📋 Document Lifecycle - Complete workflow demonstration
🚀 Transport Examples - STDIO, HTTP, and SSE protocols
⚡ Batch Operations - High-performance bulk processing
🛡️ Error Handling - Resilience patterns
📊 Examples Summary - Comprehensive overview and statistics

🤝 Contributing

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

📄 License

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

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 ./docs/
💡 Examples: Implementation patterns in ./examples/
🧪 Testing: Quality assurance in ./docs/testing_guide.md
🛠️ Troubleshooting: Problem solving in ./docs/troubleshooting.md
🐛 Issues: GitHub Issues

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

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Python-based server that provides AI-native access to Alfresco content management operations through the Model Context Protocol, enabling search, document lifecycle management, version control, and other content operations.

Related MCP Servers

Nash MCP Server
nash-app
-
security
A
license
-
quality
A Model Context Protocol server that enables seamless execution of commands, Python code, web content fetching, and reusable task management with secure credentials handling.
Last updated -
2
Python
MIT License
MCP Python Toolbox
gianlucamazza
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.
Last updated -
1
Python
Confluence MCP
cosmix
A
security
A
license
A
quality
A Model Context Protocol server that enables AI assistants to interact with Confluence content, supporting operations like retrieving, searching, creating, and updating pages and spaces.
Last updated -
9
8
TypeScript
MIT License
MCP Toolkit
zxfgds
-
security
F
license
-
quality
A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
Last updated -
16
TypeScript

View all related MCP servers