内容
# WPConvert 开发工具
[](https://www.npmjs.com/package/wpconvert)
[](https://www.npmjs.com/package/@wpconvert/mcp)
[](LICENSE)
**用于从终端、API 或 AI 助手将 AI 构建的网站转换为 WordPress 主题的开源开发工具。**
> CLI 和 MCP 服务器是开源的。WPConvert 转换引擎运行在 [WPConvert.ai](https://wpconvert.ai) 上，需要 API 密钥。
本仓库包含开源的 [WPConvert](https://wpconvert.ai) 开发工具：
| 软件包 | 描述 |
| --- | --- |
| [`wpconvert`](packages/cli) | CLI — 将本地文件夹转换为 WordPress 主题 |
| [`@wpconvert/mcp`](packages/mcp) | MCP 服务器 — 从 Cursor、Claude Desktop 或其他 MCP 客户端转换 |
| [`examples/`](examples) | API 使用示例（curl + Node.js） |
| [`docs/`](docs) | CLI、MCP 和 API 参考 |
这些工具是调用托管 API 的薄客户端。
## 本仓库不包含的内容
本仓库 **不包含** WPConvert 转换引擎、后端工作器、AI 提示、解析器/映射器逻辑、计费/配额逻辑或主题生成系统。这些运行在 WPConvert.ai 服务器上。
## 要求
- **Node.js >= 18**
- 从仪表盘（**设置 → API & CLI**）获取的 **WPConvert API 密钥** (`wpc_live_...`)
- **Pro/Agency** 计划包含开发者访问权限；**PAYG** 计划适用于可用的积分
- CLI、API 和 MCP 使用与仪表盘转换相同的积分（1 个积分/成功转换；失败转换退款）
## 快速入门（CLI）
```bash
npm install -g wpconvert
wpconvert login
wpconvert convert . --type theme
```
CLI 智能压缩文件夹，上传，轮询直到完成，然后下载主题 `.zip`。
### 上传前预览
```bash
wpconvert convert . --dry-run
```
`--dry-run` 列出将要上传的内容 — 无上传，无积分消耗。
### 安全默认值
CLI 默认排除：
- `.env` 和机密文件 (`*.pem`, `*.key`, `id_rsa*`, `.npmrc`, `.ssh/`, `credentials*.json`, …)
- `node_modules`, `.git`, 构建输出 (`dist/`, `build/`, …)
- 项目的 `.gitignore` 模式
永不跟随符号链接。只有在确实打算上传机密文件时，才使用 `--include-env`（不推荐）。
> **仅上传您拥有或有权通过 WPConvert 处理的项目。**
## MCP 设置（Cursor / Claude Desktop）
将以下内容添加到您的 MCP 配置：
```json
{
"mcpServers": {
"wpconvert": {
"command": "npx",
"args": ["-y", "@wpconvert/mcp"],
"env": {
"WPCONVERT_API_KEY": "wpc_live_xxx"
}
}
}
}
```
可选：设置 `WPCONVERT_API_BASE` 以指向非默认 API 主机（仅用于测试）。
参见 [docs/mcp.md](docs/mcp.md) 获取工具参考和典型代理流程。
## API 概述
所有请求都需要 `X-API-Key` 头部。基准 URL：`https://api.wpconvert.ai`
| 方法 | 端点 | 目的 |
| --- | --- | --- |
| `POST` | `/api/convert` | 上传 zip 并启动转换（multipart） |
| `GET` | `/api/convert/:jobId/status` | 轮询转换状态 |
| `GET` | `/api/download/:projectId` | 获取已完成转换的下载 URL |
### 启动转换
```bash
curl -X POST https://api.wpconvert.ai/api/convert \
-H "X-API-Key: wpc_live_xxx" \
-F "file=@my-site.zip" \
-F "project_name=my-site" \
-F "export_type=theme"
```
返回 `{ "jobId": "...", "status": "queued", ... }`。
### 检查状态
```bash
curl https://api.wpconvert.ai/api/convert/JOB_ID/status \
-H "X-API-Key: wpc_live_xxx"
```
### 下载结果
```bash
curl https://api.wpconvert.ai/api/download/PROJECT_ID \
-H "X-API-Key: wpc_live_xxx"
```
返回 `{ "download_url": "https://...", "name": "my-site-theme.zip" }`。跟随 `download_url` 获取主题 zip — 不要硬编码存储路径。
参见 [docs/api.md](docs/api.md) 和 [examples/](examples/) 获取完整示例。
## 环境变量
| 变量 | 目的 |
| --- | --- |
| `WPCONVERT_API_KEY` | API 密钥（覆盖存储配置） |
| `WPCONVERT_API_BASE` | 覆盖 API 基准 URL（高级/测试） |
参见 [.env.example](.env.example) 获取带有假值的的安全模板。
## 开发
```bash
git clone https://github.com/FTWAgency/wpconvert-devtools.git
cd wpconvert-devtools
npm install
npm run check
```
## 许可证
MIT — Copyright (c) 2026 FTW Agency, operating WPConvert.ai. 参见 [LICENSE](LICENSE).
## 安全
参见 [SECURITY.md](SECURITY.md) 获取漏洞报告和上传安全指南。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md).
