Pandoc

Incluído oficialmente no projeto open-source Model Context Protocol servers. 🎉

Visão Geral

Um servidor Model Context Protocol para conversão de formatos de documentos usando pandoc. Este servidor fornece ferramentas para transformar conteúdo entre diferentes formatos de documentos, preservando formatação e estrutura.

Observe que o mcp-pandoc está atualmente em desenvolvimento inicial. O suporte a PDF está em desenvolvimento, e a funcionalidade e as ferramentas disponíveis estão sujeitas a mudanças e expansões à medida que continuamos a melhorar o servidor.

Crédito: Este projeto usa o Pandoc Python package para conversão de documentos, formando a base para este projeto.

📋 Referência Rápida

Novo no mcp-pandoc? Consulte 📖 CHEATSHEET.md para

• ⚡ Exemplos de copiar e colar para todos os formatos
• 🔄 Matriz de conversão bidirecional
• 🎯 Fluxos de trabalho comuns e dicas profissionais
• 🌟 Guia de estilo de documento de referência

Perfeito para consultas rápidas e para começar rapidamente!

Demonstração

🎥 Assista no YouTube

Capturas de tela

Mais em breve...

Ferramentas

1. convert-contents

   • Transforma conteúdo entre formatos suportados

   • Entradas:

     • contents (string): Conteúdo de origem para converter (obrigatório se input_file não for fornecido)
     • input_file (string): Caminho completo para o arquivo de entrada (obrigatório se contents não for fornecido)
     • input_format (string): Formato de origem do conteúdo (padrão: markdown)
     • output_format (string): Formato de destino (padrão: markdown)
     • output_file (string): Caminho completo para o arquivo de saída (obrigatório para formatos pdf, docx, rst, latex, epub, odt, pptx)
     • reference_doc (string): Caminho para um documento de referência para usar na estilização (suportado para saída docx, odt e pptx; o arquivo deve corresponder ao formato de saída)
     • defaults_file (string): Caminho para um arquivo de padrões do Pandoc (YAML) contendo opções de conversão
     • filters (array): Lista de caminhos de filtros do Pandoc para aplicar durante a conversão

   • Formatos suportados, por direção:

     Formato	Leitura	Escrita
     markdown	✅	✅
     html	✅	✅
     docx	✅	✅
     odt	✅	✅
     rst	✅	✅
     latex	✅	✅
     epub	✅	✅
     ipynb	✅	✅
     txt	✅	✅
     pdf	❌	✅
     pptx	❌	✅

   • Nota: Para formatos avançados (pdf, docx, rst, latex, epub, odt, pptx), um caminho de output_file é obrigatório

🔧 Recursos Avançados

Arquivos de Padrões (Configuração YAML)

Use arquivos de padrões para criar modelos de conversão reutilizáveis com formatação consistente:

# academic-paper.yaml
from: markdown
to: pdf
number-sections: true
toc: true
metadata:
  title: "Academic Paper"
  author: "Research Team"

Exemplo de uso: "Convert paper.md to PDF using defaults academic-paper.yaml and save as paper.pdf"

Filtros do Pandoc

Aplique filtros personalizados para processamento aprimorado:

Exemplo de uso: "Convert docs.md to HTML with filters ['/path/to/mermaid-filter.py'] and save as docs.html"

💡 Para exemplos abrangentes e fluxos de trabalho, consulte CHEATSHEET.md

📊 Formatos e Conversões Suportados

Matriz de Conversão Bidirecional

As linhas são formatos de origem, as colunas são destinos. PDF e PPTX não têm linhas porque o pandoc não pode lê-los.

Uma Nota sobre Formatos Somente de Escrita

PDF e PPTX podem ser produzidos, mas não lidos.

O Pandoc nunca incluiu um leitor de PDF. O Pandoc ganhou um leitor de PowerPoint na versão 3.8.3 (lançada em 2025-12-01), mas este projeto não declara uma versão mínima do pandoc, e o Ubuntu 24.04 ainda inclui o pandoc 3.1.3, então a entrada pptx não é oferecida. Rastreado em #54 e #49.

