Compeller

Конечная точка MCP Compeller (/api/mcp)

Конечная точка MCP Compeller реализует Протокол контекста модели как тонкую обёртку JSON-RPC 2.0 поверх существующего REST API v1. Она предназначена для интеграторов агентов (Claude Desktop, Cursor, пользовательские MCP-клиенты, DigiRAMP), которые говорят на MCP нативно, а не через сырой HTTP.

• Транспорт: Streamable HTTP (одно JSON-RPC-сообщение на HTTP POST).
• URL: POST https://compeller.ai/api/mcp
• Версия протокола: 2024-11-05
• Имя / версия сервера: compeller-mcp / см. результат initialize.
• Контракт инструментов: список инструментов ниже — это публичный интеграционный контракт. Используйте tools/list для набора, рекламируемого в рантайме на развёрнутом сервере.
• Списки каталогов: Официальный реестр MCP · Smithery · Glama

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

Анонимные (дискавери) методы: initialize, tools/list, ping, notifications/initialized, плюс анонимные инструменты get_capabilities, get_pricing, list_styles.

Каждый остальной инструмент требует API-токен Compeller, передаваемый в самом HTTP-запросе, не внутри тела JSON-RPC. Подойдёт любой из заголовков:

Authorization: Bearer <api-token>
X-API-Token: <api-token>

