<<<<<<< HEAD # MCP Mailu Server A FastMCP server for integrating with Mailu email server administration using the official Mailu REST API. This server automatically converts the entire Mailu API into MCP tools and resources, providing seamless integration between AI assistants and your Mailu mail server. ## Features ### 🔧 **Automatically Generated Tools** (from Mailu API) - **User Management**: Create, update, delete, and find users - **Domain Management**: Create, update, delete, and find domains - **Alias Management**: Create, update, delete, and find email aliases - **DKIM Operations**: Generate DKIM keys for domains - **Manager Operations**: Assign and manage domain managers ### 📊 **Automatically Generated Resources** - **Users**: `GET /user` - List all users - **Domains**: `GET /domain` - List all domains - **Aliases**: `GET /alias` - List all aliases - **Domain Users**: `GET /domain/{domain}/users` - List users for specific domain - **User Details**: `GET /user/{email}` - Get specific user information - **Domain Details**: `GET /domain/{domain}` - Get specific domain information ### ⚡ **Key Benefits** - **Complete API Coverage**: Every Mailu API endpoint automatically available - **Type Safety**: Full TypeScript-like type checking with Pydantic models - **Smart Resource Mapping**: GET requests become Resources, modifications become Tools - **Authentication Handled**: Bearer token authentication built-in - **Error Handling**: Comprehensive error responses and validation ## Installation ### From PyPI (Recommended) ```bash # Install from PyPI pip install mcp-mailu # Or with uv uv add mcp-mailu ``` ### From Source This project uses [uv](https://github.com/astral-sh/uv) for dependency management. ```bash # Clone and navigate to the project git clone https://git.supported.systems/MCP/mcp-mailu.git cd mcp-mailu # Install dependencies uv sync # Install in development mode uv pip install -e . ``` ## Configuration ### 1. Get Your Mailu API Token First, you need to obtain an API token from your Mailu instance: 1. Log into your Mailu admin interface 2. Go to the API section 3. Generate a new API token 4. Copy the token for configuration ### 2. Set Environment Variables Copy the example configuration: ```bash cp .env.example .env ``` Edit `.env` and set your values: ```bash # Your Mailu server URL (without /api/v1) MAILU_BASE_URL=https://mail.yourdomain.com # Your Mailu API token MAILU_API_TOKEN=your_actual_token_here # Optional: Enable debug logging DEBUG=true ``` ### 3. Alternative: Environment Variables You can also set environment variables directly: ```bash export MAILU_BASE_URL="https://mail.yourdomain.com" export MAILU_API_TOKEN="your_token_here" ``` ## Usage ### Running the Server ```bash # Using uv uv run mcp-mailu # Or directly with Python python -m mcp_mailu.server # With environment variables MAILU_BASE_URL="https://mail.example.com" MAILU_API_TOKEN="token" uv run mcp-mailu ``` ### Available Operations The server automatically exposes all Mailu API operations. Here are some examples: #### **User Operations** - `create_user` - Create a new email user with password, quota, and settings - `update_user` - Update user settings, password, or quota - `delete_user` - Remove a user account - `find_user` - Get detailed user information - `list_users` - Get all users across all domains #### **Domain Operations** - `create_domain` - Add a new email domain - `update_domain` - Modify domain settings and quotas - `delete_domain` - Remove a domain (and all its users) - `find_domain` - Get domain details including DNS settings - `list_domain` - Get all domains - `generate_dkim` - Generate new DKIM keys for a domain #### **Alias Operations** - `create_alias` - Create email aliases with multiple destinations - `update_alias` - Modify alias destinations or settings - `delete_alias` - Remove email aliases - `find_alias` - Get alias details - `list_alias` - Get all aliases #### **Examples with Parameters** **Create a new user:** ```json { "email": "john.doe@example.com", "raw_password": "SecurePassword123!", "displayed_name": "John Doe", "quota_bytes": 2000000000, "enabled": true, "comment": "Sales team member" } ``` **Create a domain:** ```json { "name": "newcompany.com", "max_users": 50, "max_aliases": 100, "signup_enabled": false, "comment": "New company domain" } ``` **Create an alias:** ```json { "email": "sales@example.com", "destination": ["john@example.com", "jane@example.com"], "comment": "Sales team alias" } ``` ## Development ### Setup Development Environment ```bash # Install with development dependencies uv sync --dev # Run tests uv run pytest # Format code uv run black src/ uv run ruff check src/ --fix # Type checking uv run mypy src/ ``` ### Project Structure ``` src/ ├── mcp_mailu/ │ ├── __init__.py # Package initialization │ └── server.py # Main FastMCP server with OpenAPI integration ├── .env.example # Configuration template ├── scripts/ # Build and publish scripts ├── pyproject.toml # UV project configuration ├── README.md # This file └── .gitignore # Git ignore rules ``` ### Publishing to PyPI The project includes scripts for easy PyPI publishing: ```bash # Build the package python scripts/publish.py --build # Check package validity python scripts/publish.py --check # Upload to TestPyPI for testing python scripts/publish.py --test # Upload to production PyPI python scripts/publish.py --prod ``` Before publishing: 1. Update version in `pyproject.toml` and `src/mcp_mailu/__init__.py` 2. Update author information in `pyproject.toml` 3. Set up PyPI credentials with `uv run twine configure` ## How It Works This server uses FastMCP's `from_openapi` method to automatically convert the Mailu REST API into an MCP server: 1. **OpenAPI Conversion**: The Mailu API OpenAPI/Swagger specification is used to generate MCP tools and resources 2. **Smart Mapping**: GET requests become MCP Resources for data retrieval, while POST/PATCH/DELETE become Tools for actions 3. **Authentication**: Bearer token authentication is automatically handled for all requests 4. **Type Safety**: All request/response models are automatically validated using Pydantic ## Troubleshooting ### Common Issues **Authentication Errors:** - Verify your `MAILU_API_TOKEN` is correct - Check that the token has sufficient permissions - Ensure your Mailu instance has the API enabled **Connection Errors:** - Verify `MAILU_BASE_URL` is correct and accessible - Check firewall settings and network connectivity - Ensure HTTPS is properly configured if using SSL **Permission Errors:** - Ensure your API token has admin privileges - Check that the specific domain/user operations are permitted ### Debug Mode Enable debug logging to troubleshoot issues: ```bash DEBUG=true uv run mcp-mailu ``` ## API Reference The server exposes the complete Mailu API. For detailed parameter information, refer to: - [Mailu Official Documentation](https://mailu.io/2024.06/) - [Mailu API Swagger Specification](https://mail.supported.systems/api/v1/swagger.json) ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Run tests and linting 5. Submit a pull request ## License This project is licensed under the MIT License. ======= # mcp-mailu FastMCP server for Mailu email server API integration - Automatically converts the entire Mailu REST API into MCP tools and resources for AI assistant integration >>>>>>> b7add7334e2d55bda3bce941f6bb4424ecfdd44a