A saída PPTX não requer uma versão específica do pandoc. O escritor do PowerPoint existe desde o pandoc 2.0.5.

Categorias de Formatos

Requisitos por Formato

• PDF (.pdf) - requer instalação do TeX Live
• DOCX (.docx), ODT (.odt), PPTX (.pptx) - suportam estilização personalizada via documentos de referência, e a referência deve ser do mesmo formato que a saída
• Todos os outros - sem requisitos adicionais

Nota: Para formatos avançados:

1. Caminhos de arquivo completos com nome e extensão são obrigatórios
2. A conversão de PDF requer instalação do TeX Live (veja a seção Requisitos Críticos -> Para macOS: brew install texlive)
3. Quando nenhum caminho de saída é especificado:
   • Formatos básicos: Exibe o conteúdo convertido no chat
   • Formatos avançados: Pode salvar no diretório temporário do sistema (/tmp/ em sistemas Unix)

Uso e configuração

NOTA: Certifique-se de concluir a instalação dos pacotes necessários mencionados abaixo em 'Requisitos Críticos'.

Para usar a versão publicada

{
  "mcpServers": {
    "mcp-pandoc": {
      "command": "uvx",
      "args": ["mcp-pandoc"]
    }
  }
}

💡 Início Rápido: Consulte CHEATSHEET.md para exemplos de copiar e colar e fluxos de trabalho comuns.

⚠️ Notas Importantes

Requisitos Críticos

1. Instalação do Pandoc

• Obrigatório: Instale pandoc - o mecanismo central de conversão de documentos

• Instalação:

  # macOS
  brew install pandoc
  
  # Ubuntu/Debian
  sudo apt-get install pandoc
  
  # Windows
  # Download installer from: https://pandoc.org/installing.html
  

• Verifique: pandoc --version

2. Instalação do pacote UV

• Obrigatório: Instale o pacote uv (inclui o comando uvx)

• Instalação:

  # macOS
  brew install uv
  
  # Windows/Linux
  pip install uv
  

• Verifique: uvx --version

3. Pré-requisitos para conversão de PDF: Necessário apenas se você precisar converter e salvar PDF

• O TeX Live deve ser instalado antes de tentar a conversão de PDF

• Comandos de instalação:

  # Ubuntu/Debian
  sudo apt-get install texlive-xetex
  
  # macOS
  brew install texlive
  
  # Windows
  # Install MiKTeX or TeX Live from:
  # https://miktex.org/ or https://tug.org/texlive/
  

4. Requisitos de Caminho de Arquivo

• Ao salvar ou converter arquivos, você DEVE fornecer caminhos completos, incluindo nome do arquivo e extensão
• A ferramenta não gera automaticamente nomes de arquivo ou extensões

Exemplos

✅ Uso Correto:

# Converting content to PDF
"Convert this text to PDF and save as /path/to/document.pdf"

# Converting between file formats
"Convert /path/to/input.md to PDF and save as /path/to/output.pdf"

# Converting to DOCX with a reference document template
"Convert input.md to DOCX using template.docx as reference and save as output.docx"

# Converting to ODT with a reference document template
"Convert input.md to ODT using template.odt as reference and save as output.odt"

# Converting to a branded PowerPoint deck
"Convert slides.md to PPTX using template.pptx as reference and save as deck.pptx"

# Step-by-step reference document workflow
"First create a reference document: pandoc -o custom-reference.docx --print-default-data-file reference.docx" or if you already have one, use that
"Then convert with custom styling: Convert this text to DOCX using /path/to/custom-reference.docx as reference and save as /path/to/styled-output.docx"

❌ Uso Incorreto:

# Missing filename and extension
"Save this as PDF in /documents/"

# Missing complete path
"Convert this to PDF"

# Missing extension
"Save as /documents/story"

Problemas Comuns e Soluções

1. Falha na Conversão de PDF

   • Erro: "xelatex not found"
   • Solução: Instale o TeX Live primeiro (veja os comandos de instalação acima)

