WPConvert MCP

@wpconvert/mcp

WPConvert.ai 用の Model Context Protocol サーバーです。Cursor、Claude Code、Claude Desktop などの AI エージェントを使って、現在のワークスペースフォルダーを WordPress テーマに変換できます。手動で ZIP ファイルを作成する必要はありません。

wpconvert CLI と同じ HTTP API およびスマート ZIP ロジックを利用する薄いラッパーです。

Node.js >= 18 が必要です。利用開始に API キーは必要ありません。エージェントは、無料のゲストプレビューを利用するためのリンク（ブラウザーで簡単な確認を一度行うだけで、アカウントは不要）か、サインイン用のリンクを提示できます。ダウンロードには Starter、Pro、Agency、または従量課金クレジットが必要です。これらは同じ会話から購入できます。

ツール

ツール	目的
wpconvert_convert_folder	node_modules、ビルド出力、シークレットを除外してフォルダーを ZIP に圧縮し、変換を開始します。jobId を返します。
wpconvert_check_status	ジョブのステータスをポーリングします。永続化される値は OpenAPI の ConversionStatus 列挙型（queued、パイプラインの各段階、done、failed）に従います。ツールレイヤーの分類値 processing は処理中を意味し、永続化される API の値ではありません。
wpconvert_download_result	完了した変換結果をディスクにダウンロードします。
wpconvert_create_preview	WordPress Playground の URL を取得して、ブラウザー上で実行される WordPress でテーマを表示します。リンクは約 10 分後に期限切れとなり、機密情報を含むため、ブラウザーで開いてください。
wpconvert_explain_failure	失敗したジョブの理由を返します。
wpconvert_quota	利用枠、利用可能な機能、recommended_next を表示します。変換の前に呼び出してください。ゲストセッションでは、残りの無料プレビュー数が表示されます。
wpconvert_connect	ブラウザーで開くリンクを開始します。kind: "guest"（無料プレビュー、アカウント不要）または kind: "login"（サインイン。新しい API キーをローカルに保存）を指定します。エージェントがリンクを開くことはありません。リンクとコードが返されます。
wpconvert_connect_status	リンクの手続きが完了したか（約 20 秒待機）と、現在の WPConvert の接続状態を確認します。
wpconvert_plans	含まれる内容と本日の価格を含む、すべてのプランを表示します。Starter（テーマ 1 つ）、Pro、Agency（月払い／年払い）、従量課金パックがあります。その変換で利用できるプランを表示するには、jobId を指定します。
wpconvert_checkout	選択したプランの Stripe チェックアウトリンクを生成します。サインイン済みのアカウントが必要です。リンクを開いて支払いを行うのはユーザーです。エージェントが支払いを行うことはありません。

設定（Claude Code）

claude mcp add wpconvert --scope user -- npx -y @wpconvert/mcp

--scope user を指定すると、すべてのプロジェクトでサーバーを利用できます。claude mcp list（wpconvert … ✔ Connected）またはセッション内の /mcp で確認してください。その後、エージェントにフォルダーの変換を依頼すると、ゲスト用リンクまたはサインイン用リンクが提示されます。

既存の API キーを使うには、サーバー名の後、-- の前に追加します。claude mcp add wpconvert --scope user -e WPCONVERT_API_KEY=wpc_live_xxx -- npx -y @wpconvert/mcp（-e は複数の値を受け付けるため、変数名を先に指定してください）。

設定（Cursor / Claude Desktop）

{
  "mcpServers": {
    "wpconvert": {
      "command": "npx",
      "args": ["-y", "@wpconvert/mcp"]
    }
  }
}

env は任意です。WPCONVERT_API_KEY（既存のキー。サインインで保存されたキーより優先されます）および WPCONVERT_API_BASE（テスト用のデフォルト以外の API ホスト）を指定できます。

サインインセッションとゲストセッションは ~/.wpconvert/config.json（モード 0600）に保存され、wpconvert CLI と共有されます。ツールの結果にキー、ゲストトークン、リンクのデバイスコードが含まれることはありません。

一般的なエージェントのフロー

クォータを最初に確認（推奨）：

1. wpconvert_quota → capabilities（変換モード、can_start、ダウンロードの可否）と recommended_next を確認します
2. wpconvert_convert_folder { "path": "./my-site", "type": "theme" } → jobId + idempotency_key + recommended_next
3. wpconvert_check_status { "jobId": "..." }（done になるまで繰り返し、recommended_next に従います。通常は約15秒ごとにポーリングします）
4. recommended_next.tool が wpconvert_download_result の場合 → テーマの .zip をダウンロードします
5. プレビューのみの場合、またはダウンロードがロックされている場合 → wpconvert_create_preview で WordPress Playground の URL を取得します（ZIP はありません）

