MCP-сервер Magic Hour

MCP-сервер на основе OpenAPI для генерации изображений, видео и аудио в Magic Hour.

При запуске сервер читает docs/openapi.json и создает инструменты MCP с помощью

FastMCP.from_openapi(). Спецификация OpenAPI определяет доступные эндпоинты, а

политики Magic Hour MCP дополняют ее рекомендациями для агентов по опросу асинхронных

задач, загрузке файлов и скачиванию проектов.

Документация:

Навыки агентов Magic Hour — сценарии работы с медиа, опубликованные примеры и рекомендации по восстановлению после ошибок
user.md — руководство пользователя для размещенного эндпоинта
integration-handoff.md — список проверки для подключения через FastAPI
docs/detailed-step-by-step-integration.md — полное руководство по интеграции с серверной частью
docs/api-reference.md — автоматически сгенерированный справочник API

Установка

pip install -e .

Локальный запуск

python main.py

Локальный эндпоинт MCP:

http://127.0.0.1:8000/

Локальный сервер для разработки работает по адресу /, а не /mcp. Хост-приложение добавляет /mcp при подключении сервера.

По умолчанию запросы отправляются в рабочую среду API Magic Hour:

https://api.magichour.ai

Список доступных инструментов можно просматривать без аутентификации. Для вызова инструментов требуется API-ключ Magic Hour:

Authorization: Bearer <magic_hour_api_key>

Агенты могут получить карточку размещенного сервера по адресу:

https://mcp.magichour.ai/.well-known/mcp/server-card.json

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

MAGIC_HOUR_API_BASE_URL=https://api.magichour.ai
MAGIC_HOUR_OPENAPI_PATH=docs/openapi.json
MCP_OAUTH_ISSUER_URL=https://mcp.magichour.ai
MCP_OAUTH_RESOURCE_URL=https://mcp.magichour.ai

Чтобы использовать имитационный или другой базовый адрес API, задайте значение MAGIC_HOUR_API_BASE_URL:

MAGIC_HOUR_API_BASE_URL=https://api.sideko.dev/v1/mock/magichour/magic-hour/latest python main.py

OAuth

Этот сервер выступает только в роли защищенного ресурса OAuth. Сервер авторизации — веб-приложение Magic Hour

(https://magichour.ai): пользователи входят в систему и дают согласие в приложении, после чего оно возвращает

API-ключ Magic Hour в качестве токена доступа. Сервер передает этот ключ в API. Для рабочей среды необходимо

задать MCP_OAUTH_ISSUER_URL и MCP_OAUTH_RESOURCE_URL. См. docs/future-oauth-support.md.

Проверка с помощью MCP Inspector

Запустите сервер.
Выполните команду:

npx @modelcontextprotocol/inspector

В Inspector укажите:
- Транспорт: Streamable HTTP
- URL: http://127.0.0.1:8000/
- Заголовок: Authorization: Bearer
Вызовите ping.
Вызовите video_assets_generate_presigned_url или другой сгенерированный инструмент.

Примечания:

FastMCP при запуске автоматически создает инструменты для эндпоинтов на основе OpenAPI.
Инструменты создания сразу возвращают id и credits_charged.
Значения OpenAPI operationId преобразуются в понятные имена инструментов в формате snake_case.
Общий эндпоинт /v1/files/upload-urls называется video_assets_generate_presigned_url. Он принимает элементы типов video, audio и image.
Для опроса задач используйте wait_for_*_project. Используйте exact_download_urls без изменений

в том виде, в котором они возвращены; никогда не добавляйте к ним метаданные срока действия.

Инструменты ожидания для изображений и аудио также возвращают медиафайлы непосредственно в ответе, если это поддерживается.

Пересоберите интерфейс MCP App и проверьте типы командой cd web && npm ci && npm run build.

Загрузка файлов

Magic Hour не принимает необработанные байты файлов в аргументах инструментов. Порядок действий:

Вызовите сгенерированный общий инструмент для получения URL загрузки — video_assets_generate_presigned_url
Загрузите байты файла по полученному адресу upload_url
Передайте полученное значение file_path в сгенерированный инструмент создания контента

Прямые общедоступные URL-адреса медиафайлов могут работать, однако значения file_path для загруженных

файлов надежнее. Загружайте байты со стороны вызывающего клиента или через выделенный мост загрузки; размещенный

сервер MCP не читает локальные пути файловой системы, переданные вызывающей стороной. Для чата в браузере нужен

отдельный интерфейс загрузки или мост; см. docs/future-chat-ui-handoff.md.

Голосовые пресеты MCP

AI Voice Generator раскрывает и принимает только точные строки API voice_name, перечисленные в

APPROVED_VOICE_NAMES в mcp_magichour/openapi_policies.py. Чтобы включить инструмент в следующем развертывании,

заполните этот кортеж проверенными разрешенными универсальными пресетами, не связанными со знаменитостями. Безопасность

существующих голосов из исходного API не предполагается. Если список разрешенных значений пуст, Voice Generator не

будет доступен при обнаружении инструментов и вызове. Voice Cloner всегда исключен из MCP.

При запуске и повторной генерации docs/api-reference.md политика MCP удаляет описания голосов из исходного API,

значения по умолчанию, примеры и фрагменты SDK. Ежедневная синхронизация OpenAPI не может расширить список разрешенных

значений. Не редактируйте docs/openapi.json, чтобы задать голоса для MCP: этот файл остается неизмененным снимком

исходного API. Основной продукт Magic Hour и публичный API не меняются.

MCP Meme Generator раскрывает только универсальный вариант шаблона Random, поэтому названия шаблонов с публичными

фигурами не попадают в его схему.