npm package: @olbrain/cdp-api-mock-mcp
Description: CDP (Customer Data Platform) API Mock MCP Server with Users and Events CRUD operations
Author: Alchemist
Latest version: 1.0.0

# CDP API MCP Server

A Model Context Protocol (MCP) server for interacting with CDP (Customer Data Platform) APIs. Provides complete CRUD operations for user management and event tracking.

**Status**: ✅ Production Ready | **Default Server**: `http://13.235.73.96:8000` | **Tools**: 9

## Features

### User Management
- **Create User**: Add new users with flexible attributes (ID auto-generated if not provided)
- **Get All Users**: Retrieve paginated list of users
- **Update User**: Modify existing user information
- **Delete User**: Remove users from the CDP

### Event Tracking
- **Create Event**: Track user events with custom properties
- **Get All Events**: Retrieve paginated list of events
- **Get Event by ID**: Fetch specific event details
- **Update Event**: Modify existing event data
- **Delete Event**: Remove events from the CDP

## Quick Start

### For olbrain-studio Users (Easiest)

1. Open any agent → **Tools** → **MCP Servers**
2. Search for **"CDP API"** in public servers
3. Click **"Add to Agent"**
4. Default configuration connects to production CDP server (`http://13.235.73.96:8000`)
5. Start using: *"Show me all users from the CDP"*

### NPM/NPX Installation

```bash
npx -y @olbrain/cdp-api-mock-mcp@latest
```

### Manual Installation
```bash
# Clone the repository
git clone https://github.com/alchemist-ai/alchemist-public-tools.git
cd alchemist-public-tools/mcp_servers/cdp-api-mock

# Install Node.js dependencies
npm install

# Install Python dependencies
pip3 install -r requirements.txt
```

## Configuration

### Default Production Server

The MCP server is pre-configured to connect to the production CDP server:
- **URL**: `http://13.235.73.96:8000`
- **Authentication**: None required
- **Status**: ✅ Online and verified

No configuration needed for default use!

### Custom Server Configuration

If you want to use your own CDP server:

#### Required Environment Variables

- `CDP_API_BASE_URL`: Base URL of your CDP API server
  - Default: `http://13.235.73.96:8000`
  - Example: `http://your-cdp-server.com:8000`

#### Optional Environment Variables

- `API_AUTH_TOKEN`: Bearer token for API authentication (if required)

### Configuration in olbrain-studio

When adding this MCP server to olbrain-studio:

1. Navigate to Tools → MCP Servers
2. Add new MCP server
3. Upload `server_config.json` or manually configure:
   - **CDP API Base URL**: Your CDP API endpoint
   - **API Authentication Token**: (Optional) If your API requires auth

## Available Tools

### User Tools

#### 1. `cdp_create_user`
Create a new user in the CDP.

**Parameters:**
- `ID` (optional): User ID (auto-generated if not provided)
- `full_name` (optional): User's full name
- `msisdn` (optional): Phone number in MSISDN format (e.g., +919876543210)
- `email_id` (optional): User's email address
- `date_of_birth` (optional): Date of birth (YYYY-MM-DD format)
- `gender` (optional): User's gender
- `client_id` (optional): Client ID

**Example:**
```json
{
  "ID": "user123456789",
  "full_name": "John Doe",
  "msisdn": "+919876543210",
  "email_id": "john.doe@example.com",
  "date_of_birth": "1990-05-15",
  "gender": "Male",
  "client_id": "CLT001"
}
```

#### 2. `cdp_get_all_users`
Get paginated list of all users.

**Parameters:**
- `page` (optional, default: 0): Page number (0-indexed)
- `size` (optional, default: 10): Number of items per page

#### 3. `cdp_update_user`
Update an existing user.

**Parameters:**
- `ID` (required): User ID
- `full_name` (optional): Updated full name
- `email_id` (optional): Updated email
- Other user fields as needed

**Example:**
```json
{
  "ID": "user123456789",
  "full_name": "John Updated Doe",
  "email_id": "john.updated@example.com"
}
```

#### 4. `cdp_delete_user`
Delete a user by ID.

**Parameters:**
- `user_id` (required): User ID to delete

### Event Tools

#### 5. `cdp_create_event`
Create a new event.

