内容
# @enconvert/mcp
[](https://lobehub.com/mcp/conversionapi-mcp)
官方 **模型上下文协议（MCP）服务器**，适用于 [Enconvert](https://enconvert.com) —— 允许任何与MCP兼容的AI代理（如Claude Code、Cursor、Windsurf、Claude Desktop、Continue等）通过单个命令转换文件和URL。
## 您将获得
二十一个工具，优化了可靠的LLM工具选择。所有URL/浏览器工作都通过V2工具（`perceive_url`等）进行；而V1工具则涵盖本地/远程文件转换。
### 文件转换（3）
| 工具 | 功能 |
|------|-------------|
| `convert_document` | 将DOC(X)、XLS(X)、PPT(X)、ODT、ODS、ODP、OTS、Pages、Numbers、EPUB、HTML、MD、CSV、JSON、XML、YAML、TOML转换为PDF（或相互转换） |
| `convert_image` | 在JPEG、PNG、SVG、HEIC、WebP之间转换——另外还支持PDF → JPEG栅格化（适用于iPhone HEIC → WebP） |
| `get_job_status` | 通过作业ID检查单个文件转换作业 |
### V2 — 适用于代理的网页数据（18个，需私有API密钥，计划控制）
| 工具 | 功能 |
|------|-------------|
| `perceive_url` | 将页面渲染为多个工件（markdown、HTML、截图、PDF、链接、图片）+结构化提取，缓存时间约1小时 |
| `get_perceive_operation` | 使用新鲜签名的工件URL重新获取感知结果 |
| `perceive_batch` | 感知最多1000个URL，共享选项（小批量内联，大批量异步） |
| `get_perceive_batch` | 通过作业ID轮询感知批量 |
| `discover_urls` | 通过站点地图/爬虫/混合方式枚举站点的URL——无需渲染，无渲染配额 |
| `web_search` | Google支持的搜索（网页、新闻、图片、学者、专利、地图），可选自动感知顶部结果 |
| `extract_structured` | 从最多50个URL或已发现的站点中进行模式驱动的数据提取（免费CSS通道 + LLM升级） |
| `start_ingest` | 将站点或URL列表转换为RAG-ready分段JSONL（始终异步） |
| `list_ingest_jobs` / `get_ingest_job` / `cancel_ingest_job` | 管理摄入作业 |
| `retry_ingest_webhook` | 重新传递已完成的作业的HMAC签名完成Webhook |
| `create_watcher` / `list_watchers` / `get_watcher` / `get_watcher_snapshots` / `update_watcher` / `delete_watcher` | 以每小时一次的节奏监控页面变化，带有差异历史和通知 |
不公开的设计：webhook签名密钥端点（`GET/POST /v2/ingest/webhook-secret*`）——密钥不属于LLM上下文。从Enconvert仪表板获取这些信息。
## 要求
- **Node.js 18 或更高版本**
- 一个 **Enconvert API密钥** —— 在 [enconvert.com/dashboard/api-keys](https://enconvert.com/dashboard/api-keys) 获取
## 安装 — 一个命令
```bash
npx @enconvert/mcp setup
```
就是这样。向导：
1. **检测您的AI工具** （Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Zed、Gemini CLI、Codex CLI、OpenCode）并让您选择哪些工具获取Enconvert——检测到的工具预先选中。
2. **一次性请求您的密钥** （隐藏输入）并实时验证它是否有效——甚至如果您不小心粘贴了 *公共* 密钥，它也会告诉您。
3. **正确写入所有配置** ，包括Windows需要的 `cmd /c npx` 包装。您的密钥存储在 `~/.enconvert/config.json` （权限 `600` ）中——从未复制到客户端配置中。
```
$ npx @enconvert/mcp setup
Enconvert MCP - setup
? 哪些AI工具应该获取Enconvert？
[x] Claude Code (检测到) [x] Cursor (检测到)
[ ] Claude Desktop [ ] Windsurf ...
? 粘贴您的SECRET API密钥（sk_live_...，输入隐藏）： ********
✔ API密钥有效。
+ Claude Code - claude CLI（用户范围）
+ Cursor - ~/.cursor/mcp.json
完成。重启您的AI工具以获取服务器。
```
重启您的AI工具后，您就可以运行了。
### 轻松管理
| 命令 | 功能 |
|---|---|
| `npx @enconvert/mcp status` | 安装位置 + 您的密钥是否有效（实时检查） |
| `npx @enconvert/mcp rotate-key` | 交换新的API密钥——一个命令，适用于所有客户端 |
| `npx @enconvert/mcp remove` | 从选定的工具中卸载（可选删除保存的密钥） |
| `npx @enconvert/mcp setup --yes` | 非交互式：使用保存的密钥配置所有检测到的工具 |
脚本编写？ `setup --clients claude-code,cursor --api-key sk_live_... --yes` 跳过所有提示。 `rotate-key` 没有参数提示隐藏输入，因此密钥永远不会出现在您的shell历史记录中。
### 密钥存储位置
`setup` 将您的密钥 **一次** 存储在 `~/.enconvert/config.json` （模式 `600` ）中，而不是粘贴到每个客户端的纯文本配置中。服务器在启动时读取它； `ENCONVERT_API_KEY` 环境变量始终覆盖它（适用于Docker、CI或手动设置）。因此，轮换是一个单文件更改——每个客户端在下一次启动时都会获取它。
## 高级：手动配置
如果您更喜欢自己配置？将以下内容添加到客户端的MCP配置中（`~/.cursor/mcp.json`、`~/.codeium/windsurf/mcp_config.json`等）：
```json
{
"mcpServers": {
"enconvert": {
"command": "npx",
"args": ["-y", "@enconvert/mcp@latest"],
"env": {
"ENCONVERT_API_KEY": "sk_live_your_key"
}
}
}
}
```
在 **原生Windows** 上，使用 `"command": "cmd"` 和 `"args": ["/c", "npx", "-y", "@enconvert/mcp@latest"]` ——裸`npx`挂起。（WSL表现像Linux一样。）对于Claude Code：
```bash
claude mcp add enconvert -s user \
-e ENCONVERT_API_KEY=sk_live_your_key \
-- npx -y @enconvert/mcp@latest
```
内联 `env` 块是可选的，如果您已经运行了 `setup` （或创建了 `~/.enconvert/config.json` ）——服务器会自动回落到保存的密钥。客户端配置位置：Claude Desktop `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）/ `%APPDATA%\Claude\claude_desktop_config.json` （Windows）；Cursor `~/.cursor/mcp.json` ；Windsurf `~/.codeium/windsurf/mcp_config.json` ；Gemini CLI `~/.gemini/settings.json` ；Codex `~/.codex/config.toml` 。
## 尝试
安装完成后，在新的提示中尝试以下任何一个：
1. *"给我 https://en.wikipedia.org/wiki/Model_Context_Protocol 作为markdown并总结它。"* → `perceive_url`
2. *"截图 https://news.ycombinator.com 并保存页面为PDF。"* → `perceive_url` （一个调用中的两个工件）
3. *"搜索三个最佳静态站点生成器并读取它们的首页。"* → `web_search` with `perceive_top`
4. *"从 https://example.com/pricing 获取所有计划名称和价格。"* → `extract_structured`
5. *"将 `/Users/me/Desktop/report.docx` 转换为PDF。"* → `convert_document`
6. *"将 `/Users/me/Desktop/iphone.heic` 转换为webp。"* → `convert_image`
7. *"监控 https://example.com/changelog 并在它更改时通知我。"* → `create_watcher`
代理自动选择正确的工具——描述已调整为URL工作落在 `perceive_url` 上，文件工作落在转换工具上。
## 配置
API密钥按以下顺序解析：
1. `ENCONVERT_API_KEY` 环境变量（来自MCP客户端的 `env` 块）——始终获胜
2. `~/.enconvert/config.json` ，由 `npx @enconvert/mcp setup` 编写
| 设置 | 必需 | 默认值 | 目的 |
|----------|----------|---------|---------|
| `ENCONVERT_API_KEY` （env）或 `api_key` （配置文件） | ✅ 是 | — | 您的 **秘密** Enconvert API密钥 |
| `ENCONVERT_BASE_URL` （env）或 `base_url` （配置文件） | 否 | `https://api.enconvert.com` | 覆盖 staging 或自托管 Enconvert |
## 工作原理
服务器是官方 [`@enconvert/node-sdk`](https://www.npmjs.com/package/@enconvert/node-sdk) 的薄MCP包装器——它拥有所有HTTP、身份验证、超时（5分钟）和作业轮询回退逻辑。每个工具处理程序将MCP输入映射到SDK调用并返回一致的响应：
- **文本摘要** ，包含下载URL（s）和元数据
- **`structuredContent` **块，包含完整的类型结果
- 当提供 `save_to` 时， **`resource_link` **到本地文件（文件工具）
- 对于 `perceive_url` ， **markdown工件内联** 在响应中（最多~256 KB），以便代理可以立即读取它而无需第二次HTTP获取
## 故障排除
**`npx` 在原生Windows上挂起**
使用 `cmd /c npx …` —— `cmd` 壳牌处理Windows路径解析，而裸 `npx` 不执行。（ `npx @enconvert/mcp setup` 在Windows上自动写入此内容。）
**`Authentication failed: Invalid or missing API key`**
运行 `npx @enconvert/mcp status` ——它显示您的密钥来自哪里并实时验证它。使用 `npx @enconvert/mcp rotate-key` 进行修复，或在手动配置时检查 `ENCONVERT_API_KEY` 环境块。
**工具调用超时**
重型页面的浏览器渲染（ `perceive_url` ， `extract_structured` ）可能需要15-30秒，SDK最多等待5分钟。如果您的客户端超时较短，请提高它。
**`convert_document` / `convert_image` 上的“相对路径”错误**
传递 **绝对** 路径（例如 `/Users/me/file.docx` 或 `C:\Users\me\file.docx` ），或传递 `http(s)://` URL。MCP服务器没有可靠的工作目录。
## 它如何依赖Node SDK
此MCP服务器是 [`@enconvert/node-sdk`](https://www.npmjs.com/package/@enconvert/node-sdk) 的薄包装器，它拥有所有HTTP、身份验证、超时、重试和 `job_id` 轮询-500逻辑。新SDK版本会自动使MCP服务器受益。
## 许可证
[MIT](./LICENSE)
## 链接
- **Enconvert网站** — https://enconvert.com
- **Enconvert Node SDK** — https://www.npmjs.com/package/@enconvert/node-sdk
- **MCP规范** — https://modelcontextprotocol.io
- **问题/反馈** — https://github.com/enconvert/enconvert-mcp/issues
