aimakeall-mcp 0.9.1 → 0.11.0

package/lib/cloud-tools.mjs

@@ -9,8 +9,8 @@ import { AimakeallApiError } from "./api-client.mjs";
 import { extractCompanionAudio } from "./companion-client.mjs";
 import {
   ALLOWED_IMAGE_EXTS,
-  ALLOWED_VIDEO_EXTS,
   assertAllowedInputFile,
+  assertAllowedVideoUpload,
   encodedDataUrlBytes,
   fileToDataUrl,
   fileToImagePayload,
@@ -20,11 +20,15 @@ import {
   savePayloadHandle,
   SERVER_JSON_BODY_LIMIT_BYTES,
 } from "./media-store.mjs";
-import { mp3DurationSec } from "./mp3-duration.mjs";
+import { audioDurationSecFromFile } from "./audio-duration.mjs";
 import { canonicalYoutubeWatchUrl } from "./payload-guard.mjs";
 import { createUsageEventId } from "./usage-event.mjs";
+import { fetchGenerationJob, GENERATION_JOB_PATH, submitGenerationJob } from "./generation-jobs.mjs";
 import { loudnessDbfsFromWav, silenceRatioFromWav } from "./wav-dsp.mjs";
 import { trimWavToSeconds } from "./wav-trim.mjs";
+import { registerComposerTools } from "./composer-tools.mjs";
+import { productionFields, composerTextStyle, composerOverlay } from "./production-schemas.mjs";
+import { saveProductionContext, readProductionContext, durationReview, reviewProductionPayload } from "./production-context.mjs";
 
 // 여러 파일을 base64 로 싣는 요청의 인코딩 크기 합이 서버 JSON 상한을 넘지 않게 사전 검사.
 // 서버가 전체 업로드를 받은 뒤 413 을 내는 것을 막고 행동 가능한 한국어 안내를 준다.
@@ -74,18 +78,6 @@ function isSafePublicImageUrl(rawUrl) {
   }
 }
 
-// 실측 mp3 길이(초) — 파싱 실패 시에만 CBR-128 근사로 폴백.
-function audioDurationSecFromFile(filePath) {
-  try {
-    const real = mp3DurationSec(readFileSync(filePath));
-    if (real > 0) return real;
-  } catch {
-    // fall through
-  }
-  const size = statSync(filePath).size;
-  return Math.round((size * 8) / (128 * 1000) * 10) / 10;
-}
-
 // aimakeall.com 클라우드 툴 — PAT 필요. 기획·씬 생성·TTS·SUNO·스티치·퍼블리시.
 // 렌더는 여기 없다: 스티치가 만든 타임라인 페이로드를 render_start(로컬 컴패니언)로 넘긴다.
 // 대용량 산출물(오디오·매니페스트·base64 이미지)은 모델 컨텍스트로 돌려주지 않고