**Parameters:**
- `type` (optional, default: "track"): Event type (must be "track")
- `event` (required): Event name/identifier
- `userId` (required): User ID associated with the event
- `properties` (optional): Event properties (only `data` field supported)
- `timestamp` (optional): ISO 8601 timestamp

**Example:**
```json
{
  "type": "track",
  "event": "purchase_completed",
  "userId": "user123456789",
  "properties": {
    "data": "Order ID: 12345, Amount: $99.99"
  },
  "timestamp": "2024-01-17T10:00:00Z"
}
```

#### 6. `cdp_get_all_events`
Get paginated list of all events.

**Parameters:**
- `page` (optional, default: 0): Page number (0-indexed)
- `size` (optional, default: 10): Number of items per page

#### 7. `cdp_get_event_by_id`
Get a specific event by ID.

**Parameters:**
- `event_id` (required): Event ID to retrieve

#### 8. `cdp_update_event`
Update an existing event.

**Parameters:**
- `event_id` (required): Event ID to update
- `type` (optional): Event type
- `event` (optional): Event name
- `userId` (optional): User ID
- `properties` (optional): Event properties
- `timestamp` (optional): Timestamp

#### 9. `cdp_delete_event`
Delete an event by ID.

**Parameters:**
- `event_id` (required): Event ID to delete

## API Format

This MCP server uses **snake_case** format for field names, consistent with standard REST API conventions:

- `full_name` (not `fullName`)
- `email_id` (not `emailId`)
- `date_of_birth` (not `dateOfBirth`)
- `client_id` (not `clientId`)

## Testing

To test the CDP API Mock MCP server:

1. Ensure your CDP API Mock is running:
   ```bash
   # Your CDP API should be accessible at the configured base URL
   curl http://localhost:8765/enterprise/cdp-user-api/users
   ```

2. Test the MCP server:
   ```bash
   # Set environment variables
   export CDP_API_BASE_URL=http://localhost:8765

   # Run the server
   node index.js
   ```

3. Send MCP protocol messages via stdin:
   ```json
   {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
   {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
   ```

## Development

### Project Structure
```
cdp-api-mock/
├── index.js              # Node.js entry point
├── package.json          # NPM package configuration
├── requirements.txt      # Python dependencies
├── server_config.json    # MCP server configuration
├── README.md            # This file
└── src/
    ├── server.py        # Main MCP server implementation
    ├── cdp_client.py    # CDP API client
    └── tools/
        ├── user_tools.py   # User management tools
        └── event_tools.py  # Event tracking tools
```

### Adding New Tools

1. Define tool in appropriate file (`user_tools.py` or `event_tools.py`)
2. Create async handler function
3. Add handler to `TOOL_HANDLERS` dict
4. Add tool definition to `TOOLS` list

## Requirements

- **Node.js**: >= 16.0.0
- **Python**: >= 3.7
- **Python Package**: requests >= 2.31.0

## Troubleshooting

### Server won't start
- Verify `CDP_API_BASE_URL` environment variable is set
- Check that Python 3 is installed and accessible
- Ensure `requirements.txt` dependencies are installed

### API requests failing
- Verify CDP API is running and accessible
- Check base URL format (should include protocol: http:// or https://)
- If using authentication, verify `API_AUTH_TOKEN` is correct

### Tool execution errors
- Check MCP server logs (written to stderr)
- Verify API endpoint paths match your CDP API implementation
- Ensure request data format matches expected schema (snake_case)

## Production Deployment

This MCP server is connected to a live production CDP server with real data:
- **8+ users** already in system
- **5+ events** tracked
- **Real-time updates** supported
- **No authentication** required for default server

See [DEPLOYMENT.md](./DEPLOYMENT.md) for complete deployment guide.

## Testing

The server has been tested with:
- ✅ User creation (both camelCase and snake_case formats)
- ✅ User retrieval with pagination
- ✅ User updates and deletions
- ✅ Event creation and tracking
- ✅ Event retrieval and management
- ✅ Real production CDP server integration

## Documentation

- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - Complete deployment guide
- **[README.md](./README.md)** - This file
- **[server_config.json](./server_config.json)** - MCP server configuration

## License

MIT

## Author

Alchemist

## Repository

https://github.com/alchemist-ai/alchemist-public-tools

## Support

For issues and feature requests, please visit the GitHub repository.