MCP Сервер — Руководство пользователя

Что это?

MCP сервер (Model Context Protocol) для meni.ge позволяет подключать AI-ассистентов (Claude, ChatGPT, Cursor, VS Code Copilot и др.) к данным вашего ресторана. AI получает доступ к меню, локациям, заказам, изображениям и может управлять ими от вашего имени.

Быстрый старт

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

API-ключ генерируется в админ-панели вашего ресторана.

Шаг за шагом:

Войдите в Админ-панель по адресу admin.meni.ge
В боковом меню откройте ⚙️ Настройки → 🔑 Доступ
На странице найдите раздел 🤖 MCP API Ключи
Нажмите кнопку «Сгенерировать новый ключ»
Введите имя ключа (например, «Claude Desktop», «Cursor», «Мой GPT») — это поможет отличать ключи друг от друга
Скопируйте ключ сразу — он показывается только один раз!

💡 На этой же странице отображается URL сервера (https://api.meni.ge/mcp), который тоже можно скопировать одним кликом.

Управление ключами

Вы можете создать до 10 ключей на аккаунт
Каждый ключ можно отозвать в любой момент — кнопка «Отозвать» рядом с ключом
После отзыва ключ перестаёт работать немедленно
Если ключ потерян — отзовите его и создайте новый

2. Подключите AI-ассистент

Claude Desktop / Claude Code

Файл конфигурации claude_desktop_config.json:

{
  "mcpServers": {
    "meni": {
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer ВАШ_API_КЛЮЧ"
      }
    }
  }
}

Cursor

В настройках Cursor → MCP Servers → Add, или файл .cursor/mcp.json:

{
  "mcpServers": {
    "meni": {
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer ВАШ_API_КЛЮЧ"
      }
    }
  }
}

VS Code (GitHub Copilot)

В .vscode/mcp.json проекта:

{
  "servers": {
    "meni": {
      "type": "http",
      "url": "https://api.meni.ge/mcp",
      "headers": {
        "Authorization": "Bearer ВАШ_API_КЛЮЧ"
      }
    }
  }
}

Другие AI-инструменты

Подробные пошаговые инструкции для Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Continue, ChatGPT и других — в отдельном руководстве:

👉 Подключение AI-инструментов к MCP

Что может AI-ассистент?

Для владельцев ресторанов (обычные пользователи)

Команда	Описание
`whoami`	Показать данные аккаунта (userId, email, роль)
`my_profile`	Получить свой профиль пользователя
`update_my_profile`	Обновить поля в своём профиле
`my_locations`	Список всех ваших локаций
`my_orders`	Список ваших заказов
`my_images`	Список ваших изображений (меню, категории, локации)

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

Команда	Описание
`get_user_profile`	Получить профиль пользователя по userId
`update_user_profile`	Обновить поля профиля пользователя
`list_users`	`[ADMIN]` Список всех пользователей
`search_user_by_email`	`[ADMIN]` Найти пользователя по email через Cognito

Работа с локациями

Команда	Описание
`list_locations`	Все локации пользователя
`get_location_profile`	Профиль локации (название, адрес, часы работы, настройки)
`update_location_profile`	Обновить настройки локации (синхронизируется с CDN автоматически)
`get_location_menu`	Полное меню локации с категориями и позициями

Работа с меню

Команда	Описание
`list_menu_items`	Все позиции меню (с categoryId — полные данные, без — пары item/category ID)
`get_menu_item`	Получить позицию с полными данными (включая переводы, варианты, добавки)
`update_menu_item`	Обновить позицию меню (цена, описание, статус, теги, варианты, добавки)
`create_menu_item`	Создать новую позицию меню в категории
`create_menu_category`	Создать новую категорию меню
`update_menu_category`	Обновить категорию (название, переводы, статус, порядок сортировки)
`move_menu_item`	Переместить позицию из одной категории в другую
`merge_categories`	Объединить две категории (все позиции перемещаются, исходная удаляется)
`delete_menu_category`	Удалить категорию (с `force: true` — вместе со всеми позициями)

Заказы

Команда	Описание
`list_orders`	Список заказов (по userId или домену)
`get_order`	Детали конкретного заказа

Домены

Команда	Описание
`check_domain_availability`	Проверить доступность доменного имени
`set_location_domain`	Изменить доменное имя локации (обновляет CDN и маппинги)
`resolve_domain`	Узнать userId и locationId по домену
`list_domains`	`[ADMIN]` Список всех зарегистрированных доменов

CDN (опубликованные данные)

Команда	Описание
`get_cdn_profile`	Опубликованный профиль локации (на CDN)
`get_cdn_menu`	Опубликованное меню на указанном языке
`list_cdn_files`	Все опубликованные файлы домена
`invalidate_cdn_cache`	`[ADMIN]` Сбросить кеш CloudFront CDN

Изображения

Команда	Описание
`list_user_images`	Все изображения пользователя
`get_image_upload_url`	Получить presigned URL для загрузки изображения в S3 (JPEG/PNG/WebP)
`delete_image`	Удалить изображение (пользователи — только свои)

