hushvert

@hushvert/mcp

Una herramienta de conversión de archivos para tu agente de IA.

@hushvert/mcp es un servidor del Model Context Protocol que le da a un agente de IA de codificación (Claude Code, Cursor, Cline, Zed, y cualquier otro host de MCP) una herramienta convert_file sobre la API alojada de hushvert. Cuando una tarea necesita una conversión que un navegador no puede hacer - documentos de oficina a PDF, PDF a Word, transcodificaciones de video grandes - el agente convierte el archivo en una sola llamada de herramienta, y el resultado se escribe junto a la entrada. Sin código de carga, sin sondeos, sin pegamento.

Es un cliente ligero sobre la API alojada de hushvert. Para las conversiones que SÍ se ejecutan en un navegador (imágenes, HEIC, archivos, audio, video pequeño, operaciones de páginas PDF), usa el paquete gratuito y de código abierto @hushvert/engine en su lugar - este servidor rechazará esas y te señalará allí.

Demo

Una ejecución real en Claude Code, grabada en vivo y sin acelerar: pide, y report.pdf se escribe junto a la entrada. Todo el turno tomó 23 segundos, de los cuales la conversión en sí fue de unos 7.

La grabación inicia Claude Code con solo este servidor cargado (--strict-mcp-config) para que nada no relacionado esté en pantalla. La cinta que lo produjo es assets/demo.tape, si quieres reproducirla.

Claude Code ya puede convertir archivos. ¿Por qué esto?

Porque solo puede convertir lo que tu máquina puede convertir, y cuando no puede, no falla de manera ruidosa.

Pídele a cualquier agente de codificación que convierta report.docx a PDF. Si LibreOffice está instalado, usará soffice, hará un buen trabajo, y no necesitas este servidor. Si LibreOffice no está instalado, y no está por defecto en macOS, en Windows, o en una imagen típica de CI, el recurso habitual es pandoc. Pandoc no convierte realmente un documento de Word. Lee el texto en su propio AST, lo pasa a LaTeX, y LaTeX compone un documento nuevo. Obtienes un PDF. El agente reporta éxito. Nadie abre el archivo.

Aquí está el mismo report.docx por ambos caminos:

Mismas palabras, documento diferente. Cada fuente en el PDF de pandoc es Latin Modern, el predeterminado de LaTeX. El color del encabezado desapareció, la tabla perdió su estilo de Word, y el título se movió a un bloque de título centrado de LaTeX. pdffonts en las dos salidas:

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

Carlito es métricamente compatible con Calibri, que es lo que el documento realmente pidió. Latin Modern no lo es.

Entonces, honestamente:

• Si LibreOffice está instalado y tu agente lo usa, no necesitas este servidor. Esa es una respuesta real, y es la correcta para mucha gente.
• Si no está instalado, esto es una línea de configuración en lugar de una descarga de 281 MB, y se comporta igual en tu portátil, en CI, en un contenedor, y en una máquina en la que no tienes permitido instalar software.
• Nombra la herramienta si importa. En una máquina que tenía tanto este servidor como pandoc disponibles, preguntamos de la manera simple ("convertir report.docx a PDF") dos veces: Claude Code usó convert_file una vez y pandoc la otra vez, y las dos ejecuciones produjeron los dos documentos anteriores. Qué herramienta elige un agente es su decisión, no la nuestra. "Convertir report.docx a PDF con hushvert" lo fija.

Instalación

Obtén una clave de API en hushvert.com/developers/keys (el inicio de sesión es un código de correo de un solo uso; las claves requieren un correo confirmado), luego agrega el servidor a la configuración MCP de tu agente.

Claude Code - una línea, sin archivo que editar:

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

Cursor, Cline, Zed, y otros hosts de MCP (o Claude Code, si prefieres una configuración de proyecto comprometida) - agrega este bloque a la configuración MCP del host (.mcp.json, .cursor/mcp.json, y así sucesivamente):

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

Si ese archivo está comprometido, no pongas la clave en él. Claude Code expande variables de entorno en una configuración MCP, así que usa "HUSHVERT_API_KEY": "${HUSHVERT_API_KEY}" y mantén la clave real en tu shell. Otros hosts varían; verifica el tuyo antes de comprometer.

Luego pídele a tu agente: "convertir report.docx a PDF con hushvert." Nombrar el servidor vale las dos palabras extra: si tu máquina tiene un convertidor local, el agente puede usar ese en su lugar, y para documentos de oficina el resultado suele ser peor. Ver arriba.

Herramientas

Herramienta	Qué hace
convert_file	Convierte un archivo local a otro formato. Lee la entrada, ejecuta la conversión, escribe la salida, devuelve la ruta.
convert_poll	Termina una conversión larga (video grande) que aún se estaba ejecutando cuando convert_file regresó.
list_formats	Lista las conversiones que la API alojada soporta (los pares solo de servidor).
check_usage	Muestra las conversiones gratuitas restantes, el saldo de créditos, y la ventana de facturación actual.

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)

Devuelve { output_path, jobId, pair, bytesIn, bytesOut, status }. Si el trabajo aún se está ejecutando después de wait_seconds (típico para video grande), devuelve { jobId, status: "processing", resumeWith: "convert_poll" }; llama a convert_poll con el jobId y un output_path para terminar.

Qué convierte

Los formatos solo de servidor que un navegador no puede hacer:

• Office a PDF: docx, pptx, xlsx, doc, ppt, xls, odt, ods, odp, rtf, html a pdf
• PDF a Word: pdf a docx
• Intercambio de documentos: md, html, epub, latex, rst, docx (vía pandoc)
• Video: mov, mkv, avi, webm a mp4 (y mp4 a gif)

Llama a list_formats para la lista en vivo. Todo lo demás (imágenes, HEIC, archivos, audio, video pequeño, operaciones de páginas PDF) se ejecuta gratis, del lado del cliente, en @hushvert/engine.

Configuración

Variable de entorno	Predeterminado	Propósito
HUSHVERT_API_KEY	(requerido)	Tu clave de desarrollador de hv_live_.
HUSHVERT_API_BASE	https://hushvert.com	URL base de la API (para autoalojamiento / staging).
HUSHVERT_DEFAULT_WAIT_SECONDS	120	Presupuesto de sondeo predeterminado para convert_file.
HUSHVERT_MAX_JOBS_PER_SESSION	ilimitado	Límite del lado del cliente en conversiones por ejecución del servidor (una protección contra bucles descontrolados).
HUSHVERT_ALLOWED_DIR	sin establecer	Si se establece, el servidor solo lee/escribe archivos bajo este directorio.

Facturación y privacidad

Las conversiones se facturan por uso contra tu cuenta: una asignación mensual gratuita, luego créditos. check_usage muestra tu asignación y saldo restantes en cualquier momento - haz que tu agente lo verifique antes de un lote grande. La API alojada procesa los formatos solo de servidor que genuinamente no pueden ejecutarse en un navegador; para todo lo demás, el archivo nunca sale del dispositivo vía el motor de código abierto. Ver hushvert.com/for-developers.

Seguridad

La clave de API se lee del entorno, nunca se registra, y nunca se devuelve en un resultado de herramienta o error. Ver SECURITY.md.

Licencia

MIT