Markdownify MCP Server

Un servidor que convierte varios tipos de archivos, incluyendo documentos, imágenes, audio y páginas web, al formato Markdown.

GitHub
15
Prueba este MCPPatrocinado

Documentación

Markdownify MCP Server - Mejorado con UTF-8

Esta es una versión mejorada del proyecto original Markdownify MCP, con soporte mejorado de codificación UTF-8 y manejo optimizado de contenido multilingüe.

中文文档

Mejoras

  • Se añadió soporte integral de codificación UTF-8
  • Manejo optimizado de contenido multilingüe
  • Se corrigieron problemas de codificación en sistemas Windows
  • Mecanismos mejorados de manejo de errores

Diferencias clave con el proyecto original

  1. Soporte de codificación mejorado:

    • Soporte completo de UTF-8 en todas las operaciones
    • Manejo adecuado de caracteres chinos, japoneses, coreanos y otros caracteres no ASCII
    • Se corrigieron problemas de codificación específicos de Windows (compatibilidad con cmd.exe y PowerShell)

  2. Manejo de errores mejorado:

    • Mensajes de error detallados en inglés y chino
    • Mejor manejo de excepciones para problemas de red
    • Mecanismos de respaldo elegantes para fallos de conversión

  3. Funcionalidad ampliada:

    • Se añadió soporte para procesamiento por lotes de múltiples archivos
    • Manejo mejorado de transcripciones de videos de YouTube
    • Extracción mejorada de metadatos de varios formatos de archivo
    • Mejor preservación del formato de documentos

  4. Optimizaciones de rendimiento:

    • Uso de memoria optimizado para conversiones de archivos grandes
    • Procesamiento más rápido de contenido multilingüe
    • Conflictos de dependencias reducidos

  5. Mejor experiencia de desarrollo:

    • Opciones integrales de depuración
    • Sistema de registro detallado
    • Soporte de configuración específica por entorno
    • Documentación clara en inglés y chino

Características

Admite la conversión de varios tipos de archivos a Markdown:

  • Archivos PDF
  • Imágenes (con metadatos)
  • Audio (con transcripción)
  • Documentos de Word (DOCX)
  • Hojas de cálculo de Excel (XLSX)
  • Presentaciones de PowerPoint (PPTX)
  • Contenido web:
    • Transcripciones de videos de YouTube
    • Resultados de búsqueda
    • Páginas web generales
  • Archivos Markdown existentes

Inicio rápido

  1. Clona este repositorio:

    git clone https://github.com/JDJR2024/markdownify-mcp-utf8.git
cd markdownify-mcp-utf8

  2. Instala las dependencias:

    pnpm install

    Nota: Esto también instalará uv y las dependencias de Python relacionadas.

  3. Compila el proyecto:

    pnpm run build

  4. Inicia el servidor:

    pnpm start

Requisitos

  • Node.js 16.0 o superior
  • Python 3.8 o superior
  • Gestor de paquetes pnpm
  • Git

Guía de instalación detallada

1. Configuración del entorno

  1. Instala Node.js:

  2. Instala pnpm:

    npm install -g pnpm
pnpm --version

  3. Instala Python:

    • Descárgalo desde el sitio web oficial de Python
    • Asegúrate de que Python se agregue al PATH durante la instalación
    • Verifica la instalación: python --version

  4. (Solo Windows) Configura el soporte UTF-8:

    # Set system-wide UTF-8
setx PYTHONIOENCODING UTF-8
# Set current session UTF-8
set PYTHONIOENCODING=UTF-8
# Enable UTF-8 in command prompt
chcp 65001

2. Configuración del proyecto

  1. Clona el repositorio:

    git clone https://github.com/JDJR2024/markdownify-mcp-utf8.git
cd markdownify-mcp-utf8

  2. Crea y activa el entorno virtual de Python:

    # Windows
python -m venv .venv
.venv\Scripts\activate

