Format Converter MCP

Универсальный MCP-сервер для конвертации форматов

Сервер Model Context Protocol (MCP), охватывающий конвертацию всех форматов: аудио, видео, изображения, Office, данные, электронные книги, PDF, субтитры и другие. Может вызываться любым MCP-клиентом, таким как TimeVerse Studio, Claude Desktop, Cursor, VS Code и другими.

English

✨ Возможности

Related MCP server: ChangeThisFile MCP Server

📦 Поддерживаемые форматы

* — ограниченные форматы (PAGES / WPS / NUMBERS / KEY), требуют нативных приложений macOS или экспорта через iCloud.

Итого после дедупликации около 71 формата, покрывающих 95%+ типовых потребностей в конвертации в отрасли.

⚠️ Известные ограничения

• Ограниченные форматы: PAGES / WPS / NUMBERS / KEY требуют нативных приложений macOS или экспорта через iCloud; на других платформах обычно напрямую не конвертируются.

• Декодирование HEIC/HEIF: зависит от поддержки libheif в ImageMagick; при отсутствии декодирование эффективных изображений Apple невозможно.

• Понижение при отсутствии движка: если LaTeX не установлен, Markdown→PDF понижается до weasyprint; если Calibre не установлен, электронные книги MOBI/AZW3 недоступны; если ImageMagick не установлен, конвертация изображений откатывается на Python Pillow (с более ограниченными возможностями).

• Protocol Buffers: для конвертации в PB требуются дополнительные файлы определения .proto.

• Parquet / Protobuf: соответствующие зависимости Python (pyarrow, protobuf) являются опциональными и требуют ручной установки.

🧰 Список инструментов

Основные инструменты конвертации (10)

Вспомогательные инструменты (4)

Все инструменты конвертации единообразно следуют парадигме параметров input_path + output_format + options.

🏗️ Архитектура

┌─────────────────────────────────────────────────────┐
│              MCP Client (LLM)                        │
│        Claude / Cursor / VS Code / ...               │
└──────────────────────┬──────────────────────────────┘
                       │ JSON-RPC (stdio)
┌──────────────────────┴──────────────────────────────┐
│           MCP Protocol Layer                         │
│      tool list · tool call · notifications           │
├──────────────────────────────────────────────────────┤
│           Tool Router Layer                          │
│    请求解析 → 格式识别 → 路由分发 → 结果封装           │
├───────────┬───────────┬──────────┬───────────────────┤
│  Format   │ Conversion│  File    │  Dependency       │
│  Registry │  Planner  │ Manager  │  Checker          │
├───────────┴───────────┴──────────┴───────────────────┤
│           Conversion Engine Layer                    │
│  FFmpeg · ImageMagick · LibreOffice · Pandoc         │
│  Python · PDF                                         │
└──────────────────────────────────────────────────────┘

Примеры умного планирования путей:

⚙️ Технологический стек

• Основной язык: TypeScript (Node.js ≥ 18)

• Протокол: @modelcontextprotocol/sdk

• Движки конвертации: FFmpeg / ImageMagick / LibreOffice / Pandoc / Python (изоляция venv) / PyMuPDF

Системные зависимости

LaTeX (опционально, высокое качество Markdown→PDF) и Calibre (опционально, MOBI/AZW3) могут отсутствовать — система автоматически понизит функциональность.

Зависимости Python

pip install -r python/requirements.txt

Основные зависимости: openpyxl, pandas, PyYAML, tomlkit, xmltodict, PyMuPDF, pypdf, pdf2docx, pysubs2, Pillow (pyarrow, protobuf — опциональные).

🚀 Установка

Сначала установите системные зависимости (FFmpeg / ImageMagick / LibreOffice / Pandoc):

• Windows: npm run prepare-deps (однокликовая загрузка портативных версий)

• macOS: brew install ffmpeg imagemagick pandoc && brew install --cask libreoffice

• Linux: apt install ffmpeg imagemagick libreoffice pandoc

Затем соберите проект и установите зависимости Python:

# 1. 安装 Node 依赖
npm install

# 2. 构建（生成 dist/）
npm run build

# 3. 安装 Python 依赖（建议使用虚拟环境）
python3 -m venv .venv        # macOS/Linux；Windows 使用 python
source .venv/bin/activate    # macOS/Linux；Windows 使用 .venv\Scripts\activate
pip install -r python/requirements.txt

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

Добавьте следующий сервер в конфигурацию mcpServers вашего MCP-клиента.

