@ffmpeg-micro/mcp-server

Сервер Model Context Protocol, который позволяет AI-агентам — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code и любому другому MCP-совместимому клиенту — создавать, отслеживать и скачивать видеотранскоды через REST API FFmpeg Micro.

Что он делает

Предоставляет инструменты, соответствующие публичному API FFmpeg Micro:

Blueprints

Blueprints — это готовые процессы, лежащие в основе POST /v1/blueprints/{slug}/runs. В описаниях инструментов задокументированы поля ввода каждого blueprint. Примечания:

• Большинство blueprints выполняются на FFmpeg-линии и учитываются в вычислительных минутах плана (без токенов). Генеративные blueprints (product-ad) списывают токены; ответ 402 insufficient_tokens означает, что на аккаунте нужен пакет токенов (дашборд).

• caption-video останавливается в статусе awaiting_review вместе с транскриптом (srt_text), чтобы агент мог проверить или отредактировать его перед рендерингом; возобновление — через continue_blueprint_run.

• Blueprints с несколькими выходами (listing-kit, hook-variants) возвращают массив outputs из {label, url} — при наличии отдавайте предпочтение ему, а не output_url.

• URL выходных файлов подписаны с TTL 10 минут; повторно запросите выполнение, чтобы получить свежие ссылки.

Загрузка локального файла

Пара request_upload_url + confirm_upload позволяет MCP-хосту загружать локальный файл в storage-бакет FFmpeg Micro без необходимости работать с сырыми API-ключами или URL gs://:

1. Хост вызывает request_upload_url с параметрами {filename, contentType, fileSize} → получает короткоживущий предварительно подписанный HTTPS-URL.

2. Хост отправляет байты файла на этот URL методом PUT с тем же Content-Type.

3. Хост вызывает confirm_upload с параметрами {filename: <storage filename from step 1>, fileSize} → получает итоговый fileUrl вида gs://....

4. Хост передаёт этот fileUrl в transcribe_audio / transcode_video / transcode_and_wait.

Related MCP server: Rendi MCP Server

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

Добавьте это в .mcp.json вашего проекта (или в конфигурацию вашего MCP-клиента):

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com"
    }
  }
}

Вот и всё. При первом подключении ваш AI-инструмент откроет окно браузера, чтобы вы вошли в свой аккаунт FFmpeg Micro через OAuth. После подтверждения токен кэшируется, и повторный вход не потребуется.

Никаких API-ключей для копирования и переменных окружения для настройки.

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

OAuth (рекомендуется)

MCP-сервер поддерживает OAuth 2.1 с PKCE и динамической регистрацией клиента. Ваш MCP-клиент выполняет весь процесс автоматически:

1. Клиент обнаруживает OAuth-эндпоинты через /.well-known/oauth-authorization-server

2. Клиент динамически регистрирует себя

3. Открывается браузер для входа и подтверждения доступа

4. Токен обменивается и кэшируется — последующие подключения происходят мгновенно

Это поведение по умолчанию при использовании конфигурации выше без блока headers или env.

API-ключ (альтернатива)

Если вы предпочитаете использовать API-ключ напрямую (например, для автоматизации или CI), передавайте его как Bearer-токен:

