appsgolem-mcp (Node / TypeScript)

Сервер MCP для API нарезки YouTube-видео AppsGolem. Он позволяет ИИ-агенту (Claude Desktop, Claude Code, Cursor, …) вырезать клипы из YouTube-видео — в любом формате, который поддерживает веб-резак, — и получать прямую ссылку для скачивания. REST-логика находится в небольшом клиенте без лишних зависимостей (src/client.ts); src/server.ts — это тонкий слой инструментов MCP поверх него.

Требования

• Node.js >= 18 (используется глобальный fetch).

• Ключ API AppsGolem (ag_live_…) — создайте его в панели управления по адресу https://appsgolem.com/api-billing/. Кредиты предоплачены; купите пакет или подписку там.

Related MCP server: ytmcp

Установка / подключение (без ручной установки)

npx загружает и запускает сервер по требованию — ничего глобально устанавливать не нужно.

Claude Desktop / Cursor — добавьте в конфигурацию MCP клиента (например, claude_desktop_config.json):

{
  "mcpServers": {
    "appsgolem": {
      "command": "npx",
      "args": ["-y", "appsgolem-mcp"],
      "env": { "APPSGOLEM_API_KEY": "ag_live_…" }
    }
  }
}

Claude Code — одна команда:

claude mcp add appsgolem -e APPSGOLEM_API_KEY=ag_live_… -- npx -y appsgolem-mcp

Сервер общается по MCP через stdio (транспорт, который используют эти клиенты). Отсутствие APPSGOLEM_API_KEY не является фатальным при запуске — сервер всё равно запускается и объявляет свои инструменты; каждый вызов затем возвращает понятный config_error, сообщающий, что нужно задать ключ.

Конфигурация

Цены

1 созданный клип = 1 кредит. 2160p (4K) = 4 кредита за клип — кроме audio_only, который остаётся 1. Исходник длиннее 2 часов добавляет +1 один раз за задание, но только когда его длительность известна (надбавка пропускается, если пробу не удаётся её определить). Пакет/склейка из N клипов стоит N за клип. Неудачные нарезки не тарифицируются.

Инструменты

Сервер предоставляет три инструмента. Вызов, прошедший проверку схемы входных данных MCP, возвращает структурированный результат — собственный JSON API при успехе или { "error": … } при любой ошибке обработчика/API — и никогда не вызывает ошибку на уровне протокола, так что агент всегда получает пригодный объект. (Недопустимые аргументы инструмента отклоняются MCP SDK до запуска обработчика, как текстовый результат isError.)

1. cut_youtube_video

Вырезать клип (или пакет клипов) из YouTube-видео. По умолчанию он ожидает готовности клипа и возвращает его статус (включая download_url, когда токен для скачивания готов); установите wait: false, чтобы отправить задание и сразу вернуться с текущим заданием (его состояние обычно queued после отправки).

Параметры

Возвращает (wait: true, по умолчанию) — статус созданного задания. download_url присутствует, когда токен для скачивания готов; если его ещё нет, опросите снова:

{
  "id": "e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "produced",
  "credits_reserved": 1,
  "created_at": "2026-08-22T12:00:00+00:00",
  "download_url": "https://appsgolem.com/v1/download/…/clip.mp4"
}

Возвращает (wait: false) — задание сразу, с его текущим состоянием (обычно queued после отправки) и без download_url; опросите get_cut_status с id (или получите poll_url):

{
  "id": "e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "state": "queued",
  "credits_reserved": 1,
  "poll_url": "/v1/cuts/e48db1a2-1c3d-4e5f-8a9b-0c1d2e3f4a5b"
}

Если ожидание истекло до готовности клипа, результат содержит "still_processing": true и id задания — опросите get_cut_status с этим id. Если задание достигло конечного сбоя, результат — { "error": "cut_failed", "state": "failed" | "refunded", "id": … } (и кредит не списывается).

2. get_cut_status

Проверить задание нарезки по его id. Используйте для опроса задания, запущенного с cut_youtube_video(wait=false) или того, которое превысило время ожидания.

Возвращает — состояние задания; после создания/доставки также содержит download_url, когда токен для скачивания доступен (иначе опросите снова):

{ "id": "e48db1a2-…", "state": "queued", "credits_reserved": 1, "created_at": "…" }

Состояния прогрессируют accepted → queued → produced → delivered, или failed → refunded при ошибке.

3. get_account_balance

Возвращает доступный кредитный баланс API-аккаунта и текущий часовой лимит. Без параметров.

Возвращает

{ "balance": 412, "hourly_cap": 60 }

Режимы

Примеры запросов

Поскольку агент выбирает параметры из вашего запроса, вы управляете им на простом языке:

• «Вырежи 0:30–1:15 из https://youtu.be/dQw4w9WgXcQ в 1080p.» → cut_youtube_video(url, start="0:30", end="1:15")

• «Возьми аудио этого видео с 2:00 по 5:00 как mp3.» → mode="audio_only", audio_format="mp3"

• «Сделай вертикальный шорт из хайлайта 10:00–10:45.» → mode="short", start="10:00", end="10:45"

• «Преврати 0:05–0:12 в GIF.» → mode="gif"

• «Извлеки лист кадров каждые 5 секунд с 1:00 по 2:00.» → mode="frames", interval_ms=5000, sheet=true

• «Склей 0:10–0:20 и 1:00–1:10 в один клип.» → clips=[{start:"0:10",end:"0:20"},{start:"1:00",end:"1:10"}], stitch=true

• «Сделай быструю нарезку с потоковым копированием 0:00–0:30.» → fast=true

• «Сколько у меня осталось API-кредитов?» → get_account_balance()

Формы результатов и ошибок

Каждый результат от обработчика — это обычный объект (исключение — ошибки валидации аргументов MCP; см. примечание об инструментах выше). При сбое объект содержит код error (вызов инструмента при этом всё равно завершается успешно):

Ошибки уровня API (например, ошибка валидации 400, превышение лимита запросов 429) возвращаются в виде собственного тела ошибки API плюс поле status; 429 также включает retry_after (в секундах), когда сервер отправляет Retry-After, чтобы агент мог сделать паузу.

Относительный download_url (API возвращает путь) преобразуется в полный URL на основе настроенного базового URL API только если он относится к тому же origin; уже абсолютные URL и ссылки на другой origin остаются без изменений.

Разработка

npm install
npm run build      # tsc -> dist/
npm test           # builds, then runs node --test (no network)
npm start          # run the stdio server locally (key needed for calls, not startup)

Публикация

npm publish (из этого каталога) делает npx appsgolem-mcp доступным для всех. Скрипт prepare автоматически собирает dist/ при установке/публикации.