Format Converter MCP

Servidor MCP de conversión de formatos universal

Un servidor Model Context Protocol (MCP) que cubre la conversión de todo tipo de formatos: audio, vídeo, imagen, Office, datos, libros electrónicos, PDF, subtítulos, etc. Puede ser invocado por cualquier cliente MCP como TimeVerse Studio, Claude Desktop, Cursor, VS Code, entre otros.

English

✨ Características

Related MCP server: ChangeThisFile MCP Server

📦 Formatos compatibles

Los formatos marcados con * son formatos restringidos (PAGES / WPS / NUMBERS / KEY), que requieren aplicaciones nativas de macOS o exportación desde iCloud.

En total, aproximadamente 71 formatos tras deduplicar, cubriendo más del 95% de las necesidades de conversión habituales de la industria.

⚠️ Limitaciones conocidas

• Formatos restringidos: PAGES / WPS / NUMBERS / KEY requieren aplicaciones nativas de macOS o exportación desde iCloud; normalmente no se pueden convertir directamente en otras plataformas.

• Decodificación HEIC/HEIF: depende del soporte libheif de ImageMagick; si falta, no se pueden decodificar las imágenes eficientes de Apple.

• Degradación por motor ausente: si no está instalado LaTeX, Markdown→PDF se degrada a weasyprint; si no está instalado Calibre, los libros electrónicos MOBI/AZW3 no están disponibles; si no está instalado ImageMagick, la conversión de imágenes recurre a Python Pillow (con capacidades más limitadas).

• Protocol Buffers: la conversión a PB requiere un archivo de definición .proto adicional.

• Parquet / Protobuf: las dependencias de Python correspondientes (pyarrow, protobuf) son opcionales y deben instalarse manualmente.

🧰 Lista de herramientas

Herramientas de conversión principales (10)

Herramientas auxiliares (4)

Todas las herramientas de conversión siguen uniformemente el paradigma de parámetros input_path + output_format + options.

🏗️ Arquitectura

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

Ejemplo de planificación inteligente de rutas:

⚙️ Pila tecnológica

• Lenguaje principal: TypeScript (Node.js ≥ 18)

• Protocolo: @modelcontextprotocol/sdk

• Motores de conversión: FFmpeg / ImageMagick / LibreOffice / Pandoc / Python (aislado en venv) / PyMuPDF

Dependencias del sistema

LaTeX (opcional, Markdown→PDF de alta calidad) y Calibre (opcional, MOBI/AZW3) pueden omitirse; el sistema se degrada automáticamente.

Dependencias de Python

pip install -r python/requirements.txt

Dependencias principales: openpyxl, pandas, PyYAML, tomlkit, xmltodict, PyMuPDF, pypdf, pdf2docx, pysubs2, Pillow (pyarrow, protobuf son opcionales).

🚀 Instalación

Instale primero las dependencias del sistema (FFmpeg / ImageMagick / LibreOffice / Pandoc):

• Windows: npm run prepare-deps (descarga versiones portátiles con un clic)

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

• Linux: apt install ffmpeg imagemagick libreoffice pandoc

A continuación, compile e instale las dependencias de 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

🔌 Configuración de MCP

Añada el siguiente servidor a la configuración mcpServers de su cliente MCP.

TimeVerse Studio (recomendado · alojado en npm)

TimeVerse Studio se conecta mediante el JSON estándar mcpServers. Una vez publicado en npm, se ejecuta directamente con npx sin necesidad de compilación local:

{
  "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 (compilación local)

Tras la compilación local, ejecute directamente con 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: cambie args a /Users/<you>/timeverse-omni-converter-mcp/dist/index.js y cambie FC_PYTHON_PATH a python3 (o elimine ese elemento para que detecte automáticamente .venv/python3).

🔧 Variables de entorno

💬 Ejemplos de uso

Envíe instrucciones en lenguaje natural al LLM del cliente MCP, por ejemplo:

• «Convierte a.mov a a.mp4, resolución 1920x1080» → convert_media

• «Convierte photo.heic a photo.png» → convert_image

• «Convierte report.docx a report.pdf» → convert_document

• «Convierte data.json a data.csv» → convert_data

• «Exporta cada diapositiva de slides.pptx como PNG» → convert_presentation

• «Convierte book.epub a book.mobi» → convert_ebook

• «Fusiona a.pdf y b.pdf» → convert_pdf (operation: "merge")

• «Convierte subs.ass a subs.srt» → convert_subtitle

Ejemplo de llamada a herramienta:

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

Resultado devuelto:

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

❓ Preguntas frecuentes

P: ¿Qué hago si la conversión indica que falta una dependencia o falla? R: Llame a la herramienta check_dependencies para ver el estado de disponibilidad y la versión de cada motor (FFmpeg / ImageMagick / LibreOffice / Pandoc / Python), instale las dependencias que falten y vuelva a intentarlo.

P: ¿Las conversiones relacionadas con Python (datos / PDF / hojas de cálculo / subtítulos) dan error? R: Confirme que ha instalado las dependencias con pip install -r python/requirements.txt y que FC_PYTHON_PATH apunta al intérprete de Python correcto (o que el entorno virtual está activado).

P: ¿Qué ocurre si el archivo de destino ya existe? R: De forma predeterminada se renombra automáticamente a nombre_1.extensión; en la conversión por lotes puede controlar el comportamiento con el parámetro on_conflict: overwrite / skip / rename.

P: ¿Por qué algunos formatos (como PAGES / NUMBERS) no se pueden convertir? R: Son formatos propietarios de Apple que requieren aplicaciones nativas de macOS o exportación desde iCloud; son formatos restringidos. Consulte «Limitaciones conocidas».

P: ¿Qué hago si la conversión de archivos grandes agota el tiempo de espera? R: Aumente FC_TIMEOUT (predeterminado 300000ms) y tenga en cuenta el límite de FC_MAX_FILE_SIZE (predeterminado 500MB).

🛡️ Seguridad

El servidor procesa contenido de archivos no confiables e incorpora múltiples protecciones de recursos y seguridad:

• Límites de tamaño del archivo de entrada, volumen tras descompresión, relación de compresión y píxeles de imagen (anti zip bomb / bomba de descompresión)

• Tiempo de espera por conversión y límite de concurrencia

• Los analizadores deshabilitan XXE (inyección de entidades externas), scripts incrustados en PDF y carga de recursos externos

• Los procesos externos se invocan uniformemente con matrices de argumentos (execFile) para evitar la inyección de comandos

📄 Licencia

MIT