@dynamic-mockups/mcp 1.0.7 → 1.1.0

package/README.md

@@ -13,15 +13,15 @@ Add the following to your MCP client configuration file:
 
 ```json
 {
-   "mcpServers": {
-      "dynamic-mockups": {
-         "command": "npx",
-         "args": ["-y", "@dynamic-mockups/mcp"],
-         "env": {
-            "DYNAMIC_MOCKUPS_API_KEY": "your_api_key_here"
-         }
+  "mcpServers": {
+    "dynamic-mockups": {
+      "command": "npx",
+      "args": ["-y", "@dynamic-mockups/mcp"],
+      "env": {
+        "DYNAMIC_MOCKUPS_API_KEY": "your_api_key_here"
       }
-   }
+    }
+  }
 }
 ```
 
@@ -37,15 +37,15 @@ If you want to connect via HTTP instead of NPX, use:
 
 ```json
 {
-   "mcpServers": {
-      "dynamic-mockups": {
-         "type": "http",
-         "url": "https://mcp.dynamicmockups.com",
-         "headers": {
-            "x-api-key": "your_api_key_here"
-         }
+  "mcpServers": {
+    "dynamic-mockups": {
+      "type": "http",
+      "url": "https://mcp.dynamicmockups.com",
+      "headers": {
+        "x-api-key": "your_api_key_here"
       }
-   }
+    }
+  }
 }
 ```
 
@@ -70,27 +70,34 @@ If you want to connect via HTTP instead of NPX, use:
 | `create_collection` | Create a new collection |
 | `get_mockups` | Get list of available mockups with optional filters |
 | `get_mockup_by_uuid` | Retrieve a specific mockup by UUID |
+| `search_products` | Search the POD product catalog used to ground MockAnything AI generations |
+| `create_mockanything_mockup` | Create a new MockAnything AI mockup template from a prompt or image URL |
+| `get_mockanything_status` | Poll the status of a MockAnything AI mockup creation task |
 | `create_render` | Create a single mockup render with design assets (1 credit) |
 | `create_batch_render` | Render multiple mockups in one request (1 credit per image) |
 | `export_print_files` | Export high-resolution print files for production |
 | `upload_psd` | Upload a PSD file and optionally create a mockup template |
 | `delete_psd` | Delete a PSD file with optional related mockups deletion |
+| `tool_create_embroidery_effect` | Transform any image into a realistic embroidery/stitched effect |
 
 ## Usage Examples
 
 Ask your AI assistant:
 
-| Use Case | Example Prompt |
-|----------|----------------|
-| Embed editor | "Add the full mockup editor to my web application" |
-| List catalogs | "Get my Dynamic Mockups catalogs" |
-| Browse mockups | "Show me all mockups in my T-shirt collection" |
-| Single render | "Create a mockup render using any T-shirt mockup with my artwork from url: https://example.com/my-design.png" |
-| Batch render | "Render my artwork from url: https://example.com/my-design.png on all mockups in the Winter T-shirt collection" |
-| Create collection | "Create a new collection called Summer 2025 Hoodies" |
-| Upload PSD | "Upload my PSD mockup from url: https://example.com/my-mockup.psd and create a template from it" |
-| API info | "What are the rate limits and supported file formats for Dynamic Mockups?" |
-| Print files | "Export print-ready files at 300 DPI for my poster mockup" |
+| Use Case                       | Example Prompt                                                                                                                              |
+|--------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| Embed editor                   | "Add the full mockup editor to my web application"                                                                                          |
+| List catalogs                  | "Get my Dynamic Mockups catalogs"                                                                                                           |
+| Browse mockups                 | "Show me all mockups in my T-shirt collection"                                                                                              |
+| Single render                  | "Create a mockup render using any T-shirt mockup with my artwork from url: https://example.com/my-design.png"                               |
+| Batch render                   | "Render my artwork from url: https://example.com/my-design.png on all mockups in the Winter T-shirt collection"                             |
+| Create collection              | "Create a new collection called Summer 2025 Hoodies"                                                                                        |
+| Upload PSD                     | "Upload my PSD mockup from url: https://example.com/my-mockup.psd and create a template from it"                                            |
+| API info                       | "What are the rate limits and supported file formats for Dynamic Mockups?"                                                                  |
+| Print files                    | "Export print-ready files at 300 DPI for my poster mockup"                                                                                  |
+| Embroidery effect              | "Transform my logo into an embroidery effect from url: https://example.com/my-logo.png"                                                     |
+| Create a Mockup from Prompt    | "Create a mockup of a guy wearing a Gildan 5000 t-shirt while running, then render my logo from url: https://example.com/my-logo.png on it" |
+| Create a Mockup from Image URL | "Turn this product photo into a mockup: https://example.com/product.jpg, and render my artwork on it"                                       |
 
 ## Error Handling
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamic-mockups/mcp",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Official Dynamic Mockups MCP Server - Generate product mockups with AI assistants",
   "type": "module",
   "main": "src/index.js",
