@dynamic-mockups/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dynamic Mockups
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# Dynamic Mockups MCP Server
+
+Official MCP (Model Context Protocol) server for the [Dynamic Mockups API](https://dynamicmockups.com). Generate product mockups directly from AI assistants like Claude, Cursor, Windsurf, and more.
+
+## Installation
+
+### Quick Start with npx
+
+No installation required - just configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "dynamic-mockups": {
+      "command": "npx",
+      "args": ["-y", "@dynamic-mockups/mcp"],
+      "env": {
+        "DYNAMIC_MOCKUPS_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Get Your API Key
+
+1. Go to [Dynamic Mockups Dashboard](https://app.dynamicmockups.com/account/api-keys)
+2. Create a new API key
+3. Add it to your MCP client configuration
+
+## Configuration by Client
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "dynamic-mockups": {
+      "command": "npx",
+      "args": ["-y", "@dynamic-mockups/mcp"],
+      "env": {
+        "DYNAMIC_MOCKUPS_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Code (CLI)
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "dynamic-mockups": {
+      "command": "npx",
+      "args": ["-y", "@dynamic-mockups/mcp"],
+      "env": {
+        "DYNAMIC_MOCKUPS_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "dynamic-mockups": {
+      "command": "npx",
+      "args": ["-y", "@dynamic-mockups/mcp"],
+      "env": {
+        "DYNAMIC_MOCKUPS_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dynamic-mockups": {
+      "command": "npx",
+      "args": ["-y", "@dynamic-mockups/mcp"],
+      "env": {
+        "DYNAMIC_MOCKUPS_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### API Information
+- **`get_api_info`** - Get API knowledge base (billing, rate limits, formats, best practices, support)
+
+### Catalogs
+- **`get_catalogs`** - Retrieve all available catalogs
+
+### Collections
+- **`get_collections`** - Retrieve collections (optionally filter by catalog)
+- **`create_collection`** - Create a new collection
+
+### Mockups
+- **`get_mockups`** - Get list of available mockups with optional filters
+- **`get_mockup_by_uuid`** - Retrieve a specific mockup by UUID
+
+### Rendering
+- **`create_render`** - Create a single mockup render with design assets
+- **`create_batch_render`** - Render multiple mockups in one request
+- **`export_print_files`** - Export print files for smart objects
+
+### PSD Files
+- **`upload_psd`** - Upload a PSD file with optional mockup template creation
+- **`delete_psd`** - Delete a PSD file with optional related mockups deletion
+
+## Usage Examples
+
+### Get Your Catalogs
+
+Ask your AI assistant:
+> "Get my Dynamic Mockups catalogs"
+
+### Get Mockups from a Collection
+
+> "Show me all mockups in my T-shirt collection"
+
+### Create a Render
+
+> "Create a mockup render using mockup UUID abc123 with my logo from https://example.com/logo.png"
+
+### Batch Render
+
+> "Render my design on all mockups in the Summer collection"
+
+## Development
+
+### Local Installation
+
+```bash
+git clone https://github.com/dynamicmockups/mcp-server.git
+cd mcp-server
+npm install
+```
+
+### Run Locally
+
+```bash
+DYNAMIC_MOCKUPS_API_KEY=your_key npm start
+```
+
+### Development Mode (with auto-reload)
+
+```bash
+DYNAMIC_MOCKUPS_API_KEY=your_key npm run dev
+```
+
+### Use Local Version in MCP Client
+
+```json
+{
+  "mcpServers": {
+    "dynamic-mockups": {
+      "command": "node",
+      "args": ["/path/to/mcp-server/src/index.js"],
+      "env": {
+        "DYNAMIC_MOCKUPS_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Error Handling
+
+The server returns clear error messages for common issues:
+
+- **API key not configured** - Set `DYNAMIC_MOCKUPS_API_KEY` in your environment
+- **Invalid UUID** - Ensure UUIDs are in correct format
+- **API errors** - Check the returned message for details
+
+## Links
+
+- [Dynamic Mockups Website](https://dynamicmockups.com)
+- [API Documentation](https://docs.dynamicmockups.com)
+- [Get API Key](https://app.dynamicmockups.com/account/api-keys)
+- [GitHub Issues](https://github.com/dynamicmockups/mcp-server/issues)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@dynamic-mockups/mcp",
+  "version": "1.0.0",
+  "description": "Official Dynamic Mockups MCP Server - Generate product mockups with AI assistants",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "dynamic-mockups-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "dynamic-mockups",
+    "mockups",
+    "ai",
+    "claude",
+    "anthropic",
+    "design",
+    "product-mockups"
+  ],
+  "author": "Dynamic Mockups <support@dynamicmockups.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dynamic-mockups/mcp.git"
+  },
+  "homepage": "https://dynamicmockups.com",
+  "bugs": {
+    "url": "https://github.com/dynamic-mockups/mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "src/**/*"
+  ]
+}

package/src/index.js

@@ -0,0 +1,713 @@
+#!/usr/bin/env node
+
+/**
+ * Dynamic Mockups MCP Server
+ * Official MCP server for the Dynamic Mockups API
+ * https://dynamicmockups.com
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import axios from "axios";
+import { ResponseFormatter } from "./response-formatter.js";
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+const API_BASE_URL = "https://app.dynamicmockups.com/api/v1";
+const API_KEY = process.env.DYNAMIC_MOCKUPS_API_KEY;
+const SERVER_NAME = "dynamic-mockups-mcp";
+const SERVER_VERSION = "1.0.0";
+
+// =============================================================================
+// API Knowledge Base
+// =============================================================================
+
+const API_KNOWLEDGE_BASE = {
+  overview: "Dynamic Mockups API allows you to generate product mockups programmatically.",
+
+  billing: {
+    credits_per_image: 1,
+    free_credits: 50,
+    free_tier_watermark: true,
+    pro_subscription_removes_watermark: true,
+  },
+
+  rate_limits: {
+    requests_per_minute: 300,
+  },
+
+  rendered_images: {
+    availability_hours: 24,
+    note: "Rendered image links expire after 24 hours. Contact support to extend.",
+  },
+
+  supported_formats: {
+    input: ["jpg", "jpeg", "png", "webp", "gif"],
+    output: ["jpg", "png", "webp"],
+  },
+
+  asset_upload: {
+    methods: ["URL", "binary file (form-data)"],
+    note: "Binary files must be sent as multipart/form-data in render requests.",
+  },
+
+  best_practices: [
+    "Use create_batch_render for multiple images (more efficient than single renders)",
+    "Always include Accept: application/json header (handled automatically by this MCP)",
+    "Store rendered image URLs promptly as they expire in 24 hours",
+  ],
+
+  support: {
+    email: "support@dynamicmockups.com",
+    tutorials: "https://docs.dynamicmockups.com/knowledge-base/tutorials",
+    api_docs: "https://docs.dynamicmockups.com",
+  },
+};
+
+// =============================================================================
+// Server Initialization
+// =============================================================================
+
+const server = new Server(
+  { name: SERVER_NAME, version: SERVER_VERSION },
+  { capabilities: { tools: {} } }
+);
+
+// =============================================================================
+// HTTP Client
+// =============================================================================
+
+function createApiClient() {
+  return axios.create({
+    baseURL: API_BASE_URL,
+    headers: {
+      "Accept": "application/json",
+      "Content-Type": "application/json",
+      "x-api-key": API_KEY || "",
+    },
+    timeout: 60000, // 60 second timeout for render operations
+    validateStatus: (status) => status < 500, // Only throw on 5xx errors
+  });
+}
+
+function validateApiKey() {
+  if (!API_KEY) {
+    return ResponseFormatter.error(
+      "API key not configured",
+      {
+        solution: "Set the DYNAMIC_MOCKUPS_API_KEY environment variable in your MCP client configuration.",
+        get_key_at: "https://app.dynamicmockups.com/account/api-keys",
+      }
+    );
+  }
+  return null;
+}
+
+// =============================================================================
+// Tool Definitions
+// =============================================================================
+
+const tools = [
+  // Knowledge Base Tool
+  {
+    name: "get_api_info",
+    description: "Get Dynamic Mockups API information including billing, rate limits, supported formats, and best practices. Use this to understand API capabilities and constraints.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        topic: {
+          type: "string",
+          enum: ["all", "billing", "rate_limits", "formats", "best_practices", "support"],
+          description: "Specific topic to get info about, or 'all' for complete knowledge base",
+        },
+      },
+    },
+  },
+
+  // Catalog Tools
+  {
+    name: "get_catalogs",
+    description: "Retrieve all available catalogs. Catalogs are top-level containers for organizing collections and mockups.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+
+  // Collection Tools
+  {
+    name: "get_collections",
+    description: "Retrieve collections, optionally filtered by catalog. Collections group related mockups together.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        catalog_uuid: {
+          type: "string",
+          description: "Filter collections by catalog UUID",
+        },
+        include_all_catalogs: {
+          type: "boolean",
+          description: "Include collections from all catalogs (default: false, returns only default catalog)",
+        },
+      },
+    },
+  },
+  {
+    name: "create_collection",
+    description: "Create a new collection to organize mockups",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Name for the new collection",
+        },
+        catalog_uuid: {
+          type: "string",
+          description: "Catalog UUID to create collection in (uses default catalog if not specified)",
+        },
+      },
+      required: ["name"],
+    },
+  },
+
+  // Mockup Tools
+  {
+    name: "get_mockups",
+    description: "Retrieve mockups from My Templates with optional filtering. Returns mockup UUIDs needed for rendering.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        catalog_uuid: {
+          type: "string",
+          description: "Filter by catalog UUID",
+        },
+        collection_uuid: {
+          type: "string",
+          description: "Filter by collection UUID",
+        },
+        include_all_catalogs: {
+          type: "boolean",
+          description: "Include mockups from all catalogs (default: false)",
+        },
+        name: {
+          type: "string",
+          description: "Filter mockups by name (partial match)",
+        },
+      },
+    },
+  },
+  {
+    name: "get_mockup_by_uuid",
+    description: "Get detailed information about a specific mockup including its smart objects and configuration",
+    inputSchema: {
+      type: "object",
+      properties: {
+        uuid: {
+          type: "string",
+          description: "The mockup UUID",
+        },
+      },
+      required: ["uuid"],
+    },
+  },
+
+  // Render Tools
+  {
+    name: "create_render",
+    description: "Render a single mockup with design assets. Costs 1 credit per render. For multiple renders, use create_batch_render instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mockup_uuid: {
+          type: "string",
+          description: "UUID of the mockup template to render",
+        },
+        smart_objects: {
+          type: "array",
+          description: "Smart objects configuration with design assets",
+          items: {
+            type: "object",
+            properties: {
+              uuid: {
+                type: "string",
+                description: "Smart object UUID (get from mockup details)",
+              },
+              asset: {
+                type: "object",
+                description: "Design asset configuration",
+                properties: {
+                  url: {
+                    type: "string",
+                    description: "URL to the design image (jpg, jpeg, png, webp, gif)",
+                  },
+                  fit: {
+                    type: "string",
+                    enum: ["stretch", "contain", "cover"],
+                    description: "How to fit the asset in the smart object area",
+                  },
+                  size: {
+                    type: "object",
+                    properties: {
+                      width: { type: "integer" },
+                      height: { type: "integer" },
+                    },
+                  },
+                  position: {
+                    type: "object",
+                    properties: {
+                      top: { type: "integer" },
+                      left: { type: "integer" },
+                    },
+                  },
+                  rotate: {
+                    type: "number",
+                    description: "Rotation angle in degrees",
+                  },
+                },
+              },
+              color: {
+                type: "string",
+                description: "Color overlay in hex format (e.g., #FF0000)",
+              },
+              print_area_preset_uuid: {
+                type: "string",
+                description: "Print area preset UUID for automatic positioning",
+              },
+            },
+          },
+        },
+        export_label: {
+          type: "string",
+          description: "Label for the exported image (appears in filename)",
+        },
+        export_options: {
+          type: "object",
+          properties: {
+            image_format: {
+              type: "string",
+              enum: ["jpg", "png", "webp"],
+              description: "Output image format (default: jpg)",
+            },
+            image_size: {
+              type: "integer",
+              description: "Output image size in pixels (default: 1000)",
+            },
+            mode: {
+              type: "string",
+              enum: ["view", "download"],
+              description: "URL mode - 'view' for browser display, 'download' for attachment",
+            },
+          },
+        },
+        text_layers: {
+          type: "array",
+          description: "Text layer customizations",
+          items: {
+            type: "object",
+            properties: {
+              uuid: { type: "string", description: "Text layer UUID" },
+              text: { type: "string", description: "Text content" },
+              font_family: { type: "string" },
+              font_size: { type: "number" },
+              font_color: { type: "string", description: "Hex color code" },
+            },
+          },
+        },
+      },
+      required: ["mockup_uuid", "smart_objects"],
+    },
+  },
+  {
+    name: "create_batch_render",
+    description: "Render multiple mockups in a single request. RECOMMENDED for rendering more than one image - more efficient and faster than individual renders. Costs 1 credit per image.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        renders: {
+          type: "array",
+          description: "Array of render configurations",
+          items: {
+            type: "object",
+            properties: {
+              mockup_uuid: {
+                type: "string",
+                description: "UUID of the mockup template",
+              },
+              smart_objects: {
+                type: "array",
+                description: "Smart objects configuration (same as create_render)",
+              },
+              text_layers: {
+                type: "array",
+                description: "Text layer customizations",
+              },
+              export_label: {
+                type: "string",
+                description: "Label for this specific render",
+              },
+            },
+            required: ["mockup_uuid", "smart_objects"],
+          },
+        },
+        export_options: {
+          type: "object",
+          description: "Export options applied to all renders in the batch",
+          properties: {
+            image_format: {
+              type: "string",
+              enum: ["jpg", "png", "webp"],
+            },
+            image_size: {
+              type: "integer",
+            },
+            mode: {
+              type: "string",
+              enum: ["view", "download"],
+            },
+          },
+        },
+      },
+      required: ["renders"],
+    },
+  },
+  {
+    name: "export_print_files",
+    description: "Export high-resolution print files for production. Supports custom DPI settings.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mockup_uuid: {
+          type: "string",
+          description: "UUID of the mockup template",
+        },
+        smart_objects: {
+          type: "array",
+          description: "Smart objects configuration",
+        },
+        text_layers: {
+          type: "array",
+          description: "Text layer customizations",
+        },
+        export_label: {
+          type: "string",
+          description: "Label for the export",
+        },
+        export_options: {
+          type: "object",
+          properties: {
+            image_format: { type: "string", enum: ["jpg", "png", "webp"] },
+            image_size: { type: "integer" },
+            image_dpi: { type: "integer", description: "DPI for print (e.g., 300)" },
+            mode: { type: "string", enum: ["view", "download"] },
+          },
+        },
+      },
+      required: ["mockup_uuid", "smart_objects"],
+    },
+  },
+
+  // PSD Management Tools
+  {
+    name: "upload_psd",
+    description: "Upload a PSD file to create custom mockup templates. The PSD should contain smart object layers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        psd_file_url: {
+          type: "string",
+          description: "Public URL to the PSD file",
+        },
+        psd_name: {
+          type: "string",
+          description: "Name for the uploaded PSD",
+        },
+        psd_category_id: {
+          type: "integer",
+          description: "Category ID for organization",
+        },
+        mockup_template: {
+          type: "object",
+          description: "Automatically create a mockup template from the PSD",
+          properties: {
+            create_after_upload: {
+              type: "boolean",
+              description: "Create mockup template after upload",
+            },
+            collections: {
+              type: "array",
+              items: { type: "string" },
+              description: "Collection UUIDs to add the mockup to",
+            },
+            catalog_uuid: {
+              type: "string",
+              description: "Catalog UUID for the mockup",
+            },
+          },
+        },
+      },
+      required: ["psd_file_url"],
+    },
+  },
+  {
+    name: "delete_psd",
+    description: "Delete a PSD file and optionally all mockups created from it",
+    inputSchema: {
+      type: "object",
+      properties: {
+        psd_uuid: {
+          type: "string",
+          description: "UUID of the PSD to delete",
+        },
+        delete_related_mockups: {
+          type: "boolean",
+          description: "Also delete all mockups created from this PSD (default: false)",
+        },
+      },
+      required: ["psd_uuid"],
+    },
+  },
+];
+
+// =============================================================================
+// Tool Handlers
+// =============================================================================
+
+async function handleGetApiInfo(args) {
+  const topic = args?.topic || "all";
+
+  const topicMap = {
+    billing: { billing: API_KNOWLEDGE_BASE.billing },
+    rate_limits: { rate_limits: API_KNOWLEDGE_BASE.rate_limits },
+    formats: { supported_formats: API_KNOWLEDGE_BASE.supported_formats, asset_upload: API_KNOWLEDGE_BASE.asset_upload },
+    best_practices: { best_practices: API_KNOWLEDGE_BASE.best_practices },
+    support: { support: API_KNOWLEDGE_BASE.support },
+    all: API_KNOWLEDGE_BASE,
+  };
+
+  return ResponseFormatter.ok(topicMap[topic] || API_KNOWLEDGE_BASE);
+}
+
+async function handleGetCatalogs() {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const response = await createApiClient().get("/catalogs");
+    return ResponseFormatter.fromApiResponse(response);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to get catalogs");
+  }
+}
+
+async function handleGetCollections(args = {}) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const params = new URLSearchParams();
+    if (args.catalog_uuid) params.append("catalog_uuid", args.catalog_uuid);
+    if (args.include_all_catalogs !== undefined) {
+      params.append("include_all_catalogs", args.include_all_catalogs);
+    }
+
+    const response = await createApiClient().get(`/collections?${params}`);
+    return ResponseFormatter.fromApiResponse(response);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to get collections");
+  }
+}
+
+async function handleCreateCollection(args) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const payload = { name: args.name };
+    if (args.catalog_uuid) payload.catalog_uuid = args.catalog_uuid;
+
+    const response = await createApiClient().post("/collections", payload);
+    return ResponseFormatter.fromApiResponse(response, `Collection "${args.name}" created`);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to create collection");
+  }
+}
+
+async function handleGetMockups(args = {}) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const params = new URLSearchParams();
+    if (args.catalog_uuid) params.append("catalog_uuid", args.catalog_uuid);
+    if (args.collection_uuid) params.append("collection_uuid", args.collection_uuid);
+    if (args.include_all_catalogs !== undefined) {
+      params.append("include_all_catalogs", args.include_all_catalogs);
+    }
+    if (args.name) params.append("name", args.name);
+
+    const response = await createApiClient().get(`/mockups?${params}`);
+    return ResponseFormatter.fromApiResponse(response);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to get mockups");
+  }
+}
+
+async function handleGetMockupByUuid(args) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const response = await createApiClient().get(`/mockup/${args.uuid}`);
+    return ResponseFormatter.fromApiResponse(response);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to get mockup");
+  }
+}
+
+async function handleCreateRender(args) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const payload = {
+      mockup_uuid: args.mockup_uuid,
+      smart_objects: args.smart_objects,
+    };
+    if (args.export_label) payload.export_label = args.export_label;
+    if (args.export_options) payload.export_options = args.export_options;
+    if (args.text_layers) payload.text_layers = args.text_layers;
+
+    const response = await createApiClient().post("/renders", payload);
+    return ResponseFormatter.fromApiResponse(response, "Render created (1 credit used)");
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to create render");
+  }
+}
+
+async function handleCreateBatchRender(args) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const payload = { renders: args.renders };
+    if (args.export_options) payload.export_options = args.export_options;
+
+    const response = await createApiClient().post("/renders/batch", payload);
+    const count = args.renders?.length || 0;
+    return ResponseFormatter.fromApiResponse(response, `Batch render complete (${count} credits used)`);
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to create batch render");
+  }
+}
+
+async function handleExportPrintFiles(args) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const payload = {
+      mockup_uuid: args.mockup_uuid,
+      smart_objects: args.smart_objects,
+    };
+    if (args.export_label) payload.export_label = args.export_label;
+    if (args.export_options) payload.export_options = args.export_options;
+    if (args.text_layers) payload.text_layers = args.text_layers;
+
+    const response = await createApiClient().post("/renders/print-files", payload);
+    return ResponseFormatter.fromApiResponse(response, "Print files exported");
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to export print files");
+  }
+}
+
+async function handleUploadPsd(args) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const payload = { psd_file_url: args.psd_file_url };
+    if (args.psd_name) payload.psd_name = args.psd_name;
+    if (args.psd_category_id) payload.psd_category_id = args.psd_category_id;
+    if (args.mockup_template) payload.mockup_template = args.mockup_template;
+
+    const response = await createApiClient().post("/psd/upload", payload);
+    return ResponseFormatter.fromApiResponse(response, "PSD uploaded successfully");
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to upload PSD");
+  }
+}
+
+async function handleDeletePsd(args) {
+  const error = validateApiKey();
+  if (error) return error;
+
+  try {
+    const payload = { psd_uuid: args.psd_uuid };
+    if (args.delete_related_mockups !== undefined) {
+      payload.delete_related_mockups = args.delete_related_mockups;
+    }
+
+    const response = await createApiClient().post("/psd/delete", payload);
+    return ResponseFormatter.fromApiResponse(response, "PSD deleted successfully");
+  } catch (err) {
+    return ResponseFormatter.fromError(err, "Failed to delete PSD");
+  }
+}
+
+// =============================================================================
+// Tool Router
+// =============================================================================
+
+const toolHandlers = {
+  get_api_info: handleGetApiInfo,
+  get_catalogs: handleGetCatalogs,
+  get_collections: handleGetCollections,
+  create_collection: handleCreateCollection,
+  get_mockups: handleGetMockups,
+  get_mockup_by_uuid: handleGetMockupByUuid,
+  create_render: handleCreateRender,
+  create_batch_render: handleCreateBatchRender,
+  export_print_files: handleExportPrintFiles,
+  upload_psd: handleUploadPsd,
+  delete_psd: handleDeletePsd,
+};
+
+// =============================================================================
+// MCP Request Handlers
+// =============================================================================
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  const handler = toolHandlers[name];
+  if (!handler) {
+    return ResponseFormatter.error(`Unknown tool: ${name}`);
+  }
+
+  try {
+    return await handler(args || {});
+  } catch (err) {
+    return ResponseFormatter.fromError(err, `Error executing ${name}`);
+  }
+});
+
+// =============================================================================
+// Server Startup
+// =============================================================================
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`Dynamic Mockups MCP Server v${SERVER_VERSION} running`);
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/src/response-formatter.js

@@ -0,0 +1,104 @@
+/**
+ * Response Formatter for Dynamic Mockups MCP Server
+ * Provides consistent MCP-compliant response formatting
+ */
+
+export class ResponseFormatter {
+  /**
+   * Create a successful MCP response with data
+   * @param {any} data - Data to include in response
+   * @returns {object} MCP-compliant response
+   */
+  static ok(data) {
+    const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    return {
+      content: [{ type: "text", text }],
+    };
+  }
+
+  /**
+   * Create an error MCP response
+   * @param {string} message - Error message
+   * @param {object} details - Additional error details
+   * @returns {object} MCP-compliant error response
+   */
+  static error(message, details = {}) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: { message, ...details } }, null, 2),
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  /**
+   * Format an API response, handling both success and error cases
+   * @param {object} response - Axios response object
+   * @param {string} successMessage - Optional success message prefix
+   * @returns {object} MCP-compliant response
+   */
+  static fromApiResponse(response, successMessage = null) {
+    const { status, data } = response;
+
+    // Handle API errors (4xx responses)
+    if (status >= 400) {
+      const errorMessage = data?.message || data?.error || `API error (${status})`;
+      return this.error(errorMessage, {
+        status,
+        details: data,
+      });
+    }
+
+    // Handle successful responses
+    if (successMessage) {
+      return this.ok({
+        message: successMessage,
+        ...data,
+      });
+    }
+
+    return this.ok(data);
+  }
+
+  /**
+   * Format an error from a caught exception
+   * @param {Error} error - The caught error
+   * @param {string} context - Context description for the error
+   * @returns {object} MCP-compliant error response
+   */
+  static fromError(error, context = "Operation failed") {
+    // Handle Axios errors
+    if (error.response) {
+      return this.error(context, {
+        status: error.response.status,
+        message: error.response.data?.message || error.message,
+        details: error.response.data,
+      });
+    }
+
+    // Handle network errors
+    if (error.code === "ECONNABORTED") {
+      return this.error("Request timeout", {
+        context,
+        suggestion: "The API request took too long. Try again or use smaller batch sizes.",
+      });
+    }
+
+    if (error.code === "ENOTFOUND" || error.code === "ECONNREFUSED") {
+      return this.error("Network error", {
+        context,
+        suggestion: "Unable to reach the API. Check your internet connection.",
+      });
+    }
+
+    // Handle generic errors
+    return this.error(context, {
+      message: error.message,
+    });
+  }
+}
+
+export default ResponseFormatter;