Markdownify MCP Server

Um servidor que

GitHub
15

Documentação

Markdownify MCP Server - Aprimorado com UTF-8

Esta é uma versão aprimorada do projeto original Markdownify MCP, com suporte melhorado de codificação UTF-8 e tratamento otimizado de conteúdo multilíngue.

中文文档

Aprimoramentos

  • Adicionado suporte abrangente de codificação UTF-8
  • Otimizado o tratamento de conteúdo multilíngue
  • Corrigidos problemas de codificação em sistemas Windows
  • Melhorados os mecanismos de tratamento de erros

Principais Diferenças do Projeto Original

  1. Suporte de Codificação Aprimorado:

    • Suporte completo a UTF-8 em todas as operações
    • Tratamento adequado de caracteres chineses, japoneses, coreanos e outros não-ASCII
    • Corrigidos problemas específicos de codificação no Windows (compatibilidade com cmd.exe e PowerShell)

  2. Tratamento de Erros Melhorado:

    • Mensagens de erro detalhadas em inglês e chinês
    • Melhor tratamento de exceções para problemas de rede
    • Mecanismos de fallback graciosos para falhas de conversão

  3. Funcionalidade Estendida:

    • Adicionado suporte para processamento em lote de múltiplos arquivos
    • Tratamento aprimorado de transcrições de vídeos do YouTube
    • Extração de metadados melhorada de vários formatos de arquivo
    • Melhor preservação da formatação de documentos

  4. Otimizações de Desempenho:

    • Uso de memória otimizado para conversões de arquivos grandes
    • Processamento mais rápido de conteúdo multilíngue
    • Conflitos de dependências reduzidos

  5. Melhor Experiência de Desenvolvimento:

    • Opções abrangentes de depuração
    • Sistema de registro detalhado
    • Suporte a configuração específica por ambiente
    • Documentação clara em inglês e chinês

Recursos

Suporta a conversão de vários tipos de arquivo para Markdown:

  • Arquivos PDF
  • Imagens (com metadados)
  • Áudio (com transcrição)
  • Documentos do Word (DOCX)
  • Planilhas do Excel (XLSX)
  • Apresentações do PowerPoint (PPTX)
  • Conteúdo da web:
    • Transcrições de vídeos do YouTube
    • Resultados de pesquisa
    • Páginas web em geral
  • Arquivos Markdown existentes

Início Rápido

  1. Clone este repositório:

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

  2. Instale as dependências:

    pnpm install

    Nota: Isso também instalará uv e dependências Python relacionadas.

  3. Compile o projeto:

    pnpm run build

  4. Inicie o servidor:

    pnpm start

Requisitos

  • Node.js 16.0 ou superior
  • Python 3.8 ou superior
  • Gerenciador de pacotes pnpm
  • Git

Guia de Instalação Detalhado

1. Configuração do Ambiente

  1. Instale o Node.js:

  2. Instale o pnpm:

    npm install -g pnpm
pnpm --version

  3. Instale o Python:

    • Baixe do site oficial do Python
    • Certifique-se de que o Python foi adicionado ao PATH durante a instalação
    • Verifique a instalação: python --version

  4. (Somente Windows) Configure o suporte a 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. Configuração do Projeto

  1. Clone o repositório:

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

  2. Crie e ative o ambiente virtual Python:

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

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

  3. Instale as dependências do projeto:

    # Install Node.js dependencies
pnpm install

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

  4. Compile o projeto:

    pnpm run build

3. Verificação

  1. Inicie o servidor:

    pnpm start

  2. Teste a instalação:

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

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

Guia de Uso

Uso Básico

  1. Convertendo Páginas Web:

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

    O markdown convertido será salvo como converted_result.md

  2. Convertendo Arquivos Locais:

    # 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. Convertendo Vídeos do YouTube:

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

Uso Avançado

  1. Variáveis de Ambiente:

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

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

  2. Processamento em Lote: Crie um arquivo em lote (por exemplo, convert_batch.txt) com URLs ou caminhos de arquivo:

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

    Em seguida, execute:

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

Solução de Problemas

  1. Problemas Comuns:

    • Se você encontrar erros de codificação, certifique-se de que o UTF-8 está configurado corretamente
    • Para problemas de permissão no Windows, execute como Administrador
    • Para problemas de caminho do Python, certifique-se de que o ambiente virtual está ativado

  2. Depuração:

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

Uso

Linha de Comando

Converter página web para Markdown:

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

Converter arquivo local:

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

Integração com Aplicativo Desktop

Para integrar este servidor com um aplicativo desktop, adicione o seguinte à configuração do servidor do seu aplicativo:

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

Solução de Problemas

  1. Problemas de Codificação

    • Se você encontrar problemas de codificação de caracteres, certifique-se de que a variável de ambiente PYTHONIOENCODING está definida como utf-8
    • Usuários do Windows podem precisar executar chcp 65001 para habilitar o suporte a UTF-8

  2. Problemas de Permissão

    • Certifique-se de ter permissões suficientes de leitura/escrita de arquivos
    • No Windows, você pode precisar executar como administrador

Agradecimentos

Este projeto é baseado no trabalho original de Zach Caceres. Agradecemos ao autor original por sua excelente contribuição.

Licença

Este projeto continua licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.

Contribuições

Contribuições são bem-vindas! Antes de enviar um Pull Request, por favor:

  1. Certifique-se de que seu código segue os padrões de codificação do projeto
  2. Adicione os testes e a documentação necessários
  3. Atualize as seções relevantes no README

Contato

Para problemas ou sugestões:

  1. Envie um Issue: https://github.com/JDJR2024/markdownify-mcp-utf8/issues
  2. Crie um Pull Request: https://github.com/JDJR2024/markdownify-mcp-utf8/pulls
  3. E-mail: jdidndosmmxmx@gmail.com