python-alfresco-mcp-server 1.1.0

FastMCP 2.0 server for Alfresco Content Services integration

Python Alfresco MCP Server v1.1 🚀

Model Context Protocol Server for Alfresco Content Services

A full featured MCP server for Alfresco in search and content management areas. It provides the following tools: full text search (content and properties), advanced search, metadata search, CMIS SQL like search, upload, download, checkin, checkout, cancel checkout, create folder, folder browse, delete node, and get/set properties. Also has a tool for getting repository status/config (also a resource). Has one prompt example. Built with FastMCP 2.0. Features complete documentation, examples, and config for various MCP clients (Claude Desktop, MCP Inspector, references to configuring others).

🌟 What's New in v1.1

Modular Architecture & Enhanced Testing

• FastMCP: v1.0 had FastMCP 2.0 implementation that had all tools implementations in the fastmcp_server.py file
• Code Modularization in v1.1: Split monolithic single file into organized modular structure with separate files
• Directory Organization: Organized into tools/search/, tools/core/, resources/, prompts/, utils/ directories
• Enhanced Testing: Complete test suite transformation - 143 tests with 100% pass rate
• Client Configuration Files: Added dedicated Claude Desktop and MCP Inspector configuration files
• Live Integration Testing: 21 Alfresco server validation tests for real-world functionality
• Python-Alfresco-API: python-alfresco-mcp-server v1.1 requires the v1.1.1 python-alfresco-api package

📚 Complete Documentation

Documentation & Examples

• 📚 Complete Documentation: 9 guides covering setup to deployment
• 💡 Examples: 6 practical examples from quick start to implementation patterns
• 🔧 Configuration Management: Environment variables, .env files, and command-line configuration
• **🏗️ Setup instruction for use with MCP client

Learning Resources

• 🚀 Quick Start Guide: 5-minute setup and first operations
• 🤖 Claude Desktop Setup: Complete Claude Desktop configuration for users and developers
• 🔧 Client Configurations: Setup guide for Cursor, Claude Code, and other MCP clients
• 📖 Examples Library: Implementation patterns and examples

📖 Guides covering setup, deployment, and usage:

• 📚 Documentation Hub - Complete navigation and overview
• 🚀 Quick Start Guide - 5-minute setup and first operations
• 🤖 Claude Desktop Setup - Complete Claude Desktop configuration for users and developers
• 🔧 Client Configurations - Setup guide for Cursor, Claude Code, and other MCP clients
• 🔍 MCP Inspector Setup - Development and testing with MCP Inspector
• 🔍 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

🚀 Features

Content Management Tools

• Search APIs:
  • Full Text Search: Basic content search with wildcard support
  • Advanced Search: AFTS query language with date filters, sorting, and field targeting
  • Metadata Search: Property-based queries with operators (equals, contains, date ranges)
  • CMIS Search: SQL like queries for complex content discovery
• Document Lifecycle: Upload, download, checkin, checkout, cancel checkout
• Version Management: Create major/minor versions with comments
• Folder Operations: Create folders, delete folder nodes
• Property Management: Get and set document/folder properties and names
• Node Operations: Delete nodes (documents and folders) (trash or permanent)
• Repository Info: (Tool and Resource) Returns repository status, version and whether Community or Enterprise, and module configuration

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
• In-Memory Testing: Client testing with 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: 15 tools for content operations
• MCP Resources: Repository metadata and status information
• MCP Prompts: AI-friendly templates for common operations

Alfresco Integration

Works with Alfresco Community (tested) and Enterprise editions

FastMCP 2.0 Advantages

• Boilerplate Reduction: FastMCP reduces the amount of boilerplate code needed for implementing a MCP server
• Modular Architecture: Organized 15 tools across logical modules for maintainability
• In-Memory Testing: Client testing instead of FastAPI mocks
• Enhanced Developer Experience: Context logging, progress reporting, automatic schema generation
• Future-Proof Architecture: Ready for MCP 2.0 protocol evolution and AI platform integrations

📋 Requirements

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

🛠️ Installation

Option A: Install from PyPI (Recommended for Users)

The fastest way to get started - install directly from PyPI:

# Option 1: pipx (Recommended) - installs in isolated environment + makes globally available
pipx install python-alfresco-mcp-server

# Option 2: pip - traditional package manager  
pip install python-alfresco-mcp-server

# Option 3: UV (fastest) - Rust-based package manager
uv pip install python-alfresco-mcp-server

# Run immediately 
python-alfresco-mcp-server --help

Why pipx? pipx automatically creates isolated environments for each tool while making commands globally available - eliminates dependency conflicts while providing system-wide access.

Note: You still need to configure your MCP client (Claude Desktop, MCP Inspector, etc.) with the appropriate configuration. See the MCP Client Setup section below for client configuration details.

Option B: Install from Source (Recommended for Development)

For development or access to latest features:

1. Install UV (Recommended)

UV is a modern Python package manager written in Rust that handles everything automatically. Much faster than pip due to its compiled nature and optimized dependency resolution. Choose your installation method:

# Method 1: Official installer (recommended)
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux  
curl -LsSf https://astral.sh/uv/install.sh | sh

