@productmaker/mcp 1.16.3 → 2.0.0

package/dist/http.js

@@ -12,6 +12,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/api-client.ts
+import { createHash } from "crypto";
 var ApiHttpError = class extends Error {
   static {
     __name(this, "ApiHttpError");
@@ -38,6 +39,15 @@ var ApiClient = class {
       Authorization: `Bearer ${this.apiKey}`
     };
   }
+  /**
+  * Stable per-key identifier. The MCP never sees the userId — the API key is
+  * the only per-user handle it holds — so this stands in as the user
+  * component of derived idempotency keys. Never log or return it raw to a
+  * caller: it is derived from a secret.
+  */
+  fingerprint() {
+    return createHash("sha256").update(this.apiKey).digest("hex").slice(0, 32);
+  }
   async getJson(path3) {
     const res = await fetch(`${this.baseUrl}${path3}`, {
       headers: this.authHeaders()
@@ -132,7 +142,7 @@ var ApiClient = class {
 };
 
 // src/index.ts
-var MCP_VERSION = "1.16.3";
+var MCP_VERSION = "2.0.0";
 
 // src/tools/tasks.ts
 import { z as z39 } from "zod";
@@ -440,9 +450,11 @@ var VideoModel = z.enum([
 ]);
 var NarrativeStyle = z.enum([
   "review",
+  "ugc_how_to",
   "problem_product_cta",
   "product_showcase",
   "cinematic",
+  "wild_card",
   "metaphor_product_cta",
   "wearable_showcase",
   "animated_problem_pixar",
@@ -461,9 +473,11 @@ var VideoResolution = z.enum([
 var VideoPreset = z.enum([
   "auto",
   "ugc_dynamic",
+  "ugc_how_to",
   "problem_solution",
   "product_showcase",
   "cinematic",
+  "wild_card",
   "wearable_showcase",
   "pixar_problem",
   "pixar_sassy",
@@ -2451,6 +2465,7 @@ var TASK_CREATIVE_VARIANT_TEXT_LIMITS = {
   recommendationRationale: 600
 };
 var TaskCreativeVariantVideoPreset = VideoPreset.exclude([
+  "problem_solution",
   "ugc_unboxing_chaos",
   "ugc_curiosity_reveal",
   "ugc_listicle_3",
@@ -2563,6 +2578,7 @@ var TaskVariantSummary = z21.object({
 var MAX_LANDING_IMAGES = 20;
 var AutoResolvedPresetSchema = z22.enum([
   "ugc_dynamic",
+  "ugc_how_to",
   "ugc_demo_review",
   "ugc_unboxing_chaos",
   "ugc_curiosity_reveal",
@@ -2571,6 +2587,7 @@ var AutoResolvedPresetSchema = z22.enum([
   "problem_solution",
   "product_showcase",
   "cinematic",
+  "wild_card",
   "wearable_showcase",
   "pixar_problem",
   "pixar_sassy",
@@ -3149,6 +3166,125 @@ var AdminQualityReportListResponse = z24.object({
 var UpdateQualityReportStatusRequest = z24.object({
   status: QualityReportStatus
 });
+var AdminSupportConversationStatus = z24.enum([
+  "bot_active",
+  "human_pending",
+  "human_active",
+  "closed"
+]);
+var AdminSupportDeliveryStatus = z24.enum([
+  "draft",
+  "pending",
+  "sent",
+  "delivered",
+  "read",
+  "failed",
+  "blocked"
+]);
+var AdminSupportMessage = z24.object({
+  id: z24.string().uuid(),
+  direction: z24.enum([
+    "inbound",
+    "outbound"
+  ]),
+  senderKind: z24.enum([
+    "user",
+    "bot",
+    "admin",
+    "system"
+  ]),
+  messageType: z24.enum([
+    "text",
+    "image",
+    "audio",
+    "document",
+    "interactive",
+    "status"
+  ]),
+  bodyRedacted: z24.string().nullable(),
+  deliveryStatus: AdminSupportDeliveryStatus.nullable(),
+  createdAt: z24.string().datetime()
+});
+var AdminSupportTicket = z24.object({
+  id: z24.string().uuid(),
+  category: z24.enum([
+    "how_to",
+    "credits",
+    "billing",
+    "task_status",
+    "task_error",
+    "video_quality",
+    "landing_quality",
+    "image_quality",
+    "feature_request",
+    "other"
+  ]),
+  failureMode: z24.string().nullable(),
+  status: z24.enum([
+    "open",
+    "triaged",
+    "resolved",
+    "rejected"
+  ]),
+  summary: z24.string(),
+  taskId: z24.string().nullable(),
+  mixTaskId: z24.string().nullable(),
+  qualityReportId: z24.string().nullable(),
+  handoffReason: z24.string().nullable(),
+  createdAt: z24.string().datetime(),
+  updatedAt: z24.string().datetime()
+});
+var AdminSupportConversation = z24.object({
+  id: z24.string().uuid(),
+  status: AdminSupportConversationStatus,
+  priority: z24.enum([
+    "low",
+    "normal",
+    "high",
+    "urgent"
+  ]),
+  currentIntent: z24.string().nullable(),
+  assignedAdminId: z24.string().nullable(),
+  customerServiceWindowEndsAt: z24.string().datetime().nullable(),
+  lastInboundAt: z24.string().datetime().nullable(),
+  createdAt: z24.string().datetime(),
+  updatedAt: z24.string().datetime(),
+  contact: z24.object({
+    id: z24.string().uuid(),
+    userId: z24.string().nullable(),
+    verifiedAt: z24.string().datetime().nullable(),
+    botMode: z24.enum([
+      "enabled",
+      "paused",
+      "opted_out"
+    ]),
+    locale: z24.string()
+  }),
+  messages: z24.array(AdminSupportMessage),
+  tickets: z24.array(AdminSupportTicket)
+});
+var AdminSupportListQuery = z24.object({
+  status: AdminSupportConversationStatus.optional(),
+  take: z24.coerce.number().int().min(1).max(100).default(50),
+  cursorId: z24.string().uuid().optional()
+}).strict();
+var AdminSupportListResponse = z24.object({
+  conversations: z24.array(AdminSupportConversation),
+  nextCursor: z24.string().uuid().nullable()
+});
+var AdminSupportReplyRequest = z24.object({
+  body: z24.string().trim().min(1).max(4096),
+  idempotencyKey: z24.string().regex(/^[A-Za-z0-9_-]{8,128}$/)
+}).strict();
+var AdminSupportEmptyActionRequest = z24.object({}).strict();
+var AdminSupportActionResponse = z24.object({
+  conversation: AdminSupportConversation
+});
+var AdminSupportReplyResponse = z24.object({
+  messageId: z24.string().uuid(),
+  deliveryStatus: AdminSupportDeliveryStatus,
+  duplicate: z24.boolean()
+});
 
 // ../../packages/types/src/promo.ts
 import { z as z25 } from "zod";
@@ -3984,6 +4120,23 @@ var DEFAULT_PRICING = {
     ourCostCents: 0.4,
     userPriceCents: 0.8
   },
+  // WhatsApp ProductMaker intent proposal. Real OpenRouter usage.cost wins;
+  // this is only the fallback when the relay omits cost.
+  "openrouter:whatsapp-product-agent-intent": {
+    ourCostCents: 0.4,
+    userPriceCents: 0.8
+  },
+  // Internal support calls are cost-only: callers explicitly override user
+  // price to zero. Static COGS estimates apply because OpenAI Responses exposes
+  // token counts but not the provider's dollar charge.
+  "openai:whatsapp-support-classifier": {
+    ourCostCents: 0.1,
+    userPriceCents: 0.2
+  },
+  "openai:whatsapp-support-draft": {
+    ourCostCents: 0.4,
+    userPriceCents: 0.8
+  },
   // Task-derived creative recommendation (angle/persona/script/landing-section).
   // OpenRouter usage normally supplies the exact COGS and the call layer charges
   // 2x. This rule is the fail-closed fallback when usage.cost is unavailable.
@@ -6430,6 +6583,151 @@ var SceneSubjectContractSchema = z37.object({
   }
 });
 
+// ../../packages/types/src/productmaker-chat-capabilities.ts
+var PRODUCTMAKER_MCP_CAPABILITIES = [
+  {
+    name: "approve_video_script",
+    confirmation: "credit_consuming",
+    schemaHash: "bab794a9700a8d3f42b97f444a776e7ed4dcd833038c52588f951b50970ff3fa"
+  },
+  {
+    name: "cost_product",
+    confirmation: "none",
+    schemaHash: "6d1f85a999dbdabae4eda406ff4689cdff2016df375b5b6741b91f4308d819af"
+  },
+  {
+    name: "create_creative_variant",
+    confirmation: "credit_consuming",
+    schemaHash: "8feeed1e6e6a14bdcb0a1d9d8b03350ce7d8117d926db49f19ca5c5a8f1e7033"
+  },
+  {
+    name: "create_product_task",
+    confirmation: "credit_consuming",
+    schemaHash: "5346684b007a40f6e8d53cc0b56ebb20aeb7e5ba48cdde43bc9f4e6163ed2d3f"
+  },
+  {
+    name: "edit_task_draft",
+    confirmation: "state_change",
+    schemaHash: "f1763564083dcaac2d1f4d5e6c4625a2d4ec0ea3eea273aadc0fb9d4ab6c7d47"
+  },
+  {
+    name: "estimate_creative_variant",
+    confirmation: "none",
+    schemaHash: "a5601adcb9578319528ca0a96f37a35b613370646a75932d1b3978d593f7e302"
+  },
+  {
+    name: "find_winning_products",
+    confirmation: "credit_consuming",
+    schemaHash: "40f581e270ca668fb5fd1505a1f7cced6f629936e7d8394426aa0c655b9cef4f"
+  },
+  {
+    name: "generate_free_video",
+    confirmation: "credit_consuming",
+    schemaHash: "a6f984d175c1ae5bc5f36ade27ee12c57763192000453c0387cd4cd6a9f1751d"
+  },
+  {
+    name: "generate_image_creatives",
+    confirmation: "credit_consuming",
+    schemaHash: "fb6afcf8571887906340fa0b8dd17196d2814e480b734ad5d374e8810958152e"
+  },
+  {
+    name: "generate_landing",
+    confirmation: "credit_consuming",
+    schemaHash: "539922b8fe611c73a7349b1c3f92632fe21f161d7874a0ef2172abfec5834759"
+  },
+  {
+    name: "generate_video_creative",
+    confirmation: "credit_consuming",
+    schemaHash: "94e90d60ad5d68538c31d880a635c5be69d6d204fd2119139735af83ebf0b94a"
+  },
+  {
+    name: "get_meta_campaign_status",
+    confirmation: "none",
+    schemaHash: "92077241cf4e9d14edefca410e85715cc383b1433081c3461c925f8fc3d6e8ab"
+  },
+  {
+    name: "get_product_research_run",
+    confirmation: "none",
+    schemaHash: "3d0bfa4409daa4a8126d18787c3dc619dbdf2fbb679a2cffe9ffcd1c0d96402f"
+  },
+  {
+    name: "get_task_status",
+    confirmation: "none",
+    schemaHash: "6876d865685dd371ae6c2da2d5a69b657731e5a032aff46ac95b6077e9a6d93e"
+  },
+  {
+    name: "get_tiktok_campaign_status",
+    confirmation: "none",
+    schemaHash: "7a2f90a9a9ba91506fbb57a0a881d5a7b9ca1bb1074b0a754520f02fd81b2801"
+  },
+  {
+    name: "get_video_script",
+    confirmation: "none",
+    schemaHash: "c96e7042368ba6f241773d26d4a443894b092801d1c81054f3798865138edfba"
+  },
+  {
+    name: "list_meta_ad_accounts",
+    confirmation: "none",
+    schemaHash: "7a014b717a77aac971ea0ab5c0ff47bb13e6cae7ef9442d9dedb15ce36381b15"
+  },
+  {
+    name: "list_product_research_runs",
+    confirmation: "none",
+    schemaHash: "3b8fac903cd9e30c5b6a6c584cc70a819af5392bbdbb32b69eab4c65dc52b556"
+  },
+  {
+    name: "list_shopify_products",
+    confirmation: "none",
+    schemaHash: "152b137e01066f3b443987ad75f5be00de8696ce984144bd775416192be20667"
+  },
+  {
+    name: "list_shopify_shops",
+    confirmation: "none",
+    schemaHash: "7a014b717a77aac971ea0ab5c0ff47bb13e6cae7ef9442d9dedb15ce36381b15"
+  },
+  {
+    name: "list_tasks",
+    confirmation: "none",
+    schemaHash: "cac5e9dda34b90550024cc546976fab1d6de4fc8fca85a3ec6abde65223cb56c"
+  },
+  {
+    name: "list_tiktok_advertisers",
+    confirmation: "none",
+    schemaHash: "7a014b717a77aac971ea0ab5c0ff47bb13e6cae7ef9442d9dedb15ce36381b15"
+  },
+  {
+    name: "publish_creatives_to_meta",
+    confirmation: "external_mutation",
+    schemaHash: "ddb45071d61746b443124346e7a82095315a2a80bd393c73a45f12b895939cf5"
+  },
+  {
+    name: "publish_to_meta",
+    confirmation: "external_mutation",
+    schemaHash: "4b6daa1a25e739ccf208a6acede067ec1c22b1ea5509f332361a17dd46f6bb0b"
+  },
+  {
+    name: "publish_to_shopify",
+    confirmation: "external_mutation",
+    schemaHash: "ec37111aac872e6be22f34c8b547c1e4b58875f798c48e24ca9ca067a0a22d8b"
+  },
+  {
+    name: "publish_to_tiktok",
+    confirmation: "external_mutation",
+    schemaHash: "4f8dccba51b99687f04e1a58e3fde003b6f52ec6c891afe74b1d81d4b6992908"
+  },
+  {
+    name: "regenerate_video_script",
+    confirmation: "credit_consuming",
+    schemaHash: "745687cb41f904e293105f93bbe6bc0471f63fe097ab8f85d3df8d9833084844"
+  },
+  {
+    name: "resolve_pending_action",
+    confirmation: "credit_consuming",
+    schemaHash: "3a9f33a26fce63b20bece3a528f8eb16e917dabc8a9ec5f04e746bad84757aa3"
+  }
+];
+var PRODUCTMAKER_MCP_CAPABILITY_NAMES = PRODUCTMAKER_MCP_CAPABILITIES.map((capability) => capability.name);
+
 // src/resolve-media.ts
 var MAX_MEDIA_BYTES = CAMPAIGN_LIMITS.MAX_FILE_SIZE_BYTES;
 var MEDIA_FORMATS = [
@@ -6689,20 +6987,22 @@ var LandingImageFormatEnum = z38.enum([
 var VideoPresetEnum = z38.enum([
   "auto",
   "ugc_dynamic",
+  "ugc_how_to",
   "ugc_unboxing_chaos",
-  "problem_solution",
   "product_showcase",
   "wearable_showcase",
   "cinematic",
+  "wild_card",
   "pixar_problem",
   "pixar_sassy"
 ]);
 var TaskCreativeVariantVideoPresetEnum = z38.enum([
   "auto",
   "ugc_dynamic",
-  "problem_solution",
+  "ugc_how_to",
   "product_showcase",
   "cinematic",
+  "wild_card",
   "wearable_showcase",
   "pixar_problem",
   "pixar_sassy",
@@ -6715,15 +7015,15 @@ var VIDEO_PRESET_RESOLUTION = {
     narrativeStyle: "review",
     videoModel: "veo"
   },
-  ugc_unboxing_chaos: {
+  ugc_how_to: {
     videoStyle: "ai_dynamic",
-    narrativeStyle: "ugc_unboxing_chaos",
+    narrativeStyle: "ugc_how_to",
     videoModel: "veo"
   },
-  problem_solution: {
+  ugc_unboxing_chaos: {
     videoStyle: "ai_dynamic",
-    narrativeStyle: "problem_product_cta",
-    videoModel: "kling"
+    narrativeStyle: "ugc_unboxing_chaos",
+    videoModel: "veo"
   },
   pixar_problem: {
     videoStyle: "ai_dynamic",
@@ -6749,6 +7049,11 @@ var VIDEO_PRESET_RESOLUTION = {
     videoStyle: "product_only",
     narrativeStyle: "cinematic",
     videoModel: "grok"
+  },
+  wild_card: {
+    videoStyle: "product_only",
+    narrativeStyle: "wild_card",
+    videoModel: "grok"
   }
 };
 function resolveVideoPreset(preset) {
@@ -6783,9 +7088,11 @@ var VideoStyleEnum = z38.enum([
 ]);
 var NarrativeStyleEnum = z38.enum([
   "review",
+  "ugc_how_to",
   "problem_product_cta",
   "product_showcase",
   "cinematic",
+  "wild_card",
   "metaphor_product_cta",
   "wearable_showcase",
   "animated_problem_pixar",
@@ -6798,11 +7105,12 @@ var NarrativeStyleEnum = z38.enum([
 ]);
 var PublicNarrativeStyleEnum = z38.enum([
   "review",
+  "ugc_how_to",
   "ugc_unboxing_chaos",
-  "problem_product_cta",
   "product_showcase",
   "wearable_showcase",
   "cinematic",
+  "wild_card",
   "animated_problem_pixar",
   "sassy_product_pixar"
 ]);
@@ -6930,6 +7238,28 @@ async function submitCreative(api, opts) {
   });
 }
 __name(submitCreative, "submitCreative");
+var ResearchTargetCountryEnum = z38.enum([
+  "CO",
+  "MX",
+  "PE",
+  "EC",
+  "CL"
+]);
+var ResearchCategoryEnum = z38.enum([
+  "auto",
+  "automotive",
+  "kitchen",
+  "pets",
+  "home_organization",
+  "beauty",
+  "wellness",
+  "fitness",
+  "baby",
+  "tech",
+  "tools",
+  "garden",
+  "cleaning"
+]);
 
 // src/errors.ts
 var McpErrorCode = {
@@ -6961,6 +7291,7 @@ var McpErrorCode = {
   TASK_NOT_READY: "TASK_NOT_READY",
   CREATIVE_VARIANT_FAILED: "CREATIVE_VARIANT_FAILED",
   CREATIVE_VARIANT_DISPATCH_FAILED: "CREATIVE_VARIANT_DISPATCH_FAILED",
+  PRODUCT_RESEARCH_IDEMPOTENCY_CONFLICT: "PRODUCT_RESEARCH_IDEMPOTENCY_CONFLICT",
   // Connection presence
   NO_SHOPIFY_SHOPS: "NO_SHOPIFY_SHOPS",
   NO_META_AD_ACCOUNTS: "NO_META_AD_ACCOUNTS",
@@ -7082,12 +7413,13 @@ var CODE_MESSAGES = {
   TASK_NOT_READY: "The task is not ready for this action yet. Wait for it to finish and retry.",
   CREATIVE_VARIANT_FAILED: "The previous creative variant attempt failed. Ask for confirmation before starting a new paid attempt with a new clientRequestId.",
   CREATIVE_VARIANT_DISPATCH_FAILED: "The creative variant could not be queued. Retry as a new paid attempt with a new clientRequestId.",
+  PRODUCT_RESEARCH_IDEMPOTENCY_CONFLICT: "A product research run with the same country and category is already running. Check it with `list_product_research_runs` instead of starting a new paid run.",
   // API key
   INVALID_API_KEY: "Invalid API key. Check your PM_API_KEY in the MCP client configuration.",
   REVOKED_API_KEY: "API key revoked. Generate a new one at https://productmaker.app/account/api-keys.",
   // Rate
   RATE_LIMITED: "Too many requests. Wait a few seconds.",
-  INSUFFICIENT_CREDITS: "Insufficient credits to create this variant. Check your balance and retry after adding credits.",
+  INSUFFICIENT_CREDITS: "Insufficient credits for this action. Check your balance and add credits at https://productmaker.app before retrying.",
   TASK_QUOTA_EXCEEDED: "You reached the active-task limit. Wait for a task to finish before creating another variant.",
   // Generic
   UPSTREAM_UNAVAILABLE: "The Product Maker service did not respond. Try again shortly.",
@@ -7100,6 +7432,7 @@ var INVALID_PARAM_CODES = /* @__PURE__ */ new Set([
   McpErrorCode.INVALID_INPUT,
   McpErrorCode.INSUFFICIENT_CREDITS,
   McpErrorCode.TASK_QUOTA_EXCEEDED,
+  McpErrorCode.PRODUCT_RESEARCH_IDEMPOTENCY_CONFLICT,
   McpErrorCode.INVALID_API_KEY,
   McpErrorCode.REVOKED_API_KEY,
   McpErrorCode.IMAGE_PATH_NOT_FOUND,
@@ -7162,6 +7495,7 @@ var PASSTHROUGH_CODES = /* @__PURE__ */ new Set([
   McpErrorCode.INSUFFICIENT_CREDITS,
   McpErrorCode.TASK_QUOTA_EXCEEDED,
   McpErrorCode.CREATIVE_VARIANT_DISPATCH_FAILED,
+  McpErrorCode.PRODUCT_RESEARCH_IDEMPOTENCY_CONFLICT,
   // Shopify
   McpErrorCode.SHOPIFY_NOT_CONNECTED,
   McpErrorCode.SHOPIFY_TOKEN_EXPIRED,
@@ -7275,9 +7609,11 @@ function translateError(err) {
     const body = isRecord(err.body) ? err.body : {};
     if (typeof body.code === "string" && PASSTHROUGH_CODES.has(body.code)) {
       const code = body.code;
-      return mcp(code, resolveMessage(code, body.message), body.helpUrl ? {
-        helpUrl: body.helpUrl
-      } : {});
+      const extra = {};
+      if (body.helpUrl !== void 0) extra.helpUrl = body.helpUrl;
+      if (typeof body.requiredCredits === "number") extra.requiredCredits = body.requiredCredits;
+      if (typeof body.availableCredits === "number") extra.availableCredits = body.availableCredits;
+      return mcp(code, resolveMessage(code, body.message), extra);
     }
     if (err.status === 401) {
       return mcp(McpErrorCode.INVALID_API_KEY, resolveMessage(McpErrorCode.INVALID_API_KEY, void 0));
@@ -7533,7 +7869,7 @@ var CreateProductTaskInput = z39.object({
   paymentMethods: z39.string().min(1).max(240).optional().describe('Opcional. M\xE9todos de pago que puede mostrar la landing. Ej. "Tarjeta, PSE, Nequi, Contraentrega". Si se omite, la landing no muestra m\xE9todos de pago.'),
   productContext: z39.string().max(3e3).optional().describe("Opcional. Informacion adicional del producto que la IA debe usar como contexto prioritario: uso real, comprador, restricciones, diferenciadores o direccion creativa. No reemplaza la investigacion de competencia; si hay competencia, guia el primer angulo y los outputs no deben contradecirlo."),
   productLabel: z39.string().trim().max(80).optional().describe('Opcional. Qu\xE9 es el producto, en pocas palabras (ej. "quita pelusas para ropa"). Es AUTORITATIVO: si lo env\xEDas, la IA usa esta identidad y no la reemplaza por otra categor\xEDa. Si lo omites, la IA detecta el producto desde la imagen.'),
-  videoPreset: VideoPresetEnum.default("auto").describe('Opcional. Tipo/narrativa del video \u2014 \xFAnico campo de "estilo" que el usuario controla (en la web es el \xFAnico dropdown). Default "auto" (la IA escoge tras analizar el producto). Los presets funcionan a 15s y 30s; 30s usa el ritmo Multiescena. Opciones: "auto", "ugc_dynamic" (UGC testimonial), "ugc_unboxing_chaos" (unboxing agresivo), "ugc_curiosity_reveal" (hook con producto oculto), "ugc_listicle_3" (3 razones), "ugc_skeptic_confession" (esc\xE9ptico\u2192conversi\xF3n), "ugc_demo_review" (demo en uso), "problem_solution" (problema\u2192producto\u2192CTA), "pixar_problem" (problema animado 3D), "pixar_sassy" (producto que habla), "product_showcase" (solo producto, sin actor), "wearable_showcase" (ropa/accesorios puestos). Si el usuario pide algo fuera de esta lista (ej. "estilo anime"), p\xEDdele una opci\xF3n v\xE1lida.'),
+  videoPreset: VideoPresetEnum.default("auto").describe('Opcional. Tipo/narrativa del video \u2014 \xFAnico campo de "estilo" que el usuario controla. Default "auto" (la IA escoge tras analizar el producto). Los presets funcionan a 15s y 30s. Opciones: "auto", "ugc_dynamic" (review con experiencia y prueba), "ugc_how_to" (tutorial con pasos y resultado visible), "ugc_unboxing_chaos" (apertura y primera prueba), "product_showcase" (producto ejecutando una funci\xF3n real), "wearable_showcase" (prenda o accesorio modelado), "cinematic" (TV spot con receta cinematogr\xE1fica), "wild_card" (una regla visual experimental original), "pixar_problem" (problema animado 3D), "pixar_sassy" (producto que habla). Si el usuario pide algo fuera de esta lista, p\xEDdele una opci\xF3n v\xE1lida.'),
   durationSeconds: z39.union([
     z39.literal(15),
     z39.literal(30)
@@ -7542,7 +7878,7 @@ var CreateProductTaskInput = z39.object({
   videoTier: VideoTierEnum.optional().describe('Opcional. Estilo del video. "basic" = "Realista" para 15s; al pedir durationSeconds=30 el sistema selecciona internamente Multiescena. No se expone el tier interno directamente.'),
   videoResolution: VideoResolutionEnum.optional().describe('Opcional. Resoluci\xF3n del render. En la web se pregunta "\xBFResoluci\xF3n del video?". "480p" = excelente calidad y m\xE1s econ\xF3mico (RECOMENDADO, default si se omite); "720p" = m\xE1xima nitidez (~el doble de precio). Si el usuario no menciona resoluci\xF3n, OMITE este campo (el backend usa 480p).'),
   multiAngleVideos: z39.boolean().optional().describe("Opcional. Si true, genera m\xFAltiples \xE1ngulos de venta en paralelo (3-5 videos). Si false/omitido, genera 1 video del \xE1ngulo principal. Default false."),
-  angleNarratives: PublicNarrativeStyleEnum.array().max(3).optional().describe('Opcional. Narrativa POR \xC1NGULO (posicional). Valores actuales: "review", "ugc_unboxing_chaos", "problem_product_cta", "product_showcase", "wearable_showcase", "cinematic", "animated_problem_pixar", "sassy_product_pixar". angleNarratives[i] fuerza la narrativa del \xE1ngulo i; las posiciones restantes las elige la IA. Requiere multiAngleVideos:true para varios \xE1ngulos.'),
+  angleNarratives: PublicNarrativeStyleEnum.array().max(3).optional().describe('Opcional. Narrativa POR \xC1NGULO (posicional). Valores actuales: "review", "ugc_how_to", "ugc_unboxing_chaos", "product_showcase", "wearable_showcase", "cinematic", "wild_card", "animated_problem_pixar", "sassy_product_pixar". angleNarratives[i] fuerza la narrativa del \xE1ngulo i; las posiciones restantes las elige la IA. Requiere multiAngleVideos:true para varios \xE1ngulos.'),
   outputs: z39.array(z39.enum([
     "landing",
     "video",
@@ -8028,7 +8364,7 @@ var VideoInput = z40.object({
     z40.literal(15),
     z40.literal(30)
   ]).default(15).describe("Opcional. Duraci\xF3n objetivo: 15s (single_call, default) o 30s (Multiescena, aproximadamente 30s y facturado por escena)."),
-  videoPreset: VideoPresetEnum.default("auto").describe('Opcional. Tipo/narrativa del video \u2014 \xFAnico campo de "estilo" que el usuario controla (en la web es el \xFAnico dropdown). Default "auto" (la IA escoge tras analizar el producto). Los presets funcionan tanto a 15s como a 30s; el formato de 30s conserva el ritmo multi-escena. Opciones: "auto", "ugc_dynamic" (UGC cl\xE1sico testimonial multi-hook), "ugc_unboxing_chaos" (unboxing agresivo), "ugc_curiosity_reveal" (hook con producto oculto), "ugc_listicle_3" (3 razones numeradas), "ugc_skeptic_confession" (esc\xE9ptico\u2192conversi\xF3n), "ugc_demo_review" (demo en uso a lo largo de d\xEDas), "problem_solution" (problema\u2192producto\u2192CTA), "cinematic" (historia visual premium), "pixar_problem" (problema animado 3D estilo Pixar), "pixar_sassy" (producto que habla con personalidad), "product_showcase" (sin actor, solo producto), "wearable_showcase" (ropa/accesorios puestos).'),
+  videoPreset: VideoPresetEnum.default("auto").describe('Opcional. Tipo/narrativa del video \u2014 \xFAnico campo de "estilo" que el usuario controla. Default "auto" (la IA escoge tras analizar el producto). Los presets funcionan a 15s y 30s. Opciones: "auto", "ugc_dynamic" (review con experiencia y prueba), "ugc_how_to" (tutorial con pasos y resultado visible), "ugc_unboxing_chaos" (apertura y primera prueba), "product_showcase" (producto ejecutando una funci\xF3n real), "wearable_showcase" (prenda o accesorio modelado), "cinematic" (TV spot con receta cinematogr\xE1fica), "wild_card" (una regla visual experimental original), "pixar_problem" (problema animado 3D), "pixar_sassy" (producto que habla).'),
   videoTier: VideoTierEnum.optional().describe('Opcional. Estilo del video. "basic" = "Realista"; para durationSeconds=30 el sistema selecciona internamente Multiescena. No se expone el tier interno directamente.'),
   videoResolution: VideoResolutionEnum.optional().describe('Opcional. Resoluci\xF3n del render. En la web se pregunta "\xBFResoluci\xF3n del video?". "720p" = m\xE1xima nitidez (RECOMENDADO, default si se omite); "480p" = render m\xE1s econ\xF3mico. Si el usuario no menciona resoluci\xF3n, OMITE este campo (el backend usa 720p).'),
   features: z40.array(z40.string()).optional().describe('Opcional. Lista de features/beneficios clave a mencionar. Ej. ["resistente al agua", "bater\xEDa 24h", "carga inal\xE1mbrica"].'),
@@ -9645,6 +9981,224 @@ function formatPercent(value) {
 }
 __name(formatPercent, "formatPercent");
 
+// src/tools/product-research.ts
+import { z as z49 } from "zod";
+
+// src/tools/product-research-idempotency.ts
+import { createHash as createHash2 } from "crypto";
+var RESEARCH_IDEMPOTENCY_WINDOW_MS = 2 * 60 * 60 * 1e3;
+var NAMESPACE = "6f9d3a1e-8c47-4b52-9f10-2d7e5a3c8b64";
+function uuidV5(name, namespace) {
+  const namespaceBytes = Buffer.from(namespace.replace(/-/g, ""), "hex");
+  const digest = createHash2("sha1").update(namespaceBytes).update(name, "utf8").digest();
+  const bytes = Buffer.from(digest.subarray(0, 16));
+  bytes[6] = (bytes[6] ?? 0) & 15 | 80;
+  bytes[8] = (bytes[8] ?? 0) & 63 | 128;
+  const hex = bytes.toString("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20)
+  ].join("-");
+}
+__name(uuidV5, "uuidV5");
+function deriveIdempotencyKey(input) {
+  const window = Math.floor(input.nowMs / RESEARCH_IDEMPOTENCY_WINDOW_MS);
+  const name = `${input.fingerprint}:${input.targetCountry}:${input.categoryKey}:${window}`;
+  return uuidV5(name, NAMESPACE);
+}
+__name(deriveIdempotencyKey, "deriveIdempotencyKey");
+
+// src/tools/product-research-render.ts
+var num = /* @__PURE__ */ __name((value, suffix = "") => value === void 0 ? "\u2014" : `${Math.round(value * 100) / 100}${suffix}`, "num");
+function renderMeta(meta) {
+  if (meta.status === "evidence_failed") {
+    return [
+      "- \u26A0\uFE0F **Sin evidencia publicitaria:** no se pudo consultar Meta Ads para este producto. La puntuaci\xF3n se apoya s\xF3lo en datos de venta."
+    ];
+  }
+  if (meta.status === "evidence_empty") {
+    return [
+      "- \u26A0\uFE0F **Sin evidencia publicitaria:** no se encontraron anuncios activos en Meta. Puede ser un mercado virgen o una b\xFAsqueda sin cobertura; la puntuaci\xF3n se apoya s\xF3lo en datos de venta."
+    ];
+  }
+  return [
+    `- **Evidencia en Meta Ads:** ${meta.totalAds} anuncios de ${meta.distinctAdvertisers} anunciantes, m\xE1ximo ${meta.maxActiveDays} d\xEDas activos, oportunidad de \xE1ngulo ${meta.angleOpportunity}/100.`,
+    meta.summary ? `  ${meta.summary}` : ""
+  ].filter(Boolean);
+}
+__name(renderMeta, "renderMeta");
+function renderCandidate(candidate, index) {
+  const name = candidate.nameLocal ?? candidate.nameOriginal;
+  const lines = [
+    `### ${index + 1}. ${name}`,
+    `**${candidate.score}/100 \xB7 ${candidate.label} \xB7 confianza ${candidate.confidence}**`
+  ];
+  if (candidate.insight) lines.push("", candidate.insight);
+  lines.push("", "**Por qu\xE9:**");
+  lines.push(...candidate.reasons.map((reason) => `- ${reason}`));
+  lines.push("", "**Riesgos:**");
+  lines.push(...candidate.risks.length > 0 ? candidate.risks.map((risk) => `- ${risk}`) : [
+    "- No se identificaron riesgos espec\xEDficos."
+  ]);
+  lines.push("", ...renderMeta(candidate.meta));
+  lines.push("", `- **Venta (30d):** ${num(candidate.units30d)} unidades \xB7 ${num(candidate.revenueUsd30d, " USD")} \xB7 crecimiento ${num(candidate.growthPct30d, "%")} \xB7 precio ${num(candidate.priceUsd, " USD")}`);
+  if (candidate.productUrl) lines.push(`- [Ver producto](${candidate.productUrl})`);
+  return lines.join("\n");
+}
+__name(renderCandidate, "renderCandidate");
+function renderResearchReport(run) {
+  if (run.status === "failed" || run.status === "refunded") {
+    return [
+      `\u274C **La investigaci\xF3n no pudo completarse** (estado: ${run.status}).`,
+      run.errorCode ? `C\xF3digo: \`${run.errorCode}\`` : "",
+      run.refunded ? `Los ${run.priceCredits} cr\xE9ditos fueron reembolsados.` : "\u26A0\uFE0F No consta reembolso \u2014 rev\xEDsalo antes de reintentar."
+    ].filter(Boolean).join("\n");
+  }
+  if (run.status === "ready" && run.result === null) {
+    return [
+      `\u274C **No se pudo leer el reporte** (estado: ${run.status}).`,
+      `El cargo de ${run.priceCredits} cr\xE9ditos ya se realiz\xF3, pero el reporte qued\xF3 corrupto y no puede recuperarse.`,
+      `Contacta a soporte con este runId para revisar un reembolso: \`${run.id}\`.`
+    ].join("\n");
+  }
+  if (run.result === null) {
+    return [
+      `\u23F3 **La investigaci\xF3n sigue en curso** (estado: ${run.status}, etapa: ${run.progressStage}).`,
+      `El cargo de ${run.priceCredits} cr\xE9ditos ya se realiz\xF3; el reporte no se pierde.`,
+      `Cons\xFAltalo con \`get_product_research_run\` usando runId \`${run.id}\`.`
+    ].join("\n");
+  }
+  const { result } = run;
+  const degraded = result.candidates.filter((candidate) => candidate.meta.status !== "evidence_available").length;
+  const header = [
+    `\u2705 **Productos ganadores \xB7 ${result.targetCountry} \xB7 ${result.categoryKey}**`,
+    "",
+    `Analizados ${result.methodology.kaloCandidateCount} candidatos del mercado ${result.sourceMarket}; ${result.methodology.metaCoveredCandidateCount} con cobertura de Meta Ads. Datos con ${num(result.freshnessHours, " h")} de antig\xFCedad.`
+  ];
+  if (degraded > 0) {
+    header.push("", `\u26A0\uFE0F ${degraded} de ${result.candidates.length} productos no tienen evidencia publicitaria. Su puntuaci\xF3n se apoya s\xF3lo en datos de venta.`);
+  }
+  return [
+    ...header,
+    "",
+    ...result.candidates.map((candidate, index) => renderCandidate(candidate, index))
+  ].join("\n\n");
+}
+__name(renderResearchReport, "renderResearchReport");
+
+// src/tools/product-research.ts
+var PRICE_CREDITS = 2e3;
+var TERMINAL2 = /* @__PURE__ */ new Set([
+  "ready",
+  "failed",
+  "refunded"
+]);
+var POLL_INTERVAL_MS = 5e3;
+var MAX_WAIT_SECONDS = 120;
+var FindInput = z49.object({
+  targetCountry: ResearchTargetCountryEnum.describe("Pa\xEDs objetivo. S\xF3lo CO, MX, PE, EC y CL tienen cobertura de investigaci\xF3n."),
+  categoryKey: ResearchCategoryEnum.default("auto").describe('Categor\xEDa a investigar. Usa "auto" para que la IA elija seg\xFAn el mercado.'),
+  confirmed: z49.boolean().describe(`Ponlo en true SOLO despu\xE9s de que el usuario haya aceptado el cargo de ${PRICE_CREDITS} cr\xE9ditos. No lo asumas.`),
+  waitSeconds: z49.number().int().min(0).max(MAX_WAIT_SECONDS).optional().describe("Segundos a esperar el reporte antes de devolver el runId. M\xE1ximo 120.")
+});
+var GetInput = z49.object({
+  runId: z49.string().uuid().describe("ID del run devuelto por find_winning_products.")
+});
+var ListInput = z49.object({
+  limit: z49.number().int().min(1).max(20).default(10)
+});
+function textResult(text) {
+  return {
+    content: [
+      {
+        type: "text",
+        text
+      }
+    ]
+  };
+}
+__name(textResult, "textResult");
+var sleep2 = /* @__PURE__ */ __name((ms) => new Promise((resolve3) => setTimeout(resolve3, ms)), "sleep");
+async function pollUntilTerminal(api, runId, waitSeconds) {
+  const deadline = Date.now() + Math.min(waitSeconds, MAX_WAIT_SECONDS) * 1e3;
+  let run = await api.getJson(`/v1/product-research/runs/${runId}`);
+  while (!TERMINAL2.has(run.status) && Date.now() < deadline) {
+    await sleep2(POLL_INTERVAL_MS);
+    run = await api.getJson(`/v1/product-research/runs/${runId}`);
+  }
+  return run;
+}
+__name(pollUntilTerminal, "pollUntilTerminal");
+function registerProductResearchTools(server, api) {
+  server.tool("find_winning_products", `Busca productos ganadores de dropshipping para un pa\xEDs y categor\xEDa, y explica POR QU\xC9 la IA eligi\xF3 cada uno (razones, riesgos y evidencia real de anuncios en Meta Ads). CUESTA ${PRICE_CREDITS} CR\xC9DITOS por ejecuci\xF3n. ANTES de invocar, dile al usuario el costo y espera su aceptaci\xF3n expl\xEDcita; s\xF3lo entonces pasa confirmed: true. Consulta primero list_product_research_runs (GRATIS) \u2014 puede que el usuario ya tenga un reporte pagado para ese pa\xEDs/categor\xEDa y no necesites cobrar de nuevo. Pa\xEDses disponibles: CO, MX, PE, EC, CL. Tarda varios minutos: usa waitSeconds para esperar, y si expira consulta el resultado con get_product_research_run \u2014 el reporte NO se pierde.`, FindInput.shape, async (input) => {
+    const parsed = FindInput.parse(input);
+    if (!parsed.confirmed) {
+      throw mcp(McpErrorCode.INVALID_INPUT, `This research run costs ${PRICE_CREDITS} credits. Tell the user the cost, get an explicit yes, then call again with confirmed: true.`);
+    }
+    try {
+      const idempotencyKey = deriveIdempotencyKey({
+        fingerprint: api.fingerprint(),
+        targetCountry: parsed.targetCountry,
+        categoryKey: parsed.categoryKey,
+        nowMs: Date.now()
+      });
+      const created = await api.postJson("/v1/product-research/runs", {
+        targetCountry: parsed.targetCountry,
+        categoryKey: parsed.categoryKey,
+        idempotencyKey
+      });
+      const waitSeconds = parsed.waitSeconds ?? 0;
+      let run = created;
+      if (waitSeconds > 0 && !TERMINAL2.has(created.status)) {
+        try {
+          run = await pollUntilTerminal(api, created.id, waitSeconds);
+        } catch {
+          run = created;
+        }
+      }
+      const notice = created.reused ? `
+
+_Esta llamada no cobr\xF3 cr\xE9ditos: se reutiliz\xF3 una investigaci\xF3n reciente con los mismos par\xE1metros. Para investigar una categor\xEDa distinta, vuelve a llamar con un \`categoryKey\` expl\xEDcito \u2014 eso inicia una investigaci\xF3n NUEVA con un cargo NUEVO de ${PRICE_CREDITS} cr\xE9ditos, as\xED que pide confirmaci\xF3n expl\xEDcita al usuario antes de hacerlo._` : "";
+      return textResult(`${renderResearchReport(run)}${notice}`);
+    } catch (error) {
+      throw translateError(error);
+    }
+  });
+  server.tool("get_product_research_run", "Devuelve el reporte completo de una investigaci\xF3n de productos ganadores: score, veredicto, confianza, razones, riesgos y evidencia de Meta Ads por producto. GRATIS y read-only. \xDAsalo cuando find_winning_products expir\xF3 la espera, o para releer un reporte anterior encontrado con list_product_research_runs.", GetInput.shape, async (input) => {
+    const parsed = GetInput.parse(input);
+    try {
+      const run = await api.getJson(`/v1/product-research/runs/${parsed.runId}`);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(run)
+          },
+          {
+            type: "text",
+            text: renderResearchReport(run)
+          }
+        ]
+      };
+    } catch (error) {
+      throw translateError(error);
+    }
+  });
+  server.tool("list_product_research_runs", "Lista las investigaciones de productos ganadores ya pagadas por el usuario, de la m\xE1s reciente a la m\xE1s antigua. GRATIS y read-only. Cons\xFAltalo ANTES de lanzar una nueva: un reporte ya pagado se relee gratis con get_product_research_run.", ListInput.shape, async (input) => {
+    const parsed = ListInput.parse(input);
+    try {
+      const runs = await api.getJson(`/v1/product-research/runs?limit=${parsed.limit}`);
+      return textResult(JSON.stringify(runs));
+    } catch (error) {
+      throw translateError(error);
+    }
+  });
+}
+__name(registerProductResearchTools, "registerProductResearchTools");
+
 // src/server.ts
 function createServer(opts) {
   const { apiKey, apiBaseUrl, proxyBaseUrl = null, transport = "http" } = opts;
@@ -9661,6 +10215,7 @@ function createServer(opts) {
   });
   const api = new ApiClient(apiBaseUrl, apiKey);
   registerProductCostingTools(server);
+  registerProductResearchTools(server, api);
   registerTaskTools(server, api, {
     proxyBaseUrl,
     transport