2. Falha na Conversão de Arquivo

   • Erro: "Invalid file path"
   • Solução: Forneça o caminho completo, incluindo nome do arquivo e extensão
   • Exemplo: /path/to/document.pdf em vez de apenas /path/to/

3. Falha na Conversão de Formato

   • Erro: "Unsupported format"
   • Solução: Use apenas formatos suportados:
     • Básicos: txt, html, markdown
     • Avançados: pdf, docx, rst, latex, epub

4. Problemas com Documento de Referência

   • Erro: "Reference document not found"
   • Solução: Certifique-se de que o caminho do documento de referência existe e é acessível
   • Erro: "reference_doc must be a '.odt' file when output_format is 'odt'"
   • Solução: O documento de referência deve ser do mesmo formato que a saída. O Pandoc não verifica isso por conta própria: uma referência incompatível é silenciosamente ignorada para saída DOCX e produz um arquivo ODT que não pode ser aberto
   • Nota: Documentos de referência funcionam com formatos de saída DOCX, ODT e PPTX
   • Como criar: pandoc -o reference.docx --print-default-data-file reference.docx, e da mesma forma com reference.odt ou reference.pptx

Início Rápido

Instalando manualmente via arquivo de configuração claude_desktop_config.json

• No MacOS: open ~/Library/Application\ Support/Claude/claude_desktop_config.json
• No Windows: %APPDATA%/Claude/claude_desktop_config.json

a) Apenas para desenvolvimento local e contribuição para este repositório

"mcpServers": {
  "mcp-pandoc": {
    "command": "uv",
    "args": [
      "--directory",
      "<DIRECTORY>/mcp-pandoc",
      "run",
      "mcp-pandoc"
    ]
  }
}

b) Configuração de Servidores Publicados - Os consumidores devem usar esta configuração

"mcpServers": {
  "mcp-pandoc": {
    "command": "uvx",
    "args": [
      "mcp-pandoc"
    ]
  }
}

• Se você enfrentar qualquer problema, use a 'Configuração de Servidores Publicados' acima diretamente em vez desta cli.

Nota: Para usar o mcp-pandoc configurado localmente, siga o passo 'Configuração de Servidores de Desenvolvimento/Não Publicados' acima.

Desenvolvimento

Testes

Para executar a suíte de testes abrangente e validar todas as conversões bidirecionais suportadas, use o seguinte comando:

uv run pytest tests/test_conversions.py

Isso garante compatibilidade retroativa e verifica a funcionalidade principal da ferramenta.

Construção e Publicação

Para preparar o pacote para distribuição:

1. Sincronize as dependências e atualize o arquivo de bloqueio:

uv sync

2. Construa as distribuições do pacote:

uv build

Isso criará distribuições de origem e wheel no diretório dist/.

3. Publique no PyPI:

uv publish

Nota: Você precisará definir as credenciais do PyPI via variáveis de ambiente ou flags de comando:

• Token: --token ou UV_PUBLISH_TOKEN
• Ou usuário/senha: --username/UV_PUBLISH_USERNAME e --password/UV_PUBLISH_PASSWORD

Depuração

Como os servidores MCP rodam via stdio, a depuração pode ser desafiadora. Para a melhor experiência de depuração, recomendamos fortemente o uso do MCP Inspector.

Você pode iniciar o MCP Inspector via npm com este comando:

npx @modelcontextprotocol/inspector uv --directory /Users/vivekvells/Desktop/code/ai/mcp-pandoc run mcp-pandoc

Ao iniciar, o Inspector exibirá uma URL que você pode acessar no seu navegador para começar a depuração.

Contribuindo

Aceitamos contribuições para melhorar o mcp-pandoc! Veja como você pode participar:

1. Relate Problemas: Encontrou um bug ou tem uma solicitação de recurso? Abra uma issue na nossa página de GitHub Issues.
2. Envie Pull Requests: Melhore o código ou adicione recursos criando um pull request.