@@ -35,8 +35,8 @@
     "url": "https://github.com/dynamic-mockups/mcp/issues"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "axios": "^1.6.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "axios": "^1.15.2",
     "cors": "^2.8.5",
     "express": "^4.21.0"
   },

package/src/index.js

@@ -540,6 +540,12 @@ function getApiKey(extra) {
 // 2. Use create_render (single) or create_batch_render (multiple) to generate images
 // Note: get_mockups returns all data needed to render - no need to call get_mockup_by_uuid first!
 //
+// WORKFLOW FOR CREATING NEW MOCKUPS WITH AI (MockAnything):
+// 1. (Optional) Call search_products to find a POD product UUID for grounding
+// 2. Call create_mockanything_mockup with prompt or image_url -> returns task_id
+// 3. Poll get_mockanything_status with task_id until state=SUCCESS -> returns mockup payload
+// 4. Use mockup.uuid as mockup_uuid in create_render (works exactly like classic mockups)
+//
 // WHEN TO USE EACH TOOL:
 // - get_api_info: First call when user asks about limits, pricing, or capabilities
 // - embed_mockup_editor: When user wants to embed the mockup editor in their website/app
@@ -547,12 +553,16 @@ function getApiKey(extra) {
 // - get_collections: When user wants to browse mockup groups or find mockups by category
 // - get_mockups: PRIMARY tool - lists templates WITH smart_object UUIDs ready for rendering
 // - get_mockup_by_uuid: Only when user needs ONE specific template (already has UUID)
+// - search_products: Find a POD product UUID to ground MockAnything AI generations
+// - create_mockanything_mockup: Create a brand-new mockup on the fly via AI prompt or image URL
+// - get_mockanything_status: Poll a MockAnything task until the mockup is ready for rendering
 // - create_render: For generating 1 mockup image
 // - create_batch_render: For generating 2+ mockup images (more efficient)
 // - export_print_files: When user needs production-ready files with specific DPI
 // - upload_psd: When user wants to add their own PSD mockup template
 // - delete_psd: When user wants to remove an uploaded PSD
 // - create_collection: When user wants to organize mockups into groups
+// - tool_create_embroidery_effect: When user wants to transform an image into embroidery/stitched effect
 //
 // =============================================================================
 
@@ -789,6 +799,167 @@ RETURNS: Single mockup with:
     },
   },
 
