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