{ "markdown": "

\"hushvert\"

\n\n# @hushvert/mcp\n\n[![npm](https://img.shields.io/npm/v/@hushvert/mcp.svg)](https://www.npmjs.com/package/@hushvert/mcp)\n[![license](https://img.shields.io/npm/l/@hushvert/mcp.svg)](./LICENSE)\n\n**A file-conversion tool for your AI agent.**\n\n`@hushvert/mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)\nserver that gives an AI coding agent (Claude Code, Cursor, Cline, Zed, and any\nother MCP host) a `convert_file` tool over the hushvert hosted API. When a task\nneeds a conversion a browser cannot do - office documents to PDF, PDF to Word,\nlarge video transcodes - the agent converts the file in one tool call, and the\nresult is written next to the input. No upload code, no polling, no glue.\n\nIt is a thin client over the [hushvert](https://hushvert.com) hosted API. For the\nconversions that DO run in a browser (images, HEIC, archives, audio, small video,\nPDF page ops), use the free, open-source [`@hushvert/engine`](https://www.npmjs.com/package/@hushvert/engine)\npackage instead - this server will refuse those and point you there.\n\n## Demo\n\nA real run in Claude Code, recorded live and not sped up: ask, and `report.pdf` is\nwritten next to the input. The whole turn took 23 seconds, of which the conversion\nitself was about 7.\n\n![Claude Code converting report.docx to PDF with the hushvert MCP server](https://raw.githubusercontent.com/hushvert/mcp/main/assets/demo.gif)\n\nThe recording starts Claude Code with only this server loaded\n(`--strict-mcp-config`) so nothing unrelated is on screen. The tape that produced\nit is [`assets/demo.tape`](https://github.com/hushvert/mcp/blob/main/assets/demo.tape),\nif you want to reproduce it.\n\n## Claude Code can already convert files. Why this?\n\nBecause it can only convert what your machine can convert, and when it cannot, it\ndoes not fail loudly.\n\nAsk any coding agent to turn `report.docx` into a PDF. If LibreOffice is\ninstalled, it will shell out to `soffice`, do a good job, and you do not need this\nserver. If LibreOffice is not installed, and it is not there by default on macOS,\non Windows, or in a typical CI image, the usual fallback is pandoc. Pandoc does\nnot really convert a Word document. It reads the text into its own AST, hands that\nto LaTeX, and LaTeX typesets a new document. You get a PDF. The agent reports\nsuccess. Nobody opens the file.\n\nHere is the same `report.docx` down both paths:\n\n![The same Word document converted by pandoc and by hushvert, side by side](https://raw.githubusercontent.com/hushvert/mcp/main/assets/fidelity.png)\n\nSame words, different document. Every font in the pandoc PDF is Latin Modern,\nLaTeX's default. The heading color is gone, the table lost its Word styling, and\nthe title moved into a centered LaTeX title block. `pdffonts` on the two outputs:\n\n```\npandoc LMRoman17-Regular, LMRoman12-Bold, LMRoman10-Italic, ...\nhushvert Carlito-Regular, Carlito-Bold, Carlito-Italic\n```\n\nCarlito is metric-compatible with Calibri, which is what the document actually\nasked for. Latin Modern is not.\n\nSo, honestly:\n\n- **If LibreOffice is installed and your agent reaches for it, you do not need\n this server.** That is a real answer, and it is the right one for a lot of people.\n- If it is not installed, this is one line of config instead of a 281 MB download,\n and it behaves the same on your laptop, in CI, in a container, and on a machine\n you are not allowed to install software on.\n- Name the tool if it matters. On a machine that had both this server and pandoc\n available, we asked the plain way (\"convert report.docx to PDF\") twice: Claude\n Code used `convert_file` once and pandoc the other time, and the two runs\n produced the two documents above. Which tool an agent reaches for is its call,\n not ours. \"Convert report.docx to PDF with hushvert\" pins it.\n\n## Install\n\nGet an API key at [hushvert.com/developers/keys](https://hushvert.com/developers/keys)\n(sign-in is a one-time email code; keys require a confirmed email), then add the\nserver to your agent's MCP config.\n\n**Claude Code** - one line, no file to edit:\n\n```bash\nclaude mcp add hushvert -e HUSHVERT_API_KEY=hv_live_your_key_here -- npx -y @hushvert/mcp\n```\n\n**Cursor, Cline, Zed, and other MCP hosts** (or Claude Code, if you prefer a\ncommitted project config) - add this block to the host's MCP config\n(`.mcp.json`, `.cursor/mcp.json`, and so on):\n\n```json\n{\n \"mcpServers\": {\n \"hushvert\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@hushvert/mcp\"],\n \"env\": { \"HUSHVERT_API_KEY\": \"hv_live_your_key_here\" }\n }\n }\n}\n```\n\nIf that file is committed, do not put the key in it. Claude Code expands\nenvironment variables in an MCP config, so use `\"HUSHVERT_API_KEY\":\n\"${HUSHVERT_API_KEY}\"` and keep the real key in your shell. Other hosts vary;\ncheck yours before committing.\n\nThen ask your agent: \"convert report.docx to PDF with hushvert.\" Naming the server\nis worth the two extra words: if your machine has a local converter, the agent may\nreach for that instead, and for office documents the result is usually worse. See\n[above](#claude-code-can-already-convert-files-why-this).\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `convert_file` | Convert a local file to another format. Reads the input, runs the conversion, writes the output, returns the path. |\n| `convert_poll` | Finish a long conversion (large video) that was still running when `convert_file` returned. |\n| `list_formats` | List the conversions the hosted API supports (the server-only pairs). |\n| `check_usage` | Show free conversions remaining, credit balance, and the current billing window. |\n\n### `convert_file`\n\n```\ninput_path (required) path to the source file\nto (required) target format, e.g. \"pdf\", \"docx\", \"mp4\"\nfrom (optional) source format; inferred from the extension otherwise\noutput_path (optional) where to write; defaults beside the input. Required to overwrite.\nwait_seconds (optional) max seconds to wait before handing back a jobId to poll. Default 120.\nidempotency_key (optional) makes a retried conversion safe (same job, charged once)\n```\n\nReturns `{ output_path, jobId, pair, bytesIn, bytesOut, status }`. If the job is\nstill running after `wait_seconds` (typical for large video), it returns\n`{ jobId, status: \"processing\", resumeWith: \"convert_poll\" }`; call `convert_poll`\nwith the `jobId` and an `output_path` to finish.\n\n## What it converts\n\nThe server-only formats a browser cannot do:\n\n- **Office to PDF**: docx, pptx, xlsx, doc, ppt, xls, odt, ods, odp, rtf, html to pdf\n- **PDF to Word**: pdf to docx\n- **Document interchange**: md, html, epub, latex, rst, docx (via pandoc)\n- **Video**: mov, mkv, avi, webm to mp4 (and mp4 to gif)\n\nCall `list_formats` for the live list. Everything else (images, HEIC, archives,\naudio, small video, PDF page ops) runs free, client-side, in\n[`@hushvert/engine`](https://www.npmjs.com/package/@hushvert/engine).\n\n## Configuration\n\n| Env var | Default | Purpose |\n| --- | --- | --- |\n| `HUSHVERT_API_KEY` | (required) | Your `hv_live_` developer key. |\n| `HUSHVERT_API_BASE` | `https://hushvert.com` | API base URL (for self-host / staging). |\n| `HUSHVERT_DEFAULT_WAIT_SECONDS` | `120` | Default poll budget for `convert_file`. |\n| `HUSHVERT_MAX_JOBS_PER_SESSION` | unlimited | Client-side cap on conversions per server run (a guard against runaway loops). |\n| `HUSHVERT_ALLOWED_DIR` | unset | If set, the server only reads/writes files under this directory. |\n\n## Billing and privacy\n\nConversions are billed per use against your account: a free monthly allowance,\nthen credits. `check_usage` shows your remaining allowance and balance at any\ntime - have your agent check it before a large batch. The hosted API processes\nthe server-only formats that genuinely cannot run in a browser; for everything\nelse the file never leaves the device via the open-source engine. See\n[hushvert.com/for-developers](https://hushvert.com/for-developers).\n\n## Security\n\nThe API key is read from the environment, never logged, and never returned in a\ntool result or error. See [SECURITY.md](./SECURITY.md).\n\n## License\n\nMIT\n", "bytes": 8225, "sha": "d9491b9fa08b5def2bc0f5051ca8ff49c859d760c71305426485e3d11b125b97", "repo_slug": "hushvert/mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_com_hushvert_mcp_6419261a/readme" }