@@ -191,6 +183,65 @@ function trimAnalysis(analysis) {
 }
 
 export function registerCloudTools(server, config, api) {
+  registerComposerTools(server, config, api);
+  async function completedGenerationResult(job, includePreview) {
+    const payload = job.result || {};
+    const resultBody = { generationJobId: job.id, status: job.status, kind: job.kind,
+      model: payload.model, taskId: payload.taskId, providerTasks: job.providerTasks };
+    if (job.kind === "image") {
+      resultBody.imageUrl = payload.imageUrl || undefined;
+      let inlineImage = null;
+      if (!payload.imageUrl && payload.imageDataUrl) {
+        const match = String(payload.imageDataUrl).match(/^data:([^;]+);base64,(.+)$/s);
+        if (match) {
+          const ext = match[1].includes("png") ? "png" : "jpg";
+          resultBody.savedPath = saveMediaBuffer(config.stateDir, `scene-image.${ext}`, Buffer.from(match[2], "base64")).filePath;
+          if (includePreview && ALLOWED_INLINE_IMAGE_MIME.has(match[1].toLowerCase()) && match[2].length <= MAX_INLINE_IMAGE_BYTES * 4 / 3) {
+            inlineImage = { base64: match[2], mimeType: match[1].toLowerCase() };
+          }
+        }
+      } else if (includePreview && payload.imageUrl) {
+        inlineImage = await downloadImageAsBase64(payload.imageUrl);
+      }
+      resultBody.qc = inlineImage ? "동봉 이미지를 확인한 뒤 다음 단계로 진행하세요."
+        : "verify_scene_image로 검증하세요. imageUrl이 없으면 savedPath를 imagePath로 넘기세요.";
+      return inlineImage ? jsonWithImagesResult(resultBody, [inlineImage]) : jsonResult(resultBody);
+    }
+    Object.assign(resultBody, { videoUrl: payload.videoUrl, durationLabel: payload.durationLabel, resolvedRouteLabel: payload.resolvedRouteLabel });
+    let frames = [];
+    if (includePreview && payload.videoUrl) {
+      try {
+        const response = await api.request("/api/tracker/video/frames", {
+          method: "POST", body: { count: 3, maxWidth: 480, videoUrl: payload.videoUrl }, timeoutMs: 20_000,
+        });
+        if (response?.ok && Array.isArray(response.frames)) frames = response.frames;
+      } catch { /* A preview failure must not hide the generated video. */ }
+    }
+    resultBody.qc = frames.length ? "동봉 프레임을 확인한 뒤 stitch_timeline으로 진행하세요." : "verify_scene_video로 영상 품질을 확인하세요.";
+    return frames.length ? jsonWithImagesResult(resultBody, frames) : jsonResult(resultBody);
+  }
+
+  server.tool(
+    "get_generation_job",
+    "generate_scene_image/video가 반환한 generationJobId의 상태·결과를 조회합니다. running이면 잠시 뒤 다시 조회하고, completed의 imageUrl/videoUrl로 다음 단계를 진행하세요. MCP를 재시작해도 같은 ID로 회수할 수 있습니다.",
+    { generationJobId: z.string(), includePreview: z.boolean().optional().describe("이미지/대표 프레임 미리보기 포함. 미지정 시 생성 요청의 returnImage/returnFrames 설정 유지") },
+    wrapCloudHandler(config, async ({ generationJobId, includePreview }) => {
+      const job = await fetchGenerationJob(api, generationJobId);
+      if (job.status === "completed") return completedGenerationResult(job, includePreview ?? job.includePreview ?? true);
+      return textResult(JSON.stringify({ generationJobId: job.id, kind: job.kind, status: job.status,
+        providerTasks: job.providerTasks, error: job.error,
+        guidance: job.status === "running" ? "생성 중입니다. 5~10초 후 이 ID를 다시 조회하세요. 새로 생성하지 마세요." : "비용 원장과 providerTasks를 먼저 확인하세요. 실패·중단 작업을 자동 재생성하지 마세요." }, null, 2),
+      { isError: job.status === "failed" || job.status === "interrupted" });
+    }),
+  );
+
+  server.tool(
+    "list_generation_jobs",
+    "내 계정의 최근 이미지·영상 생성 작업 ID와 상태를 조회합니다. 연결이 끊기거나 MCP를 재시작했을 때 결과를 복구하고 중복 생성을 피하는 데 사용하세요.",
+    {},
+    wrapCloudHandler(config, async () => jsonResult(await api.request(GENERATION_JOB_PATH, { timeoutMs: 30_000 }))),
+  );
+
   server.tool(
     "get_usage",
     "내 플랜과 기능별 렌더 쿼터 현황을 조회합니다. 생성 작업 전에 확인하세요.",
@@ -247,6 +298,8 @@ export function registerCloudTools(server, config, api) {
     "plan_shorts_video",
     "쇼츠 영상 기획(시나리오·씬별 이미지 프롬프트·내레이션)을 생성합니다. topic 또는 copy 중 하나는 필수. 결과 scenes의 imagePrompt는 generate_scene_image로, skill은 씬 영상 프롬프트의 videoStylePreset으로, emphasisKeywords는 stitch_timeline의 emphasisKeywords로 이어집니다(하단자막 단어 강조).",
     {
+      productionProfile: productionFields.productionProfile,
+      durationTargetSec: z.number().positive().max(180).optional().describe("사용자가 요청한 목표 길이(예:40). 음성 길이로 덮어쓰지 않습니다."),
       topic: z.string().optional().describe("영상 주제"),
       copy: z.string().optional().describe("핵심 카피/대사"),
       categoryId: z.enum(["community-shorts", "viral-shorts", "insight"]).optional().describe("기본 community-shorts. insight=명언(통찰) 쇼츠"),
@@ -275,13 +328,15 @@ export function registerCloudTools(server, config, api) {
         forbidden: z.string().optional().describe("금지 변형 (기본: different face, different hairstyle)"),
       })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
     },
-    wrapCloudHandler(config, async ({ topic = "", copy = "", categoryId = "community-shorts", targetCustomer = "", tone = "자동 추천", sceneCount = 0, characters = [], channelFingerprint = null }) => {
+    wrapCloudHandler(config, async ({ topic = "", copy = "", categoryId = "community-shorts", targetCustomer = "", tone = "자동 추천", sceneCount = 0, characters = [], channelFingerprint = null, productionProfile, durationTargetSec }) => {
       if (!String(topic).trim() && !String(copy).trim()) {
         return textResult("topic 또는 copy 중 하나는 입력해야 합니다.", { isError: true });
       }
       const payload = await api.request("/api/tracker/shorts-video/plan", {
         body: {
           categoryId,
+          productionProfile,
+          durationTargetSec,
           channelFingerprint,
           copy,
           operationId: createUsageEventId("shorts-plan"),
@@ -296,7 +351,16 @@ export function registerCloudTools(server, config, api) {
         method: "POST",
         timeoutMs: 240_000,
       });
+      const productionPath = saveProductionContext(config.stateDir, {
+        topic, productionProfile: payload?.productionProfile, narrationScript: payload?.narrationScript,
+        narrationSource: payload?.narrationSource, tagline: payload?.tagline, emphasisKeywords: payload?.emphasisKeywords || [],
+        channelFingerprint, scenes: trimPlanScenes(payload?.scenes),
+      });
       return jsonResult({
+        productionPath,
+        productionProfile: payload?.productionProfile,
+        narrationSource: payload?.narrationSource,
+        next: "productionPath를 recommend_voice → tts_narration_with_captions → stitch_timeline에 전달하세요. 대본을 뉴스체로 바꾸지 말고, list_composer_presets/search_composer_assets로 편집 소재도 선택하세요.",
         charactersUsed: Array.isArray(payload?.charactersUsed) ? payload.charactersUsed : undefined,
         ctaText: payload?.ctaText,
         emphasisKeywords: Array.isArray(payload?.emphasisKeywords) ? payload.emphasisKeywords : [],
@@ -446,8 +510,9 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "generate_scene_image",
-    "씬 이미지를 생성합니다 (기획 결과의 imagePrompt 사용). 반환된 imageUrl을 씬 영상 생성의 입력으로 쓰세요. 인물·제품 일관성은 이 참조 방식이 권장 경로입니다: 첫 씬(또는 캐릭터 시트/제품 사진)의 이미지를 referenceImageUrls·referenceImagePaths로 모든 씬에 앵커로 전달하세요. 결과에 이미지 블록이 동봉됩니다 — 반드시 직접 보고 QC(캐릭터 앵커·왜곡·지시 이행) 후 불합격 시 재생성하세요. 이미지를 볼 수 없으면 verify_scene_image 사용.",
+    "씬 이미지 생성 작업을 접수하고 즉시 generationJobId를 반환합니다. get_generation_job으로 completed 결과의 imageUrl을 받은 뒤 씬 영상 입력에 쓰세요. 첫 씬/캐릭터/제품 이미지를 referenceImageUrls·referenceImagePaths로 전달하면 일관성 유지에 도움이 됩니다. 완료 이미지는 직접 확인하거나 verify_scene_image로 검증하세요.",
     {
+      requestId: z.string().optional().describe("접수 응답 유실 후 같은 작업을 재확인할 때 기존 generationJobId를 지정합니다. 동일 ID·입력은 중복 생성하지 않습니다."),
       prompt: z.string().describe("이미지 프롬프트 (plan 결과의 imagePrompt)"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
       model: z.enum(["gpt-image-2-beta", "gemini-3.1-flash-image-preview", "doubao-seedream-5.0-lite", "google-flow-nano-banana-pro", "kie-grok-imagine-image"]).optional().describe("이미지 모델, 기본 gpt-image-2-beta"),
@@ -457,7 +522,7 @@ export function registerCloudTools(server, config, api) {
       referenceImageUrls: z.array(z.string()).max(6).optional().describe("참조 이미지 URL (씬1 앵커 등)"),
       referenceImagePaths: z.array(z.string()).max(4).optional().describe("참조 이미지 로컬 경로 (제품 사진 등)"),
     },
-    wrapCloudHandler(config, async ({ prompt, aspectRatio = "9:16", model = "gpt-image-2-beta", resolution = "1K", referenceImageUrls = [], referenceImagePaths = [], returnImage = true, identityLock = "" }) => {
+    wrapCloudHandler(config, async ({ requestId, prompt, aspectRatio = "9:16", model = "gpt-image-2-beta", resolution = "1K", referenceImageUrls = [], referenceImagePaths = [], returnImage = true, identityLock = "" }) => {
       // identity_lock 리터럴 부착 — 이미 포함돼 있으면 재부착하지 않는다(멱등: 프롬프트 캐시 보존).
       const lock = String(identityLock || "").trim();
       if (lock && !prompt.includes(lock)) prompt = `${prompt.trim()}, ${lock}`;
@@ -471,8 +536,9 @@ export function registerCloudTools(server, config, api) {
         ...referenceImageUrls.map((url, index) => ({ name: `ref-${index + 1}`, previewUrl: url })),
       ].slice(0, 6);
 
-      const payload = await api.request("/api/tracker/gemini/storyboard-scene-image", {
-        body: {
+      return jsonResult(await submitGenerationJob(api, {
+        kind: "image", includePreview: returnImage, requestId,
+        input: {
           aspectRatio,
           model,
           prompt,
@@ -481,38 +547,7 @@ export function registerCloudTools(server, config, api) {
           resolution,
           webSearchEnabled: true,
         },
-        method: "POST",
-        timeoutMs: 240_000,
-      });
-
-      let imageUrl = String(payload?.imageUrl || "");
-      let savedPath = "";
-      let inlineImage = null;
-      if (!imageUrl && payload?.imageDataUrl) {
-        // URL 없이 base64만 온 경우 — 컨텍스트로 돌려주지 않고 파일로 저장.
-        const match = String(payload.imageDataUrl).match(/^data:([^;]+);base64,(.+)$/s);
-        if (match) {
-          const ext = match[1].includes("png") ? "png" : "jpg";
-          const saved = saveMediaBuffer(config.stateDir, `scene-image.${ext}`, Buffer.from(match[2], "base64"));
-          savedPath = saved.filePath;
-          const inlineMime = String(match[1]).toLowerCase();
-          if (returnImage && ALLOWED_INLINE_IMAGE_MIME.has(inlineMime) && match[2].length <= MAX_INLINE_IMAGE_BYTES * 4 / 3) {
-            inlineImage = { base64: match[2], mimeType: inlineMime };
-          }
-        }
-      } else if (imageUrl && returnImage) {
-        inlineImage = await downloadImageAsBase64(imageUrl);
-      }
-      const resultBody = {
-        imageUrl: imageUrl || undefined,
-        model: payload?.model,
-        qc: inlineImage
-          ? "동봉된 이미지를 직접 확인하세요: 캐릭터 앵커 일치·손가락/글자 왜곡·프롬프트 이행. 불합격이면 사유를 프롬프트에 반영해 재생성하세요. 이미지를 볼 수 없는 클라이언트라면 verify_scene_image 를 호출하세요."
-          : "이미지를 동봉하지 못했습니다 — verify_scene_image 로 서버측 검증을 수행하세요 (imageUrl 이 없으면 savedPath 를 imagePath 로 넘기세요).",
-        savedPath: savedPath || undefined,
-        taskId: payload?.taskId,
-      };
-      return inlineImage ? jsonWithImagesResult(resultBody, [inlineImage]) : jsonResult(resultBody);
+      }));
     }),
   );
 
@@ -559,8 +594,9 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "generate_scene_video",
-    "씬 영상을 생성합니다 (동기 호출, 최대 ~30분 — MCP 클라이언트의 툴 타임아웃(MCP_TIMEOUT)을 그 이상으로 늘려두세요. 타임아웃되면 이미 과금된 결과를 회수할 수 없으니 주의). 반환된 videoUrl을 stitch_timeline의 sceneVideos에 넣으세요. 결과에 대표 프레임 3장이 동봉됩니다 — 반드시 직접 보고 QC 후 불합격 시 재생성하세요. 볼 수 없으면 verify_scene_video 사용.",
+    "씬 영상 생성 작업을 접수하고 즉시 generationJobId를 반환합니다. get_generation_job으로 completed가 될 때까지 조회한 뒤 videoUrl을 stitch_timeline에 넣으세요. 접수만 된 상태에서 새로 생성하지 마세요.",
     {
+      requestId: z.string().optional().describe("접수 응답 유실 후 동일 입력을 재접수할 때 기존 generationJobId를 지정합니다."),
       prompt: z.string().describe("영상 프롬프트 (generate_scene_video_prompt의 videoPrompt)"),
       sceneImageUrl: z.string().optional().describe("씬 이미지 URL (i2v 입력)"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
@@ -569,9 +605,10 @@ export function registerCloudTools(server, config, api) {
       quality: z.string().optional().describe("기본 720p"),
       returnFrames: z.boolean().optional().describe("기본 true — 결과 영상의 대표 프레임 3장을 직접 보고 QC 할 수 있게 이미지 블록으로 반환"),
     },
-    wrapCloudHandler(config, async ({ prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p", returnFrames = true }) => {
-      const payload = await api.request("/api/tracker/gemini/storyboard-scene-video", {
-        body: {
+    wrapCloudHandler(config, async ({ requestId, prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p", returnFrames = true }) => {
+      return jsonResult(await submitGenerationJob(api, {
+        kind: "video", includePreview: returnFrames, requestId,
+        input: {
           aspectRatio,
           durationLabel: `${Math.max(1, Math.ceil(durationSec))}s`,
           generationPlan: {
@@ -587,35 +624,7 @@ export function registerCloudTools(server, config, api) {
           selectedVideoModel: { id: modelId },
           videoGenerationSettings: { inputMode: sceneImageUrl ? "image" : "text", quality },
         },
-        method: "POST",
-        // 서버 최악 경로(KIE 900s + Evolink 폴백 3회×900s)를 넘겨 잡아 조기 abort 로 과금-미회수를 방지.
-        timeoutMs: 1_800_000,
-      });
-      // 대표 프레임 동봉(1층 QC) — 실패는 조용히 넘기고 verify_scene_video 안내로 대체.
-      let frames = [];
-      if (returnFrames && payload?.videoUrl) {
-        try {
-          const frameResp = await api.request("/api/tracker/video/frames", {
-            body: { count: 3, maxWidth: 480, videoUrl: payload.videoUrl },
-            method: "POST",
-            timeoutMs: 60_000, // 과금 완료된 결과를 오래 붙들지 않기 — 실패해도 verify 폴백 안내
-          });
-          if (frameResp?.ok && Array.isArray(frameResp?.frames)) frames = frameResp.frames;
-        } catch {
-          frames = [];
-        }
-      }
-      const resultBody = {
-        durationLabel: payload?.durationLabel,
-        model: payload?.model,
-        qc: frames.length
-          ? "동봉된 대표 프레임 3장을 직접 확인하세요: 캐릭터 붕괴·모션 파탄·왜곡. 불합격이면 프롬프트를 교정해 재생성하세요. 프레임을 볼 수 없는 클라이언트라면 verify_scene_video 를 호출하세요."
-          : "프레임을 동봉하지 못했습니다 — verify_scene_video 로 서버측 검증을 수행하세요.",
-        resolvedRouteLabel: payload?.resolvedRouteLabel,
-        taskId: payload?.taskId,
-        videoUrl: payload?.videoUrl,
-      };
-      return frames.length ? jsonWithImagesResult(resultBody, frames) : jsonResult(resultBody);
+      }));
     }),
   );
 
@@ -623,14 +632,26 @@ export function registerCloudTools(server, config, api) {
     "tts_narration",
     "내레이션 TTS를 합성해 이 PC에 mp3로 저장하고 파일 경로를 반환합니다. stitch_timeline의 ttsAudioPath로 쓰세요. 사용자가 보이스를 직접 지정하지 않았다면 먼저 recommend_voice로 주제·샘플 영상에 맞는 보이스를 자동 선정해 voice에 넣으세요.",
     {
-      text: z.string().describe("내레이션 텍스트"),
+      ...productionFields,
+      text: z.string().optional().describe("생략 시 productionPath의 기획 대본"),
       provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
       voice: z.string().optional().describe("보이스 이름(라벨)"),
       speed: z.number().optional().describe("기본 1"),
+      stability: z.number().min(0).max(1).optional(), style: z.number().min(0).max(1).optional(),
+      modelId: z.string().optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, provider = "typecast", voice = "", speed = 1 }) => {
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, stability, style, modelId, similarityBoost, speakerBoost }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      productionProfile = context?.productionProfile || productionProfile;
+      text ??= context?.narrationScript;
+      provider ||= context?.voice?.provider || (productionProfile ? "elevenlabs" : "typecast");
+      if (!voice && context?.voice?.provider && context.voice.provider !== provider) return textResult("보이스 공급자가 다릅니다. 선택한 provider용 voice를 다시 선정하세요.", { isError: true });
+      voice ||= context?.voice?.voiceId || "";
+      if (!text?.trim()) return textResult("대본(text/productionPath)이 필요합니다.", { isError: true });
+      if (productionProfile?.deliveryStyle === "casual-social" && !voice) return textResult("먼저 recommend_voice에 productionPath를 전달해 커뮤니티형 보이스를 선정하세요.", { isError: true });
       const body = provider === "typecast"
         ? {
+            productionProfile,
             breath: 0.3,
             costEventId: createUsageEventId("mcp-tts-typecast"),
             emotion: "neutral",
@@ -645,15 +666,16 @@ export function registerCloudTools(server, config, api) {
             volume: 100,
           }
         : {
+            productionProfile,
             costEventId: createUsageEventId("mcp-tts-elevenlabs"),
             fileName: "mcp-narration",
             languageCode: "ko",
-            modelId: "",
-            similarityBoost: 0.8,
-            speakerBoost: true,
+            modelId,
+            similarityBoost,
+            speakerBoost,
             speed,
-            stability: 0.45,
-            style: 0.35,
+            stability,
+            style,
             text,
             voice,
           };
@@ -663,10 +685,13 @@ export function registerCloudTools(server, config, api) {
         timeoutMs: 120_000,
       });
       const saved = saveMediaBuffer(config.stateDir, "narration.mp3", result.buffer, { contentType: result.contentType });
+      const durationSec = audioDurationSecFromFile(saved.filePath);
       return jsonResult({
+        productionPath: saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text, tts: { filePath: saved.filePath, durationSec, voiceId: voice } }),
+        durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec),
         bytes: saved.bytes,
         // 실측 mp3 길이 — stitch_timeline 의 audioDurationSec 로 그대로 쓰면 타임라인이 정확하다.
-        durationSec: audioDurationSecFromFile(saved.filePath),
+        durationSec,
         filePath: saved.filePath,
         voiceName: decodeHeaderValue(
           result.headers.get("x-typecast-voice-name") || result.headers.get("x-elevenlabs-voice-name") || "",
@@ -745,6 +770,12 @@ export function registerCloudTools(server, config, api) {
     "stitch_timeline",
     "씬 영상들과 오디오를 서버에서 타임라인 매니페스트로 합칩니다. 결과는 파일 핸들(payloadPath)로 반환되며, 이를 render_start에 넘기면 이 PC에서 mp4가 렌더됩니다. 서버는 렌더하지 않습니다. 하단자막 강조: emphasisKeywords 를 주면 자막 라인 안의 해당 단어만 다른 색/크기로 강조되고, subtitleLines[].style 로 라인별 디자인도 바꿀 수 있습니다.",
     {
+      ...productionFields,
+      titleStylePresetId: z.string().optional(), subtitleStylePresetId: z.string().optional(),
+      titleStyle: composerTextStyle.optional(), subtitleStyle: composerTextStyle.optional(),
+      titleSegments: z.array(z.object({ text: z.string(), color: z.string().optional() })).max(20).optional(),
+      overlays: z.array(composerOverlay).max(40).optional().describe("검색한 소재를 장면에 맞는 시간/위치에 배치. 배경 이미지에 그려진 문양은 편집 소재 사용으로 세지 않습니다."),
+      decorationRationale: z.string().max(500).optional().describe("소재를 생략한 이유. 피해자 희화화·권리 위험이면 밈 대신 중립적 아이콘을 검토하세요."),
       sceneVideos: z.array(z.object({
         durationSec: z.number(),
         idx: z.number().int(),
@@ -764,17 +795,8 @@ export function registerCloudTools(server, config, api) {
         endSec: z.number(),
         startSec: z.number(),
         text: z.string(),
-        style: z.object({
-          fontSize: z.number().optional(),
-          fontWeight: z.enum(["bold", "normal"]).optional(),
-          strokeColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식").optional(),
-          strokeWidth: z.number().optional(),
-          textBackgroundColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식").optional(),
-          textBackgroundEnabled: z.boolean().optional(),
-          textBackgroundOpacity: z.number().optional(),
-          textColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식").optional(),
-          textEffectVariant: z.string().optional(),
-        }).optional().describe("이 라인만의 디자인 오버라이드 (내용에 따라 라인별 디자인을 달리할 때)"),
+        stylePresetId: z.string().optional(),
+        style: composerTextStyle.optional(),
       })).optional().describe("자막 타이밍 (쇼츠 하단자막) — tts_narration_with_captions의 subtitleLines를 그대로 사용"),
       emphasisKeywords: z.array(z.string()).max(12).optional().describe("강조 단어 목록 — 자막 라인 안에서 해당 단어만 다른 색/크기로 렌더 (plan_shorts_video의 emphasisKeywords 를 그대로 전달)"),
       emphasisColor: z.string().regex(/^#[0-9a-fA-F]{6}$/, "#RRGGBB 형식").optional().describe("강조 색 #RRGGBB (기본 #facc15 노랑)"),
@@ -786,7 +808,15 @@ export function registerCloudTools(server, config, api) {
       }).passthrough().optional().describe("measure_channel_spec 이 반환한 fingerprint — 자막 세로 위치·BGM 유무를 참고 채널에 맞춥니다"),
       transitionMode: z.enum(["fade", "none"]).optional().describe("기본 none(하드컷). fade 는 씬이 맞대기로 붙는 배치에서 컷마다 검은 딥을 만든다 — 명시 요청 시에만 쓸 것"),
     },
-    wrapCloudHandler(config, async ({ sceneVideos, featureKey = "commerceVideo", projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines = [], emphasisKeywords = [], emphasisColor = "", emphasisSizeScale = 0, transitionMode = "none", channelFingerprint = null }) => {
+    wrapCloudHandler(config, async ({ sceneVideos, featureKey, projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines, emphasisKeywords, emphasisColor = "", emphasisSizeScale = 0, transitionMode = "none", channelFingerprint = null, productionPath, productionProfile, titleStylePresetId, subtitleStylePresetId, titleStyle, subtitleStyle, titleSegments, overlays, decorationRationale }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      productionProfile = context?.productionProfile || productionProfile;
+      ttsAudioPath ||= context?.tts?.filePath || "";
+      titleText ||= context?.tagline || "";
+      subtitleLines ??= context?.tts?.subtitleLines || [];
+      emphasisKeywords ??= context?.emphasisKeywords || [];
+      featureKey ||= productionProfile?.categoryId?.endsWith("shorts") ? "shortsVideo" : "commerceVideo";
+      channelFingerprint ||= context?.channelFingerprint;
       // 오디오 확장자 검증 + 합산 크기 예산(서버 413 사전 차단).
       if (ttsAudioPath) assertAllowedInputFile(ttsAudioPath, new Set([".mp3", ".wav"]), { kind: "TTS 오디오" });
       if (bgmAudioPath) assertAllowedInputFile(bgmAudioPath, new Set([".mp3", ".wav"]), { kind: "BGM 오디오" });
@@ -796,9 +826,10 @@ export function registerCloudTools(server, config, api) {
         ? audioDurationSec
         : (ttsAudioPath ? audioDurationSecFromFile(ttsAudioPath) : 0);
       const body = {
+        productionProfile, titleStylePresetId, subtitleStylePresetId, titleStyle, subtitleStyle, titleSegments, overlays,
         aspectRatio,
         audioDurationSec: resolvedAudioDurationSec,
-        bgmAudioUrl: bgmAudioPath ? fileToDataUrl(bgmAudioPath, { mimeType: "audio/mpeg" }) : "",
+        bgmAudioUrl: bgmAudioPath ? fileToDataUrl(bgmAudioPath) : "",
         bgmVolume,
         featureKey,
         muteVideoAudio,
@@ -816,7 +847,7 @@ export function registerCloudTools(server, config, api) {
         subtitleLines,
         titleText,
         transitionMode,
-        ttsAudioUrl: ttsAudioPath ? fileToDataUrl(ttsAudioPath, { mimeType: "audio/mpeg" }) : "",
+        ttsAudioUrl: ttsAudioPath ? fileToDataUrl(ttsAudioPath) : "",
       };
       const response = await api.request("/api/tracker/commerce-video/stitch", {
         body,
@@ -826,11 +857,15 @@ export function registerCloudTools(server, config, api) {
       if (!response?.ok || !response?.payload) {
         return textResult(`스티치 실패: ${response?.error || "매니페스트가 비어 있습니다."}`, { isError: true });
       }
+      if (context || productionProfile) response.payload.productionContext = { ...context, productionProfile, decorationRationale };
+      const qualityReview = reviewProductionPayload(response.payload);
       const handle = savePayloadHandle(config.stateDir, response.payload, "stitch");
       return jsonResult({
         assetCount: Array.isArray(response.payload.assets) ? response.payload.assets.length : 0,
         clipCount: Array.isArray(response.payload.studio?.clips) ? response.payload.studio.clips.length : 0,
-        next: "render_start에 payloadPath를 넘겨 이 PC에서 렌더하세요.",
+        next: qualityReview.pass ? "qualityReview 경고를 검토한 뒤 render_start에 payloadPath를 전달하세요. 최종 영상 프레임과 음성도 검토해야 합니다." : "qualityReview.errors의 길이·소재 선택 검토 문제를 먼저 해결하세요. render_start는 제작 규격 불일치를 차단합니다.",
+        qualityReview,
+        compositionReport: response.payload.compositionReport,
         payloadPath: handle.filePath,
         projectTitle: response.payload.projectTitle,
         sizeBytes: handle.bytes,
@@ -895,8 +930,7 @@ export function registerCloudTools(server, config, api) {
       notifySubscribers: z.boolean().optional().describe("기본 true"),
     },
     wrapCloudHandler(config, async ({ videoPath, title, description = "", tags = [], categoryId = "", visibility = "private", madeForKids = false, notifySubscribers = true }) => {
-      assertAllowedInputFile(videoPath, ALLOWED_VIDEO_EXTS, { kind: "영상 파일" });
-      const stats = statSync(videoPath);
+      const stats = assertAllowedVideoUpload(videoPath);
       // 메타데이터가 쿼리스트링을 타므로 한국어 설명의 퍼센트 인코딩 팽창으로 헤더 상한(16KB)을
       // 넘지 않도록 보수적으로 제한한다.
       const safeTitle = title.slice(0, 100);
@@ -1338,13 +1372,28 @@ export function registerCloudTools(server, config, api) {
     "tts_narration_with_captions",
     "ElevenLabs TTS를 char-level 타이밍과 함께 합성해 mp3 파일 + 시간 동기 자막 라인(subtitleLines)을 만듭니다. 쇼츠 하단자막이 필요하면 tts_narration 대신 이걸 쓰고, 결과 subtitleLines·durationSec·filePath를 stitch_timeline에 그대로 넘기세요 (웹 쇼츠 스튜디오와 동일한 정렬 방식). 사용자가 보이스를 지정하지 않았다면 먼저 recommend_voice(provider=elevenlabs)로 자동 선정하세요.",
     {
-      text: z.string().describe("내레이션 텍스트"),
+      ...productionFields,
+      text: z.string().optional().describe("생략 시 제작 핸들의 기획 대본 그대로 합성. 사실·인용을 바꾸거나 뉴스체로 재작성하지 마세요."),
       voice: z.string().optional().describe("보이스 이름 또는 ID (생략 시 기본 보이스)"),
       speed: z.number().optional().describe("기본 1 (0.7~1.2)"),
+      modelId: z.string().optional(), stability: z.number().min(0).max(1).optional(),
+      style: z.number().min(0).max(1).optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, voice = "", speed = 1 }) => {
+    wrapCloudHandler(config, async ({ text, voice = "", speed, productionPath, productionProfile, modelId, stability, style, similarityBoost, speakerBoost }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      productionProfile = context?.productionProfile || productionProfile;
+      text ??= context?.narrationScript;
+      if (!voice && context?.voice?.provider && context.voice.provider !== "elevenlabs") {
+        return textResult("이 제작 핸들의 보이스는 ElevenLabs용이 아닙니다. recommend_voice(provider=elevenlabs)로 다시 선정하거나 ElevenLabs voice를 명시하세요.", { isError: true });
+      }
+      voice ||= context?.voice?.voiceId || "";
+      if (!text?.trim()) return textResult("text 또는 기획 대본이 있는 productionPath가 필요합니다.", { isError: true });
+      if (productionProfile?.deliveryStyle === "casual-social" && !voice) {
+        return textResult("커뮤니티형 음성을 위해 먼저 recommend_voice에 productionPath를 전달하고, 반환된 productionPath 또는 보이스 ID를 사용하세요.", { isError: true });
+      }
       const payload = await api.request("/api/tracker/tts/elevenlabs-with-timestamps", {
         body: {
+          productionProfile, modelId, stability, style, similarityBoost, speakerBoost,
           costEventId: createUsageEventId("mcp-tts-elevenlabs-ts"),
           languageCode: "ko",
           speed,
@@ -1370,7 +1419,16 @@ export function registerCloudTools(server, config, api) {
       const durationSec = Array.isArray(charEnds) && charEnds.length
         ? Math.round(Number(charEnds[charEnds.length - 1]) * 10) / 10
         : audioDurationSecFromFile(saved.filePath);
+      const updatedProductionPath = saveProductionContext(config.stateDir, {
+        ...context, productionProfile, narrationScript: text,
+        tts: { durationSec, filePath: saved.filePath, subtitleLines, voiceId: payload?.voiceId || voice, deliverySettings: payload?.deliverySettings },
+      });
       return jsonResult({
+        productionPath: updatedProductionPath,
+        productionProfile,
+        deliverySettings: payload?.deliverySettings,
+        durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec),
+        next: "이 productionPath를 stitch_timeline으로 전달하세요. 목표보다 짧으면 자동 재과금 없이 먼저 대본/말속도와 재합성 비용을 검토하세요. 자막은 실제 발화에 맞추고 강조는 편집 스타일로 적용하세요.",
         durationSec,
         filePath: saved.filePath,
         lineCount: subtitleLines.length,
@@ -1405,13 +1463,19 @@ export function registerCloudTools(server, config, api) {
     "recommend_voice",
     "주제·대본과 사용자가 샘플로 지정한 영상(유튜브)에 어울리는 TTS 보이스를 LLM이 자동 선정합니다. 사용자가 보이스를 직접 지정하지 않았다면 tts_narration/tts_narration_with_captions 전에 이 도구를 호출해 recommendations[0].voiceId를 voice로 쓰세요. 샘플 영상이 있으면 컴패니언 앱이 화자 음성을 추출·분석해 가장 비슷한 보이스를 우선합니다(컴패니언 미실행 시 주제 기반으로만 추천).",
     {
+      ...productionFields,
       topic: z.string().optional().describe("영상 주제·타깃 시청층 (예: 시니어 건강 정보, 커머스 쇼츠)"),
       scriptExcerpt: z.string().optional().describe("대본 앞부분 발췌 (선택)"),
       sampleVideoUrl: z.string().optional().describe("사용자가 샘플로 지정한 유튜브 URL 또는 11자 영상 ID"),
       provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
       sampleVoiceHints: z.string().optional().describe("사용자가 말한 보이스 요구 (예: 차분한 중년 남성)"),
     },
-    wrapCloudHandler(config, async ({ topic = "", scriptExcerpt = "", sampleVideoUrl = "", provider = "typecast", sampleVoiceHints = "" }) => {
+    wrapCloudHandler(config, async ({ topic = "", scriptExcerpt = "", sampleVideoUrl = "", provider, sampleVoiceHints = "", productionPath, productionProfile }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      productionProfile = context?.productionProfile || productionProfile;
+      provider ||= productionProfile ? "elevenlabs" : "typecast";
+      topic ||= context?.topic || "";
+      scriptExcerpt ||= context?.narrationScript?.slice(0, 2000) || "";
       const notes = [];
       let sampleAudioBase64 = "";
       const rawSample = String(sampleVideoUrl || "").trim();
@@ -1440,7 +1504,7 @@ export function registerCloudTools(server, config, api) {
         return textResult("topic, scriptExcerpt, sampleVoiceHints, sampleVideoUrl 중 하나는 필요합니다.", { isError: true });
       }
       const payload = await api.request("/api/tracker/tts/recommend-voice", {
-        body: { provider, sampleAudioBase64, sampleVoiceHints, scriptExcerpt, topic },
+        body: { provider, sampleAudioBase64, sampleVoiceHints, scriptExcerpt, topic, productionProfile },
         method: "POST",
         timeoutMs: 180_000,
       });
@@ -1451,6 +1515,8 @@ export function registerCloudTools(server, config, api) {
         );
       }
       return jsonResult({
+        productionPath: context || productionProfile ? saveProductionContext(config.stateDir, { ...context, productionProfile, voice: { ...payload?.recommendations?.[0], provider } }) : undefined,
+        productionProfile,
         next: "recommendations[0].voiceId를 tts_narration 또는 tts_narration_with_captions의 voice로 사용하세요.",
         notes: [...notes, ...(Array.isArray(payload?.notes) ? payload.notes : [])],
         provider: payload?.provider || provider,

package/lib/companion-client.mjs

@@ -1,4 +1,5 @@
-import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { closeSync, createWriteStream, mkdirSync, openSync, renameSync, rmSync, statSync } from "node:fs";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
@@ -66,6 +67,7 @@ export async function triageCompanion(companionUrl) {
     detail: `moviepy ${moviepy.payload.moviepy.version} (${moviepy.payload.moviepy.label})`,
     state: "ready",
     version: String(health.payload?.version || ""),
+    capabilities: moviepy.payload?.capabilities || {},
   };
 }
 
@@ -157,20 +159,31 @@ export function parseContentDispositionFilename(headerValue) {
  * 성공 시 컴패니언이 파일을 삭제(1회성)하므로 저장 성공 후에만 소비된 것으로 본다.
  * 반환: { filePath, bytes } 또는 { error, status }
  */
-// 사용된 파일명이 이미 있으면 -2, -3 … 을 붙여 기존 출력을 덮어쓰지 않는다.
-function uniqueOutputPath(dir, fileName) {
+// wx 로 최종 경로를 먼저 예약한다. 존재 검사만 하면 여러 프로세스가 같은
+// 이름과 .part 파일을 골라 서로의 다운로드를 덮어쓴다.
+function reserveOutputPath(dir, fileName) {
   const ext = path.extname(fileName);
   const base = fileName.slice(0, fileName.length - ext.length);
   let candidate = path.join(dir, fileName);
   let counter = 2;
-  while (existsSync(candidate)) {
-    candidate = path.join(dir, `${base}-${counter}${ext}`);
-    counter += 1;
+  while (true) {
+    try {
+      closeSync(openSync(candidate, "wx", 0o600));
+      return candidate;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      candidate = path.join(dir, `${base}-${counter}${ext}`);
+      counter += 1;
+    }
   }
-  return candidate;
 }
 
 export async function downloadRenderOutput(companionUrl, jobId, outputDir, { suggestedName = "" } = {}) {
+  try {
+    mkdirSync(outputDir, { recursive: true });
+  } catch (error) {
+    return { error: `출력 폴더를 준비하지 못했습니다: ${String(error?.message || error)}`, status: 0 };
+  }
   let response;
   try {
     response = await fetch(
@@ -193,17 +206,20 @@ export async function downloadRenderOutput(companionUrl, jobId, outputDir, { sug
   const headerName = parseContentDispositionFilename(response.headers.get("content-disposition"));
   let fileName = sanitizeOutputFilename(suggestedName || headerName, `render-${jobId}.mp4`);
   if (!/\.[A-Za-z0-9]{1,5}$/u.test(fileName)) fileName += ".mp4"; // 확장자 없으면 mp4 보정
-  mkdirSync(outputDir, { recursive: true });
-  const finalPath = uniqueOutputPath(outputDir, fileName);
-  const partPath = `${finalPath}.part`;
-
+  let finalPath = "";
+  let partPath = "";
   try {
-    await pipeline(Readable.fromWeb(response.body), createWriteStream(partPath, { mode: 0o600 }));
+    finalPath = reserveOutputPath(outputDir, fileName);
+    partPath = `${finalPath}.${randomUUID()}.part`;
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(partPath, { flags: "wx", mode: 0o600 }));
+    const bytes = statSync(partPath).size;
     renameSync(partPath, finalPath);
+    return { bytes, filePath: finalPath };
   } catch (error) {
     // 중단 시 부분 파일 정리 — 잡은 다운로드 실패로 남아 재시도 가능(네트워크 abort 시 서버가 복구).
-    try { rmSync(partPath, { force: true }); } catch { /* ignore */ }
+    await response.body?.cancel().catch(() => {});
+    if (partPath) { try { rmSync(partPath, { force: true }); } catch { /* ignore */ } }
+    if (finalPath) { try { rmSync(finalPath, { force: true }); } catch { /* ignore */ } }
     return { error: `출력 저장 중 오류: ${String(error?.message || error)} — render_status로 상태 확인 후 다시 시도하세요.`, status: 0 };
   }
-  return { bytes: statSync(finalPath).size, filePath: finalPath };
 }