media-mcp (Node.js)

中文 | English

Сервис для улучшения видео и сегментации изображений на основе протокола MCP, взаимодействующий с бэкенд-сервером HTTP в качестве MCP Client-Server.

Функции

Предоставляет следующие инструменты MCP:

• create_task — создание задачи по улучшению видео (поддерживает URL или загрузку локальных файлов)

• get_task_status — запрос статуса задачи

• enhance_video_sync — синхронное улучшение видео (блокирующее ожидание завершения)

• sam3_predict — сегментация изображений SAM3 (поддерживает локальные пути, URL или изображения в формате Base64)

Related MCP server: Grok Imagine Video MCP Server

Предварительные требования

• Node.js >= 18 (проверка: node --version)

• API Key (для аутентификации, обратитесь к поставщику услуг для получения)

Установка для ленивых (рекомендуется)

Если у вашего AI-агента есть определенный путь конфигурации MCP, просто скопируйте следующую строку и отправьте её ИИ:

帮我安装 npm 包 @avclabs.ai/media-mcp 作为 MCP server。我的 API Key 是：sk-xxxxxxxx。

ИИ автоматически выполнит:

1. Обнаружение используемого вами MCP-клиента

2. Поиск пути к файлу конфигурации

3. Запись правильной конфигурации

4. Предложение перезапустить клиент

Ручная установка

Установка не требуется, используйте npx непосредственно в конфигурации MCP-клиента.

1. Claude Code (CLI)

Запустите в Claude Code:

/mcp

Найдите путь к файлу конфигурации, соответствующий "User MCPs" в выводе, и отредактируйте этот файл.

Типичные пути (если /mcp недоступен):

• Windows: %USERPROFILE%\.claude.json

• macOS: ~/.claude.json

• Linux: ~/.claude.json

• Старая версия/резерв: ~/.claude/mcp.json

Вставьте следующее содержимое (замените your-api-key на ваш реальный API Key):

