# MJML MCP Server
A comprehensive Model Context Protocol (MCP) server for MJML email template generation, compilation, and validation. This server provides powerful tools for creating professional email templates using the MJML markup language.
## Features
- **MJML Compilation**: Compile MJML to responsive HTML with advanced options
- **Template Generation**: Pre-built templates for common email types
- **Validation**: Validate MJML syntax and structure with configurable levels
- **Component Reference**: Get documentation and examples for MJML components
- **File Support**: Work with both MJML strings and files
- **Robust Error Handling**: Comprehensive error reporting and logging
## Tools
### 1. `compile_mjml`
Compile MJML content to responsive HTML email.
**Parameters:**
- `input` (required): MJML content or file path
- `filePath` (optional): Treat input as file path (default: false)
- `beautify` (optional): Beautify output HTML (default: true)
- `minify` (optional): Minify output HTML (default: false)
- `validationLevel` (optional): Validation level - "skip", "soft", "strict" (default: "soft")
- `keepComments` (optional): Keep comments in output (default: false)
- `fonts` (optional): Custom fonts configuration
- `outputPath` (optional): Save compiled HTML to file path
### 2. `validate_mjml`
Validate MJML syntax and structure.
**Parameters:**
- `input` (required): MJML content or file path
- `filePath` (optional): Treat input as file path (default: false)
- `validationLevel` (optional): Validation level - "skip", "soft", "strict" (default: "strict")
### 3. `generate_template`
Generate pre-built email templates.
**Parameters:**
- `template` (required): Template type - "newsletter", "welcome", "promotional", "transactional", "password-reset", "verification", "announcement", "invitation"
- `variables` (optional): Template variables to replace
- `customColors` (optional): Custom color scheme
- `customFonts` (optional): Custom fonts
- `outputPath` (optional): Save template to file path
### 4. `get_component_info`
Get MJML component reference and documentation.
**Parameters:**
- `component` (optional): Specific component name
- `category` (optional): Component category - "all", "standard", "advanced", "structural" (default: "all")
## Installation
1. Clone or create the project directory
2. Install dependencies:
```bash
npm install
```
## Usage
### Start the Server
```bash
npm start
```
### Development Mode
```bash
npm run dev
```
### Running Tests
```bash
npm test
```
## Template Variables
When generating templates, you can use these variables:
- `company_name`: Your company name
- `company_logo`: URL to company logo
- `user_name`: Recipient's name
- `newsletter_date`: Date for newsletter
- `main_title`: Main title/heading
- `main_subtitle`: Main subtitle
- `featured_image`: Featured image URL
- `featured_title`: Featured article title
- `featured_content`: Featured article content
- `featured_link`: Featured article link
- `update1_title`, `update1_content`: First update
- `update2_title`, `update2_content`: Second update
- `discount_percentage`: Discount percentage for promotions
- `time_remaining`: Time remaining for promotions
- `product_name`, `product_image`, `product_description`: Product details
- `original_price`, `sale_price`: Pricing information
- `shop_url`: Shopping URL
- `dashboard_url`: Dashboard URL
- `support_email`: Support email address
- `unsubscribe_url`: Unsubscribe link
- `website_url`: Website URL
- `facebook_url`, `twitter_url`, `instagram_url`: Social media URLs
- `current_year`: Current year (automatically filled)
## Example Usage
### Compile MJML from String
```json
{
"name": "compile_mjml",
"arguments": {
"input": "<mjml><mj-body><mj-section><mj-column><mj-text>Hello World!</mj-text></mj-column></mj-section></mj-body></mjml>",
"beautify": true,
"validationLevel": "soft"
}
}
```
### Generate Welcome Template
```json
{
"name": "generate_template",
"arguments": {
"template": "welcome",
"variables": {
"company_name": "Acme Corp",
"user_name": "John Doe",
"support_email": "support@acme.com"
},
"customColors": {
"primary": "#007bff",
"success": "#28a745"
},
"outputPath": "./welcome-email.mjml"
}
}
```
### Validate MJML File
```json
{
"name": "validate_mjml",
"arguments": {
"input": "./templates/newsletter.mjml",
"filePath": true,
"validationLevel": "strict"
}
}
```
### Get Component Information
```json
{
"name": "get_component_info",
"arguments": {
"component": "mj-button"
}
}
```
## Error Handling
The server provides comprehensive error handling with detailed error messages:
- File access errors
- MJML syntax errors
- Validation failures
- Configuration issues
## Logging
The server includes structured logging with different levels:
- `INFO`: General information
- `WARN`: Warnings
- `ERROR`: Error messages
- `DEBUG`: Debug information (enable with DEBUG environment variable)
Enable debug logging:
```bash
DEBUG=1 npm start
```
## Configuration
The server supports various MJML options:
- Custom fonts configuration
- Validation levels
- Output formatting options
- File input/output handling
## Dependencies
- `@modelcontextprotocol/sdk`: MCP SDK for server implementation
- `mjml`: MJML compiler and validator
- `zod`: Schema validation
- `fs-extra`: Enhanced file system operations
## License
MIT License
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## Support
For issues and questions, please open an issue in the project repository.