+  // ─────────────────────────────────────────────────────────────────────────────
+  // MOCKANYTHING AI TOOLS
+  // ─────────────────────────────────────────────────────────────────────────────
+  {
+    name: "search_products",
+    description: `Search the Print-on-Demand (POD) product catalog used to ground MockAnything AI generations.
+
+API: GET /mock-anything/products
+
+WHEN TO USE: When user wants to anchor an AI-generated mockup around a specific product (e.g., "Gildan 5000 t-shirt", "ceramic mug") instead of letting the model pick a generic one.
+
+WORKFLOW:
+1. Call this tool with a search term (matched against POD product names)
+2. Pick the desired product from the response
+3. Pass its uuid as product.uuid when calling create_mockanything_mockup
+
+NOTE: Grounding is OPTIONAL. Skip this tool if you want the AI to compose freely from the prompt alone.
+
+RETURNS: Array of {name, uuid} POD product entries matching the query.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description: "REQUIRED. Search term matched against POD product names (e.g., 'gildan', 'mug', 'hoodie'). Must be non-empty.",
+        },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "create_mockanything_mockup",
+    description: `Create a new MockAnything AI mockup template on the fly. The resulting mockup behaves exactly like one returned by get_mockups - pass its uuid to create_render to print artwork on it.
+
+API: POST /mock-anything/create
+COST:
+- prompt flow: 5 credits (seedream_4_0, default), 6 credits (seedream_4_5), 14 credits (nano_banana_2). Charged on SUCCESS, free on FAILURE.
+- image_url flow: 4 credits per generation.
+
+WHEN TO USE: When user wants to:
+- Generate a brand-new mockup from a text prompt (e.g., "a person wearing a t-shirt in Tokyo")
+- Convert an existing public image URL into a usable mockup template
+- Create custom mockups not available in their existing template catalog
+
+EXACTLY ONE of these must be provided:
+- prompt: text used to AI-generate the mockup image. Asynchronous - returns task_id to poll.
+- image_url: public URL to an existing image. The task usually completes on the first status poll.
+
+WORKFLOW:
+1. (Optional) Call search_products to find a product UUID for grounding the AI
+2. Call this tool with prompt OR image_url
+3. Use the returned task_id with get_mockanything_status, polling every ~2 seconds until state=SUCCESS
+4. Use the returned mockup.uuid as mockup_uuid in create_render
+
+MODELS (only apply to the prompt flow):
+- seedream_4_0 (default, 5 credits, ~20s, medium quality) - quick iterations
+- seedream_4_5 (6 credits, ~40s, good quality) - higher fidelity without the pro price
+- nano_banana_2 (14 credits, ~30s, high quality) - production-ready final mockups
+
+NOTES:
+- product.uuid, model, and enhance_prompt only apply to the prompt flow (ignored otherwise).
+- collections accepts existing collections (by uuid) or new ones (by name, find-or-create).
+- Rate limit: 50 requests/minute on this endpoint.
+- File uploads (multipart image_file) are not supported via MCP - host the image and pass image_url.
+
+RETURNS: {task_id, status} - the task_id will also be the mockup.uuid once the task succeeds.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: {
+          type: "string",
+          description: "Text prompt used to AI-generate the mockup image. Required unless image_url is provided. Triggers asynchronous generation - poll status with the returned task_id.",
+        },
+        image_url: {
+          type: "string",
+          description: "Public URL of an existing image to use as the mockup. Required unless prompt is provided. Completes on the first status poll.",
+        },
+        enhance_prompt: {
+          type: "boolean",
+          description: "Optional. Run prompt enhancement before generation. Only applies to the prompt flow.",
+        },
+        product: {
+          type: "object",
+          description: "Optional. Product context used to ground the AI generation around a specific POD product type. Only applies to the prompt flow.",
+          properties: {
+            uuid: {
+              type: "string",
+              description: "POD product UUID. Get from search_products.",
+            },
+          },
+        },
+        model: {
+          type: "string",
+          enum: ["seedream_4_0", "seedream_4_5", "nano_banana_2"],
+          description: "Optional. AI model used for generation. Default: seedream_4_0. Only applies to the prompt flow.",
+        },
+        name: {
+          type: "string",
+          description: "Optional. Mockup name shown in the dashboard (max 255 chars). Defaults to the prompt or a generic fallback.",
+        },
+        collections: {
+          type: "array",
+          description: "Optional. Collections to attach the mockup to. Each item must have either uuid (existing collection) or name (new collection - find-or-create).",
+          items: {
+            type: "object",
+            properties: {
+              uuid: {
+                type: "string",
+                description: "UUID of an existing collection.",
+              },
+              name: {
+                type: "string",
+                description: "Name of a new collection to create and attach (max 255 chars).",
+              },
+            },
+          },
+        },
+        catalog_uuid: {
+          type: "string",
+          description: "Optional. UUID of the catalog to place the mockup in. Defaults to the workspace's default catalog.",
+        },
+      },
+    },
+  },
+  {
+    name: "get_mockanything_status",
+    description: `Poll the status of a MockAnything AI mockup creation task.
+
+API: GET /mock-anything/status/{taskId}
+
+WHEN TO USE: After calling create_mockanything_mockup, use this to track progress until the mockup is ready for rendering.
+
+POLLING STRATEGY:
+- Poll every ~2 seconds (recommended)
+- prompt flow: AI generations typically finish in 10-30 seconds
+- image_url flow: usually ready on the very first status call
+
+STATES:
+- PROGRESS / PENDING: Task is still running. image_url and mockup are null. Poll again shortly.
+- SUCCESS: Task complete. image_url is populated and mockup contains everything needed for create_render.
+- FAILURE: Task terminated without producing a mockup. No credits are charged.
+
+ON SUCCESS - the mockup field has the same shape as a get_mockups entry (with type "mockanything"):
+- mockup.uuid: pass as mockup_uuid in create_render
+- mockup.smart_objects[].uuid: pass as smart_objects[].uuid in create_render to place artwork on each detected print area
+
+From here, render the mockup exactly like a classic one - the Render API handles both types through the same endpoint.
+
+RETURNS: {task_id, state, image_url, status, mockup}.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        task_id: {
+          type: "string",
+          description: "REQUIRED. The task_id returned from create_mockanything_mockup.",
+        },
+      },
+      required: ["task_id"],
+    },
+  },
+
   // ─────────────────────────────────────────────────────────────────────────────
   // RENDER TOOLS
   // ─────────────────────────────────────────────────────────────────────────────
@@ -1257,6 +1428,48 @@ RETURNS: Success confirmation message.`,
       required: ["psd_uuid"],
     },
   },
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // EFFECT TOOLS
+  // ─────────────────────────────────────────────────────────────────────────────
+  {
+    name: "tool_create_embroidery_effect",
+    description: `Transform any image into a realistic embroidery/stitched effect.
+
+API: POST /tools/embroidery
+COST: 6 credits per request
+
+WHEN TO USE: When user wants to:
+- Convert artwork/designs into embroidery style
+- Create stitched/embroidered versions of logos or images
+- Prepare designs for print-on-demand embroidery products
+- Transform existing artwork to look like embroidery before rendering on mockups
+
+INPUT: Provide image via EITHER:
+- image_url: Public URL to the image (PNG, JPG, WEBP supported)
+- image_data_b64: Base64-encoded image data
+Only ONE input method is required per request.
+
+TIPS FOR BEST RESULTS:
+- Use high-contrast images with clean edges
+- Simpler designs with fewer colors produce more realistic embroidery effects
+- The output can be used directly in mockup renders or saved to asset library
+
+RETURNS: {export_path} - URL to the generated embroidery image (temporary, should be downloaded or saved to permanent storage).`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        image_url: {
+          type: "string",
+          description: "Public URL to the image to transform. Supported formats: PNG, JPG, WEBP. Either image_url OR image_data_b64 must be provided.",
+        },
+        image_data_b64: {
+          type: "string",
+          description: "Base64-encoded image data. Either image_url OR image_data_b64 must be provided.",
+        },
+      },
+    },
+  },
 ];
 
 // =============================================================================
