@ENCONVERT/MCP

@enconvert/mcp

为 AI Agent 提供网页和文件读取能力，每次读取都会得到 0-1 的 render_quality 评分。EnConvert 通过一个 API 密钥即可感知页面、发现 URL、搜索实时网页、提取结构化数据、导入适用于 RAG 的内容片段并监测变化；每次网页读取都会返回带有具体扣分项的评分，因此被屏蔽、出现验证挑战或内容为空的 SPA 页面都会被标记，而不会被误认为是内容。

适用于 EnConvert 的官方 Model Context Protocol (MCP) 服务。它让任何兼容 MCP 的 AI Agent（Claude Code、Cursor、Windsurf、Claude Desktop、Continue 等）都能通过一条命令读取网页并转换文件。

收录于：官方 MCP Registry · Glama · LobeHub · npm

你将获得

24 个工具，针对可靠的大模型工具选择进行了优化。所有 URL／浏览器操作都通过 V2 工具（perceive_url 等）执行；V1 工具用于本地／远程文件转换。默认注册全部 24 个工具；若只需注册网页工具或文件工具，请参阅工具集。

每次网页读取都会获得评分

perceive_url（以及基于它构建的所有功能）都会返回 render_quality（0.0-1.0）评分，并附上具体的 deductions，例如 anti_bot_challenge、http_error 或 login_wall，以及来源的 status_code。你的 Agent 可以依赖以下约定：

• 检测到无内容的拦截时，返回 HTTP 200，并且 is_blocked: true、outputs 为空、billed: false。工具文本会显示 Blocked: yes (not billed)。没有内容可读；请勿期待再次请求同一 URL 会得到不同结果。
• 扣分项包含 http_error 或 login_wall 的读取同样不会计费（billed: false，文本为 Not billed.）。缓存命中会计费。
• 若 render_quality 低于 0.40，应视为无有效内容：展示评分和扣分项，而不是 Markdown。
• 429 会以纯文本形式返回：Rate limited; retry after N seconds，该信息来自网关的 Retry-After 标头。

文件转换（6 项）

工具	功能
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）。SVG 光栅化支持可选的 width 和 height 控制参数
compress_image	在不更改格式的情况下压缩 PNG、JPEG 或 WebP，也可指定目标大小（KB）
convert_anything_to_markdown	将 PDF、Office、ODF、EPUB、HTML、CSV 或文本文件转换为干净的 Markdown，供 RAG 工作流使用
convert_anything_to_pdf	将几乎任何文件（Office、ODF、iWork、图像、SVG、HTML、Markdown、EPUB、RTF、CSV）转换为 PDF
get_job_status	根据作业 ID 查询单个文件转换作业的状态

压缩与尺寸调整

compress_image 不会更改格式：PNG 输入仍为 PNG，JPEG 输入仍为 JPEG，WebP 输入仍为 WebP，且结果不会比输入文件更大。它会先尝试无损压缩（去除元数据，同时保留 ICC 配置文件和 EXIF 方向信息）；如果仍无法达到 target_size_kb，则会在锁定宽高比的情况下缩小图像。无法达到 target_size_kb 并非错误：你会得到压缩后达到的最小文件，因此请检查结果中的 file_size。不支持动画 APNG 和动画 WebP。

convert_image 中的 width 和 height 仅适用于 SVG 输入（将 SVG 转换为 png、jpeg 或 webp；转换 SVG 为 HEIC 时不适用），取值范围为 1 到 10000。只传入其中一个维度时，另一个维度会根据 SVG 自身的宽高比推算。传入两个维度可设置精确画布尺寸，但可能会改变宽高比。两者都不传入时，则保留 SVG 的固有尺寸。

V2：面向 Agent 的网页数据（18 项，需要私有 API 密钥，受套餐限制）