Низкоуровневый доступ к S3

Команда	Описание
`s3_read`	Прочитать файл из S3 (пользователи — только свои)
`s3_write`	`[ADMIN]` Записать JSON-данные в S3
`s3_list`	Список файлов в S3 (пользователи — только свой префикс)
`s3_delete`	`[ADMIN]` Удалить объект из S3

Cognito

Команда	Описание
`cognito_list_users`	`[ADMIN]` Список пользователей из Cognito User Pool
`cognito_get_user`	`[ADMIN]` Подробная информация о пользователе Cognito

Статистика

Команда	Описание
`get_system_stats`	`[ADMIN]` Общесистемная статистика

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

Сервер поддерживает три способа авторизации:

1. API-ключ (рекомендуется для AI-ассистентов)

Authorization: Bearer ваш_64_символьный_ключ

Ключ генерируется в админ-панели. Привязан к вашему аккаунту — AI видит только ваши данные.

2. Cognito JWT-токен

Для программной интеграции можно получить токен через логин:

# Получить токен
curl -X POST https://api.meni.ge/mcp/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "ваш@email.com", "password": "ваш_пароль"}'

# Ответ содержит idToken — используйте его:
Authorization: Bearer eyJraWQ...

Токен действует 1 час, после чего требуется повторный логин.

3. Admin API Key (только для администраторов)

Authorization: Bearer admin_key

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

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

Каждый API-ключ привязан к конкретному аккаунту
Обычные пользователи видят только свои данные
Ключ можно отозвать в любой момент в админ-панели
Максимум 10 ключей на аккаунт
Все запросы идут через HTTPS
Команды с пометкой [ADMIN] недоступны обычным пользователям

Примеры использования

Попросить AI обновить цену блюда

«Обнови цену позиции «Хачапури» в моём меню — сделай 15 лари вместо 12»

AI вызовет my_locations → get_location_menu → update_menu_item.

Добавить новую позицию в меню

«Добавь в категорию «Десерты» новое блюдо «Чурчхела» за 8 лари»

AI вызовет my_locations → get_location_menu → create_menu_item.

Создать новую категорию

«Создай категорию «Напитки» с переводами на грузинский и английский»

AI вызовет create_menu_category с nameTranslations.

Переместить блюдо между категориями

«Перенеси «Лимонад» из «Холодные напитки» в «Безалкогольные»»

AI вызовет move_menu_item с указанием исходной и целевой категории.

Посмотреть заказы за сегодня

«Покажи мои заказы за сегодня»

AI вызовет my_orders и отфильтрует по дате.

Проверить опубликованное меню

«Как выглядит моё меню на русском языке для посетителей?»

AI вызовет resolve_domain → get_cdn_menu с языком ru.

Сменить домен ресторана

«Проверь, доступен ли домен my-restaurant, и если да — установи его»

AI вызовет check_domain_availability → set_location_domain.

Загрузить фото блюда

«Дай мне ссылку для загрузки фото к блюду X»

AI вызовет get_image_upload_url и вернёт presigned URL для загрузки.

API-эндпоинты

Метод	URL	Описание
`GET`	`https://api.meni.ge/mcp`	Информация о сервере + список инструментов
`POST`	`https://api.meni.ge/mcp`	MCP JSON-RPC (основной протокол)
`GET`	`https://api.meni.ge/mcp/health`	Проверка работоспособности
`POST`	`https://api.meni.ge/mcp/auth/login`	Логин → JWT-токены
`GET`	`https://api.meni.ge/mcp/api/keys`	Список ваших API-ключей
`POST`	`https://api.meni.ge/mcp/api/keys`	Создать новый API-ключ
`DELETE`	`https://api.meni.ge/mcp/api/keys/{id}`	Отозвать API-ключ

Управление ключами

Просмотр ключей

В админ-панели → Настройки → Доступ → MCP API Ключи. Или через API:

curl https://api.meni.ge/mcp/api/keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

Создание ключа

curl -X POST https://api.meni.ge/mcp/api/keys \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Desktop"}'

Ответ содержит поле key — это и есть ваш ключ. Сохраните его!

Отзыв ключа

curl -X DELETE https://api.meni.ge/mcp/api/keys/mk_abc123 \
  -H "Authorization: Bearer COGNITO_JWT_TOKEN"

⚠️ Создание и отзыв ключей требует Cognito JWT-токен (не API-ключ). Используйте админ-панель — это проще.

Устранение неполадок

Проблема	Решение
`401 Unauthorized`	Проверьте API-ключ. Если отозван — создайте новый
`403 user identity required`	Используйте Cognito JWT для управления ключами
`🔒 admin access required`	Команда доступна только администраторам
`🔒 access denied`	Вы пытаетесь получить данные другого пользователя
Ключ не работает	Проверьте что ключ не был отозван, и формат: `Bearer <ключ>`