WPConvert MCP

@wpconvert/mcp

面向 WPConvert.ai 的 Model Context Protocol 服务。它允许 AI Agent（Cursor、Claude Code、Claude Desktop 等）将当前工作区文件夹转换为 WordPress 主题——无需手动打包。

这是一个轻量封装，使用与 wpconvert CLI 相同的 HTTP API 和智能压缩逻辑。

需要 Node.js >= 18。启动时无需 API 密钥：Agent 可以提供链接，让你体验几次免费访客预览（只需在浏览器中快速确认一次，无需账号），或登录。下载需要 Starter、Pro、Agency 套餐或按量付费额度，你可以在同一对话中购买。

工具

工具	用途
wpconvert_convert_folder	将文件夹打包（排除 node_modules、构建输出和机密文件）并启动转换。返回 jobId。
wpconvert_check_status	轮询任务状态。持久化的值遵循 OpenAPI ConversionStatus 枚举（queued、各个流水线阶段、done、failed）。工具层的 processing 分类表示仍在进行中，并非持久化的 API 值。
wpconvert_download_result	将已完成的转换下载到磁盘。
wpconvert_create_preview	获取 WordPress Playground URL，在浏览器中实时查看主题。链接约十分钟后过期，且较为敏感——请在浏览器中打开。
wpconvert_explain_failure	返回失败任务的失败原因。
wpconvert_quota	显示配额、功能和 recommended_next。转换前请先调用。访客会话中会显示剩余的免费预览次数。
wpconvert_connect	启动浏览器链接流程：kind: "guest"（免费预览，无需账号）或 kind: "login"（登录；在本地保存新的 API 密钥）。返回一个供你打开的链接和代码——Agent 不会打开它。
wpconvert_connect_status	检查你是否已完成链接流程（等待约 20 秒），以及 WPConvert 当前的连接状态。
wpconvert_plans	列出所有套餐选项、包含内容和今日价格：Starter（一个主题）、Pro、Agency（月付/年付）以及按量付费额度包。传入 jobId 可查看解锁该转换的选项。
wpconvert_checkout	为你选择的选项生成 Stripe 结账链接。需要登录账号。由你打开链接并付款；Agent 不会代你付款。

配置（Claude Code）

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

--scope user 会使该服务在每个项目中均可用。使用 claude mcp list（wpconvert … ✔ Connected）或在会话中使用 /mcp 确认。然后让 Agent 转换文件夹；它会提供访客链接或登录链接。

若要改用现有 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 共享。工具结果绝不会包含密钥、访客令牌或链接的设备代码。

典型 Agent 工作流

配额优先（推荐）：

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——通常每隔约 15s 轮询一次）
4. 当 recommended_next.tool 为 wpconvert_download_result 时 → 下载主题 .zip
5. 仅预览或下载锁定时 → 调用 wpconvert_create_preview 获取 WordPress Playground URL（不提供 ZIP）

如果转换受阻（can_start: false），wpconvert_convert_folder 会在压缩或提交之前返回结构化拒绝信息。调用 wpconvert_quota 查看 recommended_action。

尚无密钥（访客）：

1. wpconvert_convert_folder → recommended_next: wpconvert_connect { "kind": "guest" }
2. wpconvert_connect { "kind": "guest" } → Agent 会显示链接和代码；打开链接并确认你是真人
3. wpconvert_connect_status → 状态为 connected，并显示剩余的免费预览次数
4. wpconvert_convert_folder、wpconvert_check_status，然后调用 wpconvert_create_preview，在 WordPress Playground 中查看效果（访客上传的压缩文件最大为 50MB；不会自动重试，因为每次上传都会使用一次预览）

购买（下载主题或购买套餐）：

1. wpconvert_plans { "jobId": "..." } → 显示所有选项和价格；Agent 会询问你要选哪一个
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	配额	对于没有 capabilities.conversion 的旧版后端，值为 false
recommended_next	所有工具	{ tool, reason, retry_after_seconds? } — 接下来应调用哪个 MCP 工具
next_action	转换成功	字符串（保持不变）——为 Agent 提供的操作指导
idempotency_key	转换	预检拒绝时不包含此字段（不会生成密钥）

状态 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，而不是重试下载。

依赖版本固定

此软件包将 [email protected] 固定为精确版本，用于共享能力辅助函数（resolveConvertPreflight、quota formatters）。