@enconvert/mcp

@enconvert/mcp

AI エージェント向けに、Web やファイルを読み取り、読み取りごとに 0～1 の render_quality スコアを返します。EnConvert は、1 つの API キーですべての処理を行います。ページを認識し、URL を検出し、リアルタイムの Web を検索し、構造化データを抽出し、RAG 対応のチャンクを取り込み、変更を監視します。また、Web の読み取りごとに、名前付きの減点項目とともにスコアを返すため、ブロックされたページ、チャレンジページ、空の SPA ページをコンテンツと誤認せずに検出できます。

EnConvert の公式 Model Context Protocol（MCP）サーバーです。任意の MCP 対応 AI エージェント（Claude Code、Cursor、Windsurf、Claude Desktop、Continue など）で、1 つのコマンドから Web の読み取りやファイル変換ができます。

掲載先：Official MCP Registry · Glama · LobeHub · npm

利用できる機能

LLM によるツール選択の信頼性を高めるよう最適化された 24 個のツールを利用できます。URL やブラウザー関連の処理はすべて V2 ツール（perceive_url など）を通じて行い、V1 ツールはローカル／リモートのファイル変換を担当します。デフォルトですべての 24 個が登録されます。Web ツールのみ、またはファイルツールのみを登録する方法については、ツールセットをご覧ください。

Web の読み取りごとにスコアを返します

perceive_url（およびそれを利用するすべての機能）は、render_quality（0.0～1.0）と、anti_bot_challenge、http_error、login_wall などの名前付きの deductions、さらにソースの status_code を返します。エージェントは以下の仕様に基づいて処理できます。

• コンテンツのないブロックが検出された場合、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 はプレーンテキストで返されます。内容は、ゲートウェイの Retry-After ヘッダーに基づく Rate limited; retry after N seconds です。

ファイル変換（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、テキストファイルを RAG パイプライン向けのクリーンな Markdown に変換します
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：エージェント向けウェブデータ（18、プライベート API キーが必要、プランによる制限あり）

ツール	機能
perceive_url	ページを複数の成果物（Markdown、HTML、スクリーンショット、PDF、リンク、画像）として一度にレンダリングし、構造化抽出も行います。キャッシュ期間は約 1 時間です
get_perceive_operation	新たに署名された成果物 URL を使って perceive の結果を再取得します
perceive_batch	共通オプションを使って最大 1000 個の URL を perceive します（小規模なバッチはインライン、大規模なバッチは非同期で処理します）
get_perceive_batch	ジョブ ID で perceive バッチの状態を確認します
discover_urls	レンダリングやレンダリング枠の消費なしで、サイトマップ／クロール／ハイブリッド方式によりサイトの URL を列挙します
web_search	Google を利用した検索（ウェブ、ニュース、画像、学術論文、特許、地図）を行います。上位の結果を自動で perceive することもできます
extract_structured	最大 50 個の URL または検出済みのサイトから、スキーマに基づいてデータを抽出します（無料の CSS パスと LLM によるエスカレーション）
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	差分履歴と通知機能を使い、1 時間以上の間隔でページの変更を監視します

設計上、公開されていない機能：Webhook 署名シークレットのエンドポイント（GET/POST /v2/ingest/webhook-secret*）。シークレットを LLM のコンテキストに含めるべきではないためです。これらは EnConvert ダッシュボードから取得してください。

プロンプト（7）

呼び出し可能なワークフローで、Claude Code では /mcp__enconvert__<name> として表示されます。それぞれのプロンプトには、個々のツールだけでは適用できない順序とコストのルールが組み込まれています。

プロンプト	機能
site_to_rag_corpus	サイトの URL を検出してフィルタリングし、チャンク分割済み JSONL に取り込んで、完了まで状態を確認します
monitor_page	1 回レンダリングして適切な差分モードを選び、重複を確認してからウォッチャーを作成します
convert_folder	ディレクトリ内の各ファイルを、拡張子に応じて適切な変換ツールに振り分けます
research_with_sources	web_search(perceive_top=N) を 1 往復実行し、出典を引用した回答を返します
extract_dataset	スキーマを記述し、無料の CSS パスを試した後で抽出し、LLM によるエスカレーションを報告します
diagnose_render	空、部分的、またはブロックされたレンダリングに対するエスカレーション手順です
watch_digest	すべてのウォッチャーの最近の変更をまとめ、ヘルスチェックを行います

リソース（4）

URI で指定する読み取り専用のコンテキストです。リソースの読み取りによってブラウザーのレンダリングが実行されることはないため、添付しても枠を消費しません。

