# Constant Contact MCP Server

A Model Context Protocol (MCP) server for the Constant Contact API v3, providing comprehensive email marketing automation, campaign management, contact management, and analytics capabilities.

## Features

### 🎯 Contact Management (12 tools)
- List, get, create, update, delete contacts
- Search contacts by various criteria
- Manage contact tags (list, add, remove)
- Import/export contacts in bulk
- Track contact activity and engagement

### 📧 Campaign Management (11 tools)
- Create, update, delete email campaigns
- Schedule and send campaigns
- Test send campaigns
- Clone existing campaigns
- Get campaign statistics and performance metrics
- List campaign activities

### 📋 List Management (9 tools)
- Create and manage contact lists
- Add/remove contacts from lists
- Get list membership and statistics
- Update list properties

### 🎯 Segmentation (6 tools)
- Create dynamic contact segments
- Update segment criteria
- Get segment contacts
- Delete segments

### 🎨 Templates (2 tools)
- List email templates
- Get template details

### 📊 Reporting & Analytics (11 tools)
- Campaign statistics (opens, clicks, bounces)
- Contact-level activity stats
- Bounce, click, and open reports
- Forward and optout tracking
- Campaign link analysis

### 🌐 Landing Pages (7 tools)
- Create, update, delete landing pages
- Publish landing pages
- Get landing page statistics

### 📱 Social Media (6 tools)
- Create and schedule social posts
- Manage posts across multiple platforms
- Publish posts immediately

### 🏷️ Tags (6 tools)
- Create and manage contact tags
- Get tag usage statistics
- Delete tags

**Total: 50+ MCP tools**

## Installation

```bash
npm install
npm run build
```

## Configuration

Create a `.env` file:

```env
CONSTANT_CONTACT_ACCESS_TOKEN=your_access_token_here
```

### Getting an Access Token

1. Go to [Constant Contact Developer Portal](https://developer.constantcontact.com/)
2. Create an application
3. Generate OAuth2 access token
4. Add token to `.env` file

## Usage

### As MCP Server (stdio)

```bash
npm start
```

### In Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "constant-contact": {
      "command": "node",
      "args": [
        "/path/to/constant-contact/dist/main.js"
      ],
      "env": {
        "CONSTANT_CONTACT_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Example MCP Tool Calls

**List contacts:**
```json
{
  "tool": "contacts_list",
  "arguments": {
    "limit": 50,
    "status": "active"
  }
}
```

**Create campaign:**
```json
{
  "tool": "campaigns_create",
  "arguments": {
    "name": "Summer Newsletter",
    "subject": "Check out our summer deals!",
    "from_name": "Marketing Team",
    "from_email": "marketing@example.com",
    "reply_to_email": "support@example.com",
    "html_content": "<html><body><h1>Summer Deals</h1></body></html>"
  }
}
```

**Get campaign stats:**
```json
{
  "tool": "campaigns_get_stats",
  "arguments": {
    "campaign_activity_id": "campaign_123"
  }
}
```

## React Apps

The server includes 17 pre-built React applications for managing Constant Contact data:

### Contact Management
- **contact-dashboard** (port 3000) - Overview of all contacts
- **contact-detail** (port 3002) - Individual contact details
- **contact-grid** (port 3003) - Grid view of contacts

### Campaign Management
- **campaign-dashboard** (port 3001) - Campaign overview
- **campaign-detail** (port 3004) - Individual campaign details
- **campaign-builder** (port 3005) - Campaign creation wizard

### List & Segment Management
- **list-manager** (port 3006) - Manage contact lists
- **segment-builder** (port 3007) - Create and manage segments

### Templates & Content
- **template-gallery** (port 3008) - Browse email templates

### Reporting & Analytics
- **report-dashboard** (port 3009) - Overall analytics dashboard
- **report-detail** (port 3010) - Detailed report view
- **bounce-report** (port 3015) - Bounce analysis
- **engagement-chart** (port 3016) - Engagement visualization

### Other Tools
- **landing-page-grid** (port 3011) - Manage landing pages
- **social-manager** (port 3012) - Social media post management
- **tag-manager** (port 3013) - Contact tag management
- **import-wizard** (port 3014) - Contact import tool

### Running React Apps

Each app is standalone with Vite:

```bash
cd src/ui/react-app/contact-dashboard
npm install
npm run dev
```

All apps use dark theme and client-side state management.

## API Reference

### Constant Contact API v3

- **Base URL:** `https://api.cc.email/v3`
- **Authentication:** OAuth2 Bearer token
- **Rate Limits:** 10,000 requests per day (automatically handled)
- **Documentation:** [Constant Contact API Docs](https://v3.developer.constantcontact.com/)

## Architecture

```
constant-contact/
├── src/
│   ├── clients/
│   │   └── constant-contact.ts    # API client with rate limiting
│   ├── tools/
│   │   ├── contacts-tools.ts      # 12 contact tools
│   │   ├── campaigns-tools.ts     # 11 campaign tools
│   │   ├── lists-tools.ts         # 9 list tools
│   │   ├── segments-tools.ts      # 6 segment tools
│   │   ├── templates-tools.ts     # 2 template tools
│   │   ├── reporting-tools.ts     # 11 reporting tools
│   │   ├── landing-pages-tools.ts # 7 landing page tools
│   │   ├── social-tools.ts        # 6 social tools
│   │   └── tags-tools.ts          # 6 tag tools
│   ├── types/
│   │   └── index.ts               # TypeScript definitions
│   ├── ui/
│   │   └── react-app/             # 17 React applications
│   ├── server.ts                  # MCP server setup
│   └── main.ts                    # Entry point
├── package.json
├── tsconfig.json
└── README.md
```

## Features

- ✅ **Automatic pagination** - Handles paginated responses automatically
- ✅ **Rate limiting** - Respects API rate limits with automatic retry
- ✅ **Error handling** - Comprehensive error messages
- ✅ **Type safety** - Full TypeScript support
- ✅ **Production ready** - Tested with Constant Contact API v3

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev
```

## License

MIT

## Support

For issues or questions:
- Constant Contact API: https://v3.developer.constantcontact.com/
- MCP Protocol: https://modelcontextprotocol.io/

---

**Part of MCP Engine** - https://github.com/BusyBee3333/mcpengine
