Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/stevereiner/python-alfresco-mcp-server

Python based MCP Server for Alfresco using python-alfresco-api
https://github.com/stevereiner/python-alfresco-mcp-server

Last synced: 3 months ago
JSON representation

Python based MCP Server for Alfresco using python-alfresco-api

Awesome Lists containing this project

README 

          
# 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](https://github.com/paulinephelan/FastMCP), 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](./docs/quick_start_guide.md)**: 5-minute setup and first operations

- **📖 [Examples Library](./examples/README.md)**: Beginner to advanced implementation patterns

- **🔍 [API Reference](./docs/api_reference.md)**: Complete tool documentation with examples

- **⚙️ [Configuration Guide](./docs/configuration_guide.md)**: Development to deployment

- **🧪 [Testing Guide](./docs/testing_guide.md)**: Quality assurance and test development

- **🛠️ [Troubleshooting](./docs/troubleshooting.md)**: 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



```bash

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

```bash

# 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):

```bash

# 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](./docs/configuration_guide.md) for complete setup options**



## 🚀 Usage



```bash

# 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



```python

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](./examples/README.md) 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](./docs/api_reference.md) 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](./docs/configuration_guide.md) 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



```bash

# 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](./docs/testing_guide.md) for detailed testing strategies**



## 🧪 Development



### Setup Development Environment



```bash

git clone 

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



```bash

# 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](./docs/README.md)** - Complete navigation and overview

- **[🚀 Quick Start Guide](./docs/quick_start_guide.md)** - 5-minute setup and first operations

- **[🔍 API Reference](./docs/api_reference.md)** - Complete tool and resource documentation

- **[⚙️ Configuration Guide](./docs/configuration_guide.md)** - Development to deployment

- **[🧪 Testing Guide](./docs/testing_guide.md)** - Quality assurance and test development

- **[🛠️ Troubleshooting Guide](./docs/troubleshooting.md)** - Problem diagnosis and resolution



### 💡 Examples

Real-world implementation patterns from beginner to enterprise:



- **[💡 Examples Library](./examples/README.md)** - Complete navigation and learning paths

- **[🏃 Quick Start](./examples/quick_start.py)** - 5-minute introduction and basic operations

- **[📋 Document Lifecycle](./examples/document_lifecycle.py)** - Complete workflow demonstration

- **[🚀 Transport Examples](./examples/transport_examples.py)** - STDIO, HTTP, and SSE protocols

- **[⚡ Batch Operations](./examples/batch_operations.py)** - High-performance bulk processing

- **[🛡️ Error Handling](./examples/error_handling.py)** - Resilience patterns

- **[📊 Examples Summary](./examples/examples_summary.md)** - 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 [LICENSE](LICENSE) file for details.



## 🔗 Related Projects and References



- **[Hyland Alfresco](https://www.hyland.com/en/solutions/products/alfresco-platform)** - Content management platform (Enterprise and Community editions)

- **[python-alfresco-api](https://github.com/stevereiner/python-alfresco-api)** - The underlying Alfresco API library

- **[FastMCP 2.0](https://github.com/paulinephelan/FastMCP)** - Modern framework for building MCP servers

- **[Model Context Protocol](https://modelcontextprotocol.io)** - Official MCP specification and documentation



## 🙋‍♂️ Support



- 📚 **Documentation**: Complete guides in [`./docs/`](./docs/README.md)

- 💡 **Examples**: Implementation patterns in [`./examples/`](./examples/README.md)

- 🧪 **Testing**: Quality assurance in [`./docs/testing_guide.md`](./docs/testing_guide.md)

- 🛠️ **Troubleshooting**: Problem solving in [`./docs/troubleshooting.md`](./docs/troubleshooting.md)

- 🐛 **Issues**: [GitHub Issues](https://github.com/stevereiner/python-alfresco-mcp-server/issues)



---



**🚀 MCP server built with [python-alfresco-api](https://github.com/stevereiner/python-alfresco-api) and [FastMCP 2.0](https://github.com/paulinephelan/FastMCP)**