MoyKlass MCP 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) или при истечении токена:

Сервер вызывает POST /v1/company/auth/getToken с MOYKLASS_API_KEY
Полученный accessToken кэшируется в памяти модуля (работает между warm invocations)
Токен подставляется в заголовок x-access-token всех запросов
При ответе 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 |

---

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

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

MoyKlass MCP Server