{
  "mcpServers": {
    "video-enhancement": {
      "command": "npx",
      "args": ["-y", "@avclabs.ai/media-mcp@latest"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

После сохранения выполните /mcp для проверки успешности загрузки.

2. Cursor

Перейдите в Settings > Tools & MCPs > Add New MCP Server:

• Name: video-enhancement

• Type: command

• Command:

  env HTTP_API_KEY=your-api-key npx -y @avclabs.ai/media-mcp@latest

Или отредактируйте ~/.cursor/mcp.json:

{
  "mcpServers": {
    "video-enhancement": {
      "command": "npx",
      "args": ["-y", "@avclabs.ai/media-mcp@latest"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Проверка установки

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

1. Либо просто спросите ИИ: "Какие инструменты у тебя есть?"

2. Вы должны увидеть: create_task, get_task_status, enhance_video_sync, sam3_predict

Параметры конфигурации

Пользовательский адрес сервиса

{
  "env": {
    "HTTP_API_BASE_URL": "https://your-endpoint.com",
    "API_KEY": "your-api-key",
    "SAM3_API_BASE_URL": "http://localhost:8001"
  }
}

Или через аргументы командной строки:

npx -y @avclabs.ai/media-mcp@latest --base-url https://your-endpoint.com --api-key your-api-key --sam3-base-url http://localhost:8001

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

После настройки скажите ИИ на естественном языке:

"Помоги мне улучшить это видео до 1080p: https://example.com/video.mp4"

"Улучши качество видео video.mp4 с моего рабочего стола до 2k"

ИИ автоматически вызовет соответствующий инструмент для выполнения задачи.

"Помоги мне проанализировать это изображение и найти все объекты на нем: C:\Users\xxx\photo.png"

"Используй SAM3 для сегментации этого изображения, промпт: 'find all cars'"

Предоставляемые инструменты

create_task

Создание задачи по улучшению видео (асинхронно).

Возвращаемое значение:

{
  "success": true,
  "task_id": "xxx",
  "status": "wait"
}

get_task_status

Запрос статуса задачи.

Возвращаемое значение:

{
  "success": true,
  "task_id": "xxx",
  "status": "completed",
  "progress": 100,
  "video_url": "https://..."
}

enhance_video_sync

Синхронное улучшение видео (блокирующее ожидание завершения).

sam3_predict

Использование API сегментации SAM3 для анализа изображения и генерации результатов вывода (маски, рамки, оценки).

Параметры:

Ввод изображения (один из трех, обязательно предоставление одного из них):

• imagePath (string): Абсолютный путь к локальному изображению. Поддерживаются распространенные форматы (например, PNG, JPG, JPEG).

• imageUrl (string): Публично доступный URL изображения.

• imageBase64 (string): Данные изображения в кодировке Base64.

Другие параметры:

• prompt (string, required): Текстовая подсказка на английском языке для указания целевых объектов для сегментации. Например, "person", "car", "a cat sitting on a sofa". Поскольку модель SAM3 принимает только английские промпты, рекомендуется передавать описание на английском.

Возврат:

После завершения вывода возвращается JSON-строка, содержащая поля masks, boxes и scores.

Пример содержимого JSON результата:

{
  "masks": [
    [[0, 0, 1, ...], [0, 1, 1, ...], ...],
    [[0, 0, 0, ...], [0, 0, 1, ...], ...]
  ],
  "boxes": [
    [120, 80, 300, 450],
    [400, 200, 600, 500]
  ],
  "scores": [0.95, 0.87]
}

Часто задаваемые вопросы

Ошибка "файл не найден" после перетаскивания вложения?

Это известное ограничение stdio MCP. При перетаскивании или загрузке вложений через интерфейс агента путь к файлу обычно не передается автоматически в MCP Server.

Решение:

1. Укажите путь вручную (рекомендуется): после перетаскивания изображения добавьте в тексте абсолютный путь к локальному файлу.

2. Дождитесь автоматического кодирования: Claude может автоматически закодировать изображение в base64.

3. Ответьте на запрос пути: если Claude спрашивает путь, просто укажите абсолютный путь.

Есть ли приоритет у трех способов ввода?

Строгого приоритета нет. Claude автоматически выбирает наиболее подходящий способ в зависимости от контекста диалога.

Какие форматы изображений поддерживаются?

Поддерживаются распространенные форматы: PNG, JPG, JPEG, BMP, WebP и т.д.

Что делать, если загрузка изображения по URL не удалась?

Убедитесь, что URL является публично доступным и не требует входа, Cookie или подписи.

Что делать, если Base64 изображение слишком большое?

Если изображение очень большое (например, 4K), данные в кодировке base64 будут очень тяжелыми. Рекомендуется использовать imagePath.

Инструкции по загрузке файлов

Когда type равен "local", MCP Server:

1. Считывает локальный файл

2. Загружает его напрямую в объектное хранилище TOS через предварительно подписанный URL

3. Максимальный размер файла: 100 МБ

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

"command not found: npx"

Установите Node.js >= 18: https://nodejs.org/

"Ошибка: необходимо предоставить --api-key или установить API_KEY"

Отсутствует API Key, проверьте env.API_KEY в конфигурации.

MCP Server отображается красным/ошибкой в клиенте

Проверьте логи:

• Claude Desktop macOS: ~/Library/Logs/Claude/mcp*.log

• Claude Desktop Windows: %APPDATA%\Claude\logs\mcp*.log

• Cursor: Панель Output > MCP

"Ошибка загрузки TOS"

Обычно это несоответствие подписи, убедитесь, что HTTP_API_BASE_URL и HTTP_API_KEY верны.

Глобальная установка (опционально)

Если вы не хотите использовать npx каждый раз:

npm install -g @avclabs.ai/media-mcp

Затем используйте "command": "media-mcp" с "args": ["--api-key", "your-api-key"] в конфигурации.

Лицензия

MIT License - подробнее см. файл LICENSE