wpconvert-devtools

# WPConvert Devtools

[![npm version](https://img.shields.io/npm/v/wpconvert.svg)](https://www.npmjs.com/package/wpconvert)
[![MCP package](https://img.shields.io/npm/v/@wpconvert/mcp.svg)](https://www.npmjs.com/package/@wpconvert/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Open-source developer tools for turning AI-built websites into WordPress themes from your terminal, API, or AI assistant.**

> WPConvert does **not** modify your source project and does **not** require WordPress credentials. Output is either `theme.zip` (paid) or a WordPress Playground preview URL (~10 minutes).

> The CLI and MCP server are open source. The WPConvert conversion engine runs on [WPConvert.ai](https://wpconvert.ai) and requires an API key. Free verified accounts can create preview-only developer conversions; downloading `theme.zip` requires PRO, Agency, or PAYG credits.

## Agent quickstart (MCP)

If you are a coding agent in Cursor, Claude Desktop, or another MCP host, **use the MCP tools** (do not shell out to the CLI in the same session).

1. Configure `@wpconvert/mcp` — see [examples/mcp/](examples/mcp/) and [docs/agents.md](docs/agents.md)
2. `wpconvert_quota` — inspect capabilities before converting
3. `wpconvert_convert_folder` → `wpconvert_check_status` → `wpconvert_download_result` or `wpconvert_create_preview`

| MCP tool | Purpose |
| --- | --- |
| `wpconvert_quota` | Capabilities, credits, `recommended_next` |
| `wpconvert_convert_folder` | Zip folder + start conversion |
| `wpconvert_check_status` | Poll job status |
| `wpconvert_download_result` | Download `theme.zip` when allowed |
| `wpconvert_create_preview` | Playground URL when preview-only |
| `wpconvert_explain_failure` | Failure reason + recovery |

Portable Skill: [skills/wpconvert/SKILL.md](skills/wpconvert/SKILL.md)

## MCP setup (Cursor / Claude Desktop)

Current release: **@wpconvert/mcp@0.3.1** (`npx -y @wpconvert/mcp` uses npm `latest`; pin `@0.3.1` for deterministic installs).

```json
{
  "mcpServers": {
    "wpconvert": {
      "command": "npx",
      "args": ["-y", "@wpconvert/mcp@0.3.1"],
      "env": {
        "WPCONVERT_API_KEY": "wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY"
      }
    }
  }
}
```

Optional: set `WPCONVERT_API_BASE` to point at a non-default API host (testing only).

See [docs/mcp.md](docs/mcp.md) and [docs/agents.md](docs/agents.md) for the full agent workflow.

This repository contains the open-source [WPConvert](https://wpconvert.ai) developer tools:

| Package | Description |
| --- | --- |
| [`wpconvert`](packages/cli) | CLI — convert a local folder to a WordPress theme |
| [`@wpconvert/mcp`](packages/mcp) | MCP server — convert from Cursor, Claude Desktop, or other MCP clients |
| [`examples/`](examples) | API usage examples (curl + Node.js) |
| [`docs/`](docs) | CLI, MCP, API reference, and [agent integration guide](docs/agents.md) |
| [`openapi.yaml`](openapi.yaml) | Machine-readable OpenAPI 3.1 Developer API contract (mirrored from production) |

These tools are thin clients that call the hosted API over HTTPS.

## What this repo is NOT

This repository does **not** include the WPConvert conversion engine, backend workers, AI prompts, parser/mapper logic, billing/quota logic, or theme generation system. Those run on WPConvert.ai servers.

## Requirements

- **Node.js >= 18**
- A **WPConvert API key** (`wpc_live_...`) from your dashboard (**Settings → API & CLI**)
- **PRO/Agency** or **PAYG credits** for full conversions with `theme.zip` download
- **Free verified accounts** can run up to **3 lifetime** preview-only developer conversions (Playground preview, no ZIP)
- CLI, API, and MCP use the **same credits** as dashboard conversions for paid exports (1 credit per successful conversion; failed conversions are refunded)

## Free developer previews

Free verified WPConvert accounts can create up to **3 lifetime** developer previews from the CLI, API, or MCP. Preview-only conversions generate a WordPress Playground preview, but **theme ZIP downloads are locked**. To download `theme.zip`, upgrade to PRO/Agency or add PAYG credits, then **re-run** the conversion.

- Preview-only jobs are **never retroactively downloadable** — upgrading does not unlock an old job; convert again after upgrading.
- On success, `wpconvert convert` **automatically creates a Playground preview URL**.
- Preview-only jobs **auto-open your browser** by default (the preview is the deliverable).
- Use `--no-open` in CI/headless, or `--no-preview` to skip Playground entirely.

### Expected preview-only CLI output

```bash
wpconvert convert . --type theme
```

```
Scanning /path/to/project ...
Packaging zip ...
Zip built: 1.2 MB compressed.
Uploading (multipart) and starting conversion ...
✔ Conversion queued: abc123-def456
Free developer preview 1 of 3.
Download locked. Upgrade to PRO or add PAYG credits, then re-run this conversion to download theme.zip.
  … processing 42%
✔ Conversion complete.
Download locked. Upgrade to PRO or add PAYG credits, then re-run this conversion to download theme.zip.
Creating Playground preview ...
✔ Preview ready (WordPress Playground):
  https://playground.wordpress.net/...
  Link expires ... and is single-use limited.
  Opening in your default browser ...
Upgrade to Pro/Agency or buy PAYG credits, then re-run convert to download theme.zip.
```

Paid conversions (PRO/Agency/PAYG) download `theme.zip` automatically and print the preview URL without auto-opening unless you pass `--open`.

## Quickstart (CLI)

Current release: **wpconvert@0.3.1**

```bash
npm install -g wpconvert
# or: npx wpconvert
wpconvert login
wpconvert quota
wpconvert convert . --type theme
```

The CLI smart-zips your folder, runs a capability preflight before upload, polls until done, then downloads `theme.zip` (paid) or opens a Playground preview (free preview-only).

### Useful `convert` flags

```bash
wpconvert convert . --dry-run      # list what would upload; no upload, no credit
wpconvert convert . --no-download    # paid: skip auto-download on success
wpconvert convert . --open           # paid: auto-open Playground in browser
wpconvert convert . --no-open        # preview-only: don't auto-open browser (CI/headless)
wpconvert convert . --no-preview     # skip Playground preview entirely
wpconvert preview <jobId> --open     # open an existing job's preview later
```

### Preview before uploading

```bash
wpconvert convert . --dry-run
```

`--dry-run` lists exactly what would be uploaded — no upload, no credit used.

### Safety defaults

By default the CLI excludes:

- `.env` and secret files (`*.pem`, `*.key`, `id_rsa*`, `.npmrc`, `.ssh/`, `credentials*.json`, …)
- `node_modules`, `.git`, build output (`dist/`, `build/`, …)
- Your project's `.gitignore` patterns

Symlinks are never followed. Use `--include-env` only if you truly intend to upload secrets (not recommended).

> **Only upload projects you own or have permission to process through WPConvert.**

## Developer API (REST)

WPConvert offers three developer surfaces: **REST API**, **CLI**, and **MCP**. All call the same hosted API at `https://api.wpconvert.ai`.

| Surface | Entry point |
| --- | --- |
| **OpenAPI 3.1** | [`openapi.yaml`](openapi.yaml) — canonical machine-readable contract (mirrored from production) |
| **REST guide** | [`docs/api.md`](docs/api.md) — workflows, capabilities, idempotency, status, download, Playground |
| **CLI** | [`docs/cli.md`](docs/cli.md) — `wpconvert quota`, `wpconvert convert ./site` |
| **MCP** | [`docs/mcp.md`](docs/mcp.md) — six MCP tools for Cursor, Claude Desktop, etc. |
| **Agents** | [`docs/agents.md`](docs/agents.md) — capability gate, idempotency, preview vs download |

> `openapi.yaml` is a **byte-identical mirror** of the canonical WPConvert API contract maintained in the private application repository. Do not independently modify API behavior or schemas here. Contract changes originate with the production API and are mirrored into this repository.

**Quick example:**

```bash
curl https://api.wpconvert.ai/api/convert/quota \
  -H "X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY"
```

See [`docs/api.md`](docs/api.md) for the full workflow (quota → convert → status → download or Playground) and [`examples/`](examples/) for end-to-end scripts.

## API overview (legacy quick reference)

> Prefer [`docs/api.md`](docs/api.md) and [`openapi.yaml`](openapi.yaml) for the current contract. The table below is a minimal quick reference.

All requests require the `X-API-Key` header. Base URL: `https://api.wpconvert.ai`

| Method | Endpoint | Purpose |
| --- | --- | --- |
| `GET` | `/api/convert/quota` | Preflight quota and developer capabilities |
| `POST` | `/api/convert` | Upload a zip and start conversion (multipart) |
| `POST` | `/api/convert/upload-url` | Mint a signed URL for large archives |
| `POST` | `/api/convert/from-storage` | Queue conversion after signed upload |
| `GET` | `/api/convert/{jobId}/status` | Poll conversion status |
| `GET` | `/api/download/{projectId}` | Get download URL for a completed conversion |
| `POST` | `/api/playground/sessions` | Create a Playground preview session |

### Start a conversion

```bash
curl -X POST https://api.wpconvert.ai/api/convert \
  -H "X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY" \
  -F "file=@my-site.zip" \
  -F "project_name=my-site" \
  -F "export_type=theme"
```

Returns `{ "jobId": "...", "status": "queued", ... }`.

### Check status

```bash
curl https://api.wpconvert.ai/api/convert/JOB_ID/status \
  -H "X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY"
```

### Download result

```bash
curl https://api.wpconvert.ai/api/download/PROJECT_ID \
  -H "X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY"
```

Returns `{ "download_url": "https://...", "name": "my-site-theme.zip" }`. Follow the `download_url` to fetch the theme zip — do not hard-code storage paths.

See [docs/api.md](docs/api.md), [openapi.yaml](openapi.yaml), and [examples/](examples/) f