@@ -1511,6 +1724,118 @@ async function handleDeletePsd(args, extra) {
   }
 }
 
+async function handleCreateEmbroideryEffect(args, extra) {
+  const apiKey = getApiKey(extra);
+  const error = validateApiKey(apiKey);
+  if (error) return error;
+
+  // Validate that at least one input method is provided
+  if (!args.image_url && !args.image_data_b64) {
+    return ResponseFormatter.error(
+        "Missing required input",
+        { solution: "Provide either image_url (public URL) or image_data_b64 (base64-encoded image data)." }
+    );
+  }
+
+  try {
+    const payload = {};
+    if (args.image_url) payload.image_url = args.image_url;
+    if (args.image_data_b64) payload.image_data_b64 = args.image_data_b64;
+
+    const response = await createApiClient(apiKey, "tool_create_embroidery_effect").post("/tools/embroidery", payload);
+    return ResponseFormatter.fromApiResponse(response, "Embroidery effect created (6 credits used)");
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to create embroidery effect");
+  }
+}
+
+async function handleSearchMockanythingProducts(args, extra) {
+  const apiKey = getApiKey(extra);
+  const error = validateApiKey(apiKey);
+  if (error) return error;
+
+  if (!args.query || !String(args.query).trim()) {
+    return ResponseFormatter.error(
+        "Missing required parameter",
+        { solution: "Provide a non-empty query string to search POD product names." }
+    );
+  }
+
+  try {
+    const params = new URLSearchParams();
+    params.append("query", args.query);
+
+    const response = await createApiClient(apiKey, "search_products").get(`/mock-anything/products?${params}`);
+    return ResponseFormatter.fromApiResponse(response);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to search MockAnything products");
+  }
+}
+
+async function handleCreateMockanythingMockup(args, extra) {
+  const apiKey = getApiKey(extra);
+  const error = validateApiKey(apiKey);
+  if (error) return error;
+
+  const hasPrompt = !!args.prompt;
+  const hasImageUrl = !!args.image_url;
+
+  if (!hasPrompt && !hasImageUrl) {
+    return ResponseFormatter.error(
+        "Missing required input",
+        { solution: "Provide exactly one of prompt (for AI generation) or image_url (for an existing image)." }
+    );
+  }
+  if (hasPrompt && hasImageUrl) {
+    return ResponseFormatter.error(
+        "Conflicting inputs",
+        { solution: "Provide exactly one of prompt or image_url, not both." }
+    );
+  }
+
+  try {
+    const payload = {};
+    if (hasPrompt) payload.prompt = args.prompt;
+    if (hasImageUrl) payload.image_url = args.image_url;
+    if (args.enhance_prompt !== undefined) payload.enhance_prompt = args.enhance_prompt;
+    if (args.product) payload.product = args.product;
+    if (args.model) payload.model = args.model;
+    if (args.name) payload.name = args.name;
+    if (args.collections) payload.collections = args.collections;
+    if (args.catalog_uuid) payload.catalog_uuid = args.catalog_uuid;
+
+    const response = await createApiClient(apiKey, "create_mockanything_mockup").post("/mock-anything/create", payload);
+
+    const successMessage = hasPrompt
+        ? "MockAnything AI generation started. Poll get_mockanything_status with the returned task_id (every ~2s) until state=SUCCESS, then use mockup.uuid in create_render."
+        : "MockAnything mockup creation started from image_url. Poll get_mockanything_status with the returned task_id - it usually completes on the first call.";
+
+    return ResponseFormatter.fromApiResponse(response, successMessage);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to create MockAnything mockup");
+  }
+}
+
+async function handleGetMockanythingStatus(args, extra) {
+  const apiKey = getApiKey(extra);
+  const error = validateApiKey(apiKey);
+  if (error) return error;
+
+  if (!args.task_id) {
+    return ResponseFormatter.error(
+        "Missing required parameter",
+        { solution: "Provide the task_id returned from create_mockanything_mockup." }
+    );
+  }
+
+  try {
+    const response = await createApiClient(apiKey, "get_mockanything_status").get(`/mock-anything/status/${args.task_id}`);
+    return ResponseFormatter.fromApiResponse(response);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to get MockAnything mockup status");
+  }
+}
+
 // =============================================================================
 // Tool Router
 // =============================================================================
@@ -1523,11 +1848,15 @@ const toolHandlers = {
   create_collection: handleCreateCollection,
   get_mockups: handleGetMockups,
   get_mockup_by_uuid: handleGetMockupByUuid,
+  search_products: handleSearchMockanythingProducts,
+  create_mockanything_mockup: handleCreateMockanythingMockup,
+  get_mockanything_status: handleGetMockanythingStatus,
   create_render: handleCreateRender,
   create_batch_render: handleCreateBatchRender,
   export_print_files: handleExportPrintFiles,
   upload_psd: handleUploadPsd,
   delete_psd: handleDeletePsd,
+  tool_create_embroidery_effect: handleCreateEmbroideryEffect,
 };
 
 // =============================================================================