Mailcow MCP Server

# Mailcow MCP Server - Claude Memory > **💡 This file contains essential context for Claude Code sessions** > For complete documentation, see [docs/README.md](docs/README.md) ## 🎯 Project Status **TypeScript MCP Server** for Mailcow email management - **MVP COMPLETE** ✅ ### Current State - **20 MCP Tools** implemented and registered - **Architecture**: Modular TypeScript with comprehensive type safety - **MCP SDK**: Using `@modelcontextprotocol/sdk` v0.4.0 - **Test Coverage**: 25.8% overall (Auth: 70%, Utils: 77%, Domain: 85%, Mailbox: 87%) ### Available Tools - **System** (3): health_check, get_config, test_api_connection - **Domains** (5): list, get, create, update, delete - **Mailboxes** (5): list, get, create, update, delete - **Queues** (6): list, get, flush, delete, hold, release - **Sync Jobs** (7): list, get, create, update, delete, activate, deactivate - **Logs** (4): get logs, errors, performance, access - **Email** (3): send, check status, get templates ## 🗂️ Key Files ``` src/ ├── index.ts # MCP Server entry point ✅ ├── api/ # Mailcow API clients ✅ │ ├── client.ts # HTTP client with auth │ ├── domains/ # Domain API ✅ │ ├── mailboxes/ # Mailbox API ✅ │ ├── queues/ # Queue API ✅ │ ├── syncjobs/ # Sync job API ✅ │ └── logs/ # Log API ✅ ├── tools/ # MCP tool implementations ✅ │ ├── base.ts # Base tool class ✅ │ ├── domains/ # Domain tools ✅ │ ├── mailboxes/ # Mailbox tools ✅ │ ├── queues/ # Queue tools ✅ │ ├── jobs/ # Sync job tools ✅ │ ├── logs/ # Log tools ✅ │ └── email/ # Email tools ✅ ├── auth/ # Authentication ✅ ├── config/ # Configuration ✅ ├── types/ # TypeScript types ✅ └── utils/ # Utilities ✅ ``` ## ⚡ Quick Commands ```bash # Development npm run dev # Start with auto-reload npm run build # Build TypeScript npm test # Run test suite # Testing & Quality npm run test:coverage # Generate coverage report npm run lint # ESLint npm run format # Prettier # Production npm start # Start production server ``` ## 🔑 Environment Setup ```bash # Required environment variables MAILCOW_API_URL=https://your-mailcow-server.com MAILCOW_API_KEY=your-32-character-api-key MAILCOW_API_ACCESS_TYPE=read-write MAILCOW_VERIFY_SSL=true ``` ## 🏗️ Architecture Patterns ### Tool Pattern ```typescript export class ExampleTool extends BaseTool { readonly name = 'tool_name'; readonly description = 'Tool description'; readonly inputSchema = { /* JSON schema */ }; async execute(input: ToolInput, context: ToolContext): Promise<ToolHandlerResult> { // 1. Validate permissions // 2. Validate input // 3. Call API // 4. Return formatted result } } ``` ### API Pattern (Mailcow-specific) ```typescript // ✅ Correct Mailcow patterns const domains = await client.get('/api/v1/get/domain'); await client.post('/api/v1/add/domain', data); await client.post('/api/v1/edit/domain', data); await client.post('/api/v1/delete/domain', { items: [id] }); // ❌ Wrong - RESTful doesn't work with Mailcow const domains = await client.get('/api/v1/domains'); // Won't work ``` ### Permission Patterns - **Namespace Format**: `{resource}:{action}` (e.g., `domains:read`, `mailboxes:write`) - **Generic Fallbacks**: `read`, `write`, `delete` for backward compatibility - **Validation**: Always check permissions before API calls ## 🚨 Important Notes ### Email Tools MVP - **send_email**: Simulates queue submission (generates realistic queue IDs) - **check_email_status**: Checks both queue and logs for delivery status - **Queue Integration**: Uses existing queue APIs for status tracking - **Templates**: 5 predefined templates (welcome, alert, maintenance, etc.) ### API Quirks - **Non-RESTful**: Mailcow uses `/get/`, `/add/`, `/edit/`, `/delete/` patterns - **Auth Header**: Uses `X-API-Key` header, not `Authorization` - **Delete Format**: `{ items: [item1, item2] }` for deletions ### Naming Consistency - **syncjobs** (not jobs) - matches API endpoint `/api/v1/syncjobs` - **queues** - matches API endpoint `/api/v1/queues` - **Permission namespace**: `syncjobs:read`, `syncjobs:write`, `syncjobs:delete` ## 🔄 Testing ### Key Test Commands ```bash npm test # Unit tests npm run test:integration # Integration tests npm run test:all # Everything npm run coverage:open # View coverage report ``` ### Mock Patterns - **Use MockLogger** for testing logging - **Mock API responses** with realistic Mailcow data - **Test both success and failure paths** ## 📝 Development Workflow 1. **Read existing patterns** in similar tools 2. **Follow BaseTool pattern** for consistency 3. **Add comprehensive tests** (>80% coverage target) 4. **Update documentation** as needed 5. **Test integration** with `npm run test:all` --- **For detailed information**: See [docs/README.md](docs/README.md) | **Quick Start**: [docs/QUICK_START.md](docs/QUICK_START.md)