Токены выдаются на каждый Compeller User (те же токены, что используются в /api/v1/*). Агенты могут получить его одним из двух способов:

1. Попросить пользователя войти в систему, открыть Аккаунт → API-доступ, показать токен и вставить его в хранилище секретов агента.
2. Использовать существующую конечную точку входа и отправить access_token как bearer-токен. Заголовок Cookie не нужен и не ожидается:

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"artist@example.com","password":"..."}'

Обычные пользователи получают username и access_token. roles появляется только для аккаунтов с ролями выше базового ROLE_COMPELLER; refresh_token и expires_in появляются только если не пустые.

3. Или обменять учётные данные через вспомогательный механизм аутентификации v1, который возвращает постоянный API-токен:

curl -s -X POST https://compeller.ai/api/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"email":"artist@example.com","password":"..."}'

Отсутствующий или недействительный токен проявляется как ошибка инструмента (isError: true) с сообщением "API token required." / "Invalid API token.", а не как ошибка JSON-RPC, поэтому MCP-клиенты могут запросить у пользователя учётные данные.

Методы JSON-RPC

Метод	Назначение	HTTP-результат
initialize	Ручкопожатие возможностей. Возвращает protocolVersion, serverInfo, capabilities.	200 JSON-RPC-результат
notifications/initialized	Подтверждение клиента. Без тела ответа.	204
tools/list	Перечислить все инструменты со схемой + описанием.	200 JSON-RPC-результат
tools/call	Вызвать инструмент. params = {name, arguments}.	200 JSON-RPC-результат (ошибки инструментов возвращаются как {isError: true, content: [...]})
ping	Keepalive без операции.	200 JSON-RPC result: {}

Неизвестные методы возвращают ошибку JSON-RPC -32601 Method not found. Неизвестные имена инструментов возвращают -32602 Unknown tool. Некорректное JSON-тело возвращает -32700 Parse error. Отсутствующий / неверный jsonrpc или отсутствующий method возвращает -32600 Invalid Request.

Инструменты

Все инструменты возвращают одну запись content типа type: text, чьё поле text содержит структурированный вывод в JSON-формате. При сбое возвращается та же форма ответа с isError: true и читаемым сообщением об ошибке в content[0].text — никогда как JSON-RPC error.

Обнаружение (без аутентификации)

Инструмент	Входные данные	Возвращает
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	plans[] с id, name, monthlyUsd, features[]
list_styles	—	styles[] с id, name (id — это точное значение, которое create_compel / create_compel_from_music принимают для style)

Медиа и музыка (требуется аутентификация, если не указано иное)

Инструмент	Обязательные	Необязательные	Возвращает
search_music	query	limit	Публичные результаты поиска музыки, подходящие для create_compel_from_music. Аутентификация не требуется.
upload_media	—	name, mime_type, type	Инструкции по загрузке, указывающие на POST /api/v1/media
search_media	—	type (audio/image/video/text), limit (≤100, по умолчанию 20), offset	media[], paging

Компеллы (требуется аутентификация)

Инструмент	Обязательные	Необязательные	Возвращает
create_compel_from_music	track_id	title, style, target_platform, aspect_ratio, artist_context	compel_id, status, next_action
create_compel	title, primary_media_id	style, target_platform, aspect_ratio, artist_context	compel_id, status: QUEUED
get_compel	compel_id	—	compel_id, title, status, progress_percent, stage, rendering_id, created_at, human_url, next_action
start_render	compel_id	—	Запускает финальный рендеринг, когда компелл готов; возвращает статус и следующее действие.
cancel_compel	compel_id	—	Отменяет выполняющийся компелл (идемпотентно — уже-ОТМЕНЁННЫЙ завершается успешно); возвращает compel_id, status: CANCELLED, stage.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform и aspect_ratio ограничены enum в схемах инструментов (см. get_capabilities.enums); значения style берутся напрямую из list_styles.

Аккаунт (требуется аутентификация)

Инструмент	Входные данные	Возвращает
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — вызывайте перед дорогим рендерингом, чтобы принимать решения с учётом стоимости.

Рендеринги (требуется аутентификация)

Инструмент	Обязательные	Возвращает
list_renderings	compel_id	compel_id, renderings[] с rendering_id, status, download_url
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url указывает на GET /api/v1/renderings/{id}/download (поддерживает HTTP Range). Завершённые ответы компелла/рендеринга также включают передачу react с бесплатной загрузкой REACT (https://compeller.ai/download/desktop) и URL для подробностей (https://compeller.ai/react), чтобы агенты могли рассказать пользователям, как испытать компелл как живую систему исполнения.

Вебхуки (требуется аутентификация)

Агенты, интегрирующиеся с Compeller, могут самостоятельно регистрироваться для получения подписанных push-уведомлений о событиях жизненного цикла компелла вместо опроса get_compel. Подпишитесь на compel.ready, чтобы узнать момент, когда компелл можно рендерить (затем вызовите start_render) без опроса; compel.completed / compel.failed — терминальные события.

Инструмент	Обязательные	Необязательные	Возвращает
register_webhook	url (HTTPS, ≤2048 символов)	events[] — по умолчанию ["*"]; известные значения: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (возвращается ровно один раз), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Секреты никогда не возвращаются этим инструментом.
update_webhook	webhook_id	url, events[], active — хотя бы один	webhook_id, url, events, active, created_at, updated_at. Секреты никогда не возвращаются; используйте rotate_webhook_secret для этого.
delete_webhook	webhook_id	—	webhook_id, deleted: true
test_webhook_delivery	webhook_id	—	webhook_id, event_id, event_type: "webhook.test", delivered, response_status?, response_body_preview?, latency_ms, error?. Синхронно — инструмент ждёт ответа конечной точки интегратора (макс. 5 с). Секреты никогда не возвращаются.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (новое — возвращается ровно один раз), created_at, updated_at. Старый секрет немедленно аннулируется.

Неизвестные имена событий молча сворачиваются в подстановочный *; это зеркалит POST /api/v1/webhooks, поэтому агент никогда не создаёт подписку без действия.

Доставка — как минимум один раз. Каждое событие пытается доставиться немедленно и, если ваша конечная точка недоступна или возвращает не-2xx, повторяется с экспоненциальной задержкой — до 6 попыток всего (немедленно, затем через 1м, 5м, 30м, 2ч, 6ч). Каждая попытка несёт тот же X-Compeller-Event-Id и байт-идентичное подписанное тело, поэтому дедуплицируйте по этому id. Если все попытки исчерпаны, событие отбрасывается; сверяйтесь через get_compel.

register_webhook отклоняет назначения, указывающие на внутреннюю инфраструктуру, ошибкой инструмента: loopback, частные диапазоны RFC1918, link-local (включая IP облачных метаданных, например 169.254.169.254), IPv6 ULA, CGNAT, multicast, неопределённый адрес и hostname, оканчивающиеся на .local / .internal / .localhost. Та же проверка повторно выполняется при доставке против разрешённого DNS на каждой попытке, поэтому hostname, который перепривязывается к заблокированному IP после регистрации, пропускается для этой попытки (логируется); если он остаётся заблокированным, он просто расходует свой бюджет повторных попыток и затем отбрасывается.

test_webhook_delivery отправляет синтетическое событие webhook.test с подписью HMAC-SHA256 и синхронно ждёт ответа конечной точки. Он игнорирует подписанный events конечной точки (всегда доставляется) и применяет ту же проверку безопасности URL, что и реальные доставки. Ответ не-2xx отображается как delivered: false, но сам MCP-вызов всё равно завершается успешно — результатом является полезная нагрузка.

update_webhook принимает любой из url, events, active (хотя бы один). Проверка URL зеркалит register_webhook. Секреты никогда не возвращаются этим инструментом.

rotate_webhook_secret создаёт новый 64-символьный hex-секрет подписи, возвращает его ровно один раз и немедленно аннулирует предыдущий секрет. Сохраните новый секрет при получении до следующей реальной доставки.

Каждая доставка подписана точно так же, как REST-путь — см. раздел Webhooks в openapi.yaml для полного контракта конверта и заголовков.

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

# 1. Handshake
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# 2. List tools
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Register a webhook (auth required)
curl -s https://compeller.ai/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <api-token>' \
  -d '{
        "jsonrpc":"2.0",
        "id":3,
        "method":"tools/call",
        "params":{
          "name":"register_webhook",
          "arguments":{
            "url":"https://hooks.my-agent.io/compeller",
            "events":["compel.completed","compel.failed"]
          }
        }
      }'

Ответ на шаг 3 — это JSON-RPC result, содержащий content[0].text — сам по себе JSON-документ с webhook_id, secret и т.д. Сохраните secret немедленно; сервер не вернёт его снова.

Коды ошибок

Код	Значение	Причина
-32700	Ошибка парсинга	Тело не является корректным JSON
-32600	Неверный запрос	Отсутствует/неверный jsonrpc, отсутствует method, пустое тело
-32601	Метод не найден	Неизвестный JSON-RPC метод
-32602	Неверные параметры	Неизвестный инструмент, отсутствует name инструмента, неверная форма params
-32603	Внутренняя ошибка	Необработанное исключение (логируется на стороне сервера)

Сбои на уровне инструментов (валидация, аутентификация, не найдено) возвращаются внутри успешного JSON-RPC-ответа как {result: {isError: true, content: [{type: "text", text: "..."}]}}. Это по соглашению MCP — оно позволяет LLM видеть и отображать сбой дословно. Agent audio decision tree: если пользователь предоставляет MP3/WAV/FLAC, используйте upload_media, затем create_compel; если пользователь предоставляет только строку с названием песни/исполнителя, используйте search_music, затем create_compel_from_music; не синтезируйте тон, если только явно не запрошено сгенерированное тестовое аудио.