変換がブロックされている（can_start: false）場合、wpconvert_convert_folder は ZIP 化や送信を行う前に、構造化された拒否応答を返します。wpconvert_quota を呼び出して recommended_action を確認してください。

まだキーを持っていない場合（ゲスト）：

1. wpconvert_convert_folder → recommended_next: wpconvert_connect { "kind": "guest" }
2. wpconvert_connect { "kind": "guest" } → エージェントにリンクとコードを表示させ、リンクを開いて人間であることを確認します
3. wpconvert_connect_status → connected と、残りの無料プレビュー数を確認します
4. wpconvert_convert_folder、wpconvert_check_status の順に実行し、続けて wpconvert_create_preview で WordPress Playground 上で確認します（ゲストは ZIP 圧縮後50MBまでアップロードできます。各アップロードでプレビューを使用するため、自動再試行は行われません）

購入する場合（テーマまたはプランをダウンロード）：

1. wpconvert_plans { "jobId": "..." } → すべてのオプションと価格が表示され、エージェントがどれを選ぶか尋ねます
2. サインインしていない場合は、wpconvert_connect { "kind": "login" } を実行し、続けて wpconvert_connect_status を確認してから、もう一度 wpconvert_plans を実行します
3. 選択したプランの checkout_arguments を指定して wpconvert_checkout を実行します → Stripe のリンクが表示されるので、開いて支払います
4. wpconvert_check_status → 支払いが完了すると、recommended_next が wpconvert_download_result になります。購入したゲストのテーマはアカウントに移動します。

機能と構造化レスポンス

ツールは、人が読める文章と末尾の JSON ブロックを返します（従来と同じ ok() / fail() パターンです）。主なフィールドは次のとおりです。

フィールド	場所	意味
quota	wpconvert_quota	バックエンドのクォータ全体の内容（将来追加される未知のフィールドも保持されます）
summary	クォータ、拒否応答	予測される can_start、mode、consumes、download_available
capabilities_available	quota	capabilities.conversion に対応していないレガシーバックエンドでは false
recommended_next	すべてのツール	{ tool, reason, retry_after_seconds? } — 次に呼び出す MCP ツール
next_action	変換の成功時	文字列（変更なし）— エージェント向けの操作案内
idempotency_key	convert	事前チェックで拒否された場合は省略されます（キーは生成されません）

ステータスに応じた recommended_next のルール：

• queued、パイプラインの各ステージ、またはツールレイヤーの processing → wpconvert_check_status（ポーリング）
• done + ダウンロード可能 → wpconvert_download_result
• done + プレビューのみ／ダウンロードがロックされている → wpconvert_create_preview（ダウンロードは行いません）。ロック解除のための wpconvert_plans が理由に記載されます
• done + ゲスト（guest: true、remaining_previews）→ wpconvert_create_preview を実行し、続けて wpconvert_plans で購入します
• failed → wpconvert_explain_failure

冪等性の回復

• 新たに意図して変換を行う場合は、idempotency_key を空欄にします。
• 以前の wpconvert_convert_folder 呼び出しがタイムアウトした場合、またはネットワークエラーかどうか判然としない応答が返された場合は、その呼び出しで使ったものとまったく同じ idempotency_key を指定して再試行します。省略したり、新しいキーを作成したりしないでください。
• ファイルやオプションを変更した場合、または意図的に新しい変換を行う場合は、キーを再利用しないでください。
• 事前チェックは、パス／プランの検証後、キーの生成（省略されている場合）、ZIP の作成、送信の前に行われます。そのため、ブロックされたアカウントからアップロードされることはありません。

プレビューのみ／ダウンロードがロックされている場合

無料の開発者プレビューとゲストプレビューはプレビュー専用です（Playground でのプレビューで、ZIP のダウンロードはありません）。download_available が false、または preview_only が true の場合、ステータスツールとダウンロードツールは、ダウンロードの再試行ではなく、wpconvert_create_preview、wpconvert_plans、または wpconvert_quota を推奨します。

依存関係の固定

このパッケージでは、共有機能ヘルパー（resolveConvertPreflight、クォータフォーマッター）のために、[email protected] を正確に固定しています。