Pandoc

Um servidor para converter formatos de documentos usando Pandoc.

Documentação

PyPI Downloads

mcp-pandoc: Um servidor MCP de conversão de documentos

Oficialmente incluído 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ão à medida que continuamos a melhorar o servidor.

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

Demonstração

🎥 Assista no YouTube

Capturas de tela

Mais em breve...

Ferramentas

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)
- Formatos de entrada/saída suportados:
  - markdown
  - html
  - pdf
  - docx
  - rst
  - latex
  - epub
  - txt
- Nota: Para formatos avançados (pdf, docx, rst, latex, epub), um caminho de output_file é obrigatório

Formatos Suportados

Formatos atualmente suportados:

Formatos básicos (conversão direta):

Texto simples (.txt)
Markdown (.md)
HTML (.html)

Formatos avançados (exigem caminhos de arquivo completos):

PDF (.pdf) - requer instalação do TeX Live
DOCX (.docx)
RST (.rst)
LaTeX (.tex)
EPUB (.epub)

Nota: Para formatos avançados:

Caminhos de arquivo completos com nome e extensão são obrigatórios
A conversão de PDF requer instalação do TeX Live (veja a seção Requisitos Críticos -> Para macOS: brew install texlive)
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"]
    }
  }
}

⚠️ Notas Importantes

Requisitos Críticos

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

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

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/

Requisitos de Caminho de Arquivo

Ao salvar ou converter arquivos, você DEVE fornecer caminhos de arquivo completos, incluindo nome 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"

❌ 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

Falha na Conversão de PDF
- Erro: "xelatex não encontrado"
- Solução: Instale o TeX Live primeiro (veja os comandos de instalação acima)
Falha na Conversão de Arquivo
- Erro: "Caminho de arquivo inválido"
- Solução: Forneça o caminho completo, incluindo nome e extensão
- Exemplo: /path/to/document.pdf em vez de apenas /path/to/
Falha na Conversão de Formato
- Erro: "Formato não suportado"
- Solução: Use apenas formatos suportados:
  - Básicos: txt, html, markdown
  - Avançados: pdf, docx, rst, latex, epub

Início Rápido

Instalação

Opção 1: Instalação manual 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

Configuração de Servidores de Desenvolvimento/Não Publicados

ℹ️ Substitua pelo caminho do seu projeto clonado localmente

"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"
    ]
  }
}

Opção 2: Para instalar a Configuração de Servidores Publicados automaticamente via Smithery

Execute o seguinte comando bash para instalar o publicado mcp-pandoc pypi para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install mcp-pandoc --client claude

Se você enfrentar algum problema, use a "Configuração de Servidores Publicados" acima diretamente em vez deste cli.

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

Desenvolvimento

Construção e Publicação

Para preparar o pacote para distribuição:

Sincronize as dependências e atualize o lockfile:

uv sync

Construa as distribuições do pacote:

uv build

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

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 são executados 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:

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