# yourept-mcp

MCP-сервер к CRM **YOUREPT**. Подключается к Claude, Cursor, Codex и другим
клиентам MCP и даёт агенту доступ к данным админки — заявкам, ученикам,
преподавателям, урокам, платежам, выплатам и финансовым отчётам.

Вопросы, ради которых он существует:

> «Сколько заработали в этом месяце и сколько ушло на выплаты?»
> «Какие заявки просрочены и у кого из менеджеров?»
> «Покажи учеников, у которых не было уроков две недели»
> «Какие преподаватели не подписали сделку в Рокет Ворк»

То есть то, ради чего в интерфейсе пришлось бы открыть три раздела и свести
цифры руками.

---

## Установка

### 1. Получите ключ

В админке: **Настройки → API-ключи → Создать ключ**. Ключ показывается
**один раз** — скопируйте сразу. Потеряли — выпустите новый, старый отзовите.

Ключ работает от имени того сотрудника, который его выпустил, и с его правами:
разделы, закрытые для человека, закрыты и для агента. Ключ «только для чтения»
(по умолчанию) физически не может ничего изменить в CRM.

### 2. Пропишите сервер в своей программе

Отдельно ставить ничего не нужно — `npx` скачает пакет сам.

> Пакет ставится прямо с GitHub. После публикации в npm вместо
> `github:Skamatoz/yourept-mcp` можно будет писать просто `yourept-mcp`.

**Claude Desktop** — Настройки → Developer → Edit Config:

```json
{
  "mcpServers": {
    "yourept": {
      "command": "npx",
      "args": ["-y", "github:Skamatoz/yourept-mcp"],
      "env": {
        "YOUREPT_API_URL": "https://api-admin.yourept.ru",
        "YOUREPT_API_KEY": "yrp_live_ваш_ключ"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add yourept \
  --env YOUREPT_API_URL=https://api-admin.yourept.ru \
  --env YOUREPT_API_KEY=yrp_live_ваш_ключ \
  -- npx -y github:Skamatoz/yourept-mcp
```

**Cursor** — файл `~/.cursor/mcp.json`, формат тот же, что у Claude Desktop.

**Codex** — файл `~/.codex/config.toml`:

```toml
[mcp_servers.yourept]
command = "npx"
args = ["-y", "github:Skamatoz/yourept-mcp"]

[mcp_servers.yourept.env]
YOUREPT_API_URL = "https://api-admin.yourept.ru"
YOUREPT_API_KEY = "yrp_live_ваш_ключ"
```

После правки конфига программу нужно перезапустить.

---

## Что умеет

| Инструмент | О чём |
|---|---|
| `search` | поиск по всей CRM: люди, заявки, платежи, выплаты |
| `list_leads`, `get_lead` | заявки, в том числе проблемные группы |
| `list_students`, `get_student` | ученики и их контракты |
| `list_teachers`, `get_teacher` | преподаватели, ставки, статус самозанятого |
| `list_lessons` | уроки за период, включая неотмеченные |
| `list_enrollments` | контракты, ставки, остатки на балансе |
| `list_tasks` | задачи сотрудников и проверки контроля качества |
| `list_trial_scores` | ИИ-оценки пробных уроков |
| `list_payments` | приход денег от родителей |
| `list_payouts` | выплаты преподавателям и этапы сделок Рокет Ворк |
| `finance_report` | P&L, движение денег, когорты |
| `dashboard` | сводки: финансы, воронка, удержание, юнит-экономика |
| `alerts` | что требует внимания прямо сейчас |
| `whoami` | от чьего имени работает ключ и какие разделы доступны |

Суммы отдаются в рублях, время — московское.

---

## Если что-то не работает

**«Ключ недействителен»** — ключ отозван, истёк или скопирован с потерей
символов. Проверьте его в админке и при необходимости выпустите новый.

**«Недостаточно прав»** — у сотрудника, на которого выписан ключ, нет доступа
к этому разделу. Спросите у агента `whoami`: он покажет, какие разделы открыты.

**«Ключ выдан только на чтение»** — ожидаемо: ключ по умолчанию ничего не меняет.

**«Админка не ответила»** — проверьте `YOUREPT_API_URL`. Адрес нужен тот, по
которому работает API (обычно начинается с `api-`), а не адрес самого сайта
админки.

**Сервер не появился в списке** — почти всегда незакрытая скобка или лишняя
запятая в конфиге. В админке на экране выпуска ключа есть готовый сниппет
для копирования целиком.

---

## Безопасность

- В базе хранится только хэш ключа — восстановить ключ из неё нельзя.
- Ключ наследует права своего сотрудника и не может их превысить.
- Ключом нельзя управлять ключами: выписать себе новый доступ через API не выйдет.
- Отзыв действует мгновенно.
- Персональные данные, которых нет в интерфейсе (расшифровки пробных уроков),
  через этот сервер недоступны.

При увольнении сотрудника отзывайте его ключи вместе с учётной записью.

---

## Разработка

```bash
pnpm install
pnpm build     # tsc → dist/
```

Проверить сервер, не подключая к клиенту:

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | YOUREPT_API_URL=http://localhost:4001 YOUREPT_API_KEY=ключ node dist/index.js
```

Диагностика идёт в stderr — в stdout только протокол, туда писать нельзя.