# Roistat MCP Server

MCP (Model Context Protocol) сервер для интеграции с платформой маркетинговой аналитики **Roistat**. Позволяет AI-агентам (Claude, GPT и др.) напрямую работать с данными Roistat: анализировать статистику, управлять лидами, отслеживать звонки и каналы.

---

## Возможности

### 📊 Аналитика
| Инструмент | Описание |
|---|---|
| `roistat_get_statistics` | Маркетинговая статистика: визиты, лиды, ROI, CPL по каналам/кампаниям |
| `roistat_get_report` | Гибкий отчёт с группировкой по дням/неделям/месяцам |

### 🎯 Лиды и заявки
| Инструмент | Описание |
|---|---|
| `roistat_list_leads` | Список лидов с фильтрацией по дате, статусу |
| `roistat_get_lead` | Детальная информация о конкретном лиде |
| `roistat_update_lead` | Обновление статуса, выручки, полей лида |
| `roistat_create_lead` | Создание нового лида (оффлайн-конверсии) |

### 📞 Коллтрекинг
| Инструмент | Описание |
|---|---|
| `roistat_list_calls` | История звонков с фильтрацией |
| `roistat_get_call` | Детали звонка: источник, запись, длительность |
| `roistat_list_phones` | Список подменных номеров |

### 📡 Рекламные каналы
| Инструмент | Описание |
|---|---|
| `roistat_list_channels` | Все маркетинговые каналы проекта |
| `roistat_get_channel_costs` | Расходы по каналам за период |
| `roistat_set_channel_costs` | Ручная загрузка расходов (оффлайн-каналы) |

### ⚙️ Проект
| Инструмент | Описание |
|---|---|
| `roistat_get_project_info` | Информация о проекте, настройки, интеграции |
| `roistat_list_events` | Конверсионные события |
| `roistat_send_event` | Ручная отправка события конверсии |
| `roistat_get_billing` | Тариф, баланс, статистика использования |
| `roistat_get_mediaplan` | Медиаплан: план vs факт по каналам |

---

## Установка

### Требования
- Node.js 18+
- npm или yarn
- Аккаунт Roistat с API-доступом

### Шаги

```bash
git clone <repo-url>
cd roistat-mcp-server
npm install
npm run build
```

### Переменные окружения

```bash
# Обязательные
ROISTAT_API_KEY=ваш_api_ключ        # Профиль → API-ключ
ROISTAT_PROJECT_ID=12345            # Номер проекта (из URL или настроек)

# Опциональные
TRANSPORT=stdio                     # или "http" для удалённого сервера
PORT=3000                           # только при TRANSPORT=http
```

**Где найти API ключ:**
Roistat → Настройки → API-ключ → Скопировать

---

## Запуск

### stdio (локально, для Claude Desktop / Claude Code)

```bash
ROISTAT_API_KEY=xxx ROISTAT_PROJECT_ID=12345 node dist/index.js
```

### HTTP (удалённое развёртывание, VPS/Docker)

```bash
TRANSPORT=http PORT=3000 ROISTAT_API_KEY=xxx ROISTAT_PROJECT_ID=12345 node dist/index.js
```

---

## Конфигурация Claude Desktop

Добавьте в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "roistat": {
      "command": "node",
      "args": ["/path/to/roistat-mcp-server/dist/index.js"],
      "env": {
        "ROISTAT_API_KEY": "ваш_api_ключ",
        "ROISTAT_PROJECT_ID": "12345"
      }
    }
  }
}
```

## Конфигурация для HTTP (OpenClaw / удалённый MCP)

```json
{
  "mcpServers": {
    "roistat": {
      "url": "http://your-vps-ip:3000/mcp",
      "type": "streamable-http"
    }
  }
}
```

---

## Docker-деплой (для Hostinger VPS)

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist/ ./dist/
EXPOSE 3000
ENV TRANSPORT=http
CMD ["node", "dist/index.js"]
```

```bash
docker build -t roistat-mcp .
docker run -d -p 3000:3000 \
  -e ROISTAT_API_KEY=xxx \
  -e ROISTAT_PROJECT_ID=12345 \
  roistat-mcp
```

---

## Примеры запросов к Claude

После подключения MCP спрашивайте Claude:

- *"Покажи ROI по каналам за последние 30 дней"*
- *"Сколько лидов пришло из Яндекс.Директ в марте?"*
- *"Найди все непринятые звонки за вчера и создай по ним задачи"*
- *"Загрузи расходы по оффлайн-каналу 500 рублей за сегодня"*
- *"Сравни CPL апреля с мартом по всем каналам"*
- *"Обнови статус лида #12345 на 'Оплачен', выручка 15000 руб"*

---

## Структура проекта

```
roistat-mcp-server/
├── src/
│   ├── index.ts              # Точка входа, инициализация сервера
│   ├── services/
│   │   └── roistat-client.ts # HTTP-клиент для Roistat API
│   └── tools/
│       ├── analytics.ts      # Статистика и отчёты
│       ├── leads.ts          # Лиды и заявки
│       ├── calltracking.ts   # Коллтрекинг
│       ├── channels.ts       # Каналы и расходы
│       └── project.ts        # Проект, события, биллинг
├── dist/                     # Скомпилированные файлы
├── package.json
└── tsconfig.json
```

---

## Лицензия

MIT