TimeVerse Studio (рекомендуется · размещение через npm)

TimeVerse Studio подключается через стандартный JSON mcpServers. После публикации в npm запускается одной командой через npx, без локальной сборки:

{
  "mcpServers": {
    "timeverse-omni-converter-mcp": {
      "command": "npx",
      "args": ["-y", "timeverse-omni-converter-mcp"],
      "env": {
        "FC_PYTHON_PATH": "python",
        "FC_TEMP_DIR": "C:/temp/format-converter",
        "FC_MAX_FILE_SIZE": "524288000",
        "FC_TIMEOUT": "300000"
      }
    }
  }
}

Claude Desktop / Cursor (локальная сборка)

После локальной сборки запускается напрямую через node:

{
  "mcpServers": {
    "timeverse-omni-converter-mcp": {
      "command": "node",
      "args": ["C:/path/to/timeverse-omni-converter-mcp/dist/index.js"],
      "env": {
        "FC_PYTHON_PATH": "python",
        "FC_TEMP_DIR": "C:/temp/format-converter",
        "FC_MAX_FILE_SIZE": "524288000",
        "FC_TIMEOUT": "300000"
      }
    }
  }
}

macOS: измените args на /Users/<you>/timeverse-omni-converter-mcp/dist/index.js и установите FC_PYTHON_PATH в python3 (или удалите этот пункт, чтобы он автоматически определял .venv/python3).

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

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

Дайте LLM в MCP-клиенте команды на естественном языке, например:

• «Конвертируй a.mov в a.mp4, разрешение 1920x1080» → convert_media

• «Конвертируй photo.heic в photo.png» → convert_image

• «Конвертируй report.docx в report.pdf» → convert_document

• «Конвертируй data.json в data.csv» → convert_data

• «Экспортируй каждую страницу slides.pptx в PNG» → convert_presentation

• «Конвертируй book.epub в book.mobi» → convert_ebook

• «Объедини a.pdf и b.pdf» → convert_pdf (operation: "merge")

• «Конвертируй subs.ass в subs.srt» → convert_subtitle

Пример вызова инструмента:

{
  "name": "convert_media",
  "arguments": {
    "input_path": "C:/media/input.mov",
    "output_format": "mp4",
    "options": {
      "video_codec": "libx264",
      "video_resolution": "1920x1080",
      "crf": 23
    }
  }
}

Возвращаемый результат:

{
  "success": true,
  "outputPath": "C:/media/input.mp4",
  "outputSize": 10485760,
  "duration": 3215,
  "warnings": []
}

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

В: Что делать, если конвертация сообщает об отсутствии зависимостей или ошибке? О: Вызовите инструмент check_dependencies, чтобы увидеть статус доступности и версии каждого движка (FFmpeg / ImageMagick / LibreOffice / Pandoc / Python), установите недостающие зависимости и повторите попытку.

В: Ошибки при конвертации, связанной с Python (данные / PDF / таблицы / субтитры)? О: Убедитесь, что зависимости установлены через pip install -r python/requirements.txt, и что FC_PYTHON_PATH указывает на правильный интерпретатор Python (или активирована виртуальная среда).

В: Что произойдёт, если целевой файл уже существует? О: По умолчанию файл автоматически переименовывается в имя_файла_1.расширение; при пакетной конвертации поведение можно управлять параметром on_conflict: overwrite / skip / rename.

В: Почему некоторые форматы (например, PAGES / NUMBERS) не конвертируются? О: Это проприетарные форматы Apple, требующие нативных приложений macOS или экспорта через iCloud; это ограниченные форматы, подробнее см. «Известные ограничения».

В: Что делать при таймауте конвертации больших файлов? О: Увеличьте FC_TIMEOUT (по умолчанию 300000 мс) и обратите внимание на верхний предел FC_MAX_FILE_SIZE (по умолчанию 500MB).

🛡️ Безопасность

Сервер обрабатывает содержимое недоверенных файлов и имеет встроенные механизмы защиты ресурсов и безопасности:

• Верхние пределы размера входного файла, объёма после распаковки, коэффициента сжатия, пикселей изображения (защита от zip bomb / бомб распаковки)

• Таймаут одной конвертации и верхний предел параллелизма

• В парсерах отключены XXE (внедрение внешних сущностей), встроенные скрипты PDF, загрузка внешних ресурсов

• Внешние процессы единообразно вызываются через массивы аргументов (execFile), что исключает внедрение команд

📄 License

MIT