npm package: @signup-storm/mcp-server
Description: MCP server for Signup Storm email management system - provides AI assistants with email signup management capabilities
Author: Signup Storm
Latest version: 2.1.0

# Signup Storm MCP Server

A Model Context Protocol (MCP) server for Signup Storm email management system. This MCP server is built on top of the official Signup Storm SDK, providing AI assistants with powerful email signup management capabilities.

## Features

### Core SDK Features
- **Email Signup Management** - Subscribe emails with full attribution tracking
- **Unsubscribe Management** - Handle unsubscribes from specific lists or globally
- **Subscriber Status** - Check subscription status and history
- **UTM Attribution** - Automatic UTM parameter capture and tracking
- **Custom Fields** - Store additional subscriber data
- **GDPR Compliance** - Handle consent tracking and timestamps

### MCP-Specific Analytics
- **Signup Statistics** - Get analytics for date ranges, sites, or lists
- **Contact Management** - List, search, and filter contacts
- **List Management** - Create and manage email lists
- **Data Export** - Export contacts, events, and subscriptions in JSON/CSV
- **Bulk Operations** - Manage subscriptions at scale

### Documentation & Integration Help
- **Framework Integration Docs** - Get comprehensive integration examples
- **SDK Usage Examples** - Framework-specific code samples
- **Setup Guides** - Environment configuration and best practices

## Installation

### Global Installation
```bash
npm install -g @signup-storm/mcp-server
```

### Local Development
```bash
git clone <repository>
cd packages/mcp-client
pnpm install
pnpm build
```

## Configuration

Set the following environment variables:

```bash
# Required: Your Signup Samurai API key
export SIGNUP_SAMURAI_API_KEY="your-api-key-here"

# Optional: Base URL (defaults to http://localhost:3000)
export SIGNUP_SAMURAI_BASE_URL="https://your-signup-samurai-instance.com"

# Optional: Enable debug mode
export NODE_ENV="development"
```