工具	功能
perceive_url	一次将页面渲染为多种产物（markdown、HTML、截图、PDF、链接、图像）并进行结构化提取，缓存约 1 小时
get_perceive_operation	重新获取 perceive 结果，并获取刚签名的产物 URL
perceive_batch	使用共享选项感知最多 1000 个 URL（小批次内联处理，大批次异步处理）
get_perceive_batch	通过任务 ID 轮询批量感知任务
discover_urls	通过站点地图／爬取／混合方式枚举网站 URL，不进行渲染，也不消耗渲染配额
web_search	由 Google 提供支持的搜索（网页、新闻、图像、学术、专利、地图），可选择自动感知排名靠前的结果
extract_structured	通过模式驱动的数据提取（免费 CSS 阶段 + LLM 升级），支持最多 50 个 URL 或已发现的网站
start_ingest	将网站或 URL 列表转换为适用于 RAG 的分块 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 控制面板获取这些密钥。

提示词（7 个）

可调用的工作流，在 Claude Code 中显示为 /mcp__enconvert__<name>。每个提示词都编码了各个工具无法自行执行的顺序和成本规则。

提示词	功能
site_to_rag_corpus	发现网站的 URL，对其进行筛选，摄取为分块 JSONL，并轮询直至完成
monitor_page	先渲染一次以选择合适的差异模式，检查是否重复，然后创建监控器
convert_folder	根据扩展名，将目录中的每个文件路由到正确的转换工具
research_with_sources	执行一次 web_search(perceive_top=N) 往返，然后给出带引用来源的答案
extract_dataset	编写模式，尝试免费的 CSS 阶段，然后执行提取并报告 LLM 升级情况
diagnose_render	针对空白、不完整或受阻渲染结果的升级处理流程
watch_digest	汇总所有监控器的近期变化，并进行健康状况审计

资源（4 个）

通过 URI 寻址的只读上下文。读取资源不会触发浏览器渲染，因此附加资源不会消耗配额。

资源	内容
enconvert://formats	完整的转换矩阵：每个已实现的转换组合及各工具接受的扩展名。离线可用，无需 API 密钥
enconvert://watchers	所有受监控页面及其频率、检查次数和错误连续计数
enconvert://ingest-jobs	最近的摄取任务及其状态、分块数量和输出链接
enconvert://watcher/{watcher_id}/snapshots	某个监控器的检查历史记录和差异

要求

• Node.js ^20.20.0 || >=22.22.0（与软件包的 engines 字段一致）
• EnConvert API 密钥。请在 enconvert.com/dashboard/api-keys 获取

一条命令完成安装

npx @enconvert/mcp setup

就这么简单。向导会：

1. 检测你的 AI 工具（Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Zed、Gemini CLI、Codex CLI、OpenCode），并让你选择要接入 EnConvert 的工具。检测到的工具会默认选中。
2. 只需输入一次秘密 API 密钥（输入内容会隐藏），向导会实时向 API 验证密钥。要是误粘贴了公开密钥，它也会提醒你。
3. 正确写入所有配置，包括 Windows 所需的 cmd /c npx 封装命令。你的密钥只会保存一次，位于 ~/.enconvert/config.json（权限为 600），不会复制到客户端配置中。

$ npx @enconvert/mcp setup

  EnConvert MCP - setup

? Which AI tools should get EnConvert?
  [x] Claude Code (detected)    [x] Cursor (detected)
  [ ] Claude Desktop            [ ] Windsurf   ...
? Paste your SECRET API key (sk_live_..., input hidden): ********
  ✔ API key is valid.
  + Claude Code - claude CLI (user scope)
  + Cursor - ~/.cursor/mcp.json

  Done. Restart your AI tools to pick up the server.

之后重启你的 AI 工具，就可以开始使用了。

管理同样简单

命令	功能
npx @enconvert/mcp status	查看安装位置，以及密钥是否有效（实时检查）
npx @enconvert/mcp rotate-key	换用新的 API 密钥：只需一条命令，即可应用到每个客户端
npx @enconvert/mcp upgrade	检查 npm 上是否有更新版本并升级（添加 --dry-run 可预览）
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 等）：

