MoyKlass Server

MCP (Model Context Protocol) сервер для МойКласс CRM. Позволяет AI-агентам (Claude Desktop, Claude Code, ChatGPT и другим MCP-клиентам) читать данные CRM на естественном языке.

Итерация 1: только чтение (GET-эндпоинты).

Стек: TypeScript · MCP SDK 1.27+ · AWS Lambda (Node.js 24) · API Gateway V2 · SAM

---

Инструменты (16 tools)

Инструмент	Эндпоинт	Описание
list_joins	GET /v1/company/joins	Список записей учеников в группы с фильтрацией
get_join	GET /v1/company/joins/{id}	Детали записи в группу
list_users	GET /v1/company/users	Поиск учеников по имени, телефону, email, тегам
get_user	GET /v1/company/users/{id}	Полная информация об ученике
list_user_tags	GET /v1/company/userTags	Список тегов учеников
list_tasks	GET /v1/company/tasks	Список задач с фильтрацией
get_task	GET /v1/company/tasks/{id}	Детали задачи
list_courses	GET /v1/company/courses	Список программ обучения
list_classes	GET /v1/company/classes	Список учебных групп
get_class	GET /v1/company/classes/{id}	Детали группы
list_lessons	GET /v1/company/lessons	Расписание занятий с фильтрацией
get_lesson	GET /v1/company/lessons/{id}	Детали занятия
list_lesson_records	GET /v1/company/lessonRecords	Журнал посещаемости
get_lesson_record	GET /v1/company/lessonRecords/{id}	Детали записи на занятие
list_user_subscriptions	GET /v1/company/userSubscriptions	Абонементы учеников
get_user_subscription	GET /v1/company/userSubscriptions/{id}	Детали абонемента

---

Установка и локальная разработка

1. Клонирование и зависимости

git clone <repo-url>
cd MoyKlass
npm install

2. Переменная окружения

Создайте .env или экспортируйте переменную:

export MOYKLASS_API_KEY=ваш_api_ключ
# Опционально, по умолчанию https://api.moyklass.com
export CRM_API_URL=https://api.moyklass.com

API-ключ находится в настройках компании в МойКласс → Интеграции → API.

3. Запуск в stdio-режиме

MOYKLASS_API_KEY=ваш_ключ npm run dev

При старте сервер автоматически получает accessToken через POST /v1/company/auth/getToken и кэширует его. При получении ошибки 401 токен обновляется автоматически.

4. Тестирование через MCP Inspector

npm run build          # tsc → build/
npx @modelcontextprotocol/inspector build/index.js

Откроется браузерный инспектор на http://localhost:5173 для ручного вызова инструментов.

---

Подключение к Claude Desktop

Локально (stdio)

npm run build   # собрать один раз

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "moyklass": {
      "command": "node",
      "args": ["/абсолютный/путь/к/MoyKlass/build/index.js"],
      "env": {
        "MOYKLASS_API_KEY": "ваш_api_ключ"
      }
    }
  }
}

Перезапустите Claude Desktop. В интерфейсе появится значок инструментов.

Remote (Lambda)

{
  "mcpServers": {
    "moyklass": {
      "transport": "http",
      "url": "https://xxx.execute-api.eu-central-1.amazonaws.com/prod/mcp"
    }
  }
}

---

Деплой на AWS Lambda

1. Предварительные требования

# AWS CLI + SAM CLI
brew install awscli aws-sam-cli

# Аутентификация AWS
aws configure

2. Сборка

npm run build:lambda   # → dist/lambda.js (~780 KB)

3. Деплой

sam deploy --guided

SAM запросит параметры при первом деплое:

Параметр	Описание
MoyKlassApiKey	API-ключ МойКласс
CrmApiUrl	Base URL (по умолчанию https://api.moyklass.com)

После деплоя SAM выведет McpUrl — URL для подключения MCP-клиентов.

4. Повторный деплой

npm run build:lambda
sam deploy   # использует сохранённую конфигурацию

---

Архитектура

AI-клиент (Claude Desktop / ChatGPT)
  │
  │  POST /mcp  (MCP JSON-RPC)
  ▼
API Gateway HTTP API
  │
  ▼
Lambda (Node.js 24)
  ├── apiGatewayEventToRequest()       — адаптер Lambda ↔ Web Request
  ├── WebStandardStreamableHTTPServerTransport
  │     sessionIdGenerator: undefined  — stateless (нет хранилища сессий)
  │     enableJsonResponse: true       — JSON вместо SSE (для API Gateway)
  ├── McpServer  →  tool handler
  │     └── apiRequest()
  │           ├── getAccessToken()     — кэш токена в памяти Lambda container
  │           │     POST /v1/company/auth/getToken  (при промахе кэша)
  │           └── fetch()  →  МойКласс CRM API
  └── cleanup: transport.close() + server.close()

Аутентификация

При старте Lambda-контейнера (cold start) или при истечении токена:

1. Сервер вызывает POST /v1/company/auth/getToken с MOYKLASS_API_KEY
2. Полученный accessToken кэшируется в памяти модуля (работает между warm invocations)
3. Токен подставляется в заголовок x-access-token всех запросов
4. При ответе 401 Unauthorized — токен инвалидируется и немедленно обновляется

Stateless Streamable HTTP

Каждый Lambda-вызов полностью независим: создаёт свой McpServer и транспорт, обрабатывает запрос и уничтожается. Нет shared state, нет сессий, автоматическое горизонтальное масштабирование.

---

Сборка

npm run build          # tsc → build/  (для stdio)
npm run build:lambda   # esbuild → dist/lambda.js  (для Lambda)
npm run typecheck      # проверка типов без компиляции
npm run dev            # tsx watch src/index.ts  (hot reload)

---

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

Переменная	Обязательная	По умолчанию	Описание
MOYKLASS_API_KEY	Да	—	API-ключ компании МойКласс
CRM_API_URL	Нет	https://api.moyklass.com	Base URL CRM API

---

Добавление нового инструмента

1. Найти GET-эндпоинт в docs/openapi.json
2. Добавить метод в src/client/moyKlassClient.ts (если нужна специфичная обработка) или вызывать apiRequest напрямую
3. Зарегистрировать инструмент в src/server.ts через server.tool(name, description, zodSchema, handler)
4. Запустить npm run typecheck