hushvert

Conversão de arquivos para agentes de IA: documentos do Office para PDF, PDF para Word, intercâmbio de documentos e transcodificações de áudio/vídeo via a API hospedada do hushvert.

GitHub

Experimente este MCPPatrocinado

Documentação

@hushvert/mcp

Uma ferramenta de conversão de arquivos para seu agente de IA.

@hushvert/mcp é um servidor Model Context Protocol que dá a um agente de codificação de IA (Claude Code, Cursor, Cline, Zed e qualquer outro host MCP) uma ferramenta convert_file sobre a API hospedada do hushvert. Quando uma tarefa precisa de uma conversão que um navegador não pode fazer - documentos do Office para PDF, PDF para Word, transcodificações de vídeo grandes - o agente converte o arquivo em uma única chamada de ferramenta, e o resultado é gravado ao lado da entrada. Sem código de upload, sem polling, sem cola.

É um cliente leve sobre a API hospedada do hushvert. Para as conversões que REALMENTE rodam em um navegador (imagens, HEIC, arquivos, áudio, vídeo pequeno, operações de páginas de PDF), use o pacote gratuito e de código aberto @hushvert/engine em vez disso - este servidor recusará essas e apontará você para lá.

Demonstração

Uma execução real no Claude Code, gravada ao vivo e sem aceleração: peça, e report.pdf é gravado ao lado da entrada. A rodada inteira levou 23 segundos, dos quais a conversão em si foi cerca de 7.

Claude Code converting report.docx to PDF with the hushvert MCP server

A gravação inicia o Claude Code com apenas este servidor carregado (--strict-mcp-config) para que nada não relacionado esteja na tela. A fita que o produziu é assets/demo.tape, se você quiser reproduzi-la.

O Claude Code já pode converter arquivos. Por que isso?

Porque ele só pode converter o que sua máquina pode converter, e quando não pode, ele não falha de forma evidente.

Peça a qualquer agente de codificação para transformar report.docx em um PDF. Se o LibreOffice estiver instalado, ele chamará o soffice, fará um bom trabalho, e você não precisará deste servidor. Se o LibreOffice não estiver instalado, e ele não estiver lá por padrão no macOS, no Windows ou em uma imagem típica de CI, o fallback usual é o pandoc. O pandoc não converte realmente um documento do Word. Ele lê o texto em sua própria AST, entrega isso ao LaTeX, e o LaTeX compõe um novo documento. Você obtém um PDF. O agente relata sucesso. Ninguém abre o arquivo.

Aqui está o mesmo report.docx nos dois caminhos:

The same Word document converted by pandoc and by hushvert, side by side

Mesmas palavras, documento diferente. Cada fonte no PDF do pandoc é Latin Modern, o padrão do LaTeX. A cor do título desapareceu, a tabela perdeu seu estilo do Word, e o título foi movido para um bloco de título centralizado do LaTeX. pdffonts nas duas saídas:

pandoc     LMRoman17-Regular, LMRoman12-Bold, LMRoman10-Italic, ...
hushvert   Carlito-Regular, Carlito-Bold, Carlito-Italic

Carlito é metricamente compatível com Calibri, que é o que o documento realmente pediu. Latin Modern não é.

Então, honestamente:

Se o LibreOffice estiver instalado e seu agente o usar, você não precisa deste servidor. Essa é uma resposta real, e é a certa para muitas pessoas.
Se não estiver instalado, isso é uma linha de configuração em vez de um download de 281 MB, e se comporta da mesma forma no seu laptop, no CI, em um contêiner e em uma máquina em que você não tem permissão para instalar software.
Nomeie a ferramenta se isso importar. Em uma máquina que tinha tanto este servidor quanto o pandoc disponíveis, pedimos da forma simples ("convert report.docx to PDF") duas vezes: o Claude Code usou convert_file uma vez e o pandoc na outra, e as duas execuções produziram os dois documentos acima. Qual ferramenta um agente escolhe é decisão dele, não nossa. "Convert report.docx to PDF with hushvert" fixa isso.

Instalação

Obtenha uma chave de API em hushvert.com/developers/keys (o login é um código de e-mail único; as chaves exigem um e-mail confirmado) e adicione o servidor à configuração MCP do seu agente.

Claude Code - uma linha, sem arquivo para editar:

