Format Converter MCP

Universeller Formatkonverter-MCP-Server

Ein Model Context Protocol (MCP)-Server für die Konvertierung aller Formate – Audio, Video, Bilder, Office, Daten, E-Books, PDF, Untertitel u. v. m. – der von beliebigen MCP-Clients wie TimeVerse Studio, Claude Desktop, Cursor, VS Code usw. aufgerufen werden kann.

English

✨ Funktionen

Related MCP server: ChangeThisFile MCP Server

📦 Unterstützte Formate

Mit * markierte Formate sind eingeschränkt (PAGES / WPS / NUMBERS / KEY) und erfordern native macOS-Apps oder iCloud-Export.

Insgesamt nach Deduplizierung ca. 71 Formate, die über 95 % der gängigen Konvertierungsanforderungen der Branche abdecken.

⚠️ Bekannte Einschränkungen

• Eingeschränkte Formate: PAGES / WPS / NUMBERS / KEY erfordern native macOS-Apps oder iCloud-Export; auf anderen Plattformen ist eine direkte Konvertierung in der Regel nicht möglich.

• HEIC/HEIF-Dekodierung: Erfordert libheif-Unterstützung in ImageMagick; ohne diese können Apple-Hocheffizienzbilder nicht dekodiert werden.

• Engine-Degradierung: Ohne installiertes LaTeX wird Markdown→PDF auf weasyprint degradiert; ohne installiertes Calibre sind MOBI/AZW3-E-Books nicht verfügbar; ohne installiertes ImageMagick fällt die Bildkonvertierung auf Python Pillow zurück (mit eingeschränkteren Funktionen).

• Protocol Buffers: Für die Konvertierung in PB ist eine zusätzliche .proto-Definitionsdatei erforderlich.

• Parquet / Protobuf: Die entsprechenden Python-Abhängigkeiten (pyarrow, protobuf) sind optional und müssen manuell installiert werden.

🧰 Tool-Liste

Kernkonvertierungstools (10)

Hilfstools (4)

Alle Konvertierungstools folgen einheitlich dem Parameterschema input_path + output_format + options.

🏗️ Architektur

┌─────────────────────────────────────────────────────┐
│              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                                         │
└──────────────────────────────────────────────────────┘

Beispiele für intelligente Pfadplanung:

⚙️ Technologie-Stack

• Hauptsprache: TypeScript (Node.js ≥ 18)

• Protokoll: @modelcontextprotocol/sdk

• Konvertierungs-Engines: FFmpeg / ImageMagick / LibreOffice / Pandoc / Python (venv-isoliert) / PyMuPDF

Systemabhängigkeiten

LaTeX (optional, hochwertiges Markdown→PDF) und Calibre (optional, MOBI/AZW3) können fehlen; das System degradiert automatisch.

Python-Abhängigkeiten

pip install -r python/requirements.txt

Kernabhängigkeiten: openpyxl, pandas, PyYAML, tomlkit, xmltodict, PyMuPDF, pypdf, pdf2docx, pysubs2, Pillow (pyarrow, protobuf sind optional).

🚀 Installation

Zuerst die Systemabhängigkeiten installieren (FFmpeg / ImageMagick / LibreOffice / Pandoc):

• Windows: npm run prepare-deps (portable Versionen mit einem Klick herunterladen)

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

• Linux: apt install ffmpeg imagemagick libreoffice pandoc

Dann Python-Abhängigkeiten erstellen und installieren:

# 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-Konfiguration

Fügen Sie den folgenden Server zur mcpServers-Konfiguration Ihres MCP-Clients hinzu.

TimeVerse Studio (empfohlen · npm-gehostet)

TimeVerse Studio verwendet das Standard-mcpServers-JSON. Nach der Veröffentlichung auf npm kann es direkt über npx mit einem Klick ausgeführt werden, ohne lokalen Build:

{
  "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 (lokaler Build)

Nach dem lokalen Build direkt über node ausführen:

{
  "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: Ändern Sie args zu /Users/<you>/timeverse-omni-converter-mcp/dist/index.js und setzen Sie FC_PYTHON_PATH auf python3 (oder entfernen Sie den Eintrag, damit automatisch .venv/python3 erkannt wird).

🔧 Umgebungsvariablen

💬 Verwendungsbeispiele

Geben Sie dem LLM im MCP-Client natürliche Sprachbefehle, z. B.:

• „Konvertiere a.mov in a.mp4, Auflösung 1920x1080" → convert_media

• „Konvertiere photo.heic in photo.png" → convert_image

• „Konvertiere report.docx in report.pdf" → convert_document

• „Konvertiere data.json in data.csv" → convert_data

• „Exportiere jede Folie von slides.pptx als PNG" → convert_presentation

• „Konvertiere book.epub in book.mobi" → convert_ebook

• „Führe a.pdf und b.pdf zusammen" → convert_pdf (operation: "merge")

• „Konvertiere subs.ass in subs.srt" → convert_subtitle

Beispiel für einen Tool-Aufruf:

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

Rückgabeergebnis:

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

❓ Häufig gestellte Fragen

F: Was tun, wenn bei der Konvertierung fehlende Abhängigkeiten gemeldet werden oder ein Fehler auftritt? A: Rufen Sie das Tool check_dependencies auf, um den Verfügbarkeitsstatus und die Versionen der einzelnen Engines (FFmpeg / ImageMagick / LibreOffice / Pandoc / Python) zu prüfen, installieren Sie die fehlenden Abhängigkeiten und versuchen Sie es erneut.

F: Python-bezogene Konvertierungen (Daten / PDF / Tabellen / Untertitel) melden Fehler? A: Stellen Sie sicher, dass die Abhängigkeiten über pip install -r python/requirements.txt installiert wurden, und zeigen Sie mit FC_PYTHON_PATH auf den richtigen Python-Interpreter (oder aktivieren Sie die virtuelle Umgebung).

F: Was passiert, wenn die Zieldatei bereits existiert? A: Standardmäßig wird automatisch in Dateiname_1.Endung umbenannt; bei Stapelkonvertierung kann über den Parameter on_conflict zwischen overwrite / skip / rename gewählt werden.

F: Warum können bestimmte Formate (z. B. PAGES / NUMBERS) nicht konvertiert werden? A: Dies sind proprietäre Apple-Formate, die native macOS-Apps oder iCloud-Export erfordern. Sie gehören zu den eingeschränkten Formaten – siehe „Bekannte Einschränkungen".

F: Was tun bei Timeout bei der Konvertierung großer Dateien? A: Erhöhen Sie FC_TIMEOUT (Standard 300000 ms) und beachten Sie die Obergrenze von FC_MAX_FILE_SIZE (Standard 500 MB).

🛡️ Sicherheit

Der Server verarbeitet nicht vertrauenswürdige Dateiinhalte und verfügt über mehrere integrierte Ressourcen- und Sicherheitsschutzmechanismen:

• Obergrenzen für Eingabedateigröße, Volumen nach Extraktion, Kompressionsrate und Bildpixel (Schutz vor Zip-Bomben / Dekompressionsbomben)

• Timeout für einzelne Konvertierungen und Parallelitätsgrenzen

• Parser deaktivieren XXE (External Entity Injection), eingebettete PDF-Skripte und Laden externer Ressourcen

• Externe Prozesse werden einheitlich über Parameterarrays aufgerufen (execFile), um Befehlsinjektion zu vermeiden

📄 License

MIT