mcp

# @enconvert/mcp

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

EnConvert is the unified ingestion layer for AI agents. Perceive pages, discover URLs, search the live web, extract structured data, ingest RAG-ready chunks, and monitor for changes, all through one API key. This MCP server gives any MCP-compatible AI agent instant access to the full V2 endpoint suite.

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.) convert files and URLs through a single command.

## 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.

### 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.):

```json
{
  "mcpServers": {
    "enconvert": {
      "command": "npx",
      "args": ["-y", "@enconvert/mcp@latest"],
      "env": {
        "ENCONVERT_API_KEY": "sk_live_your_key"
      }
    }
  }
}
```

On **native Windows**, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@enconvert/mcp@latest"]`, because bare `npx` hangs. (WSL behaves like Linux.) For Claude Code:

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

The inline `env` block is optional if you've run `setup` (or created `~/.enconvert/config.json`); the server falls back to the saved key automatically. Client config locations: 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`.

## Try it

Once installed, try any of these in a fresh prompt:

1. *"Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it."* → `perceive_url`
2. *"Screenshot https://news.ycombinator.com and save the page as a PDF too."* → `perceive_url` (both artifacts in one call)
3. *"Search for the three best static site generators and read their homepages."* → `web_search` with `perceive_top`
4. *"Get every plan name and price from https://example.com/pricing."* → `extract_structured`
5. *"Convert `/Users/me/Desktop/report.docx` to PDF."* → `convert_document`
6. *"Convert `/Users/me/Desktop/iph