## Usage with Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "signup-samurai": {
      "command": "signup-samurai-mcp",
      "env": {
        "SIGNUP_SAMURAI_API_KEY": "your-api-key-here",
        "SIGNUP_SAMURAI_BASE_URL": "https://your-instance.com"
      }
    }
  }
}
```

## Available Tools

### Core Signup Management

#### `signup`
Subscribe an email address to a list with full attribution tracking.

```typescript
{
  email: "user@example.com",
  list: "newsletter",
  tags: ["landing-page", "early-access"],
  utm: {
    source: "twitter",
    medium: "social",
    campaign: "product-launch"
  },
  customFields: {
    firstName: "John",
    company: "Acme Corp"
  },
  pageUrl: "https://example.com/signup",
  gdprConsent: true
}
```

#### `unsubscribe`
Unsubscribe an email from a specific list or globally.

```typescript
{
  email: "user@example.com",
  list: "newsletter", // Optional - omit for global unsubscribe
  reason: "No longer interested"
}
```

#### `get_subscriber_status`
Check the subscription status of an email address.

```typescript
{
  email: "user@example.com"
}
```

### Analytics & Management

#### `signup_stats`
Get signup statistics and analytics.

```typescript
{
  dateFrom: "2025-01-01",
  dateTo: "2025-01-31",
  listSlug: "newsletter",
  siteId: "main-site"
}
```

#### `list_contacts`
List and search contacts with filtering.

```typescript
{
  page: 1,
  limit: 50,
  search: "john@",
  status: "SUBSCRIBED",
  listSlug: "newsletter",
  tags: ["vip", "early-access"]
}
```

#### `get_lists`
Get all email lists, optionally filtered by site.

```typescript
{
  siteId: "main-site" // Optional
}
```

#### `create_list`
Create a new email list.

```typescript
{
  name: "Product Updates",
  slug: "product-updates",
  description: "Updates about our product releases",
  siteId: "main-site" // Optional
}
```

#### `manage_subscription`
Subscribe or unsubscribe a contact (alternative to direct signup/unsubscribe).

```typescript
{
  email: "user@example.com",
  listSlug: "newsletter",
  action: "subscribe", // or "unsubscribe"
  tags: ["manual-add"]
}
```

#### `export_data`
Export contacts, events, or subscriptions data.

```typescript
{
  type: "contacts", // or "events", "subscriptions"
  format: "json", // or "csv"
  listSlug: "newsletter",
  dateFrom: "2025-01-01",
  dateTo: "2025-01-31",
  limit: 1000
}
```

## Example AI Conversations

### Subscribe a User
> "Subscribe john@example.com to the newsletter list with tags 'vip' and 'early-access'"

The AI will use the `signup` tool to add the subscriber with proper attribution.

### Check Subscription Status
> "What's the subscription status of sarah@example.com?"

The AI will use `get_subscriber_status` to check the user's current status across all lists.

### Get Analytics
> "Show me signup statistics for the newsletter list in January 2025"

The AI will use `signup_stats` with appropriate date filters.

### Export Data
> "Export all contacts from the newsletter list as CSV"

The AI will use `export_data` to generate a CSV export.

### Documentation & Integration Help

#### `get_integration_docs`
Get framework-specific integration documentation and examples.

```typescript
{
  framework: "nextjs", // "nextjs", "react-router", "astro", "react", "vanilla", "overview"
  section: "all" // "installation", "basic-usage", "advanced", "server-side", "troubleshooting", "all"
}
```

**Example Usage:**
- "Show me Next.js integration examples" → The AI will use `get_integration_docs` with `framework: "nextjs"`
- "How do I integrate with React Router v7?" → The AI will use `get_integration_docs` with `framework: "react-router"`
- "Give me a vanilla JavaScript example" → The AI will use `get_integration_docs` with `framework: "vanilla"`

## SDK Integration

This MCP server is built on top of the official Signup Samurai SDK (`@signup-samurai/sdk`), which provides:

- **Type Safety** - Full TypeScript support with comprehensive types
- **Error Handling** - Structured error responses with proper error codes
- **Validation** - Input validation using Zod schemas
- **Attribution** - Automatic UTM parameter capture and enrichment
- **Event System** - Event listeners for signup success/error tracking
- **Browser Support** - Works in both Node.js and browser environments

## Development

### Building
```bash
pnpm build
```

### Running in Development
```bash
pnpm dev
```

### Testing
```bash
# Test with a simple MCP client
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/server.js
```

## Architecture

```
MCP Client
├── SignupSamuraiMCPAPI (extends SignupSamurai SDK)
│   ├── Core SDK methods (signup, unsubscribe, getSubscriberStatus)
│   └── MCP-specific methods (getStats, getContacts, exportData)
├── Tool Handlers
│   ├── Input validation (Zod schemas)
│   ├── API calls via SDK
│   └── Response formatting
└── MCP Server
    ├── Tool registration
    ├── Request handling
    └── Error management
```

## Error Handling

The MCP server provides structured error responses:

```json
{
  "content": [
    {
      "type": "text",
      "text": "Error: VALIDATION_ERROR - Email is required"
    }
  ],
  "isError": true
}
```

Common error codes:
- `VALIDATION_ERROR` - Invalid input parameters
- `NETWORK_ERROR` - Connection or timeout issues
- `HTTP_ERROR` - API server errors
- `ALREADY_SUBSCRIBED` - Email already subscribed to list

## Version History

### v2.0.0
- **SDK Integration** - Now built on official Signup Samurai SDK
- **Enhanced Tools** - Added `signup`, `unsubscribe`, and `get_subscriber_status`
- **Better Error Handling** - Structured errors with proper codes
- **Type Safety** - Full TypeScript support throughout
- **Attribution Tracking** - Automatic UTM capture and enrichment

### v1.0.0
- Initial MCP server implementation
- Basic analytics and management tools

## License

MIT License - see LICENSE file for details.