# Kayzen Analytics MCP Server

A Model Context Protocol (MCP) server implementation for interacting with Kayzen Analytics API. This package enables AI models to access and analyze Kayzen advertising campaign data through a standardized interface.

## Features

* **Automated Authentication**: Built-in token management with automatic refresh mechanism
* **Report Management**: Easy access to Kayzen analytics reports
* **Error Handling**: Comprehensive error handling for API interactions
* **TypeScript Support**: Full TypeScript implementation with type definitions
* **Environment Based Configuration**: Simple setup using environment variables

## Installation

```bash
npm install @feedmob-ai/kayzen-mcp
```

## Configuration

Create a `.env` file with your Kayzen credentials:

```bash
KAYZEN_USERNAME=your_username
KAYZEN_PASSWORD=your_password
KAYZEN_BASIC_AUTH=your_basic_auth_token
KAYZEN_BASE_URL=https://api.kayzen.io/v1  # Optional, defaults to this value
```

## Usage

### Basic Setup

```typescript
import { KayzenMCPServer } from '@feedmob-ai/kayzen-mcp';

const server = new KayzenMCPServer();
server.start();
```

## Available Tools

### 1. `list_reports`
Lists all available reports from Kayzen Analytics.

* **Inputs**: None
* **Returns**: Array of report objects containing:
  - `id`: Report identifier
  - `name`: Report name
  - `type`: Report type

```typescript
const reports = await server.tools.list_reports();
```

### 2. `get_report_results`
Retrieves results for a specific report.

* **Inputs**:
  - `report_id` (string, required): ID of the report to fetch
  - `start_date` (string, optional): Start date in YYYY-MM-DD format
  - `end_date` (string, optional): End date in YYYY-MM-DD format
* **Returns**: Report data and metadata

```typescript
const results = await server.tools.get_report_results({
  report_id: 'report_id',
  start_date: '2024-01-01',  // optional
  end_date: '2024-01-31'     // optional
});
```

### 3. `analyze_report_results` (Prompt)
Analyzes report results and provides insights.

* **Inputs**:
  - `report_id` (string): ID of the report to analyze
* **Analysis includes**:
  - Performance metrics
  - Key trends
  - Areas for optimization
  - Unusual patterns or anomalies


## Setup

### Usage with Claude Desktop
To use this with Claude Desktop, add the following to your `claude_desktop_config.json`:

### NPX

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@feedmob-ai/kayzen-mcp"
      ],
      "env": {
        "KAYZEN_USERNAME": "username",
        "KAYZEN_PASSWORD": "pasword",
        "KAYZEN_BASIC_AUTH": "auth token"
      }
    }
  }
}
```


## Development

### Prerequisites

- Node.js (v16 or higher)
- npm (v7 or higher)
- Kayzen API credentials

### Scripts

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

# Development mode with hot-reload
npm run dev
```

## Project Structure

```
kayzen-mcp/
├── src/
│   ├── server.ts        # MCP server implementation
│   └── kayzen-client.ts # Kayzen API client
├── dist/               # Compiled JavaScript
└── package.json       # Project configuration
```

## Dependencies

Main dependencies:
- `@modelcontextprotocol/sdk`: ^1.7.0
- `axios`: ^1.8.3
- `dotenv`: ^16.4.7
- `zod`: ^3.24.2

## Error Handling

The server handles various error scenarios:
- Authentication failures
- Invalid API requests
- Network issues
- Token expiration and refresh
- Invalid parameters

## License

MIT License

## Author

FeedMob