python-alfresco-mcp-server

Name	python-alfresco-mcp-server JSON
Version	1.1.0 JSON
	download
home_page	None
Summary	FastMCP 2.0 server for Alfresco Content Services integration
upload_time	2025-07-25 04:26:45
maintainer	None
docs_url	None
author	None
requires_python	>=3.10
license	Apache-2.0
keywords	alfresco mcp content-management fastmcp ai
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # 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](https://github.com/paulinephelan/FastMCP). 
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](./docs/quick_start_guide.md)**: 5-minute setup and first operations
- **🤖 [Claude Desktop Setup](./docs/claude_desktop_setup.md)**: Complete Claude Desktop configuration for users and developers
- **🔧 [Client Configurations](./docs/client_configurations.md)**: Setup guide for Cursor, Claude Code, and other MCP clients
- **📖 [Examples Library](./examples/README.md)**: Implementation patterns and examples

### 📖 Guides covering setup, 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
- **[🤖 Claude Desktop Setup](./docs/claude_desktop_setup.md)** - Complete Claude Desktop configuration for users and developers
- **[🔧 Client Configurations](./docs/client_configurations.md)** - Setup guide for Cursor, Claude Code, and other MCP clients
- **[🔍 MCP Inspector Setup](./docs/mcp_inspector_setup.md)** - Development and testing with MCP Inspector
- **[🔍 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

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

```bash
# 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](#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:

```bash
# 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

```bash
# 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):**

```bash
# 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):**

```bash
# 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**
```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.

📖 **See [Configuration Guide](./docs/configuration_guide.md) 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
   ```bash
   git clone https://github.com/Alfresco/acs-deployment.git
```

**Start Alfresco with Docker Compose**
   ```bash
   cd acs-deployment/docker-compose
```
   Note: you will likely need to comment out activemq ports other than 8161
   in community-compose.yaml
   ```bash   
      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):**

```bash
# 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):**

```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 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](./docs/claude_desktop_setup.md)**

**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`](./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](./docs/client_configurations.md)**

**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](./docs/mcp_inspector_setup.md)

**Working Method (Recommended):**

1. **Start MCP Server with HTTP transport:**
```bash
# 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:**
```bash
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](./examples/README.md) 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](./docs/api_reference.md) 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](./docs/api_reference.md) 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](./docs/api_reference.md) 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](./docs/configuration_guide.md) 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

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

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

