@socialneuron/mcp-server 1.9.0 → 1.9.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@socialneuron/mcp-server` will be documented in this fil
 
 ## [Unreleased]
 
+## [1.9.1] - 2026-07-18
+
+### Fixed
+
+- **`generate_video` seedance audio default.** Seedance requests no longer silently drop audio: the audio flag now defaults on for audio-capable seedance models instead of rendering silent clips.
+- **Budget-limit errors are self-explanatory.** Budget rejections now state the limit, current usage, and what to do next, instead of a generic failure.
+- **`localOnly` tools no longer leak into remote listings.** Local-only tools are filtered from the tool catalogue when the server runs in remote/HTTP mode.
+- **`check_status` error scrubbing.** Internal error details are scrubbed from `check_status` responses; callers get actionable, non-internal messages.
+- **Carousel per-slide images inherit the resolved project.** `create_carousel` now threads the resolved `project_id` to the carousel job and every per-slide image job, so slide uploads carry project/organization context and are no longer rejected at upload ("A verified project or organization is required for uploads").
+
 ## [1.9.0] - 2026-07-15
 
 ### Added

package/dist/http.js

@@ -2509,7 +2509,7 @@ function checkRateLimit(category, key) {
 init_supabase();
 
 // src/lib/version.ts
-var MCP_VERSION = "1.9.0";
+var MCP_VERSION = "1.9.1";
 
 // src/tools/ideation.ts
 function asEnvelope(data) {
@@ -2914,6 +2914,86 @@ init_edge_function();
 import { z as z2 } from "zod";
 init_supabase();
 
+// src/lib/sanitize-error.ts
+var ERROR_PATTERNS = [
+  // Postgres / PostgREST
+  [
+    /PGRST301|permission denied/i,
+    "Access denied. Check your account permissions."
+  ],
+  [
+    /42P01|does not exist/i,
+    "Service temporarily unavailable. Please try again."
+  ],
+  [
+    /23505|unique.*constraint|duplicate key/i,
+    "A duplicate record already exists."
+  ],
+  [/23503|foreign key/i, "Referenced record not found."],
+  // Gemini / Google AI
+  [
+    /google.*api.*key|googleapis\.com.*40[13]/i,
+    "Content generation failed. Please try again."
+  ],
+  [
+    /RESOURCE_EXHAUSTED|quota.*exceeded|429.*google/i,
+    "AI service rate limit reached. Please wait and retry."
+  ],
+  [
+    /SAFETY|prompt.*blocked|content.*filter/i,
+    "Content was blocked by the AI safety filter. Try rephrasing."
+  ],
+  [
+    /gemini.*error|generativelanguage/i,
+    "Content generation failed. Please try again."
+  ],
+  // Kie.ai
+  [/kie\.ai|kieai|kie_api/i, "Media generation failed. Please try again."],
+  // Stripe
+  [
+    /stripe.*api|sk_live_|sk_test_/i,
+    "Payment processing error. Please try again."
+  ],
+  // Network / fetch
+  [
+    /ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET/i,
+    "External service unavailable. Please try again."
+  ],
+  [
+    /fetch failed|network error|abort.*timeout/i,
+    "Network request failed. Please try again."
+  ],
+  [/CERT_|certificate|SSL|TLS/i, "Secure connection failed. Please try again."],
+  // Supabase Edge Function internals
+  [
+    /FunctionsHttpError|non-2xx status/i,
+    "Backend service error. Please try again."
+  ],
+  [
+    /JWT|token.*expired|token.*invalid/i,
+    "Authentication expired. Please re-authenticate."
+  ],
+  // Generic sensitive patterns (API keys, URLs with secrets)
+  [
+    /[a-z0-9]{32,}.*key|Bearer [a-zA-Z0-9._-]+/i,
+    "An internal error occurred. Please try again."
+  ]
+];
+var UUID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+var EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+function redactSensitiveIdentifiers(message) {
+  return message.replace(EMAIL_PATTERN, "[redacted-email]").replace(UUID_PATTERN, "[redacted-id]");
+}
+function sanitizeError(error) {
+  const msg = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error";
+  for (const [pattern, userMessage] of ERROR_PATTERNS) {
+    if (pattern.test(msg)) {
+      return userMessage;
+    }
+  }
+  return "An unexpected error occurred. Please try again.";
+}
+
 // src/lib/checkStatusShape.ts
 function buildCheckStatusPayload(job, liveStatus) {
   const status = liveStatus?.status ?? job.status;
@@ -2963,8 +3043,14 @@ function buildCheckStatusPayload(job, liveStatus) {
 
 // src/lib/budget.ts
 init_request_context();
-var MAX_CREDITS_PER_RUN = Math.max(0, Number(process.env.SOCIALNEURON_MAX_CREDITS_PER_RUN || 0));
-var MAX_ASSETS_PER_RUN = Math.max(0, Number(process.env.SOCIALNEURON_MAX_ASSETS_PER_RUN || 0));
+var MAX_CREDITS_PER_RUN = Math.max(
+  0,
+  Number(process.env.SOCIALNEURON_MAX_CREDITS_PER_RUN || 0)
+);
+var MAX_ASSETS_PER_RUN = Math.max(
+  0,
+  Number(process.env.SOCIALNEURON_MAX_ASSETS_PER_RUN || 0)
+);
 var _globalCreditsUsed = 0;
 var _globalAssetsGenerated = 0;
 function getCreditsUsed() {
@@ -3009,9 +3095,22 @@ function checkCreditBudget(estimatedCost) {
   }
   const used = getCreditsUsed();
   if (used + estimatedCost > MAX_CREDITS_PER_RUN) {
+    const message = `Per-run credit cap reached \u2014 this is a local spend guard, not a server rate limit, so retrying will not help. The SOCIALNEURON_MAX_CREDITS_PER_RUN environment variable is set to ${MAX_CREDITS_PER_RUN} credits. This run has already spent ${used} credits and this call is estimated at ~${estimatedCost} more (${used} + ${estimatedCost} = ${used + estimatedCost} > ${MAX_CREDITS_PER_RUN}). To proceed, raise or unset SOCIALNEURON_MAX_CREDITS_PER_RUN.`;
     return {
       ok: false,
-      message: `Credit budget exceeded for this MCP run. Used=${used}, next~=${estimatedCost}, limit=${MAX_CREDITS_PER_RUN}.`
+      message,
+      error: toolError("billing_error", message, {
+        recover_with: [
+          "Raise SOCIALNEURON_MAX_CREDITS_PER_RUN to a higher credit ceiling.",
+          "Unset SOCIALNEURON_MAX_CREDITS_PER_RUN to remove the per-run cap."
+        ],
+        details: {
+          env_var: "SOCIALNEURON_MAX_CREDITS_PER_RUN",
+          credits_used_this_run: used,
+          estimated_call_cost: estimatedCost,
+          max_credits_per_run: MAX_CREDITS_PER_RUN
+        }
+      })
     };
   }
   return { ok: true };
@@ -3061,6 +3160,10 @@ var VIDEO_CREDIT_ESTIMATES = {
   "seedance-1.5-pro": 150,
   kling: 170
 };
+var AUDIO_NATIVE_DEFAULT_MODELS = /* @__PURE__ */ new Set([
+  "seedance-2-fast",
+  "seedance-2"
+]);
 var VIDEO_MODEL_ENUM = [
   "seedance-2-fast",
   "kling-3",
@@ -3089,7 +3192,7 @@ var IMAGE_CREDIT_ESTIMATES = {
 function registerContentTools(server) {
   server.tool(
     "generate_video",
-    "Start an async AI video generation job \u2014 returns a job_id immediately. Poll with check_status every 10-30s until complete. Base credit costs (reference config; dynamic models scale with duration/audio/resolution): seedance-2-fast 264 (8s, best quality/credit) \xB7 kling-3 100 (5s no-audio) \xB7 grok-imagine 30 (6s, cheapest) \xB7 veo3-fast 65 (8s) \xB7 kling-3-pro 135 (5s no-audio) \xB7 seedance-2 328 (8s 720p) \xB7 veo3-quality 1000 (8s) \xB7 wan-2.6 105 (5s) \xB7 gemini-omni-video 126 (multi-reference composites) \xB7 hailuo-02-standard 180 / seedance-1.5-pro 150 / kling 170 (legacy/budget fallbacks). Costs are estimated pre-check and reconciled post-response from the actual charge. audio adds ~1.5x on kling-3/kling-3-pro and ~2.65x on kling (enable_audio defaults to FALSE). Check get_credit_balance first for expensive generations.",
+    "Start an async AI video generation job \u2014 returns a job_id immediately. Poll with check_status every 10-30s until complete. Base credit costs (reference config; dynamic models scale with duration/audio/resolution): seedance-2-fast 264 (8s, best quality/credit) \xB7 kling-3 100 (5s no-audio) \xB7 grok-imagine 30 (6s, cheapest) \xB7 veo3-fast 65 (8s) \xB7 kling-3-pro 135 (5s no-audio) \xB7 seedance-2 328 (8s 720p) \xB7 veo3-quality 1000 (8s) \xB7 wan-2.6 105 (5s) \xB7 gemini-omni-video 126 (multi-reference composites) \xB7 hailuo-02-standard 180 / seedance-1.5-pro 150 / kling 170 (legacy/budget fallbacks). Costs are estimated pre-check and reconciled post-response from the actual charge. audio adds ~1.5x on kling-3/kling-3-pro and ~2.65x on kling; enable_audio defaults to FALSE EXCEPT the seedance-2 family (seedance-2-fast, seedance-2) where audio is ON by default and its cost is already included. Check get_credit_balance first for expensive generations.",
     {
       prompt: z2.string().max(2500).describe(
         'Video prompt \u2014 be specific about visual style, camera movement, lighting, and mood. Example: "Aerial drone shot of coastal cliffs at golden hour, slow dolly forward, cinematic 24fps, warm color grading." Vague prompts produce generic results.'
@@ -3104,7 +3207,7 @@ function registerContentTools(server) {
         "Video aspect ratio. 16:9 for YouTube/landscape, 9:16 for TikTok/Reels/Shorts, 1:1 for Instagram feed/square. Defaults to 16:9."
       ),
       enable_audio: z2.boolean().optional().describe(
-        "Enable native audio generation. DEFAULTS TO FALSE (cost control). Cost multiplier when true: kling 2.6 ~2.65x (17->45 cr/sec), kling-3 1.5x (20->30 cr/sec), kling-3-pro ~1.5x (27->40 cr/sec). seedance-2/-fast generate audio natively regardless. 5+ languages."
+        "Enable native audio generation. For most models this DEFAULTS TO FALSE (cost control). EXCEPTION: the seedance-2 family (seedance-2-fast, seedance-2) DEFAULTS TO TRUE \u2014 these generate audio natively and their credit cost already includes it, so audio is on unless you explicitly pass false. Cost multiplier when true on other models: kling 2.6 ~2.65x (17->45 cr/sec), kling-3 1.5x (20->30 cr/sec), kling-3-pro ~1.5x (27->40 cr/sec). 5+ languages."
       ),
       image_url: z2.string().optional().describe(
         "Start frame image URL for image-to-video (Kling 3.0 frame control)."
@@ -3140,10 +3243,7 @@ function registerContentTools(server) {
       const estimatedCost = VIDEO_CREDIT_ESTIMATES[model] ?? 120;
       const budgetCheck = checkCreditBudget(estimatedCost);
       if (!budgetCheck.ok) {
-        return {
-          content: [{ type: "text", text: budgetCheck.message }],
-          isError: true
-        };
+        return budgetCheck.error;
       }
       const rateLimit = checkRateLimit(
         "generation",
@@ -3167,9 +3267,12 @@ function registerContentTools(server) {
           model,
           duration: duration ?? 5,
           aspectRatio: aspect_ratio ?? "16:9",
-          // Default FALSE (2026-07-13): the old `?? true` default silently multiplied
-          // kling-family costs (2.65x on kling 2.6) for callers that never asked for audio.
-          enableAudio: enable_audio ?? false,
+          // Default FALSE for most models (2026-07-13): the old `?? true` default silently
+          // multiplied kling-family costs (2.65x on kling 2.6) for callers that never asked
+          // for audio. Exception (2026-07-17): the seedance-2 family bills audio into its base
+          // cost and generates it natively, so a false default there shipped silent no-audio
+          // mp4s — those models default TRUE when the caller omits enable_audio.
+          enableAudio: enable_audio ?? AUDIO_NATIVE_DEFAULT_MODELS.has(model),
           ...image_url && { imageUrl: image_url },
           ...end_frame_url && { endFrameUrl: end_frame_url },
           // The server reads projectId and enforces
@@ -3291,10 +3394,7 @@ function registerContentTools(server) {
       const estimatedCost = IMAGE_CREDIT_ESTIMATES[model] ?? 30;
       const budgetCheck = checkCreditBudget(estimatedCost);
       if (!budgetCheck.ok) {
-        return {
-          content: [{ type: "text", text: budgetCheck.message }],
-          isError: true
-        };
+        return budgetCheck.error;
       }
       const rateLimit = checkRateLimit(
         "generation",
@@ -3539,7 +3639,7 @@ function registerContentTools(server) {
         );
       }
       if (job.error_message) {
-        lines.push(`Error: ${job.error_message}`);
+        lines.push(`Error: ${redactSensitiveIdentifiers(job.error_message)}`);
       }
       const fallbackDisclosure = buildFallbackDisclosureLine(
         job.result_metadata
@@ -3693,10 +3793,7 @@ Return ONLY valid JSON in this exact format:
       const estimatedCost = 10;
       const budgetCheck = checkCreditBudget(estimatedCost);
       if (!budgetCheck.ok) {
-        return {
-          content: [{ type: "text", text: budgetCheck.message }],
-          isError: true
-        };
+        return budgetCheck.error;
       }
       const { data, error } = await callEdgeFunction(
         "social-neuron-ai",
@@ -3783,10 +3880,7 @@ Return ONLY valid JSON in this exact format:
       const estimatedCost = 15;
       const budgetCheck = checkCreditBudget(estimatedCost);
       if (!budgetCheck.ok) {
-        return {
-          content: [{ type: "text", text: budgetCheck.message }],
-          isError: true
-        };
+        return budgetCheck.error;
       }
       const rateLimit = checkRateLimit(
         "generation",
@@ -3949,10 +4043,7 @@ Return ONLY valid JSON in this exact format:
       const estimatedCost = 10 + slideCount * 2;
       const budgetCheck = checkCreditBudget(estimatedCost);
       if (!budgetCheck.ok) {
-        return {
-          content: [{ type: "text", text: budgetCheck.message }],
-          isError: true
-        };
+        return budgetCheck.error;
       }
       const userId = await getDefaultUserId();
       const rateLimit = checkRateLimit(
@@ -4061,51 +4152,6 @@ init_edge_function();
 import { z as z3 } from "zod";
 import { createHash } from "node:crypto";
 
-// src/lib/sanitize-error.ts
-var ERROR_PATTERNS = [
-  // Postgres / PostgREST
-  [/PGRST301|permission denied/i, "Access denied. Check your account permissions."],
-  [/42P01|does not exist/i, "Service temporarily unavailable. Please try again."],
-  [/23505|unique.*constraint|duplicate key/i, "A duplicate record already exists."],
-  [/23503|foreign key/i, "Referenced record not found."],
-  // Gemini / Google AI
-  [/google.*api.*key|googleapis\.com.*40[13]/i, "Content generation failed. Please try again."],
-  [
-    /RESOURCE_EXHAUSTED|quota.*exceeded|429.*google/i,
-    "AI service rate limit reached. Please wait and retry."
-  ],
-  [
-    /SAFETY|prompt.*blocked|content.*filter/i,
-    "Content was blocked by the AI safety filter. Try rephrasing."
-  ],
-  [/gemini.*error|generativelanguage/i, "Content generation failed. Please try again."],
-  // Kie.ai
-  [/kie\.ai|kieai|kie_api/i, "Media generation failed. Please try again."],
-  // Stripe
-  [/stripe.*api|sk_live_|sk_test_/i, "Payment processing error. Please try again."],
-  // Network / fetch
-  [
-    /ECONNREFUSED|ENOTFOUND|ETIMEDOUT|ECONNRESET/i,
-    "External service unavailable. Please try again."
-  ],
-  [/fetch failed|network error|abort.*timeout/i, "Network request failed. Please try again."],
-  [/CERT_|certificate|SSL|TLS/i, "Secure connection failed. Please try again."],
-  // Supabase Edge Function internals
-  [/FunctionsHttpError|non-2xx status/i, "Backend service error. Please try again."],
-  [/JWT|token.*expired|token.*invalid/i, "Authentication expired. Please re-authenticate."],
-  // Generic sensitive patterns (API keys, URLs with secrets)
-  [/[a-z0-9]{32,}.*key|Bearer [a-zA-Z0-9._-]+/i, "An internal error occurred. Please try again."]
-];
-function sanitizeError(error) {
-  const msg = error instanceof Error ? error.message : typeof error === "string" ? error : "Unknown error";
-  for (const [pattern, userMessage] of ERROR_PATTERNS) {
-    if (pattern.test(msg)) {
-      return userMessage;
-    }
-  }
-  return "An unexpected error occurred. Please try again.";
-}
-
 // src/lib/ssrf.ts
 import { promises as dnsPromises } from "node:dns";
 var BLOCKED_IP_PATTERNS = [
@@ -11887,6 +11933,14 @@ init_supabase();
 init_request_context();
 var KNOWLEDGE_BASE_URL = "https://socialneuron.com/for-developers";
 var KNOWLEDGE_SEARCH_LIMIT = 10;
+function isHostedTransport() {
+  return process.env.MCP_TRANSPORT === "http";
+}
+function isPubliclyDiscoverable(tool) {
+  if (tool.internal || tool.hiddenFromPublicCount) return false;
+  if (tool.localOnly && isHostedTransport()) return false;
+  return true;
+}
 var SearchOutputSchema = {
   results: z23.array(
     z23.object({
@@ -11959,7 +12013,8 @@ function toolKnowledgeDocument(tool) {
   if (tool.task_intent) lines.push(`Task intent: ${tool.task_intent}`);
   if (tool.use_when) lines.push(`Use when: ${tool.use_when}`);
   if (tool.avoid_when) lines.push(`Avoid when: ${tool.avoid_when}`);
-  if (tool.next_tools?.length) lines.push(`Common next tools: ${tool.next_tools.join(", ")}`);
+  if (tool.next_tools?.length)
+    lines.push(`Common next tools: ${tool.next_tools.join(", ")}`);
   return {
     id: `tool:${tool.name}`,
     title: `MCP tool: ${tool.name}`,
@@ -11976,9 +12031,7 @@ function toolKnowledgeDocument(tool) {
 function getKnowledgeDocuments() {
   return [
     ...STATIC_KNOWLEDGE_DOCUMENTS,
-    ...TOOL_CATALOG.filter((t) => !t.internal && !t.hiddenFromPublicCount).map(
-      toolKnowledgeDocument
-    )
+    ...TOOL_CATALOG.filter(isPubliclyDiscoverable).map(toolKnowledgeDocument)
   ];
 }
 function tokenize(input) {
@@ -12032,7 +12085,9 @@ function registerDiscoveryTools(server) {
       };
       return {
         structuredContent,
-        content: [{ type: "text", text: JSON.stringify(structuredContent) }]
+        content: [
+          { type: "text", text: JSON.stringify(structuredContent) }
+        ]
       };
     }
   );
@@ -12053,10 +12108,14 @@ function registerDiscoveryTools(server) {
       }
     },
     async ({ id }) => {
-      const doc = getKnowledgeDocuments().find((candidate) => candidate.id === id);
+      const doc = getKnowledgeDocuments().find(
+        (candidate) => candidate.id === id
+      );
       if (!doc) {
         return {
-          content: [{ type: "text", text: `Document not found: ${id}` }],
+          content: [
+            { type: "text", text: `Document not found: ${id}` }
+          ],
           isError: true
         };
       }
@@ -12069,7 +12128,9 @@ function registerDiscoveryTools(server) {
       };
       return {
         structuredContent,
-        content: [{ type: "text", text: JSON.stringify(structuredContent) }]
+        content: [
+          { type: "text", text: JSON.stringify(structuredContent) }
+        ]
       };
     }
   );
@@ -12078,7 +12139,9 @@ function registerDiscoveryTools(server) {
     'Search available tools by name, description, module, or scope. Use "name" detail (~50 tokens) for quick lookup, "summary" (~500 tokens) for descriptions, "full" for complete input schemas. Start here if unsure which tool to call \u2014 filter by module (e.g. "planning", "content", "analytics") to narrow results.',
     {
       query: z23.string().optional().describe("Search query to filter tools by name or description"),
-      module: z23.string().optional().describe('Filter by module name (e.g. "planning", "content", "analytics")'),
+      module: z23.string().optional().describe(
+        'Filter by module name (e.g. "planning", "content", "analytics")'
+      ),
       scope: z23.string().optional().describe('Filter by required scope (e.g. "mcp:read", "mcp:write")'),
       detail: z23.enum(["name", "summary", "full"]).default("summary").describe(
         'Detail level: "name" for just tool names, "summary" for names + descriptions, "full" for complete info including scope and module'
@@ -12095,14 +12158,18 @@ function registerDiscoveryTools(server) {
       if (query) {
         results = searchTools(query);
       }
-      results = results.filter((t) => !t.internal && !t.hiddenFromPublicCount);
+      results = results.filter(isPubliclyDiscoverable);
       if (module) {
         const moduleTools = getToolsByModule(module);
-        results = results.filter((t) => moduleTools.some((mt) => mt.name === t.name));
+        results = results.filter(
+          (t) => moduleTools.some((mt) => mt.name === t.name)
+        );
       }
       if (scope) {
         const scopeTools = getToolsByScope(scope);
-        results = results.filter((t) => scopeTools.some((st) => st.name === t.name));
+        results = results.filter(
+          (t) => scopeTools.some((st) => st.name === t.name)
+        );
       }
       if (available_only) {
         results = results.filter(isAvailable);
@@ -12140,7 +12207,12 @@ function registerDiscoveryTools(server) {
             text: JSON.stringify(
               {
                 toolCount: results.length,
-                ...hasKnownScopes ? { scopes: { available: currentScopes, unavailable_matches: unavailableCount } } : {},
+                ...hasKnownScopes ? {
+                  scopes: {
+                    available: currentScopes,
+                    unavailable_matches: unavailableCount
+                  }
+                } : {},
                 tools: output
               },
               null,
@@ -14621,25 +14693,39 @@ function registerCarouselTools(server) {
       ]).optional().describe("Carousel template. Default: hormozi-authority."),
       slide_count: z28.number().min(3).max(10).optional().describe("Number of slides (3-10). Default: 7."),
       aspect_ratio: z28.enum(["1:1", "4:5", "9:16"]).optional().describe("Aspect ratio for both carousel and images. Default: 1:1."),
-      style: z28.enum(["minimal", "bold", "professional", "playful", "hormozi"]).optional().describe("Visual style. Default: hormozi for hormozi-authority template."),
+      style: z28.enum(["minimal", "bold", "professional", "playful", "hormozi"]).optional().describe(
+        "Visual style. Default: hormozi for hormozi-authority template."
+      ),
       image_style_suffix: z28.string().max(500).optional().describe(
         'Style suffix appended to every image prompt for visual consistency across slides. Example: "dark moody lighting, cinematic, 35mm film grain".'
       ),
       hook: z28.string().max(300).optional().describe(
         "Explicit hook/opener for slide 1. Overrides any hook derived from topic. Keep under 15 words for strongest scroll-stop."
       ),
-      hook_family: z28.enum(["curiosity", "authority", "pain_point", "contrarian", "data_driven"]).optional().describe(
+      hook_family: z28.enum([
+        "curiosity",
+        "authority",
+        "pain_point",
+        "contrarian",
+        "data_driven"
+      ]).optional().describe(
         "Hook family tag. Recorded on the carousel so downstream analytics can attribute engagement to hook pattern."
       ),
-      cta_text: z28.string().max(200).optional().describe("Explicit CTA copy for the final slide. If omitted, derived from topic."),
-      cta_url: z28.string().url().optional().describe("URL promoted on the CTA slide. Defaults to the project landing page."),
+      cta_text: z28.string().max(200).optional().describe(
+        "Explicit CTA copy for the final slide. If omitted, derived from topic."
+      ),
+      cta_url: z28.string().url().optional().describe(
+        "URL promoted on the CTA slide. Defaults to the project landing page."
+      ),
       tone: z28.string().max(200).optional().describe(
         'Voice/tone override. Composes with the brand profile voice when present. Example: "educational, confident, not arrogant".'
       ),
       constraints: z28.string().max(500).optional().describe(
         'Content constraints applied at generation time. Example: "No fabricated statistics. Sentence case only. No ALL CAPS."'
       ),
-      platform: z28.enum(["linkedin", "instagram", "tiktok", "x"]).optional().describe("Target platform. Affects tone conventions and slide-count guardrails."),
+      platform: z28.enum(["linkedin", "instagram", "tiktok", "x"]).optional().describe(
+        "Target platform. Affects tone conventions and slide-count guardrails."
+      ),
       brand_id: z28.string().optional().describe(
         "Brand/project ID to pull visual context from (colors, logo, mood). Falls back to project_id, then default project."
       ),
@@ -14671,7 +14757,9 @@ function registerCarouselTools(server) {
       const slideCount = slide_count ?? 7;
       const ratio = aspect_ratio ?? "1:1";
       let brandContext = null;
-      const brandProjectId = brand_id || project_id || await getDefaultProjectId();
+      const defaultProjectId = await getDefaultProjectId();
+      const brandProjectId = brand_id || project_id || defaultProjectId;
+      const resolvedProjectId = project_id || defaultProjectId;
       if (brandProjectId) {
         brandContext = await fetchBrandVisualContext(brandProjectId);
       }
@@ -14680,10 +14768,7 @@ function registerCarouselTools(server) {
       const totalEstimatedCost = carouselTextCost + slideCount * perImageCost;
       const budgetCheck = checkCreditBudget(totalEstimatedCost);
       if (!budgetCheck.ok) {
-        return {
-          content: [{ type: "text", text: budgetCheck.message }],
-          isError: true
-        };
+        return budgetCheck.error;
       }
       const assetBudget = checkAssetBudget(slideCount);
       if (!assetBudget.ok) {
@@ -14693,7 +14778,10 @@ function registerCarouselTools(server) {
         };
       }
       const userId = await getDefaultUserId();
-      const rateLimit = checkRateLimit("generation", `create_carousel:${userId}`);
+      const rateLimit = checkRateLimit(
+        "generation",
+        `create_carousel:${userId}`
+      );
       if (!rateLimit.allowed) {
         return {
           content: [
@@ -14713,7 +14801,7 @@ function registerCarouselTools(server) {
           slideCount,
           aspectRatio: ratio,
           style: resolvedStyle,
-          projectId: project_id,
+          projectId: resolvedProjectId,
           hook,
           hookFamily: hook_family,
           ctaText: cta_text,
@@ -14727,7 +14815,12 @@ function registerCarouselTools(server) {
       if (carouselError || !carouselData?.carousel) {
         const errMsg = carouselError ?? "No carousel data returned";
         return {
-          content: [{ type: "text", text: `Carousel text generation failed: ${errMsg}` }],
+          content: [
+            {
+              type: "text",
+              text: `Carousel text generation failed: ${errMsg}`
+            }
+          ],
           isError: true
         };
       }
@@ -14756,7 +14849,8 @@ function registerCarouselTools(server) {
               {
                 prompt: imagePrompt,
                 model: image_model,
-                aspectRatio: ratio
+                aspectRatio: ratio,
+                ...resolvedProjectId && { projectId: resolvedProjectId }
               },
               { timeoutMs: 3e4 }
             );
@@ -14813,14 +14907,19 @@ function registerCarouselTools(server) {
               type: "text",
               text: JSON.stringify(
                 {
-                  _meta: { version: MCP_VERSION, timestamp: (/* @__PURE__ */ new Date()).toISOString() },
+                  _meta: {
+                    version: MCP_VERSION,
+                    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                  },
                   data: {
                     carouselId: carousel.id,
                     templateId,
                     style: resolvedStyle,
                     slideCount: carousel.slides.length,
                     slides: carousel.slides.map((s) => {
-                      const job = imageJobs.find((j) => j.slideNumber === s.slideNumber);
+                      const job = imageJobs.find(
+                        (j) => j.slideNumber === s.slideNumber
+                      );
                       return {
                         ...s,
                         imageJobId: job?.jobId ?? null,
@@ -14847,9 +14946,17 @@ function registerCarouselTools(server) {
                     credits: {
                       textGeneration: textCredits,
                       imagesEstimated: successfulJobs.length * perImageCost,
-                      imagesCharged: imageJobs.reduce((sum, job) => sum + (job.creditsCharged ?? 0), 0),
-                      imagesRefunded: imageJobs.reduce((sum, job) => sum + (job.creditsRefunded ?? 0), 0),
-                      billingUnknownSlides: imageJobs.filter((job) => job.billingStatus === "unknown").length,
+                      imagesCharged: imageJobs.reduce(
+                        (sum, job) => sum + (job.creditsCharged ?? 0),
+                        0
+                      ),
+                      imagesRefunded: imageJobs.reduce(
+                        (sum, job) => sum + (job.creditsRefunded ?? 0),
+                        0
+                      ),
+                      billingUnknownSlides: imageJobs.filter(
+                        (job) => job.billingStatus === "unknown"
+                      ).length,
                       totalEstimated: textCredits + successfulJobs.length * perImageCost
                     }
                   }
@@ -14877,7 +14984,9 @@ function registerCarouselTools(server) {
       for (const slide of carousel.slides) {
         const job = imageJobs.find((j) => j.slideNumber === slide.slideNumber);
         const status = job?.jobId ? `image: ${job.jobId}` : `image FAILED: ${job?.error}`;
-        lines.push(`  ${slide.slideNumber}. ${slide.headline || "(no headline)"} [${status}]`);
+        lines.push(
+          `  ${slide.slideNumber}. ${slide.headline || "(no headline)"} [${status}]`
+        );
       }
       if (failedJobs.length > 0) {
         lines.push("");
@@ -14888,7 +14997,9 @@ function registerCarouselTools(server) {
       const jobIdList = successfulJobs.map((j) => j.jobId).join(", ");
       lines.push("");
       lines.push("Next steps:");
-      lines.push(`  1. Poll each job: check_status with job_id for each of: ${jobIdList}`);
+      lines.push(
+        `  1. Poll each job: check_status with job_id for each of: ${jobIdList}`
+      );
       lines.push(
         "  2. When all complete: schedule_post with job_ids=[...] and media_type=CAROUSEL_ALBUM"
       );