SudoMock

SudoMock MCP サーバー

Claude、Cursor、Windsurf、VS Code からフォトリアルな商品モックアップを生成します。

SudoMock のモックアップ生成 API 用の Model Context Protocol サーバーです。PSD テンプレートをアップロードし、スマートオブジェクトにアートワークを配置し、対応するテキストレイヤーを編集して、レンダリング済み画像の URL を取得できます。すべて自然言語で操作できます。

クイックスタート

これはローカルの stdio サーバーです。MCP クライアントが npx 経由で子プロセスとして起動し、 SUDOMOCK_API_KEY で認証します。

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

API キーは sudomock.com/dashboard/api-keys で取得できます。

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

注： ホスト型のリモート（HTTP/OAuth）トランスポートは、まだ利用できません。この パッケージで提供しているのは、上記のローカル stdio サーバーのみです。

ツール

どちらの表記でも使えます

製品では2種類のテンプレートを PSD モックアップとフォトモックアップと呼んでおり、ツールも同じ名前で呼び出せます。上記の名前は変更されていません。表の名前はすべてこれまでどおり使え、併記されている表記も、引数を含めて同じツールです。どちらでもお使いください。

render_photo_mockup は、単一のツールの別名というだけではありません。このツールから、どちらの種類のターゲットもレンダリングできます。モックアップを mockup_id として渡し、surface_uuid（coverage または明示的な width + height でサイズを指定）か、print_area_uuid（fit または明示的な width + height でサイズを指定）のどちらか一方を正確に指定してください。mockup_uuid を使い、ツールを選んでターゲットを指定する従来の方法は、引き続き render_2d_surface と render_2d_print_area で利用できます。render_2d_mockup は render_photo_mockup の別名で、モックアップは mockup_uuid として渡します。

非同期ジョブ

render_mockup、upload_psd、create_2d_mockup、両方のフォトモックアップレンダリングツールは is_async: true を受け付け、render_video は常に非同期です。これらは最終結果の代わりに、すぐに job_id（HTTP 202）を返します。（create_2d_mockup とフォトモックアップレンダリングツールは、デフォルトでは同期処理され、モックアップ／レンダリング結果を直接返します。）get_job でポーリングするか、wait_for_job でジョブが終端ステータスに達するまで待機してください。完了すると、result_url、mockup_uuid、credits_charged、および payg（従量課金ジョブの場合は {credits, unit_price, cost}、それ以外は null）が返されます。

フォトモックアップをレンダリングする場合は、get_2d_mockup で確認したターゲットに合うツールを選んでください。写真内の印刷可能な製品と、部屋の写真の主壁面はそれぞれサーフェスで、個別の surface_uuid を持ちます。render_2d_surface はそのサーフェス全体に印刷し、coverage の割合または明示的な width + height を指定します。プリントエリアは、胸元のロゴのように、製品上に描画された範囲の限られた領域です。render_2d_print_area では print_area_uuid と、fit または明示的な width + height を指定します。製品は両方を持つことができ、それぞれ別のターゲットです。保存済みのプリントエリアがあっても、その上にあるサーフェスは引き続き利用できます。

サイズ指定は、1回のレンダリングにつき1つの方法を選びます。相対指定か正確なサイズの枠のどちらか一方だけを送信し、width と height は必ずセットで指定してください。position、offset_x、offset_y、rotation を使って、どちらの種類のターゲットにもアートワークを配置できます。指定しない項目はリクエストにも含まれないため、ここに記載された値が引き継がれるのではなく、レンダラー独自のデフォルトが適用されます。

フォトモックアップの surfaces 内の各エントリーには label があり、pillow や wall のように、そこで検出された対象を示します。これにより、選択する前にサーフェスを区別できます。update_2d_print_areas では、各エリアに任意で print_area_id を指定できます。モックアップ内の ID を指定したエリアはその ID を維持し、指定しないエリアには新しい ID が割り当てられます。

パターン

