MCP Сервер cenaly.ru — Справочник для AI / GPT интеграции

Этот документ предназначен для AI-ассистентов, GPT-ботов и автоматических интеграций. Содержит точные детали протокола, схемы инструментов и поток аутентификации.

Информация о сервере#

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

Все вызовы инструментов требуют заголовок Authorization.

Вариант 1: Пользовательский MCP API-ключ (рекомендуется)#

Authorization: Bearer XXXXXXXXXXXX...  (64 hex-символа, без префикса)

Привязан к конкретному пользователю. Бот видит только данные этого пользователя.

Значение вида mk_…, которое видно в списке ключей админ-панели, — это идентификатор ключа (используется в DELETE /api/keys/{keyId}), а не сам ключ.

Вариант 2: Cognito JWT-токен#

Authorization: Bearer eyJraWQi...  (JWT id_token)

Получается через POST /auth/login. Истекает через 1 час.

Вариант 3: Admin API Key#

Authorization: Bearer <admin_api_key>

Полный доступ ко всем данным. Только для администраторов.

Получение JWT-токена#

POST https://api.cenaly.ru/mcp/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Ответ:

{
  "idToken": "eyJraWQi...",
  "accessToken": "eyJraWQi...",
  "refreshToken": "eyJjdHki...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Протокол MCP#

Инициализация#

POST https://api.cenaly.ru/mcp
Authorization: Bearer <token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-bot", "version": "1.0" }
  }
}

Список инструментов#

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

Вызов инструмента#

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "имя_инструмента",
    "arguments": { ... }
  }
}

Ответ (успех): result.content[0].text — JSON-строка с данными.
Ответ (ошибка): result.isError: true, result.content[0].text — текст ошибки.

Эндпоинты#

Маршрут /api/keys авторизуется от имени пользователя: подойдёт и Cognito JWT, и собственный 64-символьный MCP-ключ. Не подойдёт администраторский ключ — у него нет привязки к пользователю, ответ будет 403 user identity required.

Все пути относительно https://api.cenaly.ru/mcp.

Полный справочник инструментов#

Уровни доступа#

• USER — Доступно всем авторизованным пользователям (данные по своему аккаунту)
• ADMIN — Только администраторы (полный доступ)

Самообслуживание#

Профили пользователей#

Локации#

update_location_profile — обновляемые поля: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. Синхронизируется с CDN автоматически. Для смены домена используйте set_location_domain.

Меню#

check_translations — сканирует все категории и блюда локации, находит отсутствующие переводы на включённых языках и возвращает детальный отчёт по языкам с перечнем категорий и блюд без переводов.

Языки приложения#

Допустимые коды: ka, en, ru, tr, hy, zh, hi, es, fr, ar, bn, pt, id, ur, de, ja, ko, vi, it, pl, uk, fa, he, az, kk, uz, ab, sq, sr, mk, bg, ro, el, nl, mt, sv, no, da, fi, cs, hu, hr, lt, th, ms.

Часы работы#

Не указанные в set_working_hours дни остаются без изменений. Повторный add_schedule_exception на ту же дату заменяет существующее исключение.

update_menu_item — обновляемые поля: name, description, price, status, tags, variantGroups, addons, nameTranslations, descriptionTranslations, locationPrices, sortOrder. Синхронизируется с CDN автоматически.

Заказы#

Домены#

CDN#

Изображения#

get_image_upload_url — возвращает presigned URL (15 мин). После загрузки пайплайн автоматически генерирует миниатюры и синхронизирует с CDN.

S3 (хранилище)#

Enum для bucket: data.meni, cdn.cenaly.ru, i.cenaly.ru, o.cenaly.ru

Cognito#

Система#

Контроль доступа#

1. Обычные пользователи — только свои данные (по userId)
2. S3 доступ ограничен префиксом users/{userId}/
3. Для инструментов локаций/меню userId автоопределяется для обычных пользователей (только админы указывают его)
4. Admin-only: list_users, search_user_by_email, list_domains, invalidate_cdn_cache, s3_write, s3_delete, cognito_list_users, cognito_get_user, get_system_stats
5. update_user_profile доступен и обычному пользователю: аргумент userId обязателен по схеме, но для не-админа сервер всегда подставляет его собственный идентификатор — чужой профиль этим инструментом не изменить
6. Управление ключами (/api/keys) требует авторизации от имени пользователя: Cognito JWT или собственный MCP-ключ (администраторский ключ не подходит)

Коды ошибок#

Пример сессии#

→ POST /  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"bot","version":"1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"meni-user-data","version":"1.0.0"}}}

→ POST /  {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"whoami","arguments":{}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"userId\":\"abc-123\",\"email\":\"user@example.com\"}"}]}}

Конфигурация клиента#

Claude Desktop#

{
  "mcpServers": {
    "meni": {
      "url": "https://api.cenaly.ru/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

cURL#

curl -X POST https://api.cenaly.ru/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'