Hushvert MCP 是一个为 AI 智能体提供文件转换能力的 Model Context Protocol（MCP）服务器。它通过 hushvert 托管 API 向 AI 编程智能体（如 Claude Code、Cursor、Cline、Zed 以及其他任何 MCP 宿主）提供一个 convert_file 工具。当任务需要浏览器无法完成的转换时——例如 Office 文档转 PDF、PDF 转 Word、大视频转码——智能体可以在一次工具调用中完成转换，结果会写入输入文件旁边。无需上传代码、无需轮询、无需额外胶水代码。
该服务器是 hushvert 托管 API 的轻量客户端。对于确实可以在浏览器中运行的转换（图片、HEIC、压缩包、音频、小视频、PDF 页面操作），应使用免费开源的 @hushvert/engine 包；本服务器会拒绝这些请求并指向该包。
为什么需要它？因为 AI 编程智能体只能转换本机能够转换的格式，而且当它无法转换时，并不会大声报错。例如，让任何编程智能体把 report.docx 转成 PDF：如果安装了 LibreOffice，它会调用 soffice，效果很好，此时不需要本服务器；如果没有安装 LibreOffice（macOS、Windows 或典型 CI 镜像中默认都没有），通常的回退方案是 pandoc。但 pandoc 并不是真正转换 Word 文档——它把文本读入自己的 AST，交给 LaTeX，由 LaTeX 重新排版生成新文档。你会得到一个 PDF，智能体报告成功，但没有人打开文件检查。同一份 report.docx 经两条路径转换后，文字相同但文档不同：pandoc 生成的 PDF 中所有字体都是 Latin Modern（LaTeX 默认字体），标题颜色丢失，表格失去 Word 样式，标题移入居中的 LaTeX 标题块。而 Carlito 与 Calibri 度量兼容，后者才是文档实际要求的字体。
如果本机安装了 LibreOffice 且智能体使用它，则不需要本服务器。如果没有安装，本服务器只需一行配置，而不是下载 281 MB 的软件，并且在你自己的笔记本、CI、容器以及不允许安装软件的机器上行为一致。
使用方式：首先在 hushvert.com/developers/keys 获取 API 密钥（登录使用一次性邮件验证码；密钥需要已验证的邮箱），然后将服务器添加到智能体的 MCP 配置中。对于 Claude Code，可以一行命令完成，无需编辑文件；对于 Cursor、Cline、Zed 和其他 MCP 宿主（或希望使用项目配置的 Claude Code），将相应配置块添加到宿主的 MCP 配置文件中（如 .mcp.json、.cursor/mcp.json 等）。如果该文件会被提交，不要把密钥放进去；Claude Code 会在 MCP 配置中展开环境变量，因此使用 "HUSHVERT_API_KEY": "${HUSHVERT_API_KEY}" 并将真实密钥保留在 shell 中。其他宿主行为不同，提交前请检查。然后向智能体发出指令，例如“convert report.docx to PDF with hushvert”。点名服务器值得多写两个词：如果本机有本地转换器，智能体可能会改用本地转换器，而对于 Office 文档，结果通常更差。
convert_file 返回 { output_path, jobId, pair, bytesIn, bytesOut, status }。如果任务在 wait_seconds 后仍在运行（大视频常见），则返回 { jobId, status: "processing", resumeWith: "convert_poll" }；此时用 jobId 和 output_path 调用 convert_poll 来完成。
支持的转换格式（仅服务器端、浏览器无法完成的格式）：Office 转 PDF：docx、pptx、xlsx、doc、ppt、xls、odt、ods、odp、rtf、html 转 pdf；PDF 转 Word：pdf 转 docx；文档交换：md、html、epub、latex、rst、docx（通过 pandoc）；视频：mov、mkv、avi、webm 转 mp4（以及 mp4 转 gif）。可调用 list_formats 获取实时列表。其他所有转换（图片、HEIC、压缩包、音频、小视频、PDF 页面操作）在 @hushvert/engine 中免费、客户端运行。
计费与隐私：转换按使用量对账户计费——每月有免费额度，之后使用积分。check_usage 可随时显示剩余额度和余额——在大批量转换前让智能体检查一下。托管 API 处理那些确实无法在浏览器中运行的服务器端格式；对于其他所有格式，文件不会离开设备，通过开源引擎处理。API 密钥从环境变量读取，从不记录日志，也从不通过工具结果或错误返回。
