@wpconvert/mcp

A Model Context Protocol server for WPConvert.ai. It lets an AI agent (Cursor, Claude Code, Claude Desktop, etc.) convert the current workspace folder into a WordPress theme — no manual zipping required.

It's a thin wrapper over the same HTTP API and smart-zip logic as the wpconvert CLI.

Requires Node.js >= 18. No API key is needed to start: the agent can give you a link for a few free guest previews (one quick human check in the browser, no account), or for signing in. Downloads need Starter, Pro, Agency or pay-as-you-go credits, which you can buy from the same conversation.

Tools

Configure (Claude Code)

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

--scope user makes the server available in every project. Confirm with claude mcp list (wpconvert … ✔ Connected) or /mcp inside a session. Then ask the agent to convert a folder; it will offer a guest link or a sign-in link.

To use an existing API key instead, add it before the --, after the server name: claude mcp add wpconvert --scope user -e WPCONVERT_API_KEY=wpc_live_xxx -- npx -y @wpconvert/mcp (-e accepts several values, so put the name first).

Configure (Cursor / Claude Desktop)

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

Optional env: WPCONVERT_API_KEY (an existing key; it takes precedence over a key saved by sign-in) and WPCONVERT_API_BASE (a non-default API host, for testing).

Sign-in and guest sessions are saved in ~/.wpconvert/config.json (mode 0600), shared with the wpconvert CLI. Tool results never include the key, the guest token or the link's device code.

Typical agent flow

Quota-first (recommended):

1. wpconvert_quota → review capabilities (conversion mode, can_start, download availability) and recommended_next
2. wpconvert_convert_folder { "path": "./my-site", "type": "theme" } → jobId + idempotency_key + recommended_next
3. wpconvert_check_status { "jobId": "..." } (repeat until done; follow recommended_next — usually poll every ~15s)
4. When recommended_next.tool is wpconvert_download_result → download the theme .zip
5. When preview-only or download locked → wpconvert_create_preview for a WordPress Playground URL (no ZIP)

If conversion is blocked (can_start: false), wpconvert_convert_folder returns a structured denial before zipping or submitting. Call wpconvert_quota to review recommended_action.

No key yet (guest):

1. wpconvert_convert_folder → recommended_next: wpconvert_connect { "kind": "guest" }
2. wpconvert_connect { "kind": "guest" } → the agent shows you a link and code; you open it and confirm you're human
3. wpconvert_connect_status → connected, with free previews left
4. wpconvert_convert_folder, wpconvert_check_status, then wpconvert_create_preview to see it in WordPress Playground (guest uploads up to 50MB zipped; never retried automatically, since each upload uses a preview)

Buying (download a theme, or a plan):

1. wpconvert_plans { "jobId": "..." } → every option and price; the agent asks you which one
2. Not signed in? wpconvert_connect { "kind": "login" }, then wpconvert_connect_status, then wpconvert_plans again
3. wpconvert_checkout with your choice's checkout_arguments → a Stripe link you open and pay
4. wpconvert_check_status → once paid, recommended_next is wpconvert_download_result. Guest themes you buy move to your account.

Capabilities and structured responses

Tools return human-readable prose plus a trailing JSON block (same ok() / fail() pattern as before). Key fields:

Status recommended_next rules:

• queued, pipeline stages, or tool-layer processing → wpconvert_check_status (poll)
• done + downloadable → wpconvert_download_result
• done + preview-only / download locked → wpconvert_create_preview (never download); the reason names wpconvert_plans for unlocking
• done + guest (guest: true, remaining_previews) → wpconvert_create_preview, then wpconvert_plans to buy
• failed → wpconvert_explain_failure

Idempotency recovery

• Leave idempotency_key blank for a new intentional conversion.
• If a prior wpconvert_convert_folder call timed out or returned an ambiguous network error, retry with the exact idempotency_key from that call — do not omit it and do not invent a new one.
• Do not reuse a key for changed files, options, or a deliberate new conversion.
• Preflight runs after path/plan validation but before key generation (when omitted), ZIP build, and submit — so blocked accounts never upload.

Preview-only / download locked

Free developer previews and guest previews are preview-only (Playground, no ZIP download). When download_available is false or preview_only is true, status and download tools recommend wpconvert_create_preview, wpconvert_plans or wpconvert_quota — not download retry.

Dependency pin

This package pins wpconvert@0.4.0 exactly for shared capability helpers (resolveConvertPreflight, quota formatters).