# Method 2: pip (if you prefer)
pip install uv

# Method 3: Package managers
# macOS with Homebrew
brew install uv

# Windows with Chocolatey  
choco install uv

# Verify installation
uv --version

2. Get the Code

# Clone the repository
git clone https://github.com/stevereiner/python-alfresco-mcp-server.git
cd python-alfresco-mcp-server

3. Install Dependencies (Choose Method)

Option A: UV (Recommended - Automatic everything + much faster):

# UV handles venv creation and dependency installation automatically
# Rust-based performance makes this much faster than pip
uv run python-alfresco-mcp-server --help

# Or install dependencies explicitly:
uv sync                    # Basic dependencies
uv sync --extra dev        # With development tools  
uv sync --extra test       # With testing tools
uv sync --extra all        # Everything

Option B: Traditional pip (Manual venv management):

# Create and activate virtual environment  
python -m venv venv          # Traditional Python creates 'venv'
source venv/bin/activate     # Linux/macOS
# venv\Scripts\activate      # Windows

# Note: UV creates '.venv' by default (not 'venv')

# 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]

4. 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.

📖 See Configuration Guide for complete setup options

Alfresco Installation

If you don't have an Alfresco server installed you can get a docker for the Community version from Github

git clone https://github.com/Alfresco/acs-deployment.git

Start Alfresco with Docker Compose

cd acs-deployment/docker-compose

Note: you will likely need to comment out activemq ports other than 8161 in community-compose.yaml

   ports:
   - "8161:8161" # Web Console
   #- "5672:5672" # AMQP
   #- "61616:61616" # OpenWire
   #- "61613:61613" # STOMP

 docker-compose -f community-compose.yaml up

🚀 Usage

MCP Server Startup

With UV (Recommended - Automatic venv and dependency management):

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

# HTTP transport for web services
uv run python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8001

# SSE transport for real-time streaming  
uv run python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8003

Traditional Python (after manual venv setup):

# 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 Setup

🤖 Claude Desktop (Recommended)

Claude Desktop is the primary tested and recommended MCP client with native support for the Python Alfresco MCP Server.

📖 Complete Setup Guide: Claude Desktop Setup Guide

Quick Start:

For Users (PyPI Installation):

• Install with pipx install python-alfresco-mcp-server
• Use configuration files: claude-desktop-config-user-windows.json or claude-desktop-config-user-macos.json

For Developers (Source Installation):

• Clone repository and use UV
• Use configuration files: claude-desktop-config-developer-windows.json or claude-desktop-config-developer-macos.json

Using the Tools:

• Chat naturally about what you want to do with documents
• Use "Search and tools" button in the chat box for tool access
• 4 individual search tools:
  • search_content (full text search)
  • advanced_search (AFTS query language)
  • search_by_metadata (property-based queries)
  • cmis_search (CMIS SQL queries)
• Click "+" → "Add from alfresco" for quick access to resources

Search and Analyze Prompt:

• Provides a form with query field for full-text search
• Analysis types: summary, detailed, trends, or compliance
• Generates template text to copy/paste into chat for editing

Repository Info Resource (and Tool):

• Provides status information in text format for viewing or copying

Testing & Examples:

• See prompts-for-claude.md for 14 manual test scenarios and examples
• Automated versions of all scenarios available in integration test suite

🔧 Other MCP Clients

For Cursor, Claude Code, and other MCP clients:

📖 Complete Setup Guide: Client Configuration Guide

Quick Reference:

• Cursor: VS Code fork with AI and MCP support
• Claude Code: Anthropic's VS Code extension
• Other Clients: Generic MCP client configuration patterns

🔍 MCP Inspector (Development/Testing)

📖 Setup Guide: Complete MCP Inspector setup and connection instructions in MCP Inspector Setup Guide

Working Method (Recommended):

1. Start MCP Server with HTTP transport:

# With UV (recommended)
uv run python-alfresco-mcp-server --transport http --port 8003

# Or traditional method
python -m alfresco_mcp_server.fastmcp_server --transport http --port 8003

2. Start MCP Inspector with config:

npx @modelcontextprotocol/inspector --config mcp-inspector-http-config.json --server python-alfresco-mcp-server

3. Open browser with pre-filled token:
   • Use the URL provided in the output (includes authentication token)
   • Example: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>

This approach avoids proxy connection errors and provides direct authentication.

💡 See Examples Library for usage patterns

🛠️ Available Tools (15 Total)

🔍 Search Tools (4)

Tool	Description	Parameters
search_content	Search documents and folders	query (str), max_results (int), node_type (str)
advanced_search	Advanced search with filters	query (str), content_type (str), created_after (str), etc.
search_by_metadata	Search by metadata properties	property_name (str), property_value (str), comparison (str)
cmis_search	CMIS SQL queries	cmis_query (str), preset (str), max_results (int)

🛠️ Core Tools (11)