claude mcp add hushvert -e HUSHVERT_API_KEY=hv_live_your_key_here -- npx -y @hushvert/mcp

Cursor, Cline, Zed e outros hosts MCP (ou Claude Code, se preferir uma configuração de projeto versionada) - adicione este bloco à configuração MCP do host (.mcp.json, .cursor/mcp.json e assim por diante):

{
  "mcpServers": {
    "hushvert": {
      "command": "npx",
      "args": ["-y", "@hushvert/mcp"],
      "env": { "HUSHVERT_API_KEY": "hv_live_your_key_here" }
    }
  }
}

Se esse arquivo for versionado, não coloque a chave nele. O Claude Code expande variáveis de ambiente em uma configuração MCP, então use "HUSHVERT_API_KEY": "${HUSHVERT_API_KEY}" e mantenha a chave real no seu shell. Outros hosts variam; verifique o seu antes de versionar.

Então peça ao seu agente: "convert report.docx to PDF with hushvert." Nomear o servidor vale as duas palavras extras: se sua máquina tiver um conversor local, o agente pode optar por ele, e para documentos do Office o resultado geralmente é pior. Veja acima.

Ferramentas

Ferramenta	O que faz
`convert_file`	Converte um arquivo local para outro formato. Lê a entrada, executa a conversão, grava a saída e retorna o caminho.
`convert_poll`	Finaliza uma conversão longa (vídeo grande) que ainda estava em execução quando `convert_file` retornou.
`list_formats`	Lista as conversões que a API hospedada suporta (os pares somente servidor).
`check_usage`	Mostra conversões gratuitas restantes, saldo de créditos e a janela de cobrança atual.

`convert_file`

input_path       (required) path to the source file
to               (required) target format, e.g. "pdf", "docx", "mp4"
from             (optional) source format; inferred from the extension otherwise
output_path      (optional) where to write; defaults beside the input. Required to overwrite.
wait_seconds     (optional) max seconds to wait before handing back a jobId to poll. Default 120.
idempotency_key  (optional) makes a retried conversion safe (same job, charged once)

Retorna { output_path, jobId, pair, bytesIn, bytesOut, status }. Se o trabalho ainda estiver em execução após wait_seconds (típico para vídeo grande), ele retorna { jobId, status: "processing", resumeWith: "convert_poll" }; chame convert_poll com o jobId e um output_path para finalizar.

O que ele converte

Os formatos somente servidor que um navegador não pode fazer:

Office para PDF: docx, pptx, xlsx, doc, ppt, xls, odt, ods, odp, rtf, html para pdf
PDF para Word: pdf para docx
Intercâmbio de documentos: md, html, epub, latex, rst, docx (via pandoc)
Vídeo: mov, mkv, avi, webm para mp4 (e mp4 para gif)

Chame list_formats para a lista ao vivo. Todo o resto (imagens, HEIC, arquivos, áudio, vídeo pequeno, operações de páginas de PDF) roda gratuitamente, no lado do cliente, em @hushvert/engine.

Configuração

Variável de ambiente	Padrão	Finalidade
`HUSHVERT_API_KEY`	(obrigatório)	Sua chave de desenvolvedor `hv_live_`.
`HUSHVERT_API_BASE`	`https://hushvert.com`	URL base da API (para self-host / staging).
`HUSHVERT_DEFAULT_WAIT_SECONDS`	`120`	Orçamento padrão de polling para `convert_file`.
`HUSHVERT_MAX_JOBS_PER_SESSION`	unlimited	Limite no lado do cliente de conversões por execução do servidor (uma proteção contra loops descontrolados).
`HUSHVERT_ALLOWED_DIR`	unset	Se definido, o servidor só lê/grava arquivos neste diretório.

Cobrança e privacidade

As conversões são cobradas por uso na sua conta: uma cota mensal gratuita, depois créditos. check_usage mostra sua cota restante e saldo a qualquer momento - peça ao seu agente para verificar antes de um lote grande. A API hospedada processa os formatos somente servidor que genuinamente não podem rodar em um navegador; para todo o resto, o arquivo nunca sai do dispositivo via o mecanismo de código aberto. Veja hushvert.com/for-developers.

Segurança

A chave de API é lida do ambiente, nunca registrada em log e nunca retornada em um resultado de ferramenta ou erro. Veja SECURITY.md.

Licença

MIT