html-ad-generator-mcp/README.md

MCP server for generating HTML ad templates from JSON input for Google Ads, Meta Ads, and Moment Science

# HTML Ad Generator MCP Server

An MCP (Model Context Protocol) server that generates populated HTML ad templates from JSON input. Provides separate tools for Google Ads and Meta (Facebook) Ads.

## Features

- **Separate Tools**: Dedicated tools for Google Ads, Meta Ads, and Moment Science
- **Google Ads Support**: Generates BOTH Search Ads and Display Ads in one HTML file
- **Meta Ads Support**: Generate Facebook/Instagram ad previews
- **Moment Science Support**: Generate modal popup ads with Moment Science branding
- **Validation**: Built-in character limit checking and field validation
- **LLM-Friendly**: Simple input format designed for AI generation
- **Interactive Output**: Fully functional HTML with preserved JavaScript functionality

## Installation

### Option 1: Install from npm

```bash
npm install -g html-ad-generator-mcp
```

### Option 2: Install from source

1. Clone this repository
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the server:
   ```bash
   npm run build
   ```

## MCP Server Setup

After installation, you need to configure your MCP client to use this server.

### For Cursor/VSCode with Kilo Code Extension

Add the following to your MCP settings configuration:

```json
{
  "mcpServers": {
    "html-ad-generator": {
      "command": "node",
      "args": ["path/to/html-ad-generator-mcp/build/index.js"]
    }
  }
}
```

If installed globally via npm, use:

```json
{
  "mcpServers": {
    "html-ad-generator": {
      "command": "npx",
      "args": ["html-ad-generator-mcp"]
    }
  }
}
```

### For Claude Desktop

Add to your Claude Desktop configuration file:

