mcp-mailu/README.md

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