tile はアートワークをターゲット全体にパターンとして繰り返し、tile_spacing はタイル間に隙間を空けます。これはタイルサイズに対する割合で、0〜100 の範囲です。そのため、横方向の隙間はタイル幅に対するその割合、縦方向の隙間はタイル高さに対するその割合になります。tile が true の場合にのみ使用されます。

• PSD テンプレートでは、どちらも render_mockup の smart_objects エントリ内にある asset に指定します。size は 1 つのタイルのサイズ、fit は各タイル内にアートワークを配置する方法、position はグリッドの開始位置を設定します。
• render_video では、対象のスマートオブジェクトを埋めるためのパラメーターとして指定します。asset_width と asset_height は 1 つのタイルのサイズです。
• 写真モックアップのレンダリングツールでは、パラメーターとして指定します。サイズ設定（coverage、fit、または width と height）は 1 つのタイルのサイズです。offset_x と offset_y を指定した position でグリッドの開始位置を設定します。

タイルにはサイズが必要です。サイズを指定しない場合、API は 422 を返します。

背景の削除

remove_background は、7 日間有効な透過 PNG の URL を返します。有効期間中は、その URL をそのまま artwork_url として渡せます。1 回のレンダリング中にインラインでアートワークの背景を削除するには、代わりに render_mockup またはいずれかの写真モックアップレンダリングツールに remove_background: true を渡します。どちらの場合も、アートワーク 1 点につき 25 クレジットがかかります。処理に失敗した場合、クレジットは自動的に返金されます。

Webhook

非同期ジョブの完了通知を受け取るには、create_webhook_endpoint でエンドポイントを登録します。配信には 2 つのヘッダーで署名します。X-SudoMock-Signature（作成時またはローテーション時に返されるシークレットを使い、${timestamp}.${rawBody} に対して計算した 16 進数の 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。

5 つの写真モックアップイベントには、旧形式の名前もあります。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 を 1 行書き込みます。MCP ホストはこれをログファイルに保存します。記録されるのは、ツール名、呼び出しにかかった時間、成功したかどうかです。例：{"event":"mcp_tool_call","tool":"list_mockups","duration_ms":312,"ok":true}。引数、API キー、ファイルの内容、API の応答がログに記録されることはありません。各 API リクエストでは、User-Agent ヘッダーと X-SudoMock-Client ヘッダーで、このパッケージを mcp-stdio/<version> として識別します。

料金とアカウントの上限

レンダリング1回あたり $0.002 から利用できるサブスクリプションがあります。サブスクリプションがない場合は、レンダリング1回あたり $0.05 です。これは、有料プランのスタンドアロン型モックアップ API が請求する料金と同じです。残高への入金には、初回の最低入金額 $5 が必要です。フォトモックアップと動画は、一律のレンダリング料金ではなく制作コストに応じて価格が設定されているため、上記のクレジット欄は一律ではありません。

新しいアカウントには 500 クレジットが1回限りで付与 され、利用にカードは必要ありません。カードの確認が完了し、最低入金額の $5 が入金されるまでは、そのアカウントはトライアル状態となり、行うレンダリングにはすべてウォーターマークが付き、最大 1,024 px に制限されます。PSD テンプレートは 5 個まで保持でき、レンダリングは同時に 1 件まで実行できます。また、13日間レンダリングに使われていないテンプレートは削除されます。

残高に入金すると、これらの制限が一度に解除されます。ウォーターマークと幅の上限がなくなり、保存できるテンプレート数は 150 個、レンダリングは同時に 25 件、アップロードは同時に 10 件になります。また、アイドル状態のテンプレートが削除されなくなります。

トライアルは独立したプランではありません。従量課金制プランの未入金状態であるため、入金前後で get_account が報告するプランは同じです。変わるのは残高です。

そのため、従量課金のアカウントには月間利用枠がなく、支払いが可能な状態でも、get_account は credits_limit と credits_remaining を 0 として報告します。これらとあわせて prepaid_balance を確認するか、両方の情報を1行で示し、入金済みのアカウントを 0 / 0 と報告しない funding_summary を確認してください。

リクエスト例

• 「自分のモックアップテンプレートを一覧表示して」
• 「このデザインを使って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