inboxassure-mcp-server/README.md

Comprehensive MCP server for InboxAssure email marketing platform with full API coverage including campaigns, replies, and email account management.

# InboxAssure MCP Server

Comprehensive Model Context Protocol (MCP) server for the InboxAssure email marketing platform. This server provides full API coverage with **23 tools** for managing campaigns, replies, and email accounts through AI assistants like Claude and Cursor.

## Features

- **23 comprehensive tools** covering the entire InboxAssure API
- **Campaigns Management**: Create, manage, and analyze email campaigns
- **Replies Management**: Handle incoming emails and compose responses
- **Email Accounts**: Manage sender accounts and configurations
- **Multi-transport support**: STDIO, HTTP, and SSE protocols
- **Client compatibility**: Works with Claude Desktop, Cursor, and other MCP clients
- **Secure API key handling**: Client-provided keys, no server-side storage

## Prerequisites

- Node.js (version 18.x or later)
- npm (usually comes with Node.js)
- InboxAssure API key (starting with `iak_`)

## Installation

1. Clone this repository:
   ```bash
   git clone https://github.com/your-org/inboxassure-mcp-server
   cd inboxassure-mcp-server
   ```

2. Install dependencies:
    ```bash
    npm install
    ```

## Usage

### STDIO Mode (Recommended for AI Assistants)

```bash
# Using npm script
npm run start:stdio -- --api-key YOUR_INBOXASSURE_API_KEY

# Or directly using node
node src/cli.js --stdio --api-key YOUR_INBOXASSURE_API_KEY
```

### HTTP Server Mode

```bash
# Default port 3000
npm start -- --api-key YOUR_INBOXASSURE_API_KEY

# Custom port
npm start -- --api-key YOUR_INBOXASSURE_API_KEY --port 3001
```

The HTTP server provides:
- MCP Endpoint: `http://localhost:PORT/mcp` (POST requests)
- Health Check: `http://localhost:PORT/health` (GET requests)

## Available Tools

### Original Tools
- **`get_bison_hello`** - Test endpoint to verify API connectivity

### 📧 Campaigns API (11 tools)

1. **`list_campaigns`** - List all campaigns with filtering and pagination
   - Parameters: `workspace_id`, optional `params` (search, status, page, per_page)

2. **`create_campaign`** - Create a new email marketing campaign
   - Parameters: `workspace_id`, `name`, optional `type`

3. **`get_campaign_details`** - Get detailed campaign information
   - Parameters: `workspace_id`, `campaign_id`

4. **`pause_campaign`** - Temporarily pause a running campaign
   - Parameters: `workspace_id`, `campaign_id`

5. **`resume_campaign`** - Resume a paused campaign
   - Parameters: `workspace_id`, `campaign_id`

6. **`get_campaign_stats`** - Get performance metrics for date range
   - Parameters: `workspace_id`, `campaign_id`, `start_date`, `end_date`

7. **`get_campaign_leads`** - View leads in campaign with status
   - Parameters: `workspace_id`, `campaign_id`, optional `params`

8. **`create_campaign_schedule`** - Set up campaign sending schedule (days, times, timezone)
   - Parameters: `workspace_id`, `campaign_id`, `start_time`, `end_time`, `timezone`, day booleans

9. **`get_schedule_templates`** - Get predefined schedule templates for quick setup
   - Parameters: `workspace_id`

10. **`create_sequence_steps`** - Define email sequence steps for drip campaigns
    - Parameters: `workspace_id`, `campaign_id`, `title`, `sequence_steps` array

11. **`attach_lead_list`** - Import entire lead lists into campaigns
    - Parameters: `workspace_id`, `campaign_id`, `lead_list_id`

### 💬 Replies API (5 tools)

12. **`list_replies`** - Retrieve email replies with filtering
    - Parameters: `workspace_id`, optional `params` (search, status, folder, etc.)

13. **`get_reply_details`** - Get complete reply details and content
    - Parameters: `workspace_id`, `reply_id`

14. **`compose_new_email`** - Send standalone emails outside campaigns
    - Parameters: `workspace_id`, `sender_email_id`, `to_emails`, `message`, optional `content_type`, `cc_emails`, `bcc_emails`

15. **`reply_to_email`** - Respond to emails maintaining thread
    - Parameters: `workspace_id`, `reply_id`, `sender_email_id`, `to_emails`, `message`, optional `content_type`