```bash
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](./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 process 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)** - 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](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
- **[MCP Server Directory](https://playbooks.com/mcp)** - Comprehensive directory of 5,000+ MCP servers for AI agents

## 🙋‍♂️ 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)
- 🔍 **MCP Inspector**: Development testing in [`./docs/mcp_inspector_setup.md`](./docs/mcp_inspector_setup.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)**

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "python-alfresco-mcp-server",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "alfresco, mcp, content-management, fastmcp, ai",
    "author": null,
    "author_email": "Steve Reiner <example@example.com>",
    "download_url": "https://files.pythonhosted.org/packages/4d/23/96e20419205408662b2f8766ee98ae24e9928c6cc646621016ed42c54783/python_alfresco_mcp_server-1.1.0.tar.gz",
    "platform": null,
    "description": "# Python Alfresco MCP Server v1.1 \ud83d\ude80\r\n\r\n**Model Context Protocol Server for Alfresco Content Services**\r\n\r\nA 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,\r\ncheckin, 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.\r\nBuilt with [FastMCP 2.0](https://github.com/paulinephelan/FastMCP). \r\nFeatures complete documentation, examples, and \r\nconfig for various MCP clients (Claude Desktop, MCP Inspector, references to configuring others).\r\n\r\n## \ud83c\udf1f What's New in v1.1\r\n\r\n### **Modular Architecture & Enhanced Testing**\r\n- **FastMCP**: v1.0 had FastMCP 2.0 implementation that had all tools implementations in the fastmcp_server.py file\r\n- **Code Modularization in v1.1**: Split monolithic single file into organized modular structure with separate files\r\n- **Directory Organization**: Organized into `tools/search/`, `tools/core/`, `resources/`, `prompts/`, `utils/` directories\r\n- **Enhanced Testing**: Complete test suite transformation - 143 tests with 100% pass rate\r\n- **Client Configuration Files**: Added dedicated Claude Desktop and MCP Inspector configuration files\r\n- **Live Integration Testing**: 21 Alfresco server validation tests for real-world functionality\r\n- **Python-Alfresco-API**:  python-alfresco-mcp-server v1.1  requires the v1.1.1 python-alfresco-api package\r\n\r\n## \ud83d\udcda Complete Documentation\r\n\r\n### **Documentation & Examples**\r\n- **\ud83d\udcda Complete Documentation**: 9 guides covering setup to deployment\r\n- **\ud83d\udca1 Examples**: 6 practical examples from quick start to implementation patterns  \r\n- **\ud83d\udd27 Configuration Management**: Environment variables, .env files, and command-line configuration\r\n- **\ud83c\udfd7\ufe0f Setup instruction for use with MCP client\r\n\r\n### **Learning Resources**\r\n- **\ud83d\ude80 [Quick Start Guide](./docs/quick_start_guide.md)**: 5-minute setup and first operations\r\n- **\ud83e\udd16 [Claude Desktop Setup](./docs/claude_desktop_setup.md)**: Complete Claude Desktop configuration for users and developers\r\n- **\ud83d\udd27 [Client Configurations](./docs/client_configurations.md)**: Setup guide for Cursor, Claude Code, and other MCP clients\r\n- **\ud83d\udcd6 [Examples Library](./examples/README.md)**: Implementation patterns and examples\r\n\r\n### \ud83d\udcd6 Guides covering setup, deployment, and usage:\r\n\r\n- **[\ud83d\udcda Documentation Hub](./docs/README.md)** - Complete navigation and overview\r\n- **[\ud83d\ude80 Quick Start Guide](./docs/quick_start_guide.md)** - 5-minute setup and first operations\r\n- **[\ud83e\udd16 Claude Desktop Setup](./docs/claude_desktop_setup.md)** - Complete Claude Desktop configuration for users and developers\r\n- **[\ud83d\udd27 Client Configurations](./docs/client_configurations.md)** - Setup guide for Cursor, Claude Code, and other MCP clients\r\n- **[\ud83d\udd0d MCP Inspector Setup](./docs/mcp_inspector_setup.md)** - Development and testing with MCP Inspector\r\n- **[\ud83d\udd0d API Reference](./docs/api_reference.md)** - Complete tool and resource documentation\r\n- **[\u2699\ufe0f Configuration Guide](./docs/configuration_guide.md)** - Development to deployment\r\n- **[\ud83e\uddea Testing Guide](./docs/testing_guide.md)** - Quality assurance and test development\r\n- **[\ud83d\udee0\ufe0f Troubleshooting Guide](./docs/troubleshooting.md)** - Problem diagnosis and resolution\r\n\r\n## \ud83d\ude80 Features\r\n\r\n### Content Management Tools\r\n- **Search APIs**: \r\n  - **Full Text Search**: Basic content search with wildcard support\r\n  - **Advanced Search**: AFTS query language with date filters, sorting, and field targeting\r\n  - **Metadata Search**: Property-based queries with operators (equals, contains, date ranges)\r\n  - **CMIS Search**: SQL like queries for complex content discovery\r\n- **Document Lifecycle**: Upload, download, checkin, checkout, cancel checkout\r\n- **Version Management**: Create major/minor versions with comments\r\n- **Folder Operations**: Create folders, delete folder nodes\r\n- **Property Management**: Get and set document/folder properties and names\r\n- **Node Operations**: Delete nodes (documents and folders) (trash or permanent)\r\n- **Repository Info**: (Tool and Resource) Returns repository status, version and whether Community or Enterprise, and module configuration\r\n\r\n### Modern Architecture\r\n- **FastMCP 2.0 Framework**: Modern, high-performance MCP server implementation\r\n- **Multiple Transports**: \r\n  - **STDIO** (direct MCP protocol) - Default and fastest\r\n  - **HTTP** (RESTful API) - Web services and testing\r\n  - **SSE** (Server-Sent Events) - Real-time streaming updates\r\n- **Enterprise Security**: OAuth 2.1, SSO, audit logging, and encrypted communications (optional)\r\n- **Type Safety**: Full Pydantic v2 models and async support\r\n- **In-Memory Testing**: Client testing with faster execution\r\n- **Progress Reporting**: Real-time operation progress and context logging\r\n- **Configuration**: Environment variables, .env files, and CLI support\r\n- **Error Handling**: Graceful error handling with detailed messages and recovery patterns\r\n\r\n### AI Integration\r\n- **MCP Tools**: 15 tools for content operations\r\n- **MCP Resources**: Repository metadata and status information\r\n- **MCP Prompts**: AI-friendly templates for common operations\r\n\r\n### Alfresco Integration \r\nWorks with Alfresco Community (tested) and Enterprise editions\r\n\r\n### FastMCP 2.0 Advantages\r\n- **Boilerplate Reduction**: FastMCP reduces the amount of boilerplate code needed for implementing a MCP server\r\n- **Modular Architecture**: Organized 15 tools across logical modules for maintainability \r\n- **In-Memory Testing**: Client testing instead of FastAPI mocks\r\n- **Enhanced Developer Experience**: Context logging, progress reporting, automatic schema generation\r\n- **Future-Proof Architecture**: Ready for MCP 2.0 protocol evolution and AI platform integrations\r\n\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n- Python 3.10+\r\n- Alfresco Content Services (Community or Enterprise)\r\n- python-alfresco-api >= 1.1.1\r\n\r\n## \ud83d\udee0\ufe0f Installation\r\n\r\n### Option A: Install from PyPI (Recommended for Users)\r\n\r\nThe fastest way to get started - install directly from PyPI:\r\n\r\n```bash\r\n# Option 1: pipx (Recommended) - installs in isolated environment + makes globally available\r\npipx install python-alfresco-mcp-server\r\n\r\n# Option 2: pip - traditional package manager  \r\npip install python-alfresco-mcp-server\r\n\r\n# Option 3: UV (fastest) - Rust-based package manager\r\nuv pip install python-alfresco-mcp-server\r\n\r\n# Run immediately \r\npython-alfresco-mcp-server --help\r\n```\r\n\r\n**Why pipx?** pipx automatically creates isolated environments for each tool while making commands globally available - eliminates dependency conflicts while providing system-wide access.\r\n\r\n**Note**: You still need to configure your MCP client (Claude Desktop, MCP Inspector, etc.) with the appropriate configuration. See the [MCP Client Setup](#mcp-client-setup) section below for client configuration details.\r\n\r\n### Option B: Install from Source (Recommended for Development)\r\n\r\nFor development or access to latest features:\r\n\r\n### 1. Install UV (Recommended)\r\n\r\nUV 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:\r\n\r\n```bash\r\n# Method 1: Official installer (recommended)\r\n# Windows\r\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\r\n\r\n# macOS/Linux  \r\ncurl -LsSf https://astral.sh/uv/install.sh | sh\r\n\r\n# Method 2: pip (if you prefer)\r\npip install uv\r\n\r\n# Method 3: Package managers\r\n# macOS with Homebrew\r\nbrew install uv\r\n\r\n# Windows with Chocolatey  \r\nchoco install uv\r\n\r\n# Verify installation\r\nuv --version\r\n```\r\n\r\n### 2. Get the Code\r\n\r\n```bash\r\n# Clone the repository\r\ngit clone https://github.com/stevereiner/python-alfresco-mcp-server.git\r\ncd python-alfresco-mcp-server\r\n```\r\n\r\n### 3. Install Dependencies (Choose Method)\r\n\r\n**Option A: UV (Recommended - Automatic everything + much faster):**\r\n\r\n```bash\r\n# UV handles venv creation and dependency installation automatically\r\n# Rust-based performance makes this much faster than pip\r\nuv run python-alfresco-mcp-server --help\r\n\r\n# Or install dependencies explicitly:\r\nuv sync                    # Basic dependencies\r\nuv sync --extra dev        # With development tools  \r\nuv sync --extra test       # With testing tools\r\nuv sync --extra all        # Everything\r\n```\r\n\r\n**Option B: Traditional pip (Manual venv management):**\r\n\r\n```bash\r\n# Create and activate virtual environment  \r\npython -m venv venv          # Traditional Python creates 'venv'\r\nsource venv/bin/activate     # Linux/macOS\r\n# venv\\Scripts\\activate      # Windows\r\n\r\n# Note: UV creates '.venv' by default (not 'venv')\r\n\r\n# Install MCP server\r\npip install -e .\r\n\r\n# Or with development dependencies\r\npip install -e .[dev]\r\n\r\n# Or with testing dependencies\r\npip install -e .[test]\r\n\r\n# Or install everything\r\npip install -e .[all]\r\n```\r\n\r\n### 4. Configure Alfresco Connection\r\n\r\n**Option 1: Environment Variables**\r\n```bash\r\n# Linux/Mac\r\nexport ALFRESCO_URL=\"http://localhost:8080\"\r\nexport ALFRESCO_USERNAME=\"admin\"\r\nexport ALFRESCO_PASSWORD=\"admin\"\r\nexport ALFRESCO_VERIFY_SSL=\"false\"\r\n\r\n# Windows PowerShell\r\n$env:ALFRESCO_URL=\"http://localhost:8080\"\r\n$env:ALFRESCO_USERNAME=\"admin\"\r\n$env:ALFRESCO_PASSWORD=\"admin\"\r\n$env:ALFRESCO_VERIFY_SSL=\"false\"\r\n\r\n# Windows Command Prompt\r\nset ALFRESCO_URL=http://localhost:8080\r\nset ALFRESCO_USERNAME=admin\r\nset ALFRESCO_PASSWORD=admin\r\nset ALFRESCO_VERIFY_SSL=false\r\n```\r\n\r\n**Option 2: .env file** (recommended - cross-platform):\r\n```bash\r\n# Copy sample-dot-env.txt to .env and customize\r\ncp sample-dot-env.txt .env\r\n\r\n# Edit .env file with your settings\r\nALFRESCO_URL=http://localhost:8080\r\nALFRESCO_USERNAME=admin\r\nALFRESCO_PASSWORD=admin\r\nALFRESCO_VERIFY_SSL=false\r\n```\r\n> **Note**: The `.env` file is not checked into git for security. Use `sample-dot-env.txt` as a template.\r\n\r\n\ud83d\udcd6 **See [Configuration Guide](./docs/configuration_guide.md) for complete setup options**\r\n\r\n## Alfresco Installation \r\n\r\nIf you don't have an Alfresco server installed you can get a docker for the \r\nCommunity version from Github\r\n   ```bash\r\n   git clone https://github.com/Alfresco/acs-deployment.git\r\n```\r\n\r\n**Start Alfresco with Docker Compose**\r\n   ```bash\r\n   cd acs-deployment/docker-compose\r\n```\r\n   Note: you will likely need to comment out activemq ports other than 8161\r\n   in community-compose.yaml\r\n   ```bash   \r\n      ports:\r\n      - \"8161:8161\" # Web Console\r\n      #- \"5672:5672\" # AMQP\r\n      #- \"61616:61616\" # OpenWire\r\n      #- \"61613:61613\" # STOMP\r\n\r\n    docker-compose -f community-compose.yaml up\r\n```\r\n\r\n## \ud83d\ude80 Usage\r\n\r\n### MCP Server Startup\r\n\r\n**With UV (Recommended - Automatic venv and dependency management):**\r\n\r\n```bash\r\n# Run MCP server with STDIO transport (default)\r\nuv run python-alfresco-mcp-server\r\n\r\n# HTTP transport for web services\r\nuv run python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8001\r\n\r\n# SSE transport for real-time streaming  \r\nuv run python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8003\r\n```\r\n\r\n**Traditional Python (after manual venv setup):**\r\n\r\n```bash\r\n# Run MCP server with STDIO transport (default)\r\npython-alfresco-mcp-server\r\n\r\n# Or directly with module (also STDIO by default)\r\npython -m alfresco_mcp_server.fastmcp_server\r\n\r\n# HTTP transport for web services\r\npython -m alfresco_mcp_server.fastmcp_server --transport http --host 127.0.0.1 --port 8001\r\n\r\n# SSE transport for real-time streaming  \r\npython -m alfresco_mcp_server.fastmcp_server --transport sse --host 127.0.0.1 --port 8003\r\n```\r\n\r\n### MCP Client Setup\r\n\r\n#### \ud83e\udd16 **Claude Desktop** (Recommended)\r\n\r\nClaude Desktop is the primary tested and recommended MCP client with native support for the Python Alfresco MCP Server.\r\n\r\n\ud83d\udcd6 **Complete Setup Guide**: **[Claude Desktop Setup Guide](./docs/claude_desktop_setup.md)**\r\n\r\n**Quick Start:**\r\n\r\n**For Users (PyPI Installation):**\r\n- Install with `pipx install python-alfresco-mcp-server`\r\n- Use configuration files: `claude-desktop-config-user-windows.json` or `claude-desktop-config-user-macos.json`\r\n\r\n**For Developers (Source Installation):**\r\n- Clone repository and use UV\r\n- Use configuration files: `claude-desktop-config-developer-windows.json` or `claude-desktop-config-developer-macos.json`\r\n\r\n**Using the Tools:**\r\n- **Chat naturally** about what you want to do with documents\r\n- Use **\"Search and tools\"** button in the chat box for tool access\r\n- **4 individual search tools**: \r\n  - `search_content` (full text search)\r\n  - `advanced_search` (AFTS query language)\r\n  - `search_by_metadata` (property-based queries)\r\n  - `cmis_search` (CMIS SQL queries)\r\n- Click **\"+\" \u2192 \"Add from alfresco\"** for quick access to resources\r\n\r\n**Search and Analyze Prompt:**\r\n- Provides a form with query field for full-text search\r\n- Analysis types: **summary**, **detailed**, **trends**, or **compliance**\r\n- **Generates template text** to copy/paste into chat for editing\r\n\r\n**Repository Info Resource (and Tool):**\r\n- Provides status information in text format for viewing or copying\r\n\r\n**Testing & Examples:**\r\n- See [`prompts-for-claude.md`](./prompts-for-claude.md) for 14 manual test scenarios and examples\r\n- Automated versions of all scenarios available in integration test suite\r\n\r\n#### \ud83d\udd27 **Other MCP Clients**\r\n\r\nFor Cursor, Claude Code, and other MCP clients:\r\n\r\n\ud83d\udcd6 **Complete Setup Guide**: **[Client Configuration Guide](./docs/client_configurations.md)**\r\n\r\n**Quick Reference:**\r\n- **Cursor**: VS Code fork with AI and MCP support\r\n- **Claude Code**: Anthropic's VS Code extension  \r\n- **Other Clients**: Generic MCP client configuration patterns\r\n\r\n#### \ud83d\udd0d **MCP Inspector** (Development/Testing)\r\n\r\n> \ud83d\udcd6 **Setup Guide**: Complete MCP Inspector setup and connection instructions in [MCP Inspector Setup Guide](./docs/mcp_inspector_setup.md)\r\n\r\n**Working Method (Recommended):**\r\n\r\n1. **Start MCP Server with HTTP transport:**\r\n```bash\r\n# With UV (recommended)\r\nuv run python-alfresco-mcp-server --transport http --port 8003\r\n\r\n# Or traditional method\r\npython -m alfresco_mcp_server.fastmcp_server --transport http --port 8003\r\n```\r\n\r\n2. **Start MCP Inspector with config:**\r\n```bash\r\nnpx @modelcontextprotocol/inspector --config mcp-inspector-http-config.json --server python-alfresco-mcp-server\r\n```\r\n\r\n3. **Open browser with pre-filled token:**\r\n   - Use the URL provided in the output (includes authentication token)\r\n   - Example: `http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>`\r\n\r\nThis approach avoids proxy connection errors and provides direct authentication.\r\n\r\n\r\n\r\n\ud83d\udca1 **See [Examples Library](./examples/README.md) for usage patterns**\r\n\r\n## \ud83d\udee0\ufe0f Available Tools (15 Total)\r\n\r\n### \ud83d\udd0d Search Tools (4)\r\n| Tool | Description | Parameters |\r\n|------|-------------|------------|\r\n| `search_content` | Search documents and folders | `query` (str), `max_results` (int), `node_type` (str) |\r\n| `advanced_search` | Advanced search with filters | `query` (str), `content_type` (str), `created_after` (str), etc. |\r\n| `search_by_metadata` | Search by metadata properties | `property_name` (str), `property_value` (str), `comparison` (str) |\r\n| `cmis_search` | CMIS SQL queries | `cmis_query` (str), `preset` (str), `max_results` (int) |\r\n\r\n### \ud83d\udee0\ufe0f Core Tools (11)\r\n| Tool | Description | Parameters |\r\n|------|-------------|------------|\r\n| `browse_repository` | Browse repository folders | `node_id` (str) |\r\n| `repository_info` | Get repository information | None |\r\n| `upload_document` | Upload new document | `filename` (str), `content_base64` (str), `parent_id` (str), `description` (str) |\r\n| `download_document` | Download document content | `node_id` (str), `save_to_disk` (bool) |\r\n| `create_folder` | Create new folder | `folder_name` (str), `parent_id` (str), `description` (str) |\r\n| `get_node_properties` | Get node metadata | `node_id` (str) |\r\n| `update_node_properties` | Update node metadata | `node_id` (str), `name` (str), `title` (str), `description` (str), `author` (str) |\r\n| `delete_node` | Delete document/folder | `node_id` (str), `permanent` (bool) |\r\n| `checkout_document` | Check out for editing | `node_id` (str), `download_for_editing` (bool) |\r\n| `checkin_document` | Check in after editing | `node_id` (str), `comment` (str), `major_version` (bool), `file_path` (str) |\r\n| `cancel_checkout` | Cancel checkout/unlock | `node_id` (str) |\r\n\r\n\ud83d\udcd6 **See [API Reference](./docs/api_reference.md) for detailed tool documentation**\r\n\r\n## \ud83d\udcca Available Resources\r\n\r\n### Repository Information\r\n| Resource | Description | Access Method |\r\n|----------|-------------|---------------|\r\n| `repository_info` | Get comprehensive repository information including version, edition, license details, installed modules, and system status | Available as both MCP resource and tool |\r\n\r\nThe `repository_info` resource provides:\r\n- **Repository Details**: ID, edition (Community/Enterprise), version information\r\n- **License Information**: Issued/expires dates, remaining days, license holder, entitlements\r\n- **System Status**: Read-only mode, audit enabled, quick share, thumbnail generation\r\n- **Installed Modules**: Up to 10 modules with ID, title, version, and installation state\r\n\r\n\ud83d\udcd6 **See [API Reference](./docs/api_reference.md) for detailed resource documentation**\r\n\r\n## \ud83c\udfaf Available Prompts\r\n\r\n### Search and Analyze Prompt\r\n| Prompt | Description | Parameters |\r\n|--------|-------------|------------|\r\n| `search_and_analyze` | Interactive form for guided content search and analysis | `query` (search terms), `analysis_type` (summary/detailed/trends/compliance) |\r\n\r\nThe Search and Analyze Prompt provides:\r\n- **Interactive Form**: User-friendly interface with query input field\r\n- **Analysis Options**: Choose from summary, detailed analysis, trends, or compliance reporting\r\n- **Template Generation**: Creates copyable template text for chat conversations\r\n- **Query Assistance**: Helps users structure effective search queries\r\n- **Multiple Search Types**: Integrates with all 4 search tools (content, advanced, metadata, CMIS)\r\n\r\n\ud83d\udcd6 **See [API Reference](./docs/api_reference.md) for detailed prompt documentation**\r\n\r\n## \ud83d\udd27 Configuration Options\r\n\r\n| Environment Variable | Default | Description |\r\n|---------------------|---------|-------------|\r\n| `ALFRESCO_URL` | `http://localhost:8080` | Alfresco server URL |\r\n| `ALFRESCO_USERNAME` | `admin` | Username for authentication |\r\n| `ALFRESCO_PASSWORD` | `admin` | Password for authentication |\r\n| `ALFRESCO_VERIFY_SSL` | `false` | Verify SSL certificates |\r\n| `ALFRESCO_TIMEOUT` | `30` | Request timeout (seconds) |\r\n| `FASTAPI_HOST` | `localhost` | FastAPI host |\r\n| `FASTAPI_PORT` | `8000` | FastAPI port |\r\n| `LOG_LEVEL` | `INFO` | Logging level |\r\n| `MAX_FILE_SIZE` | `100000000` | Max upload size (bytes) |\r\n\r\n\u2699\ufe0f **See [Configuration Guide](./docs/configuration_guide.md) for deployment options**\r\n\r\n## \ud83c\udfd7\ufe0f Architecture\r\n\r\n```\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502                   MCP Clients                       \u2502\r\n\u2502  Claude Desktop \u2502 MCP Inspector \u2502 Cursor \u2502 Claude   \u2502\r\n\u2502     Code \u2502 n8n \u2502 LangFlow \u2502 Custom MCP Client App   \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n                  \u2502 stdio/HTTP/SSE\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502             FastMCP 2.0 MCP Server                  \u2502\r\n\u2502  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510    \u2502\r\n\u2502  \u2502 MCP Tools   \u2502 MCP         \u2502 HTTP/SSE API    \u2502    \u2502\r\n\u2502  \u2502 (15 total)  \u2502 Resources   \u2502                 \u2502    \u2502\r\n\u2502  \u2502             \u2502 MCP Prompts \u2502                 \u2502    \u2502\r\n\u2502  \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518    \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n                  \u2502 python-alfresco-api\r\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u25bc\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\r\n\u2502            Alfresco Content Services                \u2502\r\n\u2502         (Community/Enterprise Edition)              \u2502\r\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\r\n```\r\n\r\n## \ud83e\uddea Testing & Quality\r\n\r\n### Test Suite Overview\r\n- **143 Total Tests**: **100% passed** - Coverage of all functionality\r\n- **122 Unit Tests**: **100% passed** - Core functionality validated with mocking (FastMCP 2.0, tools, coverage)\r\n- **21 Integration Tests**: **100% passed** - Live server testing (search, upload, download, document lifecycle)\r\n- **Integration Tests**: Automated end-to-end testing covering all 14 manual scenarios from prompts-for-claude.md\r\n- **Performance Validated**: Search <1s, concurrent operations, resource access\r\n\r\n### Coverage Report (Post-Cleanup)\r\n- **Overall Coverage**: 51% (1,829 statements tested)\r\n- **FastMCP 2.0 Core**: Well tested with comprehensive unit coverage\r\n- **Configuration Module**: 93% coverage - Fully tested\r\n- **Package Initialization**: 100% coverage (5/5 lines) - Complete\r\n- **Overall Project**: 51% coverage of comprehensive codebase\r\n\r\n### Run Tests\r\n\r\n```bash\r\n# Run full test suite\r\npytest\r\n\r\n# Run with coverage report\r\npytest --cov=alfresco_mcp_server --cov-report=term-missing\r\n\r\n# Run specific test categories\r\npytest -m \"unit\"           # Unit tests only\r\npytest -m \"fastmcp\"        # FastMCP 2.0 tests\r\npytest -m \"integration\"    # Integration tests (requires Alfresco)\r\n```\r\n\r\n\ud83e\uddea **See [Testing Guide](./docs/testing_guide.md) for detailed testing strategies**\r\n\r\n### \ud83e\uddea Test Categories and Execution\r\n\r\nThe project includes **4 levels of testing**:\r\n\r\n1. **\ud83d\udccb Unit Tests** (122 tests) - Fast, mocked, isolated component testing\r\n2. **\ud83d\udd17 Integration Tests** (21 tests) - Live Alfresco server testing  \r\n3. **\ud83d\udcdd Comprehensive Tests** - Automated prompts-for-claude.md scenarios\r\n4. **\ud83d\udcca Coverage Tests** - Edge cases and error path coverage\r\n\r\n**New Integration Tests:**\r\n- **Automated Manual Scenarios**: All manual test scenarios from `prompts-for-claude.md` now available as automated tests\r\n\r\n## \ud83e\uddea Development\r\n\r\n### Setup Development Environment\r\n\r\n```bash\r\ngit clone <repository>\r\ncd python-alfresco-mcp-server\r\n\r\n# Create virtual environment\r\npython -m venv venv\r\nsource venv/bin/activate  # or venv\\Scripts\\activate on Windows\r\n\r\n# Install development dependencies\r\npip install -e .[dev]\r\n\r\n# Install python-alfresco-api (local development)\r\npip install -e ../python-alfresco-api\r\n```\r\n\r\n## \ud83d\udca1 Examples\r\n\r\n### Real-world implementation patterns from beginner to enterprise:\r\n\r\n- **[\ud83d\udca1 Examples Library](./examples/README.md)** - Complete navigation and learning paths\r\n- **[\ud83c\udfc3 Quick Start](./examples/quick_start.py)** - 5-minute introduction and basic operations\r\n- **[\ud83d\udccb Document Lifecycle](./examples/document_lifecycle.py)** - Complete process demonstration\r\n- **[\ud83d\ude80 Transport Examples](./examples/transport_examples.py)** - STDIO, HTTP, and SSE protocols\r\n- **[\u26a1 Batch Operations](./examples/batch_operations.py)** - High-performance bulk processing\r\n- **[\ud83d\udee1\ufe0f Error Handling](./examples/error_handling.py)** - Resilience patterns\r\n- **[\ud83d\udcca Examples Summary](./examples/examples_summary.md)** - Overview and statistics\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/new-feature`)\r\n3. Commit your changes (`git commit -m 'Add new feature'`)\r\n4. Push to the branch (`git push origin feature/new-feature`)\r\n5. Open a Pull Request\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\udd17 Related Projects and References\r\n\r\n- **[Hyland Alfresco](https://www.hyland.com/en/solutions/products/alfresco-platform)** - Content management platform (Enterprise and Community editions)\r\n- **[python-alfresco-api](https://github.com/stevereiner/python-alfresco-api)** - The underlying Alfresco API library\r\n- **[FastMCP 2.0](https://github.com/paulinephelan/FastMCP)** - Modern framework for building MCP servers\r\n- **[Model Context Protocol](https://modelcontextprotocol.io)** - Official MCP specification and documentation\r\n- **[MCP Server Directory](https://playbooks.com/mcp)** - Comprehensive directory of 5,000+ MCP servers for AI agents\r\n\r\n## \ud83d\ude4b\u200d\u2642\ufe0f Support\r\n\r\n- \ud83d\udcda **Documentation**: Complete guides in [`./docs/`](./docs/README.md)\r\n- \ud83d\udca1 **Examples**: Implementation patterns in [`./examples/`](./examples/README.md)\r\n- \ud83e\uddea **Testing**: Quality assurance in [`./docs/testing_guide.md`](./docs/testing_guide.md)\r\n- \ud83d\udd0d **MCP Inspector**: Development testing in [`./docs/mcp_inspector_setup.md`](./docs/mcp_inspector_setup.md)\r\n- \ud83d\udee0\ufe0f **Troubleshooting**: Problem solving in [`./docs/troubleshooting.md`](./docs/troubleshooting.md)\r\n- \ud83d\udc1b **Issues**: [GitHub Issues](https://github.com/stevereiner/python-alfresco-mcp-server/issues)\r\n\r\n---\r\n\r\n**\ud83d\ude80 MCP server built with [python-alfresco-api](https://github.com/stevereiner/python-alfresco-api) and [FastMCP 2.0](https://github.com/paulinephelan/FastMCP)**\r\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "FastMCP 2.0 server for Alfresco Content Services integration",
    "version": "1.1.0",
    "project_urls": {
        "Documentation": "https://github.com/stevereiner/python-alfresco-mcp-server#readme",
        "Homepage": "https://github.com/stevereiner/python-alfresco-mcp-server",
        "Issues": "https://github.com/stevereiner/python-alfresco-mcp-server/issues",
        "Repository": "https://github.com/stevereiner/python-alfresco-mcp-server"
    },
    "split_keywords": [
        "alfresco",
        " mcp",
        " content-management",
        " fastmcp",
        " ai"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "4678a8216ef9ce2c64127d1b9c99901a4ac4d4a16c80a4886716a014b1081d24",
                "md5": "ca6eabb1abd5669b6802bf2755b47a17",
                "sha256": "93bfe9250a0b57fc4d50e90d63bf6d4047d03a85d0f4a2c00c14e443c8fb0571"
            },
            "downloads": -1,
            "filename": "python_alfresco_mcp_server-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "ca6eabb1abd5669b6802bf2755b47a17",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 64258,
            "upload_time": "2025-07-25T04:26:43",
            "upload_time_iso_8601": "2025-07-25T04:26:43.672309Z",
            "url": "https://files.pythonhosted.org/packages/46/78/a8216ef9ce2c64127d1b9c99901a4ac4d4a16c80a4886716a014b1081d24/python_alfresco_mcp_server-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "4d2396e20419205408662b2f8766ee98ae24e9928c6cc646621016ed42c54783",
                "md5": "cec16c21ddc0cc31a08c315845f89647",
                "sha256": "a7f8a033878fce9b5214612ce9bab83b749fa0f17079b8d7bffc2f9803640bc0"
            },
            "downloads": -1,
            "filename": "python_alfresco_mcp_server-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "cec16c21ddc0cc31a08c315845f89647",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 179274,
            "upload_time": "2025-07-25T04:26:45",
            "upload_time_iso_8601": "2025-07-25T04:26:45.259840Z",
            "url": "https://files.pythonhosted.org/packages/4d/23/96e20419205408662b2f8766ee98ae24e9928c6cc646621016ed42c54783/python_alfresco_mcp_server-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-25 04:26:45",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "stevereiner",
    "github_project": "python-alfresco-mcp-server#readme",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "python-alfresco-mcp-server"
}