mcp

# @enconvert/mcp

[![MCP Badge](https://lobehub.com/badge/mcp/enconvert-mcp?style=for-the-badge)](https://lobehub.com/mcp/enconvert-mcp)

[![mcp MCP server](https://glama.ai/mcp/servers/enconvert/mcp/badges/card.svg)](https://glama.ai/mcp/servers/enconvert/mcp)

[![mcp MCP server](https://glama.ai/mcp/servers/enconvert/mcp/badges/score.svg)](https://glama.ai/mcp/servers/enconvert/mcp)

Web and file reading for AI agents with a 0-1 `render_quality` score on every read. EnConvert perceives pages, discovers URLs, searches the live web, extracts structured data, ingests RAG-ready chunks and watches for changes, all through one API key, and every web read comes back scored with named deductions so a blocked, challenge or empty-SPA page is flagged instead of mistaken for content.

Official **Model Context Protocol (MCP) server** for [EnConvert](https://enconvert.com). It lets any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, Claude Desktop, Continue, etc.) read the web and convert files through a single command.

Listed on: [Official MCP Registry](https://registry.modelcontextprotocol.io/?search=com.enconvert%2Fmcp) · [Glama](https://glama.ai/mcp/servers/enconvert/mcp) · [LobeHub](https://lobehub.com/mcp/enconvert-mcp) · [npm](https://www.npmjs.com/package/@enconvert/mcp)

## What you get

Twenty-four tools, optimized for reliable LLM tool selection. All URL/browser work goes through the V2 tools (`perceive_url` and friends); the V1 tools cover local/remote FILE conversion. All 24 are registered by default; see [Toolsets](#toolsets) to register only the web or only the file tools.

### Every web read is scored

`perceive_url` (and everything built on it) returns `render_quality` (0.0-1.0) with named `deductions` such as `anti_bot_challenge`, `http_error` or `login_wall`, plus the source `status_code`. The contract your agent can rely on:

- A detected content-free block is **HTTP 200 with `is_blocked: true`, empty `outputs` and `billed: false`**. The tool text says `Blocked: yes (not billed)`. There is nothing to read; do not retry the same URL expecting a different answer.
- Reads whose deductions include `http_error` or `login_wall` are also not billed (`billed: false`, text `Not billed.`). Cache hits are billed.
- Treat `render_quality` below 0.40 as not-content: surface the score and deductions instead of the markdown.
- A 429 comes back as plain text: `Rate limited; retry after N seconds`, from the gateway's `Retry-After` header.

### File conversion (6)

| Tool | What it does |
|------|-------------|
| `convert_document` | Convert DOC(X), XLS(X), PPT(X), ODT, ODS, ODP, OTS, Pages, Numbers, EPUB, HTML, MD, CSV, JSON, XML, YAML, TOML to PDF (or between each other) |
| `convert_image` | Convert between JPEG, PNG, SVG, HEIC, WebP, plus PDF → JPEG rasterization (handy for iPhone HEIC → WebP). SVG rasterization takes optional `width` and `height` controls |
| `compress_image` | Shrink a PNG, JPEG or WebP without changing its format, optionally to a target size in KB |
| `convert_anything_to_markdown` | Turn PDF, Office, ODF, EPUB, HTML, CSV or text files into clean Markdown for RAG pipelines |
| `convert_anything_to_pdf` | Turn almost any file (Office, ODF, iWork, images, SVG, HTML, Markdown, EPUB, RTF, CSV) into a PDF |
| `get_job_status` | Check a single file-conversion job by its job ID |

### Compression and sizing

`compress_image` never changes the format: a PNG comes back as a PNG, a JPEG as a JPEG, a WebP as a WebP, and the result is never larger than the input. It goes lossless first (metadata stripped, ICC profile and EXIF orientation preserved), then downscales with the aspect ratio locked if `target_size_kb` is still out of reach. An unreachable `target_size_kb` is not an error: you get back the smallest file achieved, so check `file_size` on the result. Animated APNG and animated WebP are rejected.

`width` and `height` on `convert_image` apply to SVG input only (svg to png, jpeg or webp; SVG to HEIC does not take them), 1 to 10000 each. Pass one alone and the other dimension is derived from the SVG's own aspect ratio. Pass both to set the exact canvas, which may change the aspect ratio. Omit both and the SVG's intrinsic size is kept.

### V2: web data for agents (18, private API key required, plan-gated)

| Tool | What it does |
|------|-------------|
| `perceive_url` | Render a page into multiple artifacts at once (markdown, HTML, screenshots, PDF, links, images) + structured extraction, with ~1h caching |
| `get_perceive_operation` | Re-fetch a perceive result with freshly signed artifact URLs |
| `perceive_batch` | Perceive up to 1000 URLs with shared options (inline for small batches, async for large) |
| `get_perceive_batch` | Poll a perceive batch by job ID |
| `discover_urls` | Enumerate a site's URLs via sitemap/crawl/hybrid, with no rendering and no render quota |
| `web_search` | Google-backed search (web, news, images, scholar, patents, maps) with optional auto-perceive of top results |
| `extract_structured` | Schema-driven data extraction (free CSS pass + LLM escalation) from up to 50 URLs or a discovered site |
| `start_ingest` | Turn a site or URL list into RAG-ready chunked JSONL (always async) |
| `list_ingest_jobs` / `get_ingest_job` / `cancel_ingest_job` | Manage ingest jobs |
| `retry_ingest_webhook` | Re-deliver a completed job's HMAC-signed completion webhook |
| `create_watcher` / `list_watchers` / `get_watcher` / `get_watcher_snapshots` / `update_watcher` / `delete_watcher` | Monitor pages for changes on an hourly-plus cadence with diff history and notifications |

Not exposed by design: the webhook signing-secret endpoints (`GET/POST /v2/ingest/webhook-secret*`), because secrets do not belong in LLM context. Fetch those from the EnConvert dashboard.

### Prompts (7)

Invokable workflows, surfaced as `/mcp__enconvert__<name>` in Claude Code. Each encodes ordering and cost rules the individual tools cannot enforce on their own.

| Prompt | What it does |
|------|-------------|
| `site_to_rag_corpus` | Discover a site's URLs, filter them, ingest to chunked JSONL, poll to completion |
| `monitor_page` | Render once to pick the right diff mode, check for duplicates, then create the watcher |
| `convert_folder` | Route every file in a directory to the correct conversion tool by extension |
| `research_with_sources` | One `web_search(perceive_top=N)` round trip, then an answer with cited sources |
| `extract_dataset` | Write the schema, try the free CSS pass, then extract and report the LLM escalation |
| `diagnose_render` | Escalation ladder for an empty, partial or blocked render |
| `watch_digest` | Roll up every watcher's recent changes plus a health audit |

### Resources (4)

Read-only context addressed by URI. **No resource read triggers a browser render**, so attaching them costs no quota.

| Resource | What it holds |
|------|-------------|
| `enconvert://formats` | The full conversion matrix: every implemented pair and accepted extension per tool. Offline, works without an API key |
| `enconvert://watchers` | Every page being monitored, with cadence, check counts and error streaks |
| `enconvert://ingest-jobs` | Recent ingest jobs with status, chunk counts and output links |
| `enconvert://watcher/{watcher_id}/snapshots` | One watcher's check history and diffs |

## Requirements

- **Node.js `^20.20.0 || >=22.22.0`** (matches the package's `engines` field)
- An **EnConvert API key**. Get one at [enconvert.com/dashboard/api-keys](https://enconvert.com/dashboard/api-keys)

## Install in one command

```bash
npx @enconvert/mcp setup
```

That's it. The wizard:

1. **Detects your AI tools** (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Codex CLI, OpenCode) and lets you pick which get EnConvert. Detected tools are preselected.
2. **Asks for your secret API key once** (hidden input) and validates it live against the API. It even tells you if you pasted a *public* key by mistake.
3. **Writes every config correctly**, including the `cmd /c npx` wrapper Windows needs. Your key is stored once in `~/.enconvert/config.json` (permissions `600`), never copied into client configs.

```
$ 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.
```

Restart your AI tools afterwards, and you're running.

### Manage it just as easily

| Command | What it does |
|---|---|
| `npx @enconvert/mcp status` | Where it's installed + whether your key is valid (live check) |
| `npx @enconvert/mcp rotate-key` | Swap in a new API key: one command, applies to every client |
| `npx @enconvert/mcp upgrade` | Check npm for a newer version and upgrade (add `--dry-run` to preview) |
| `npx @enconvert/mcp remove` | Uninstall from selected tools (optionally delete the saved key) |
| `npx @enconvert/mcp setup --yes` | Non-interactive: configure all detected tools with the saved key |

Scripting? `setup --clients claude-code,cursor --api-key sk_live_... --yes` skips all prompts. `rotate-key` with no argument prompts with hidden input so the key never lands in your shell history.

### Where the key lives

`setup` stores your key **once** in `~/.enconvert/config.json` (mode `600`) instead of pasting it into every client's plaintext config. The server reads it at startup; the `ENCONVERT_API_KEY` environment variable always overrides it (for Docker, CI, or manual setups). Rotating is therefore a single-file change, and every client picks it up on its next launch.

## Advanced: manual configuration

Prefer to wire it yourself? Add this to your client's MCP config (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, etc.):

`