{
  "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：

claude mcp add enconvert -s user \
  -e ENCONVERT_API_KEY=sk_live_your_key \
  -- npx -y @enconvert/mcp@latest

如果你已运行 setup（或创建了 ~/.enconvert/config.json），则可省略内联的 env 块；服务会自动回退到已保存的密钥。客户端配置文件位置：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. “将 /Users/me/Desktop/screenshot.png 压缩到小于 200 KB。” → compress_image
8. “将 /Users/me/Docs/whitepaper.pdf 转成 Markdown，供我的 RAG 索引使用。” → convert_anything_to_markdown
9. “监控 https://example.com/changelog，并在内容变更时告诉我。” → create_watcher

Agent 会自动选择合适的工具。工具描述经过优化：处理 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 密钥
ENCONVERT_BASE_URL（env）或 base_url（配置文件）	否	https://api.enconvert.com	用于暂存环境或可自托管 EnConvert 的覆盖值
ENCONVERT_TOOLSETS（env）	否	all	要注册的工具系列：web、files 或 all

工具集

每个已注册的工具都会在每轮对话中占用上下文，因此如果只需要一个系列，请缩减工具集：

ENCONVERT_TOOLSETS	工具	适用场景
web	18 个 V2 工具：perceive、discover、search、extract、ingest、watch	Agent 浏览网页；无需转换磁盘上的文件
files	6 个 V1 文件工具：convert、compress、job status	纯文档转换助手
all（默认）	全部 24 个	两者都需要

在客户端的 env 块中，将其与 API 密钥并列设置，例如 "ENCONVERT_TOOLSETS": "web"。服务启动时会将 [enconvert-mcp] toolsets=all: 24 tools registered 记录到 stderr（stdout 是 MCP 传输通道）。未知值会导致启动错误，而不会静默回退到默认值。提示词和资源始终会注册。

工作原理

该服务是对官方 @enconvert/node-sdk 的轻量 MCP 封装，所有 HTTP、身份验证、超时（5 min）和作业轮询回退逻辑均由该 SDK 负责。每个工具处理程序都会将 MCP 输入映射到 SDK 调用，并返回一致的响应：

• 包含下载 URL 和元数据的文本摘要
• 包含完整类型化结果的 structuredContent 块
• 提供 save_to 时，指向本地文件的 resource_link（文件工具）
• 对于 perceive_url，响应中会内嵌 Markdown 产物（最多约 256 KB），以便 Agent 无需再次发起 HTTP 请求即可立即读取

故障排查

npx 在原生 Windows 上卡住 使用 cmd /c npx …。cmd 垫片会处理裸 npx 无法处理的 Windows 路径解析问题。（在 Windows 上，npx @enconvert/mcp setup 会自动写入此配置。）

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 s，而 SDK 最多会等待 5 min。如果你的客户端超时时间较短，请调高该值。

文件工具出现 "Relative path" 错误 请传入绝对路径（例如，/Users/me/file.docx 或 C:\Users\me\file.docx），或者传入 http(s):// URL。MCP 服务没有可靠的工作目录。

对 Node SDK 的依赖方式

该 MCP 服务是对 @enconvert/node-sdk 的轻量封装，所有 HTTP、身份验证、超时、重试以及 job_id 的 500 状态轮询逻辑均由该 SDK 负责。SDK 的新版本会自动惠及 MCP 服务。

许可证

MIT

链接

• Agent 技能文件（AI Agent 的工具路由规则）：SKILL.md
• EnConvert 网站：https://enconvert.com
• EnConvert Node SDK：https://www.npmjs.com/package/@enconvert/node-sdk
• MCP 规范：https://modelcontextprotocol.io
• 问题 / 反馈：https://github.com/enconvert/mcp/issues