Markdownify

Servidor MCP Markdownify

Markdownify é um servidor Model Context Protocol (MCP) que converte vários tipos de arquivos e conteúdo web para o formato Markdown. Ele fornece um conjunto de ferramentas para transformar PDFs, imagens, arquivos de áudio, páginas web e muito mais em texto Markdown facilmente legível e compartilhável.

Recursos

• Converte vários tipos de arquivo para Markdown:
  • PDF
  • Imagens
  • Áudio (com transcrição)
  • DOCX
  • XLSX
  • PPTX
• Converte conteúdo web para Markdown:
  • Transcrições de vídeos do YouTube
  • Resultados de busca do Bing
  • Páginas web em geral
• Recupera arquivos Markdown existentes

Começando

1. Clone este repositório

2. Instale as dependências:

   bun install
   

   O passo preinstall cria um ambiente virtual Python em .venv e instala markitdown[all].

3. Compile o projeto:

   bun run build
   

4. Inicie o servidor:

   bun start
   

Desenvolvimento

• Use bun run dev para iniciar o compilador TypeScript em modo de observação
• Modifique src/server.ts para personalizar o comportamento do servidor
• Adicione ou modifique ferramentas em src/tools.ts

Uso com Aplicativo Desktop

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

{
  "mcpServers": {
    "markdownify": {
      "command": "node",
      "args": [
        "{ABSOLUTE PATH TO FILE HERE}/dist/index.js"
      ]
    }
  }
}

Variáveis de ambiente

Todos os caminhos usam valores padrão sensatos; substitua apenas quando os padrões não se adequarem ao seu layout de instalação.

Variável	Padrão	Finalidade
MARKITDOWN_PATH	<project>/.venv/bin/markitdown, depois markitdown em PATH	Caminho absoluto para o executável markitdown. Defina isso quando você instalou o markitdown em todo o sistema (ex.: pipx install "markitdown[pdf]") em vez de usar o venv incluído.
REPOMIX_PATH	<project>/node_modules/.bin/repomix, depois repomix em PATH	Caminho absoluto para o executável repomix usado por git-repo-to-markdown.
MD_ALLOWED_PATHS	não definido (sem restrições)	Lista separada por delimitador de caminho (: em POSIX, ; no Windows) de diretórios que o servidor pode ler. Quando definido, todas as ferramentas de entrada de arquivo (pdf-to-markdown, get-markdown-file, etc.) rejeitam caminhos fora desses diretórios.
MD_SHARE_DIR	não definido	Alias obsoleto para MD_ALLOWED_PATHS (diretório único). Ainda é respeitado para compatibilidade reversa.

Uso com Docker

Compile e execute:

docker build -t markdownify-mcp .
docker run --rm -i \
  -v "$HOME/Documents:/data:ro" \
  -e MD_ALLOWED_PATHS=/data \
  markdownify-mcp

Notas para o catálogo Docker MCP (mcp/markdownify):

• Monte quaisquer diretórios do host que você deseja que o servidor leia no contêiner e, em seguida, passe os caminhos do contêiner para as ferramentas (ex.: /data/foo.pdf, não /Users/you/Documents/foo.pdf).
• Defina MD_ALLOWED_PATHS como a lista separada por dois-pontos dos diretórios montados para que o servidor aplique um limite de leitura que corresponda ao bind mount.
• A imagem Docker publicada instala apenas markitdown[pdf] — transcrição de áudio e OCR de imagens (audio-to-markdown, image-to-markdown) exigem os extras [all] e falharão na imagem enxuta. Use a instalação local (bun install) para o conjunto completo de recursos.

Ferramentas Disponíveis

• youtube-to-markdown: Converte vídeos do YouTube para Markdown

• pdf-to-markdown: Converte arquivos PDF para Markdown

• bing-search-to-markdown: Converte resultados de busca do Bing para Markdown

• webpage-to-markdown: Converte páginas web para Markdown

• image-to-markdown: Converte imagens para Markdown com metadados

• audio-to-markdown: Converte arquivos de áudio para Markdown com transcrição

• docx-to-markdown: Converte arquivos DOCX para Markdown

• xlsx-to-markdown: Converte arquivos XLSX para Markdown

• pptx-to-markdown: Converte arquivos PPTX para Markdown

• get-markdown-file: Recupera um arquivo Markdown existente. A extensão do arquivo deve terminar com: *.md, *.markdown.

  OPCIONAL: defina MD_ALLOWED_PATHS para restringir cada ferramenta de entrada de arquivo a uma lista de diretórios, ex.: MD_ALLOWED_PATHS=/data/in:/data/out bun start.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.