SudoMock

SudoMock MCP 服务

在 Claude、Cursor、Windsurf 和 VS Code 中生成逼真的产品样机。

SudoMock 样机生成 API 的 Model Context Protocol 服务。上传 PSD 模板，将 artwork 放置到智能对象上，编辑支持的文本图层，并获取渲染后的图片 URL —— 全部通过自然语言完成。

快速开始

这是一个本地 stdio 服务：你的 MCP 客户端通过 npx 将其作为子进程启动， 并使用 SUDOMOCK_API_KEY 进行身份验证。

claude mcp add sudomock \
  -e SUDOMOCK_API_KEY=sm_your_key_here \
  -- npx -y @sudomock/mcp

在 sudomock.com/dashboard/api-keys 获取 API 密钥。

{
  "mcpServers": {
    "sudomock": {
      "command": "npx",
      "args": ["-y", "@sudomock/mcp"],
      "env": {
        "SUDOMOCK_API_KEY": "sm_your_key_here"
      }
    }
  }
}

注意： 目前尚未提供托管的远程（HTTP/OAuth）传输方式。此 软件包仅提供上文所示的本地 stdio 服务。

工具

两种拼写都可用

该产品将两类模板称为 PSD mockup 和 photo mockup，工具也支持这两种名称。上文没有任何名称被重命名：表格中的每个名称都和以前一样可用，旁边列出的拼写则是具有相同参数的同一个工具。任选其一即可。

render_photo_mockup 是唯一一个并非只是某个工具的第二个名称的工具。它可以用一个工具渲染任意一种目标：将 mockup 作为 mockup_id 传入，并且准确指定 surface_uuid（通过 coverage 或显式的 width + height 设置大小）或 print_area_uuid（通过 fit 或显式的 width + height 设置大小）中的一个。render_2d_surface 和 render_2d_print_area 仍然通过选择工具来选择目标，并使用 mockup_uuid。render_2d_mockup 是 render_photo_mockup 的另一个名称，mockup 通过 mockup_uuid 传入。

异步任务

render_mockup、upload_psd、create_2d_mockup 和两个 photo mockup 渲染工具都接受 is_async: true，而 render_video 始终为异步。这些工具会立即返回 job_id（HTTP 202），而不是最终结果。（create_2d_mockup 和 photo mockup 渲染工具默认同步运行，并直接返回 mockup / 渲染结果。）使用 get_job 轮询，或者让 wait_for_job 阻塞，直到任务达到终止状态并返回 result_url、mockup_uuid、credits_charged 和 payg（按量付费任务会返回 {credits, unit_price, cost}，否则为 null）。

渲染 photo mockup 时，请选择与从 get_2d_mockup 读取的目标相匹配的工具。照片中的每个可打印产品，以及房间照片中的主墙面，都是具有独立 surface_uuid 的表面：render_2d_surface 会在整个表面上打印，并接受 coverage 百分比或显式的 width + height。打印区域是某人在产品上绘制的有界区域，例如胸前的徽标：render_2d_print_area 接受其 print_area_uuid，以及 fit 或显式的 width + height。一个产品可以同时拥有这两种目标，它们彼此独立——已保存的打印区域不会限制其所在的表面。

每次渲染的尺寸设置只能有一种：发送相对选项或精确尺寸框，不能同时发送，并且 width 和 height 必须一起发送。position、offset_x、offset_y 和 rotation 可用于在任意一种目标上放置图稿。省略的参数不会包含在请求中，因此渲染器会采用自身的默认值，而不是使用此处保存的默认值副本。

photo mockup 的 surfaces 中每个条目都包含一个 label，用于描述检测到的表面，例如 pillow 或 wall，以便你在选择表面之前区分它们。update_2d_print_areas 接受每个区域上可选的 print_area_id：如果区域传入 mockup 的某个 ID，就会保留该 ID；未传入 ID 的区域则会获得一个新 ID。

图案平铺

tile 会将图稿重复平铺为覆盖整个目标的图案；tile_spacing 则会在平铺块之间留出间距：以平铺块尺寸的百分比表示，范围为 0 到 100。因此，水平间距是平铺块宽度的该百分比，垂直间距是平铺块高度的该百分比。只有当 tile 为 true 时才会使用它。

• 对于 PSD 模板，两者都放在 render_mockup 中 smart_objects 条目的 asset 里。size 表示一个平铺块的尺寸，fit 用于将图稿放入每个平铺块，position 用于设置网格的起始位置。
• render_video 将它们作为要填充的智能对象的参数，并使用 asset_width 和 asset_height 表示一个平铺块的尺寸。
• 照片样机渲染工具将它们作为参数。尺寸设置（coverage、fit，或 width 和 height）表示一个平铺块的尺寸，position 与 offset_x、offset_y 一起用于设置网格的起始位置。

平铺块需要指定尺寸；未指定时，API 会返回 422。

移除背景