Tool	Description	Parameters
browse_repository	Browse repository folders	node_id (str)
repository_info	Get repository information	None
upload_document	Upload new document	filename (str), content_base64 (str), parent_id (str), description (str)
download_document	Download document content	node_id (str), save_to_disk (bool)
create_folder	Create new folder	folder_name (str), parent_id (str), description (str)
get_node_properties	Get node metadata	node_id (str)
update_node_properties	Update node metadata	node_id (str), name (str), title (str), description (str), author (str)
delete_node	Delete document/folder	node_id (str), permanent (bool)
checkout_document	Check out for editing	node_id (str), download_for_editing (bool)
checkin_document	Check in after editing	node_id (str), comment (str), major_version (bool), file_path (str)
cancel_checkout	Cancel checkout/unlock	node_id (str)

📖 See API Reference for detailed tool documentation

📊 Available Resources

Repository Information

Resource	Description	Access Method
repository_info	Get comprehensive repository information including version, edition, license details, installed modules, and system status	Available as both MCP resource and tool

The repository_info resource provides:

• Repository Details: ID, edition (Community/Enterprise), version information
• License Information: Issued/expires dates, remaining days, license holder, entitlements
• System Status: Read-only mode, audit enabled, quick share, thumbnail generation
• Installed Modules: Up to 10 modules with ID, title, version, and installation state

📖 See API Reference for detailed resource documentation

🎯 Available Prompts

Search and Analyze Prompt

Prompt	Description	Parameters
search_and_analyze	Interactive form for guided content search and analysis	query (search terms), analysis_type (summary/detailed/trends/compliance)

The Search and Analyze Prompt provides:

• Interactive Form: User-friendly interface with query input field
• Analysis Options: Choose from summary, detailed analysis, trends, or compliance reporting
• Template Generation: Creates copyable template text for chat conversations
• Query Assistance: Helps users structure effective search queries
• Multiple Search Types: Integrates with all 4 search tools (content, advanced, metadata, CMIS)

📖 See API Reference for detailed prompt 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 deployment options

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   MCP Clients                       │
│  Claude Desktop │ MCP Inspector │ Cursor │ Claude   │
│     Code │ n8n │ LangFlow │ Custom MCP Client App   │
└─────────────────┬───────────────────────────────────┘
                  │ stdio/HTTP/SSE
┌─────────────────▼───────────────────────────────────┐
│             FastMCP 2.0 MCP Server                  │
│  ┌─────────────┬─────────────┬─────────────────┐    │
│  │ MCP Tools   │ MCP         │ HTTP/SSE API    │    │
│  │ (15 total)  │ Resources   │                 │    │
│  │             │ MCP Prompts │                 │    │
│  └─────────────┴─────────────┴─────────────────┘    │
└─────────────────┬───────────────────────────────────┘
                  │ python-alfresco-api
┌─────────────────▼───────────────────────────────────┐
│            Alfresco Content Services                │
│         (Community/Enterprise Edition)              │
└─────────────────────────────────────────────────────┘

🧪 Testing & Quality

Test Suite Overview

• 143 Total Tests: 100% passed - Coverage of all functionality
• 122 Unit Tests: 100% passed - Core functionality validated with mocking (FastMCP 2.0, tools, coverage)
• 21 Integration Tests: 100% passed - Live server testing (search, upload, download, document lifecycle)
• Integration Tests: Automated end-to-end testing covering all 14 manual scenarios from prompts-for-claude.md
• Performance Validated: Search <1s, concurrent operations, resource access

Coverage Report (Post-Cleanup)

• Overall Coverage: 51% (1,829 statements tested)
• FastMCP 2.0 Core: Well tested with comprehensive unit coverage
• Configuration Module: 93% coverage - Fully tested
• Package Initialization: 100% coverage (5/5 lines) - Complete
• Overall Project: 51% coverage of comprehensive codebase

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

🧪 Test Categories and Execution

The project includes 4 levels of testing:

1. 📋 Unit Tests (122 tests) - Fast, mocked, isolated component testing
2. 🔗 Integration Tests (21 tests) - Live Alfresco server testing
3. 📝 Comprehensive Tests - Automated prompts-for-claude.md scenarios
4. 📊 Coverage Tests - Edge cases and error path coverage

New Integration Tests:

• Automated Manual Scenarios: All manual test scenarios from prompts-for-claude.md now available as automated tests

🧪 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

💡 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 process demonstration
• 🚀 Transport Examples - STDIO, HTTP, and SSE protocols
• ⚡ Batch Operations - High-performance bulk processing
• 🛡️ Error Handling - Resilience patterns
• 📊 Examples Summary - Overview and statistics

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-feature)
3. Commit your changes (git commit -m 'Add new feature')
4. Push to the branch (git push origin feature/new-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

• 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
• MCP Server Directory - Comprehensive directory of 5,000+ MCP servers for AI agents

🙋‍♂️ Support

• 📚 Documentation: Complete guides in ./docs/
• 💡 Examples: Implementation patterns in ./examples/
• 🧪 Testing: Quality assurance in ./docs/testing_guide.md
• 🔍 MCP Inspector: Development testing in ./docs/mcp_inspector_setup.md
• 🛠️ Troubleshooting: Problem solving in ./docs/troubleshooting.md
• 🐛 Issues: GitHub Issues

---

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