{
  "mcpServers": {
    "ffmpeg-micro": {
      "type": "http",
      "url": "https://mcp.ffmpeg-micro.com",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

Получите API-ключ в дашборде.

stdio (локальная установка)

Запускает сервер как локальный процесс с помощью npx. Требуется Node.js 22.14 или новее.

{
  "mcpServers": {
    "ffmpeg-micro": {
      "command": "npx",
      "args": ["-y", "@ffmpeg-micro/mcp-server"],
      "env": {
        "FFMPEG_MICRO_API_KEY": "your_api_key_here"
      }
    }
  }
}

npx -y каждый раз загружает последнюю версию. С этой конфигурацией работает любой MCP-клиент, поддерживающий stdio-серверы.

Совместимые инструменты

HTTP-конфигурация (OAuth) работает с любым MCP-клиентом, поддерживающим транспорт Streamable HTTP:

• Claude Code (CLI)

• Claude Desktop

• Cursor

• Windsurf

• VS Code (GitHub Copilot MCP)

stdio-конфигурация работает с любым MCP-клиентом, поддерживающим транспорт stdio.

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

После подключения можно задавать, например, такие запросы:

• «Транскодируй это видео в MP4 720p и дай мне ссылку для скачивания, когда закончишь.»

• «Обрежь это горизонтальное видео до квадрата.»

• «Добавь на моё видео текстовую накладку с надписью „Эпизод 12“.»

• «Покажи список моих неудачных задач за эту неделю.»

• «Отмени задачу b5f5a9c0-9e33-4e77-8a5b-6a0c2cd9c0b3.»

Разработка

git clone https://github.com/javidjamae/ffmpeg-micro-mcp.git
cd ffmpeg-micro-mcp
./scripts/setup.sh

setup.sh устанавливает зависимости, собирает проект и настраивает git-хуки.

Укажите вашему MCP-клиенту на локальную сборку, чтобы итерироваться:

{
  "mcpServers": {
    "ffmpeg-micro-dev": {
      "command": "node",
      "args": ["/absolute/path/to/ffmpeg-micro-mcp/dist/index.js"],
      "env": { "FFMPEG_MICRO_API_KEY": "…" }
    }
  }
}

MCP Inspector — самый быстрый способ итерироваться по схемам инструментов и ответам:

npx @modelcontextprotocol/inspector node dist/index.js

Чтобы запустить HTTP-сервер локально, направив его на локальный API-шлюз:

FFMPEG_MICRO_API_URL=http://localhost:8081 npm run serve

Запуск интеграционных тестов локально

FFMPEG_MICRO_API_KEY=your_key npm run test:integration

Интеграционные тесты обращаются к реальному production API FFmpeg Micro. Они работают только на чтение (задачи не создаются).

Смоук-тестирование инструментов загрузки end-to-end

Модульные тесты используют замоканный fetch, поэтому они проверяют регистрацию инструментов + схемы Zod + пути URL, но не то, что структуры данных на проводе совпадают с тем, что реально возвращает шлюз. Два смоук-скрипта прогоняют полный процесс request_upload_url → PUT → confirm_upload против реального MCP-сервера с реальным API-ключом. Запускайте их по порядку: сначала stdio (самый быстрый сигнал), затем развёрнутый HTTP-сервер до/после мёрджа:

# 1. stdio (local dist build) — spawns dist/index.js as a subprocess
npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-upload-stdio.mjs <local-file>

# 2. HTTP (any deployed server — local `npm run serve`, Vercel preview, or prod)
FFMPEG_MICRO_API_KEY=your_key MCP_URL=https://mcp.ffmpeg-micro.com/ \
  node scripts/smoke-upload-http.mjs <local-file>

Оба скрипта по умолчанию обращаются к production API и расходуют оплачиваемые минуты (stdio-скрипт дополнительно задействует transcribe_audio для сквозной проверки). Передавайте небольшой файл, например 15-second.mp3, чтобы стоимость была незначительной.

Третий скрипт смоук-тестирует инструменты blueprint (run_blueprint + get_blueprint_run с опросом до завершения на resize-format, затем run_blueprint_and_wait на hook-variants для проверки нескольких выходов). Он использует только blueprints на FFmpeg-линии, поэтому расходует вычислительные минуты плана, но не токены:

npm run build
FFMPEG_MICRO_API_KEY=your_key node scripts/smoke-blueprints-stdio.mjs

Тестирование превью Vercel, защищённых Deployment Protection

Превью-развёртывания Vercel по умолчанию ограничены Deployment Protection. Чтобы прогнать HTTP-смоук-скрипт против превью-URL, создайте токен Protection-Bypass-for-Automation в настройках Vercel проекта и передайте его через VERCEL_BYPASS:

FFMPEG_MICRO_API_KEY=your_key \
  MCP_URL=https://your-preview.vercel.app/ \
  VERCEL_BYPASS=your_bypass_token \
  node scripts/smoke-upload-http.mjs <local-file>

Скрипт отправляет токен в заголовке x-vercel-protection-bypass в каждом запросе. Он не отправляет x-vercel-set-bypass-cookie: true — этот вариант вызывает 307-редирект с установкой cookie на POST, который StreamableHTTPClientTransport из MCP SDK не обрабатывает, из-за чего запрос завершается ошибкой. Только заголовок возвращает 200 напрямую, без танцев с редиректами.

Процесс релиза

Релизы публикуются в npm через trusted publishing и в MCP Registry под именем com.ffmpeg-micro/mcp-server, с аутентификацией через Ed25519 DNS TXT-запись на ffmpeg-micro.com. Соответствующий закрытый ключ хранится в секрете MCP_PRIVATE_KEY GitHub Actions. Со стороны npm используется OIDC trusted publishing, поэтому npm-токен не хранится.

Релизы автоматизированы с помощью Changesets. Контрибьюторы не поднимают версии вручную, не ставят теги на коммиты и не запускают команды публикации — они прикрепляют changeset к своему PR, а остальное делает пайплайн релизов.

Процесс для контрибьюторов (каждый PR)

Каждый PR, изменяющий поставляемый код, должен включать changeset. Это обеспечивает CI-проверка.

# While working on your PR:
npx changeset

CLI запросит тип обновления версии (major/minor/patch) и краткое описание. Он создаёт markdown-файл в каталоге .changeset/ — закоммитьте этот файл вместе с вашим PR.

Запасные варианты для PR без релиза (документация, CI, внутренний рефакторинг, изменения тестов без влияния на поведение):

• Добавьте метку no-changeset к PR или

• Выполните npx changeset --empty, чтобы явно указать: «релиз не нужен».

Процесс для мейнтейнера (выпуск релиза)

Вы не выпускаете релизы вручную. Это делает пайплайн:

1. PR с прикреплёнными changeset-файлами попадают в main.

2. .github/workflows/release.yml запускается при каждом пуше в main. Когда есть ожидающие changeset, он открывает (или обновляет) PR chore(release): version packages, созданный action. Этот PR:

   • Запускает changeset version, чтобы применить ожидающие changeset

   • Поднимает версию в package.json

   • Повторно синхронизирует server.json через scripts/sync-server-version.mjs

   • Добавляет записи в CHANGELOG.md

   • Коммитит результат в собственную ветку

3. Просмотрите и смёржите PR Version Packages, когда будете готовы к выпуску. Можно накопить несколько changeset перед мёрджем — PR обновляется сам по мере появления новых изменений в main.

4. После мёрджа пайплайн релизов запускается снова. На этот раз ожидающих changeset нет, поэтому changesets/action обнаруживает изменение версии и:

   • npm publish (OIDC trusted publishing с аттестацией происхождения)

   • Автоматически создаёт GitHub Release и git-тег

5. Финальные шаги воркфлоу устанавливают mcp-publisher, выполняют аутентификацию через DNS-приватный ключ и публикуют в MCP Registry под именем com.ffmpeg-micro/mcp-server.

Защита синхронизации версий

.github/workflows/release.yml дополнительно выполняет проверку равенства версий при каждом пуше в main. Если package.json.version, server.json.version и server.json.packages[0].version когда-либо разойдутся, сборка завершится с явной ошибкой. Обычно scripts/sync-server-version.mjs поддерживает их в согласованном состоянии, но защита ловит ручные правки, пропустившие синхронизацию.

Проверка

После мёрджа PR Version Packages, когда воркфлоу зелёный:

npm view @ffmpeg-micro/mcp-server version
curl -s "https://registry.modelcontextprotocol.io/v0/servers?search=com.ffmpeg-micro/mcp-server" | jq '.servers[] | {v: .server.version, isLatest: ._meta."io.modelcontextprotocol.registry/official".isLatest}'

Пример: прохождение для контрибьютора

Предположим, вы добавляете новый инструмент delete_transcode. Ваш процесс PR:

git switch -c feat/delete-transcode
# ... make the code + test changes ...

npx changeset
# ? Which packages would you like to include? › @ffmpeg-micro/mcp-server
# ? Which type of change is this for @ffmpeg-micro/mcp-server? › minor
# ? Please enter a summary for this change › Add delete_transcode tool

git add .changeset/*.md src/ tests/
git commit -m "feat: add delete_transcode tool"
git push -u origin feat/delete-transcode
gh pr create

CI выполняет три проверки:

• test — модульные тесты

• check (Require changeset) — подтверждает наличие .changeset/*.md

• Vercel — превью-развёртывание

После слияния Version Packages PR либо открывается, либо обновляется автоматически, чтобы включить вашу запись. Мержите его, когда будете готовы к релизу.

Правила

• Никогда не редактируйте поля версий в server.json или package.json вручную. Changesets отвечает за оба файла — scripts/sync-server-version.mjs зеркалирует package.json в server.json. Защита от дрейфа в CI останавливает релиз, если они расходятся.

• Никогда не создавайте git tag вручную. changesets/action создаёт тег и GitHub Release в рамках публикации. Вручную созданные теги новый workflow не подхватывает.

• Никогда не обходите проверку Require-changeset, коммитя изменения в .changeset/config.json или .changeset/README.md (они не учитываются). Используйте npx changeset, метку no-changeset или npx changeset --empty.

Файлы, связанные с релизом

• package.json — источник истины для версии. Также содержит mcpName (обязателен для MCP Registry при валидации npm-пакета). Обновляется командой changeset version.

• server.json — метаданные MCP Registry. Поля версий автоматически синхронизируются из package.json.

• .changeset/config.json — конфигурация Changesets (публичный доступ, форматтер changelog с учётом GitHub).

• .changeset/*.md — накопившиеся заметки о релизе, ожидающие обработки следующим запуском changeset version.

• scripts/sync-server-version.mjs — зеркалирует версию из package.json в server.json.

• .github/workflows/release.yml — конвейер публикации (changesets/action + шаг MCP Registry).

• .github/workflows/require-changeset.yml — проверяет наличие changeset в PR.

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

• Проверка Require changeset не проходит на моём PR — выполните npx changeset и закоммитьте сгенерированный файл. Для PR только с документацией / только для CI добавьте метку no-changeset или выполните npx changeset --empty.

• CI падает на шаге контроля синхронизации версий — server.json был отредактирован вручную. Локально: node scripts/sync-server-version.mjs, закоммитьте, запушьте. Контроль сравнивает package.json.version, server.json.version и server.json.packages[0].version.

• changesets/action не открыл Version Packages PR после слияния моего feature-PR — проверьте, что файл .changeset/*.md в вашем PR действительно содержал данные (непустой front matter с типом бампа и кратким описанием). Пустые changeset'ы означают «релиз не нужен» и намеренно игнорируются.

• mcp-publisher publish падает с ошибкой "package not found" — npm ещё не завершил распространение новой версии. Шаг Determine if MCP Registry publish is needed в workflow релиза повторяет запрос npm view до ~50 секунд и отступает, если версия так и не стала доступной, откладывая публикацию в реестр до следующего пуша в main (что автоматически устраняет дрейф). Если вы видите это при ручном запуске, просто подождите 30 секунд и повторите публикацию.

• MCP Registry застрял на одну версию позади npm — шаг Determine if MCP Registry publish is needed был пропущен (или вернул needed=false). Запушьте любой коммит в main, чтобы запустить повторный прогон; контроль сравнивает package.json ↔ npm ↔ registry и автоматически навёрстывает отставание. Если пропуск продолжается, посмотрите в логах шага, какую версию сообщил каждый источник.

• mcp-publisher publish не проходит валидацию с ошибкой "mcpName mismatch" — mcpName в package.json должен совпадать с name в server.json (оба должны быть com.ffmpeg-micro/mcp-server).

• mcp-publisher login dns падает с ошибкой "public key mismatch" — секрет MCP_PRIVATE_KEY больше не соответствует TXT-записи на ffmpeg-micro.com. Перегенерируйте пару ключей локально и обновите и TXT-запись, и секрет GitHub.

Лицензия

MIT — см. LICENSE.