リソース	内容
enconvert://formats	実装済みのすべての変換ペアと、各ツールが受け付ける拡張子を網羅した完全な変換マトリックスです。オフラインで利用でき、API キーは不要です
enconvert://watchers	監視中のすべてのページと、監視間隔、確認回数、エラーの連続回数です
enconvert://ingest-jobs	最近の取り込みジョブと、ステータス、チャンク数、出力リンクです
enconvert://watcher/{watcher_id}/snapshots	1 つのウォッチャーの確認履歴と差分です

要件

• Node.js ^20.20.0 || >=22.22.0（パッケージの engines フィールドに準拠）
• EnConvert API キー。enconvert.com/dashboard/api-keys で取得できます。

1 つのコマンドでインストール

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 キーに切り替えます。1 つのコマンドで、すべてのクライアントに反映されます
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 を実行すると、入力内容が非表示の状態でキーの入力を求めるため、キーがシェルの履歴に残ることはありません。

キーの保存場所

setup は、各クライアントのプレーンテキスト設定にキーを貼り付ける代わりに、~/.enconvert/config.json（モード 600）にキーを一度だけ保存します。サーバーは起動時にキーを読み込みます。ENCONVERT_API_KEY 環境変数が設定されている場合は、常にそちらが優先されます（Docker、CI、手動で設定する場合に便利です）。そのため、キーのローテーションは 1 つのファイルを変更するだけで済み、各クライアントは次回の起動時に新しいキーを読み込みます。

上級者向け：手動での設定

自分で設定する場合は、クライアントの 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 では、裸の npx がハングするため、"command": "cmd" と "args": ["/c", "npx", "-y", "@enconvert/mcp@latest"] を使用してください。（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（1 回の呼び出しで両方の成果物を取得）
3. 「静的サイトジェネレーターを 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 を RAG インデックス用の Markdown に変換してください。」 → convert_anything_to_markdown
9. 「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	ステージング環境またはセルフホスト可能な EnConvert 用の上書き設定
ENCONVERT_TOOLSETS（env）	いいえ	all	登録するツール群：web、files、または all

ツール群

登録する各ツールはターンごとにコンテキストを消費するため、必要なツール群が1つだけの場合は数を絞ってください。

ENCONVERT_TOOLSETS	ツール	使用する場面
web	18個のV2ツール：perceive、discover、search、extract、ingest、watch	エージェントがウェブを読み取る場合。変換対象のファイルがディスク上にない場合
files	6個のV1ファイルツール：convert、compress、job status	ドキュメント変換専用のアシスタント
all（デフォルト）	24個すべて	両方を使う場合

クライアントの env ブロックで、API キーの隣に設定します。例："ENCONVERT_TOOLSETS": "web"。サーバーは起動時に標準エラー出力へ [enconvert-mcp] toolsets=all: 24 tools registered をログ出力します（標準出力は MCP トランスポートに使用されます）。未定義の値を指定すると、暗黙にデフォルトが使われるのではなく、起動エラーになります。プロンプトとリソースは常に登録されます。

仕組み

このサーバーは、公式の @enconvert/node-sdk を薄くラップした MCP サーバーです。HTTP 通信、認証、タイムアウト（5分）、ジョブのポーリングに関するフォールバック処理はすべて SDK が担います。各ツールハンドラーは MCP 入力を SDK 呼び出しに対応付け、次の一貫した応答を返します。

• ダウンロード URL とメタデータを含むテキストの概要
• 型付けされた完全な結果を含む structuredContent ブロック
• save_to が指定されている場合は、ローカルファイルへの resource_link（ファイルツール）
• perceive_url の場合は、Markdown アーティファクトを応答にインラインで含めます（最大約256 KB）。これにより、エージェントは追加の HTTP フェッチなしですぐに読み取ることができます

トラブルシューティング

ネイティブ Windows で npx がハングする cmd /c npx … を使用してください。cmd シムは、単独の npx では対応できない Windows のパス解決を処理します。（npx @enconvert/mcp setup は Windows では自動的にこの形式を書き込みます。）

Authentication failed: Invalid or missing API key npx @enconvert/mcp status を実行してください。API キーの取得元が表示され、キーが有効かどうかがリアルタイムで検証されます。npx @enconvert/mcp rotate-key で修正するか、手動で設定した場合は ENCONVERT_API_KEY の env ブロックを確認してください。

ツール呼び出しがタイムアウトする 重いページのブラウザーでのレンダリング（perceive_url、extract_structured）には15～30秒かかる場合があり、SDK は最大5分まで待機します。クライアントのタイムアウトがそれより短い場合は、時間を延長してください。

ファイルツールで「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

リンク

• エージェントスキルファイル（AI エージェント向けのツール振り分けルール）：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