内容
# @enconvert/mcp
Enconvert 官方 **模型上下文协议（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 就绪的 chunked 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. **仅需一次请求您的秘密 API 密钥**（隐藏输入）并实时验证它是否有效 — 甚至如果您不小心粘贴了 *公共* 密钥，它也会告诉您。
3. **正确写入所有配置**，包括 Windows 需要的 `cmd /c npx` 包装器。您的密钥仅存储在 `~/.enconvert/config.json`（权限 `600`）中 — 永远不会复制到客户端配置中。
```
$ npx @enconvert/mcp setup
Enconvert MCP - 设置
? 哪些 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. *"搜索三个最佳静态站点生成器并读取它们的首页。"* → 带有 `perceive_top` 的 `web_search`
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 和元数据
- **`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