16. **`get_conversation_thread`** - Get complete conversation history
    - Parameters: `workspace_id`, `reply_id`

### 👤 Email Accounts API (6 tools)

17. **`list_email_accounts`** - List configured email accounts
    - Parameters: `workspace_id`, optional `params` (search, page, per_page)

18. **`get_email_account_details`** - Get account configuration and stats
    - Parameters: `workspace_id`, `email_id`

19. **`update_email_account`** - Modify account settings
    - Parameters: `workspace_id`, `email_id`, optional `daily_limit`, `name`, `email_signature`

20. **`get_account_campaigns`** - See which campaigns use this email account
    - Parameters: `workspace_id`, `email_id`

21. **`get_account_replies`** - View replies received by this email account
    - Parameters: `workspace_id`, `email_id`

22. **`bulk_update_email_signatures`** - Update signatures across multiple accounts
    - Parameters: `workspace_id`, `sender_email_ids` array, `email_signature`

**Total: 23 tools** (1 original + 11 campaigns + 5 replies + 6 email accounts)

## Client Configuration

### For Claude Desktop

Add to your Claude MCP configuration:

```json
{
  "mcpServers": {
    "InboxAssure": {
      "command": "node",
      "args": [
        "/path/to/inboxassure-mcp-server/src/cli.js",
        "--api-key=YOUR_INBOXASSURE_API_KEY",
        "--stdio"
      ]
    }
  }
}
```

### For Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "InboxAssure Email Marketing": {
      "command": "node",
      "args": [
        "/full/path/to/src/cli.js",
        "--api-key=YOUR_INBOXASSURE_API_KEY",
        "--stdio"
      ]
    }
  }
}
```

### Global NPM Installation (Coming Soon)

Once published to NPM:

```json
{
  "mcpServers": {
    "InboxAssure": {
      "command": "npx",
      "args": [
        "-y",
        "inboxassure-mcp-server",
        "--api-key=YOUR_INBOXASSURE_API_KEY",
        "--stdio"
      ]
    }
  }
}
```

## API Key Management

This server follows security best practices:

- **Client-provided**: API keys are provided via `--api-key` argument
- **No server storage**: Keys are never stored on the server
- **Header extraction**: Supports multiple header formats for compatibility
- **Per-request authentication**: Each API call uses the client's key

## Development

### Development Scripts

```bash
# Start with placeholder API key (update in package.json)
npm run dev
npm run dev:stdio

# Linting (placeholder)
npm run lint
```

### Testing Locally

1. Start the server:
   ```bash
   node src/cli.js --api-key=YOUR_KEY --stdio
   ```

2. Send test JSON-RPC messages:
   ```json
   {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}
   ```

## Deployment

### Production Deployment (PM2)

The project includes PM2 ecosystem configuration:

```bash
# Deploy to production server
ssh -i ~/.ssh/mcpx root@167.99.230.52 "cd /root/mcpx && git pull && pm2 restart all"
```

### Docker Deployment

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY src/ ./src/
EXPOSE 3000
CMD ["node", "src/cli.js"]
```

## API Documentation

The server integrates with the complete InboxAssure API:

- **Base URL**: `https://bison.imnodev.com/api/`
- **Authentication**: `X-API-Key` header with InboxAssure API key
- **Endpoints**: Campaigns, Replies, Email Accounts APIs

### Common Parameters

- **workspace_id**: Your InboxAssure workspace identifier
- **Pagination**: `page` (default: 1), `per_page` (default: 15, max: 100)
- **Filtering**: `search`, `status`, `folder` parameters
- **Date Format**: ISO 8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`)

## Troubleshooting

### Common Issues

1. **"API key is required"**: Ensure `--api-key` is provided in client configuration
2. **Connection errors**: Verify API key format starts with `iak_`
3. **Tools not appearing**: Check client MCP configuration and restart client
4. **Permission errors**: Verify API key has appropriate workspace permissions

### Debug Logging

The server provides extensive debug logging:

```bash
# Check server logs
tail -f /var/log/your-app/mcp-server.log

# Enable verbose debugging
DEBUG=* node src/cli.js --api-key=YOUR_KEY
```

### Client Logs

- **Windows**: `%APPDATA%\Claude\logs\mcp*.log`
- **macOS**: `~/Library/Logs/Claude/mcp*.log`

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Create an issue on GitHub
- Check the InboxAssure API documentation
- Review the MCP specification