内容
# @hushvert/mcp
[](https://www.npmjs.com/package/@hushvert/mcp)
[](./LICENSE)
**适用于 AI 代理的文件转换工具**
`@hushvert/mcp` 是一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为 AI 编程代理（如 Claude Code、Cursor、Cline、Zed 等）提供 `convert_file` 工具，基于 hushvert 托管的 API。当任务需要浏览器无法完成的转换时，例如将 Office 文档转换为 PDF、将 PDF 转换为 Word 或大视频转码，代理可以在一次工具调用中完成转换，结果将写入输入文件旁边。无需上传代码，无需轮询，无需粘合剂。
它是 hushvert 托管 API 的一个薄客户端。对于浏览器可以执行的转换（图像、HEIC、存档、音频、小视频、PDF 页面操作），请改用免费、开源的 [`@hushvert/engine`](https://www.npmjs.com/package/@hushvert/engine) 包；该服务器将拒绝这些请求并指向那里。
## 安装
从您的 [hushvert 账户](https://hushvert.com/account)（开发者部分 - 需要确认的电子邮件地址）获取 API 密钥，然后将服务器添加到您的代理的 MCP 配置中。
**Claude Code**（项目中的 `.mcp.json` 文件或用户配置）：
```json
{
"mcpServers": {
"hushvert": {
"command": "npx",
"args": ["-y", "@hushvert/mcp"],
"env": { "HUSHVERT_API_KEY": "hv_live_your_key_here" }
}
}
}
```
相同的 `command` / `args` / `env` 块适用于 Cursor、Cline、Zed 等其他 MCP 主机。然后向您的代理询问：“将 report.docx 转换为 PDF。”
## 工具
| 工具 | 功能描述 |
| --- | --- |
| `convert_file` | 将本地文件转换为另一种格式。读取输入、运行转换、写入输出、返回路径。 |
| `convert_poll` | 完成在 `convert_file` 返回时仍在运行的长时间转换（大视频）。 |
| `list_formats` | 列出托管 API 支持的转换（服务器端对）。 |
| `check_usage` | 显示剩余的免费转换次数、信用余额和当前计费窗口。 |
### `convert_file`
```
input_path （必填）源文件路径
to （必填）目标格式，例如 "pdf"、"docx"、"mp4"
from （可选）源格式；否则从扩展名推断
output_path （可选）写入位置；默认为输入文件旁边。需要覆盖时必填。
wait_seconds （可选）最大等待时间，单位为秒，默认为 120 秒。
idempotency_key （可选）使重试转换安全（相同作业，仅需一次计费）
```
返回 `{ 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`](https://www.npmjs.com/package/@hushvert/engine) 中免费、客户端运行。
## 配置
| 环境变量 | 默认值 | 用途 |
| --- | --- | --- |
| `HUSHVERT_API_KEY` | （必填）您的 `hv_live_` 开发者密钥。 |
| `HUSHVERT_API_BASE` | `https://hushvert.com` | API 基地址（用于自托管 / 预发布环境）。 |
| `HUSHVERT_DEFAULT_WAIT_SECONDS` | `120` | `convert_file` 的默认轮询超时。 |
| `HUSHVERT_MAX_JOBS_PER_SESSION` | 无限制 | 每个服务器运行的转换次数客户端上限（防止失控循环）。 |
| `HUSHVERT_ALLOWED_DIR` | 未设置 | 如果设置，服务器仅读取/写入此目录下的文件。 |
## 计费和隐私
每次转换都会根据您的账户进行计费：免费的每月额度，然后是信用额度。`check_usage` 随时显示您的剩余额度：让您的代理在进行大量转换前检查。托管 API 处理服务器端格式，这些格式确实无法在浏览器中运行；对于其他所有内容，文件都不会通过开源引擎离开设备。参见 [hushvert.com/for-developers](https://hushvert.com/for-developers)。
## 安全
API 密钥从环境中读取，绝不会被记录或在工具结果或错误中返回。参见 [SECURITY.md](./SECURITY.md)。
## 许可证
MIT
