{
  "markdown": "# WPConvert Devtools\n\n[![npm version](https://img.shields.io/npm/v/wpconvert.svg)](https://www.npmjs.com/package/wpconvert)\n[![MCP package](https://img.shields.io/npm/v/@wpconvert/mcp.svg)](https://www.npmjs.com/package/@wpconvert/mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n**Open-source developer tools for turning AI-built websites into WordPress themes from your terminal, API, or AI assistant.**\n\n> 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).\n\n> 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.\n\n## Agent quickstart (MCP)\n\nIf 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).\n\n1. Configure `@wpconvert/mcp` — see [examples/mcp/](examples/mcp/) and [docs/agents.md](docs/agents.md)\n2. `wpconvert_quota` — inspect capabilities before converting\n3. `wpconvert_convert_folder` → `wpconvert_check_status` → `wpconvert_download_result` or `wpconvert_create_preview`\n\n| MCP tool | Purpose |\n| --- | --- |\n| `wpconvert_quota` | Capabilities, credits, `recommended_next` |\n| `wpconvert_convert_folder` | Zip folder + start conversion |\n| `wpconvert_check_status` | Poll job status |\n| `wpconvert_download_result` | Download `theme.zip` when allowed |\n| `wpconvert_create_preview` | Playground URL when preview-only |\n| `wpconvert_explain_failure` | Failure reason + recovery |\n\nPortable Skill: [skills/wpconvert/SKILL.md](skills/wpconvert/SKILL.md)\n\n## MCP setup (Cursor / Claude Desktop)\n\nCurrent release: **@wpconvert/mcp@0.3.1** (`npx -y @wpconvert/mcp` uses npm `latest`; pin `@0.3.1` for deterministic installs).\n\n```json\n{\n  \"mcpServers\": {\n    \"wpconvert\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@wpconvert/mcp@0.3.1\"],\n      \"env\": {\n        \"WPCONVERT_API_KEY\": \"wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY\"\n      }\n    }\n  }\n}\n```\n\nOptional: set `WPCONVERT_API_BASE` to point at a non-default API host (testing only).\n\nSee [docs/mcp.md](docs/mcp.md) and [docs/agents.md](docs/agents.md) for the full agent workflow.\n\nThis repository contains the open-source [WPConvert](https://wpconvert.ai) developer tools:\n\n| Package | Description |\n| --- | --- |\n| [`wpconvert`](packages/cli) | CLI — convert a local folder to a WordPress theme |\n| [`@wpconvert/mcp`](packages/mcp) | MCP server — convert from Cursor, Claude Desktop, or other MCP clients |\n| [`examples/`](examples) | API usage examples (curl + Node.js) |\n| [`docs/`](docs) | CLI, MCP, API reference, and [agent integration guide](docs/agents.md) |\n| [`openapi.yaml`](openapi.yaml) | Machine-readable OpenAPI 3.1 Developer API contract (mirrored from production) |\n\nThese tools are thin clients that call the hosted API over HTTPS.\n\n## What this repo is NOT\n\nThis 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.\n\n## Requirements\n\n- **Node.js >= 18**\n- A **WPConvert API key** (`wpc_live_...`) from your dashboard (**Settings → API & CLI**)\n- **PRO/Agency** or **PAYG credits** for full conversions with `theme.zip` download\n- **Free verified accounts** can run up to **3 lifetime** preview-only developer conversions (Playground preview, no ZIP)\n- CLI, API, and MCP use the **same credits** as dashboard conversions for paid exports (1 credit per successful conversion; failed conversions are refunded)\n\n## Free developer previews\n\nFree 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.\n\n- Preview-only jobs are **never retroactively downloadable** — upgrading does not unlock an old job; convert again after upgrading.\n- On success, `wpconvert convert` **automatically creates a Playground preview URL**.\n- Preview-only jobs **auto-open your browser** by default (the preview is the deliverable).\n- Use `--no-open` in CI/headless, or `--no-preview` to skip Playground entirely.\n\n### Expected preview-only CLI output\n\n```bash\nwpconvert convert . --type theme\n```\n\n```\nScanning /path/to/project ...\nPackaging zip ...\nZip built: 1.2 MB compressed.\nUploading (multipart) and starting conversion ...\n✔ Conversion queued: abc123-def456\nFree developer preview 1 of 3.\nDownload locked. Upgrade to PRO or add PAYG credits, then re-run this conversion to download theme.zip.\n  … processing 42%\n✔ Conversion complete.\nDownload locked. Upgrade to PRO or add PAYG credits, then re-run this conversion to download theme.zip.\nCreating Playground preview ...\n✔ Preview ready (WordPress Playground):\n  https://playground.wordpress.net/...\n  Link expires ... and is single-use limited.\n  Opening in your default browser ...\nUpgrade to Pro/Agency or buy PAYG credits, then re-run convert to download theme.zip.\n```\n\nPaid conversions (PRO/Agency/PAYG) download `theme.zip` automatically and print the preview URL without auto-opening unless you pass `--open`.\n\n## Quickstart (CLI)\n\nCurrent release: **wpconvert@0.3.1**\n\n```bash\nnpm install -g wpconvert\n# or: npx wpconvert\nwpconvert login\nwpconvert quota\nwpconvert convert . --type theme\n```\n\nThe 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).\n\n### Useful `convert` flags\n\n```bash\nwpconvert convert . --dry-run      # list what would upload; no upload, no credit\nwpconvert convert . --no-download    # paid: skip auto-download on success\nwpconvert convert . --open           # paid: auto-open Playground in browser\nwpconvert convert . --no-open        # preview-only: don't auto-open browser (CI/headless)\nwpconvert convert . --no-preview     # skip Playground preview entirely\nwpconvert preview <jobId> --open     # open an existing job's preview later\n```\n\n### Preview before uploading\n\n```bash\nwpconvert convert . --dry-run\n```\n\n`--dry-run` lists exactly what would be uploaded — no upload, no credit used.\n\n### Safety defaults\n\nBy default the CLI excludes:\n\n- `.env` and secret files (`*.pem`, `*.key`, `id_rsa*`, `.npmrc`, `.ssh/`, `credentials*.json`, …)\n- `node_modules`, `.git`, build output (`dist/`, `build/`, …)\n- Your project's `.gitignore` patterns\n\nSymlinks are never followed. Use `--include-env` only if you truly intend to upload secrets (not recommended).\n\n> **Only upload projects you own or have permission to process through WPConvert.**\n\n## Developer API (REST)\n\nWPConvert offers three developer surfaces: **REST API**, **CLI**, and **MCP**. All call the same hosted API at `https://api.wpconvert.ai`.\n\n| Surface | Entry point |\n| --- | --- |\n| **OpenAPI 3.1** | [`openapi.yaml`](openapi.yaml) — canonical machine-readable contract (mirrored from production) |\n| **REST guide** | [`docs/api.md`](docs/api.md) — workflows, capabilities, idempotency, status, download, Playground |\n| **CLI** | [`docs/cli.md`](docs/cli.md) — `wpconvert quota`, `wpconvert convert ./site` |\n| **MCP** | [`docs/mcp.md`](docs/mcp.md) — six MCP tools for Cursor, Claude Desktop, etc. |\n| **Agents** | [`docs/agents.md`](docs/agents.md) — capability gate, idempotency, preview vs download |\n\n> `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.\n\n**Quick example:**\n\n```bash\ncurl https://api.wpconvert.ai/api/convert/quota \\\n  -H \"X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY\"\n```\n\nSee [`docs/api.md`](docs/api.md) for the full workflow (quota → convert → status → download or Playground) and [`examples/`](examples/) for end-to-end scripts.\n\n## API overview (legacy quick reference)\n\n> Prefer [`docs/api.md`](docs/api.md) and [`openapi.yaml`](openapi.yaml) for the current contract. The table below is a minimal quick reference.\n\nAll requests require the `X-API-Key` header. Base URL: `https://api.wpconvert.ai`\n\n| Method | Endpoint | Purpose |\n| --- | --- | --- |\n| `GET` | `/api/convert/quota` | Preflight quota and developer capabilities |\n| `POST` | `/api/convert` | Upload a zip and start conversion (multipart) |\n| `POST` | `/api/convert/upload-url` | Mint a signed URL for large archives |\n| `POST` | `/api/convert/from-storage` | Queue conversion after signed upload |\n| `GET` | `/api/convert/{jobId}/status` | Poll conversion status |\n| `GET` | `/api/download/{projectId}` | Get download URL for a completed conversion |\n| `POST` | `/api/playground/sessions` | Create a Playground preview session |\n\n### Start a conversion\n\n```bash\ncurl -X POST https://api.wpconvert.ai/api/convert \\\n  -H \"X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY\" \\\n  -F \"file=@my-site.zip\" \\\n  -F \"project_name=my-site\" \\\n  -F \"export_type=theme\"\n```\n\nReturns `{ \"jobId\": \"...\", \"status\": \"queued\", ... }`.\n\n### Check status\n\n```bash\ncurl https://api.wpconvert.ai/api/convert/JOB_ID/status \\\n  -H \"X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY\"\n```\n\n### Download result\n\n```bash\ncurl https://api.wpconvert.ai/api/download/PROJECT_ID \\\n  -H \"X-API-Key: wpc_live_EXAMPLE_ONLY_NOT_A_REAL_KEY\"\n```\n\nReturns `{ \"download_url\": \"https://...\", \"name\": \"my-site-theme.zip\" }`. Follow the `download_url` to fetch the theme zip — do not hard-code storage paths.\n\nSee [docs/api.md](docs/api.md), [openapi.yaml](openapi.yaml), and [examples/](examples/) for full examples.\n\n## Environment variables\n\n| Variable | Purpose |\n| --- | --- |\n| `WPCONVERT_API_KEY` | API key (overrides stored config) |\n| `WPCONVERT_API_BASE` | Override API base URL (advanced/testing) |\n\nSee [.env.example](.env.example) for a safe template with fake values.\n\n## Development\n\n```bash\ngit clone https://github.com/FTWAgency/wpconvert-devtools.git\ncd wpconvert-devtools\nnpm install\nnpm run check\n```\n\n## License\n\nMIT — Copyright (c) 2026 FTW Agency, operating WPConvert.ai. See [LICENSE](LICENSE).\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for reporting vulnerabilities and upload safety guidance.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n",
  "bytes": 10680,
  "sha": "73acb6fd2582363926236054d02ae7d9f1a7dcae4e86972e434c3dcce95f1c58",
  "repo_slug": "ftwagency/wpconvert-devtools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_wpconvert_mcp_79d896aa/readme"
}