# Linux/macOS
python3 -m venv .venv
source .venv/bin/activate

  3. Instala las dependencias del proyecto:

    # Install Node.js dependencies
pnpm install

# Install Python dependencies (will be handled by setup.sh)
./setup.sh

  4. Compila el proyecto:

    pnpm run build

3. Verificación

  1. Inicia el servidor:

    pnpm start

  2. Prueba la instalación:

    # Convert a web page
python convert_utf8.py "https://example.com"

# Convert a local file
python convert_utf8.py "path/to/your/file.docx"

Guía de uso

Uso básico

  1. Conversión de páginas web:

    python convert_utf8.py "https://example.com"

    El markdown convertido se guardará como converted_result.md

  2. Conversión de archivos locales:

    # Convert DOCX
python convert_utf8.py "document.docx"

# Convert PDF
python convert_utf8.py "document.pdf"

# Convert PowerPoint
python convert_utf8.py "presentation.pptx"

# Convert Excel
python convert_utf8.py "spreadsheet.xlsx"

  3. Conversión de videos de YouTube:

    python convert_utf8.py "https://www.youtube.com/watch?v=VIDEO_ID"

Uso avanzado

  1. Variables de entorno:

    # Set custom UV path
export UV_PATH="/custom/path/to/uv"

# Set custom output directory
export MARKDOWN_OUTPUT_DIR="/custom/output/path"

  2. Procesamiento por lotes: Crea un archivo por lotes (por ejemplo, convert_batch.txt) con URLs o rutas de archivo:

    https://example1.com
https://example2.com
file1.docx
file2.pdf

    Luego ejecuta:

    while read -r line; do python convert_utf8.py "$line"; done < convert_batch.txt

Solución de problemas

  1. Problemas comunes:

    • Si ves errores de codificación, asegúrate de que UTF-8 esté configurado correctamente
    • Para problemas de permisos en Windows, ejecuta como Administrador
    • Para problemas de ruta de Python, asegúrate de que el entorno virtual esté activado

  2. Depuración:

    # Enable debug output
export DEBUG=true
python convert_utf8.py "your_file.docx"

Uso

Línea de comandos

Convierte una página web a Markdown:

python convert_utf8.py "https://example.com"

Convierte un archivo local:

python convert_utf8.py "path/to/your/file.docx"

Integración con aplicaciones de escritorio

Para integrar este servidor con una aplicación de escritorio, agrega lo siguiente a la configuración del servidor de tu aplicación:

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "{ABSOLUTE_PATH}/dist/index.js"
      ],
      "env": {
        "UV_PATH": "/path/to/uv"
      }
    }
  }
}

Solución de problemas

  1. Problemas de codificación

    • Si encuentras problemas de codificación de caracteres, asegúrate de que la variable de entorno PYTHONIOENCODING esté configurada en utf-8
    • Los usuarios de Windows pueden necesitar ejecutar chcp 65001 para habilitar el soporte UTF-8

  2. Problemas de permisos

    • Asegúrate de tener permisos suficientes de lectura/escritura de archivos
    • En Windows, es posible que necesites ejecutar como administrador

Agradecimientos

Este proyecto se basa en el trabajo original de Zach Caceres. Gracias al autor original por su destacada contribución.

Licencia

Este proyecto continúa bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.

Contribuciones

¡Las contribuciones son bienvenidas! Antes de enviar un Pull Request, por favor:

  1. Asegúrate de que tu código siga los estándares de codificación del proyecto
  2. Agrega las pruebas y documentación necesarias
  3. Actualiza las secciones relevantes del README

Contacto

Para problemas o sugerencias:

  1. Envía un Issue: https://github.com/JDJR2024/markdownify-mcp-utf8/issues
  2. Crea un Pull Request: https://github.com/JDJR2024/markdownify-mcp-utf8/pulls
  3. Correo electrónico: jdidndosmmxmx@gmail.com