hushvert

@hushvert/mcp

为你的 AI Agent 提供的文件转换工具。

@hushvert/mcp 是一个 Model Context Protocol 服务，通过 hushvert 托管 API 为 AI 编码 Agent（Claude Code、Cursor、Cline、Zed 以及任何其他 MCP 宿主）提供 convert_file 工具。当任务需要进行浏览器无法完成的转换时——例如将办公文档转换为 PDF、将 PDF 转换为 Word，或进行大型视频转码——Agent 只需调用一次工具即可转换文件，结果会写入输入文件所在目录。无需编写上传代码，无需轮询，也无需胶水代码。

它是 hushvert 托管 API 的轻量客户端。对于确实可以在浏览器中完成的转换（图像、HEIC、压缩包、音频、小型视频、PDF 页面操作），请改用免费、开源的 @hushvert/engine 包——本服务会拒绝处理这些转换，并指引你使用该包。

演示

这是在 Claude Code 中现场录制的真实运行过程，没有加速：提出请求后，report.pdf 就会写入输入文件所在目录。整个轮次耗时 23 秒，其中转换本身约耗时 7 秒。

录制时启动 Claude Code 时只加载了此服务（--strict-mcp-config），因此屏幕上没有任何无关内容。生成该录制的脚本是 assets/demo.tape，你可以用它来重现。

Claude Code 已经能转换文件了，为什么还需要这个？

因为它只能转换你的机器能够转换的文件，而且做不到时，它不会明确报错。

让任何编码 Agent 将 report.docx 转换为 PDF。如果安装了 LibreOffice，它会调用 soffice，效果不错，你也不需要此服务。如果没有安装 LibreOffice——macOS、Windows 或典型 CI 镜像默认都没有安装——通常会退而使用 pandoc。Pandoc 并不会真正转换 Word 文档。它会将文本读入自己的 AST，再交给 LaTeX，由 LaTeX 排版生成一份新文档。你得到了一份 PDF。Agent 报告成功。却没有人打开文件查看。

下面是同一个 report.docx 通过这两种方式转换后的结果：

文字相同，文档却不同。pandoc 生成的 PDF 中所有字体都是 Latin Modern，也就是 LaTeX 的默认字体。标题颜色消失了，表格失去了 Word 样式，文档标题也变成了居中的 LaTeX 标题块。对两份输出运行 pdffonts，结果如下：

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

Carlito 的字宽与 Calibri 兼容，而文档实际指定的正是 Calibri。Latin Modern 则不兼容。

所以，坦白说：

• 如果安装了 LibreOffice，而且你的 Agent 会使用它，就不需要此服务。 这确实是一个可行的答案，对很多人来说也完全正确。
• 如果没有安装，相比下载一个 281 MB 的文件，只需一行配置；而且无论在笔记本电脑、CI、容器中，还是在不允许安装软件的机器上，行为都一致。
• 如果工具选择很重要，就明确指定。在一台同时可以使用此服务和 pandoc 的机器上，我们用普通说法（“将 report.docx 转换为 PDF”）问了两次：Claude Code 一次使用了 convert_file，另一次使用了 pandoc，最终生成了上面展示的两份文档。Agent 选择哪个工具，由它决定，而不是由我们决定。使用“用 hushvert 将 report.docx 转换为 PDF”即可固定选择。

安装

在 hushvert.com/developers/keys 获取 API 密钥 （登录时会发送一次性邮件验证码；密钥需要经过验证的邮箱），然后将 服务添加到 Agent 的 MCP 配置中。

Claude Code - 一行命令，无需编辑文件：

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

Cursor、Cline、Zed 和其他 MCP 宿主（或者你更喜欢使用已提交到项目中的配置时，也可用于 Claude Code）- 将此代码块添加到宿主的 MCP 配置中 （.mcp.json、.cursor/mcp.json 等）：

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

如果该文件已提交，不要将密钥写入其中。Claude Code 会在 MCP 配置中展开 环境变量，因此请使用 "HUSHVERT_API_KEY": "${HUSHVERT_API_KEY}"，并将真实密钥保存在 Shell 中。其他宿主的行为各不相同； 提交前请先确认。

然后对 Agent 说：“用 hushvert 将 report.docx 转换为 PDF。”指出服务名称值得多说两个词：如果 你的机器上有本地转换器，Agent 可能会优先使用它，而对于办公文档，转换结果通常更差。请参阅 上文。

工具

工具	功能
convert_file	将本地文件转换为其他格式。读取输入文件、执行转换、写入输出文件并返回路径。
convert_poll	完成耗时较长的转换（大型视频）；此类转换在 convert_file 返回时仍可能正在运行。
list_formats	列出托管 API 支持的转换格式（仅限服务端转换的格式组合）。
check_usage	显示剩余免费转换次数、余额和当前计费周期。

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)

返回 { 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 在客户端免费处理。

配置

环境变量	默认值	用途
HUSHVERT_API_KEY	（必填）	你的 hv_live_ 开发者密钥。
HUSHVERT_API_BASE	https://hushvert.com	API 基础 URL（用于自托管 / staging）。
HUSHVERT_DEFAULT_WAIT_SECONDS	120	convert_file 的默认轮询时限。
HUSHVERT_MAX_JOBS_PER_SESSION	unlimited	每次服务运行的客户端转换次数上限（用于防止循环失控）。
HUSHVERT_ALLOWED_DIR	unset	如果设置，服务只会读取 / 写入此目录下的文件。

计费与隐私

转换按次计费，费用从你的账户中扣除：每月提供免费额度，之后使用积分。check_usage 随时 显示剩余免费额度和余额；进行大批量转换前，请让 Agent 先检查。托管 API 会处理 确实无法在浏览器中运行的服务端格式；其他所有格式都通过开源引擎在设备本地处理，文件不会离开设备。请参阅 hushvert.com/for-developers。

安全

API 密钥从环境变量中读取，不会被记录，也不会出现在工具结果或错误信息中。请参阅 SECURITY.md。

许可证

MIT