remove_background 会返回一个有效期为 7 天的透明 PNG URL。在此有效期内，你可以直接将该 URL 作为 artwork_url 传回。若要在单次渲染中直接清理图稿，请将 remove_background: true 传给 render_mockup 或任一照片样机渲染工具。无论哪种方式，每张图稿都会收取 25 个点数；如果处理失败，点数会自动退还。

Webhook

使用 create_webhook_endpoint 注册端点，以便在异步任务完成时收到通知。投递内容使用两个标头签名：X-SudoMock-Signature（使用创建或轮换时返回的密钥，对 ${timestamp}.${rawBody} 计算的十六进制 HMAC-SHA256）和 X-SudoMock-Timestamp（Unix 秒）。请采用恒定时间进行验证，并在 |now - timestamp| > 300s 时拒绝请求。

渲染、上传和视频任务的投递内容使用 {event, job_id, kind, status, result_url, error, created_at}。带类型的照片样机创建事件会额外包含 version、mockup_id、name，以及 print_areas（ready 时）或 reason（rejected 时）。带类型的照片样机渲染事件包含 mockup_id、result_url、适用时的公开 {error_code, message} 错误，以及可选的 export_format / duration_ms。事件类型：render.succeeded、render.failed、upload.succeeded、video.succeeded、video.failed、photo_mockup.ready、photo_mockup.rejected、photo_mockup.failed、photo_mockup_render.succeeded、photo_mockup_render.failed、webhook.test。

这五种照片样机事件也有旧版名称：2d_mockup.ready、2d_mockup.rejected、2d_mockup.failed、2d_render.succeeded、2d_render.failed（载荷中的 kind 为 2d_create / 2d_render）。端点收到哪种名称，由其 event_naming 固定设置决定；该设置在 create_webhook_endpoint 时设定，并在每个端点上返回：current（上述名称）或 legacy。未固定名称的创建请求，只有在 event_types 仅使用照片样机事件的系列名称时才会采用 current；其他情况（包括空列表）均采用 legacy。在该设置推出前注册的端点会继续使用 legacy，因此，按照旧名称编写的接收端无需任何改动即可继续工作。接收端支持新名称后，可使用 update_webhook_endpoint 和 event_naming: "current" 更新设置；单独发送此更新请求时，也会重新写入端点已存储的订阅列表，使其名称与设置一致。

日志

每次工具调用都会向 stderr 写入一行 JSON；MCP 主机会将其保存在日志文件中。内容包括工具名称、调用耗时以及是否成功，例如 {"event":"mcp_tool_call","tool":"list_mockups","duration_ms":312,"ok":true}。参数、API 密钥、文件内容和 API 响应绝不会记录。每个 API 请求都会在 User-Agent 和 X-SudoMock-Client 标头中使用 mcp-stdio/<version> 标识此软件包。

定价和账户限制

订阅后，每次渲染低至 $0.002。不订阅时，每次渲染收费 $0.05，与独立样机 API 在付费方案中的费率相同。为余额充值，首次至少需要支付 $5。照片样机和视频按制作成本定价，而非采用统一的渲染费率，因此上方的 Credits 列并不统一。

新账户会一次性获赠 500 个积分，使用这些积分无需绑定银行卡。在验证银行卡并充值至少 $5 之前，该账户处于试用状态，所有渲染结果都会带水印，宽度上限为 1,024 px。账户最多可保留 5 个 PSD 模板，每次只能运行 一个 渲染任务；超过 13 天未用于渲染的模板会被删除。

充值后，所有限制会一次性解除。水印和宽度上限会取消，存储模板上限提高到 150，最多可同时运行 25 个渲染任务和 10 个上传任务，模板也不会再因闲置而被删除。

试用并非单独的方案，而是按量付费层级的未充值状态，因此充值前后，get_account 报告的层级相同；变化的是余额。

因此，按量付费的账户没有月度额度，而且即使账户完全可以付费，get_account 报告的 credits_limit 和 credits_remaining 仍为 0。请同时查看 prepaid_balance，或查看 funding_summary；它会在一行中显示这两项信息，并且绝不会将已充值的账户报告为 0 / 0。

请求示例

• “列出我的样机模板”
• “用这个设计渲染 T 恤样机：https://example.com/logo.png”
• “替换可编辑的标题文本，然后渲染样机”
• “抠掉这张产品照片的背景，然后将其渲染到托特包上”
• “列出我的照片样机，然后用这张图片渲染第一个样机：https://example.com/logo.png”
• “异步渲染这个设计，并等待完成”
• “将该照片样机渲染任务加入异步队列，并提供用于跟踪的任务 ID”
• “将连帽衫样机制作成一段 5 秒的视频片段”
• “将此 PSD 上传为新模板：https://example.com/mockup.psd”
• “在 https://example.com/hooks 设置 webhook，以便在渲染完成时通知我”
• “我还剩多少积分？”

链接

• 控制面板 -- 管理样机和 API 密钥
• API 文档 -- 完整的 REST API 参考
• 定价
• 状态 -- 服务运行时间

许可证

MIT