npm package: @rockship/cosmoagents-mcp
Description: A powerful Model Context Protocol (MCP) server implementation for seamless Cosmoagents API integration, enabling AI assistants to interact with Cosmoagents data
Latest version: 1.0.14

# Cosmoagents MCP Server

A powerful Model Context Protocol (MCP) server implementation for seamless Cosmoagents API integration, enabling AI assistants to create and manage email campaigns.

## Overview

This MCP server provides a comprehensive set of tools for interacting with the Cosmoagents API, allowing AI assistants to:

- Create and manage email campaigns directly from your AI assistant interface

## Why Use This MCP Server?

- **Seamless AI Integration**: Connect your AI assistants directly to Cosmoagents data
- **Simplified API Operations**: Perform common Cosmoagents tasks through natural language commands
- **Real-time Data Access**: Get up-to-date information from Cosmoagents
- **Secure Authentication**: Uses Cosmoagents's secure API token authentication
- **Extensible Design**: Easily add more Cosmoagents API capabilities as needed

## Installation

```bash
# Clone the repository
git clone https://gitlab.rockitflow.com/rockship/mcp-servers/cosmoagents-mcp.git
cd cosmoagents-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration

The server requires an Cosmoagents API access token. You can obtain one by:

1. Going to your [Cosmoagents Account](https://cosmoagents.ai/settings/api-keys)
2. Generating an API key

You can provide the token in two ways:

1. As an environment variable:
   ```
   COSMOAGENTS_API_KEY=your-api-key
   ```

2. As a command-line argument:
   ```
   npm start -- --api-key=your-api-key
   ```

For development, create a `.env` file in the project root to store your environment variables:

```
COSMOAGENTS_API_KEY=your-api-key
```

## Usage

### Starting the Server

```bash
# Start the server
npm start

# Or with a specific API key
npm start -- --api-key=your-api-key
```

### Integrating with AI Assistants

This MCP server is designed to work with AI assistants that support the Model Context Protocol. Once running, the server exposes a set of tools that can be used by compatible AI assistants to interact with Cosmoagents data.

### Available Tools

The server exposes the following powerful Cosmoagents integration tools:

1. **create_campaign**
   - Use the create_campaign tool to create a new email campaign for a contact list
   - Parameters:
     - `contacts` (array of objects, required): Array of contacts to include in the campaign. Each contact object should have `first_name` (string), `last_name` (string), `email` (string, required), and `job_title` (string).
     - `playbook` (enum, optional): Campaign playbook type. Defaults to `revive_dormant_leads`. Possible values: `revive_dormant_leads`, `upsell_to_existing_customers`, `event_invite`, `content_offering`, `webinar_follow_up`, `click_start_from_scratch`.
     - `name` (string, optional): Optional custom name for the campaign.
   - Example:
     ```json
     {
       "contacts": [
         {
           "first_name": "John",
           "last_name": "Doe",
           "email": "john.doe@example.com",
           "job_title": "Software Engineer"
         }
       ],
       "playbook": "event_invite",
       "name": "My Event Campaign"
     }
     ```

## Extending the Server

The server is designed to be easily extensible. To add new Cosmoagents API capabilities:

1.  **Add new methods to `CosmoagentsClient`**: If you want to add a new Cosmoagents API capability, you will add a new method to the `CosmoagentsClient` class in `src/common/network/cosmoagents-client.ts`.
2.  **Create a new tool file**: Create a new TypeScript file in `src/common/tools/` (e.g., `new-tool.tool.ts`) to define your new tool. This file will implement the `ToolDefinition` interface and utilize the `CosmoagentsClient` method you added.
3.  **Register the tool in `ToolFactory`**: Add your new tool to the `registerAllTools` method in `src/common/factories/tool.factory.ts`.
4.  **Rebuild the project**: Run `npm run build` to compile your changes.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Keywords

Cosmoagents mcp, Model Context Protocol, MCP, Campaign, AI Tools