usage-examples.md•10.1 kB
# MJML MCP Server Usage Examples
This document provides practical examples of how to use the MJML MCP server for various email template tasks.
## Table of Contents
1. [Basic MJML Compilation](#basic-mjml-compilation)
2. [Template Generation](#template-generation)
3. [Advanced Compilation Options](#advanced-compilation-options)
4. [File Operations](#file-operations)
5. [Validation](#validation)
6. [Component Reference](#component-reference)
## Basic MJML Compilation
### Simple MJML to HTML
```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"
}
}
```
### MJML with Custom Styling
```json
{
"name": "compile_mjml",
"arguments": {
"input": "<mjml><mj-head><mj-attributes><mj-text color=\"#333333\" font-size=\"16px\" /></mj-attributes></mj-head><mj-body><mj-section><mj-column><mj-text>Styled text</mj-text></mj-column></mj-section></mj-body></mjml>",
"beautify": true,
"validationLevel": "strict"
}
}
```
## Template Generation
### Welcome Email Template
```json
{
"name": "generate_template",
"arguments": {
"template": "welcome",
"variables": {
"company_name": "Acme Corporation",
"user_name": "John Doe",
"support_email": "support@acme.com",
"dashboard_url": "https://dashboard.acme.com"
},
"customColors": {
"primary": "#2563eb",
"success": "#16a34a"
},
"outputPath": "./welcome-email.mjml"
}
}
```
### Newsletter Template
```json
{
"name": "generate_template",
"arguments": {
"template": "newsletter",
"variables": {
"company_name": "Tech Blog",
"newsletter_date": "November 2024",
"main_title": "This Month in Tech",
"main_subtitle": "Latest updates and insights",
"featured_title": "New AI Breakthrough",
"featured_content": "Discover the latest advancements in artificial intelligence...",
"featured_link": "https://techblog.com/ai-breakthrough",
"featured_image": "https://example.com/ai-image.jpg"
},
"customColors": {
"primary": "#6366f1",
"dark": "#1f2937"
},
"outputPath": "./newsletter.mjml"
}
}
```
### Promotional Email Template
```json
{
"name": "generate_template",
"arguments": {
"template": "promotional",
"variables": {
"company_name": "ShopHub",
"discount_percentage": "50",
"time_remaining": "24 hours",
"product_name": "Premium Headphones",
"product_description": "High-quality wireless headphones with noise cancellation",
"original_price": "199.99",
"sale_price": "99.99",
"product_image": "https://example.com/headphones.jpg",
"shop_url": "https://shophub.com/sale"
},
"customColors": {
"danger": "#dc2626",
"primary": "#dc2626"
}
}
}
```
## Advanced Compilation Options
### Custom Fonts Configuration
```json
{
"name": "compile_mjml",
"arguments": {
"input": "<mjml><mj-head><mj-font name=\"Roboto\" href=\"https://fonts.googleapis.com/css?family=Roboto\" /></mj-head><mj-body><mj-section><mj-column><mj-text font-family=\"Roboto\">Custom font text</mj-text></mj-column></mj-section></mj-body></mjml>",
"fonts": {
"Roboto": "https://fonts.googleapis.com/css?family=Roboto:300,400,500,700",
"Lato": "https://fonts.googleapis.com/css?family=Lato:400,700"
},
"beautify": true,
"validationLevel": "soft"
}
}
```
### Minified Output for Production
```json
{
"name": "compile_mjml",
"arguments": {
"input": "<mjml><mj-body><mj-section><mj-column><mj-text>Production email</mj-text></mj-column></mj-section></mj-body></mjml>",
"minify": true,
"beautify": false,
"validationLevel": "skip",
"keepComments": false,
"outputPath": "./production-email.html"
}
}
```
### Strict Validation
```json
{
"name": "compile_mjml",
"arguments": {
"input": "<mjml><mj-body><mj-section><mj-column><mj-text>Strictly validated email</mj-text></mj-column></mj-section></mj-body></mjml>",
"validationLevel": "strict",
"beautify": true
}
}
```
## File Operations
### Compile MJML from File
```json
{
"name": "compile_mjml",
"arguments": {
"input": "./templates/email.mjml",
"filePath": true,
"beautify": true,
"validationLevel": "soft",
"outputPath": "./compiled/email.html"
}
}
```
### Save Compiled HTML to File
```json
{
"name": "compile_mjml",
"arguments": {
"input": "<mjml><mj-body><mj-section><mj-column><mj-text>Saved to file</mj-text></mj-column></mj-section></mj-body></mjml>",
"outputPath": "./output/email.html",
"beautify": true
}
}
```
## Validation
### Validate MJML String
```json
{
"name": "validate_mjml",
"arguments": {
"input": "<mjml><mj-body><mj-section><mj-column><mj-text>Valid MJML</mj-text></mj-column></mj-section></mj-body></mjml>",
"validationLevel": "strict"
}
}
```
### Validate MJML File
```json
{
"name": "validate_mjml",
"arguments": {
"input": "./templates/newsletter.mjml",
"filePath": true,
"validationLevel": "strict"
}
}
```
### Soft Validation
```json
{
"name": "validate_mjml",
"arguments": {
"input": "<mjml><mj-body><mj-section><mj-column><mj-text>Soft validation</mj-text></mj-column></mj-section></mj-body></mjml>",
"validationLevel": "soft"
}
}
```
## Component Reference
### Get All Components
```json
{
"name": "get_component_info",
"arguments": {
"category": "all"
}
}
```
### Get Standard Components
```json
{
"name": "get_component_info",
"arguments": {
"category": "standard"
}
}
```
### Get Specific Component Information
```json
{
"name": "get_component_info",
"arguments": {
"component": "mj-button"
}
}
```
### Get Structural Components
```json
{
"name": "get_component_info",
"arguments": {
"category": "structural"
}
}
```
## Complete Workflow Examples
### Create, Validate, and Compile a Newsletter
1. **Generate the newsletter template:**
```json
{
"name": "generate_template",
"arguments": {
"template": "newsletter",
"variables": {
"company_name": "Monthly Digest",
"newsletter_date": "November 2024",
"main_title": "This Month's Highlights",
"main_subtitle": "Top stories and updates"
},
"outputPath": "./newsletter.mjml"
}
}
```
2. **Validate the generated template:**
```json
{
"name": "validate_mjml",
"arguments": {
"input": "./newsletter.mjml",
"filePath": true,
"validationLevel": "strict"
}
}
```
3. **Compile to HTML:**
```json
{
"name": "compile_mjml",
"arguments": {
"input": "./newsletter.mjml",
"filePath": true,
"beautify": true,
"validationLevel": "soft",
"outputPath": "./newsletter.html"
}
}
```
### A/B Testing Email Templates
1. **Generate template A:**
```json
{
"name": "generate_template",
"arguments": {
"template": "promotional",
"variables": {
"company_name": "E-commerce Store",
"discount_percentage": "25",
"product_name": "Summer Collection"
},
"customColors": {
"primary": "#3b82f6"
},
"outputPath": "./template-a.mjml"
}
}
```
2. **Generate template B (different colors):**
```json
{
"name": "generate_template",
"arguments": {
"template": "promotional",
"variables": {
"company_name": "E-commerce Store",
"discount_percentage": "25",
"product_name": "Summer Collection"
},
"customColors": {
"primary": "#ef4444"
},
"outputPath": "./template-b.mjml"
}
}
```
3. **Compile both templates:**
```json
{
"name": "compile_mjml",
"arguments": {
"input": "./template-a.mjml",
"filePath": true,
"outputPath": "./template-a.html"
}
}
```
```json
{
"name": "compile_mjml",
"arguments": {
"input": "./template-b.mjml",
"filePath": true,
"outputPath": "./template-b.html"
}
}
```
## Error Handling Examples
### Invalid MJML Structure
```json
{
"name": "validate_mjml",
"arguments": {
"input": "<mjml><mj-body><invalid-tag>Broken MJML</invalid-tag></mj-body></mjml>",
"validationLevel": "strict"
}
}
```
This will return validation errors showing what's wrong with the MJML structure.
### File Not Found
```json
{
"name": "compile_mjml",
"arguments": {
"input": "./nonexistent-file.mjml",
"filePath": true
}
}
```
This will return an error indicating the file couldn't be found.
## Best Practices
1. **Always validate MJML before compiling** in production environments
2. **Use strict validation** during development to catch issues early
3. **Save both MJML and compiled HTML** for version control and debugging
4. **Test emails across multiple clients** after compilation
5. **Use minified output for production** to reduce email size
6. **Keep custom fonts minimal** to improve loading times
## Integration Examples
### With Node.js Application
```javascript
// Example of how to integrate with a Node.js application
const { spawn } = require('child_process');
async function compileEmail(mjmlContent) {
return new Promise((resolve, reject) => {
const serverProcess = spawn('node', ['index.js'], {
cwd: './mjml-mcp-server'
});
const request = {
name: 'compile_mjml',
arguments: {
input: mjmlContent,
beautify: true,
validationLevel: 'strict'
}
};
serverProcess.stdin.write(JSON.stringify(request));
serverProcess.stdin.end();
let output = '';
serverProcess.stdout.on('data', (data) => {
output += data.toString();
});
serverProcess.on('close', (code) => {
if (code === 0) {
const result = JSON.parse(output);
resolve(result);
} else {
reject(new Error(`Server process exited with code ${code}`));
}
});
});
}
```
This comprehensive set of examples should help you understand how to effectively use the MJML MCP server for various email template tasks.