npm package: @kelpi/mcp
Description: MCP server for Kelpi customer engagement automation. Enables AI assistants to manage email templates, automation flows, contacts, and events.
Author: Kelpi AI
Latest version: 0.1.0

# @kelpi/mcp

MCP (Model Context Protocol) server for Kelpi customer engagement automation. This package enables AI assistants like Claude to interact with the Kelpi API for managing email templates, automation flows, contacts, and events.

## What is Kelpi MCP Server?

The Kelpi MCP Server provides a standardized interface for AI assistants to:

- Authenticate with your Kelpi workspace
- Create and manage email templates
- Build and activate automation flows
- Create contacts and track events
- Generate SDK integration snippets

## Installation

### Using npx (Recommended)

No installation required. Configure Claude Desktop to use npx:

```json
{
  "mcpServers": {
    "kelpi": {
      "command": "npx",
      "args": ["@kelpi/mcp"]
    }
  }
}
```

### Global Installation

```bash
npm install -g @kelpi/mcp
```

Then configure Claude Desktop:

```json
{
  "mcpServers": {
    "kelpi": {
      "command": "kelpi-mcp"
    }
  }
}
```

## Claude Desktop Configuration

1. Open Claude Desktop settings
2. Navigate to the MCP Servers section
3. Add the following configuration to your `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "kelpi": {
      "command": "npx",
      "args": ["@kelpi/mcp"]
    }
  }
}
```

4. Restart Claude Desktop
5. The Kelpi tools will now be available in your conversations

## Available Tools

### Authentication

#### `kelpi_login`
Authenticate with your Kelpi workspace using device code flow.

**Usage:** Just ask Claude to "log in to Kelpi" or "authenticate with Kelpi"

#### `kelpi_status`
Check current authentication status and workspace information.

**Returns:**
- `authenticated`: Whether you're logged in
- `workspace_id`: Your workspace ID
- `workspace_name`: Your workspace name
- `key_type`: API key type (public/secret)

### Templates

#### `kelpi_create_template`
Create a new email template.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `slug` | string | Yes | URL-friendly identifier (lowercase, hyphens) |
| `name` | string | Yes | Display name for the template |
| `subject` | string | Yes | Email subject line |
| `body_html` | string | Yes | HTML content of the email |
| `variables` | array | No | Template variables with defaults |

**Example:**
```
Create an email template called "welcome-email" with subject "Welcome to Our Service!" and body with a greeting for {{name}}
```

#### `kelpi_list_templates`
List all templates in your workspace.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | number | No | Maximum templates to return (1-100) |
| `offset` | number | No | Number of templates to skip |

### Flows

#### `kelpi_create_flow`
Create a new automation flow.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `definition` | object | Yes | Flow definition object |
| `definition.name` | string | Yes | Flow name |
| `definition.trigger_type` | string | Yes | "event", "segment", or "manual" |
| `definition.trigger_event` | string | Conditional | Required if trigger_type is "event" |
| `definition.steps` | array | No | Flow steps (delays, emails, conditions) |

**Example:**
```
Create a welcome flow that triggers on user.signup event and sends a welcome email after 1 hour
```

#### `kelpi_list_flows`
List all flows in your workspace.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `status` | string | No | Filter by status: "draft", "active", "archived" |
| `limit` | number | No | Maximum flows to return (1-100) |
| `offset` | number | No | Number of flows to skip |

#### `kelpi_activate_flow`
Activate an inactive flow.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `flow_id` | string | Yes | UUID of the flow to activate |

### Contacts

#### `kelpi_create_contact`
Create a new contact.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | Contact's email address |
| `name` | string | No | Contact's name |
| `properties` | object | No | Custom properties |

### Events

#### `kelpi_track_event`
Track a custom event for a contact.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | Yes | Contact's email address |
| `event_name` | string | Yes | Name of the event |
| `properties` | object | No | Event properties |

**Example:**
```
Track a "purchase_completed" event for user@example.com with product_id "prod_123"
```

### SDK Integration

#### `kelpi_get_public_key`
Get or create a public API key for client-side SDK usage.

**Returns:** API key object with the public key for SDK initialization

#### `kelpi_get_sdk_snippet`
Generate SDK integration code for your application.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `framework` | string | Yes | "react", "nextjs", "vanilla", "node", or "express" |

**Example:**
```
Generate a React SDK snippet for Kelpi integration
```

## Example Workflows

### Onboarding Flow Setup

```
1. "Log in to Kelpi"
2. "Create a welcome email template with subject 'Welcome!' and personalized greeting"
3. "Create a flow that triggers on user.signup and sends the welcome email after 30 minutes"
4. "Activate the welcome flow"
```

### SDK Integration

```
1. "Get my Kelpi public key"
2. "Generate a React SDK snippet"
3. "Create a test contact with email test@example.com"
4. "Track a signup event for test@example.com"
```

## Error Handling

The Kelpi MCP Server provides user-friendly error messages with actionable hints:

| Error | Hint |
|-------|------|
| "Authentication required" | Run kelpi_login first to authenticate |
| "API key is invalid or expired" | Run kelpi_login to get a new API key |
| "Resource not found" | Check that the ID is correct |
| "Resource already exists" | Use a different identifier or update the existing resource |
| "Validation error" | Fix the validation errors and try again |

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/kelpi-ai/kelpi.git
cd kelpi/packages/mcp

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test
```

### Testing

```bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage
```

### Project Structure

```
packages/mcp/
  src/
    lib/
      api-client.ts      # HTTP client with retry logic
      config.ts          # Configuration management
      errors.ts          # Custom error classes
      error-formatter.ts # User-friendly error formatting
      tool-registry.ts   # MCP tool registration
    tools/
      auth/              # Login and status tools
      flows/             # Flow management tools
      templates/         # Template management tools
      contacts/          # Contact management tools
      events/            # Event tracking tools
      sdk/               # SDK integration tools
    server.ts            # MCP server implementation
    index.ts             # Package entry point
  __tests__/
    unit/                # Unit tests
    integration/         # Integration tests
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests first (TDD)
4. Implement your feature
5. Ensure all tests pass
6. Submit a pull request

## License

MIT

## Support

- [Documentation](https://docs.kelpi.io)
- [GitHub Issues](https://github.com/kelpi-ai/kelpi/issues)
- [Discord Community](https://discord.gg/kelpi)