**On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**On Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "html-ad-generator": {
      "command": "npx",
      "args": ["html-ad-generator-mcp"]
    }
  }
}
```

### Verify Installation

After configuring, restart your MCP client. The server should appear in your connected servers list with the following tools:
- `generate_google_ad_html`
- `generate_meta_ad_html`
- `generate_moment_science_ad_html`
- `validate_ad_content`
- `get_google_ad_schema`
- `get_meta_ad_schema`
- `get_moment_science_ad_schema`

## Available Tools

### 1. `generate_google_ad_html`
Generates a complete Google Ads HTML file with BOTH search and display ads.

**Input Parameters:**
- `searchAd` (required): Object with `headlines` (3 strings) and `descriptions` (2 strings)
- `displayAd` (required): Object with `headline`, `longHeadline`, `description`, `businessName`, and optional `imageUrl`

**Note:** Both searchAd and displayAd must be provided together.

**Example:**
```json
{
  "searchAd": {
    "headlines": ["Buy Running Shoes", "Free Shipping", "50% Off Today"],
    "descriptions": ["Premium quality shoes for athletes", "Limited time offer!"]
  },
  "displayAd": {
    "headline": "Summer Sale",
    "longHeadline": "Exclusive Summer Collection - Up to 70% Off",
    "description": "Limited stock available. Shop now!",
    "businessName": "FashionBrand",
    "imageUrl": "https://example.com/banner.jpg"
  }
}
```

### 2. `generate_meta_ad_html`
Generates a complete Meta (Facebook/Instagram) ad HTML file.

**Input Parameters:**
- `headline`: Main ad headline (max 40 chars)
- `description`: Short description (max 30 chars)
- `primaryText`: Main ad text content
- `cta`: Call-to-action button text
- `businessName` (optional): Business/page name
- `profileImageUrl` (optional): Profile picture URL
- `mainImageUrl` (optional): Main ad image URL

**Example:**
```json
{
  "headline": "3 Months Free Trial",
  "description": "New subscribers only",
  "primaryText": "Get 3 months of our premium service absolutely free.",
  "cta": "Start Free Trial"
}
```

### 3. `validate_ad_content`
Validates ad content for any platform.

**Input Parameters:**
- `platform`: Either "google", "meta", or "moment-science"
- `content`: The ad content to validate

### 4. `get_google_ad_schema`
Returns the expected schema for Google Ads with examples.

### 5. `get_meta_ad_schema`
Returns the expected schema for Meta Ads with examples.

### 6. `generate_moment_science_ad_html`
Generates a complete Moment Science modal popup ad HTML file.

**Input Parameters:**
- `headline`: Array of 3-5 ad headlines (max 70 chars each)
- `description`: Array of 3-5 ad descriptions (max 180 chars each)
- `positive_cta`: Array of 3-5 positive call-to-action button texts (max 20 chars each)
- `negative_cta`: Array of 3-5 negative call-to-action button texts (max 20 chars each)
- `imageUrl` (optional): Image URL for the ad

**Example:**
```json
{
  "headline": [
    "Save 25% on an AARP Membership Today!",
    "Join AARP and Save Big on Everything",
    "Exclusive AARP Member Benefits Await"
  ],
  "description": [
    "Pay only $15 for your first full year.",
    "Get access to exclusive discounts and benefits.",
    "Join millions of members saving money daily."
  ],
  "positive_cta": [
    "Join Now!",
    "Sign Up Today",
    "Get Started"
  ],
  "negative_cta": [
    "No, Thanks",
    "Maybe Later",
    "Not Now"
  ],
  "imageUrl": "https://example.com/aarp-logo.jpg"
}
```

### 7. `get_moment_science_ad_schema`
Returns the expected schema for Moment Science Ads with examples.

## Usage Examples

### Creating a Complete Google Ad Campaign
```json
{
  "searchAd": {
    "headlines": ["Premium Headphones", "Noise Cancelling", "Buy Now - 40% Off"],
    "descriptions": [
      "Crystal clear audio with 30-hour battery life. Free shipping.",
      "Rated 4.8/5 by customers. 1-year warranty included."
    ]
  },
  "displayAd": {
    "headline": "Audio Sale",
    "longHeadline": "Premium Noise-Cancelling Headphones - 40% Off Today",
    "description": "Experience studio-quality sound. Limited time offer.",
    "businessName": "AudioTech",
    "imageUrl": "https://example.com/headphones.jpg"
  }
}
```

### Creating a Meta Ad
```json
{
  "headline": "Learn Web Development",
  "description": "Start coding today",
  "primaryText": "Join our comprehensive bootcamp and master HTML, CSS, JavaScript and more.",
  "cta": "Enroll Now",
  "businessName": "CodeAcademy"
}
```

### Creating a Moment Science Ad
```json
{
  "headline": [
    "Save 25% on an AARP Membership Today!",
    "Join AARP and Save Big on Everything",
    "Exclusive AARP Member Benefits Await"
  ],
  "description": [
    "Pay only $15 for your first full year.",
    "Get access to exclusive discounts and benefits.",
    "Join millions of members saving money daily."
  ],
  "positive_cta": [
    "Join Now!",
    "Sign Up Today",
    "Get Started"
  ],
  "negative_cta": [
    "No, Thanks",
    "Maybe Later",
    "Not Now"
  ],
  "imageUrl": "https://example.com/aarp-logo.jpg"
}
```

## Character Limits

### Google Ads
- Headlines: 30 characters each
- Descriptions: 90 characters each
- Business Name: 25 characters

### Meta Ads
- Headline: 40 characters
- Description: 30 characters
- Primary Text: 125 characters

### Moment Science Ads
- Headlines: 90 characters each (3-5 options)
- Descriptions: 220 characters each (3-5 options)
- Positive CTAs: 25 characters each (3-5 options)
- Negative CTAs: 25 characters each (3-5 options)

## Output

The tools return complete HTML files that:
- Display your ad content in a professional preview interface
- Include interactive elements (dropdowns, character counters)
- Can be opened directly in a browser
- Maintain all original template functionality

For Google Ads, the HTML includes both Search and Display ad previews with tabs to switch between them.

## Error Handling

The server provides clear error messages for:
- Missing required fields (e.g., if you only provide searchAd without displayAd)
- Content exceeding character limits
- Invalid input format

## Development

To modify the server:
1. Edit files in the `src` directory
2. Run `npm run build` to compile
3. The server will automatically reload with your changes

## License

MIT