aimakeall-mcp 0.1.0

package/lib/cloud-tools.mjs

@@ -0,0 +1,644 @@
+
+import { createReadStream, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+
+import { z } from "zod";
+
+import { AimakeallApiError } from "./api-client.mjs";
+import {
+  ALLOWED_IMAGE_EXTS,
+  ALLOWED_VIDEO_EXTS,
+  assertAllowedInputFile,
+  encodedDataUrlBytes,
+  fileToDataUrl,
+  fileToImagePayload,
+  saveMediaBuffer,
+  savePayloadHandle,
+  SERVER_JSON_BODY_LIMIT_BYTES,
+} from "./media-store.mjs";
+import { mp3DurationSec } from "./mp3-duration.mjs";
+import { createUsageEventId } from "./usage-event.mjs";
+
+// 여러 파일을 base64 로 싣는 요청의 인코딩 크기 합이 서버 JSON 상한을 넘지 않게 사전 검사.
+// 서버가 전체 업로드를 받은 뒤 413 을 내는 것을 막고 행동 가능한 한국어 안내를 준다.
+const BODY_BUDGET_BYTES = SERVER_JSON_BODY_LIMIT_BYTES - 512 * 1024; // 바디의 나머지 필드 여유
+
+function assertEncodedBudget(filePaths, { context = "요청" } = {}) {
+  let total = 0;
+  for (const filePath of filePaths.filter(Boolean)) {
+    total += encodedDataUrlBytes(statSync(filePath).size);
+  }
+  if (total > BODY_BUDGET_BYTES) {
+    throw new Error(
+      `${context}의 총 크기가 서버 상한(약 ${Math.round(BODY_BUDGET_BYTES / 1024 / 1024)}MB)을 초과합니다. 더 짧거나 낮은 비트레이트의 오디오/작은 이미지를 사용하세요.`,
+    );
+  }
+}
+
+// 서버가 헤더에 encodeURIComponent 로 실어 보낸 값(한국어 보이스명 등)을 복원.
+function decodeHeaderValue(value) {
+  try {
+    return decodeURIComponent(String(value || ""));
+  } catch {
+    return String(value || "");
+  }
+}
+
+// 실측 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 이미지)은 모델 컨텍스트로 돌려주지 않고
+// 파일 경로 핸들로 주고받는다.
+
+function textResult(text, { isError = false } = {}) {
+  return { content: [{ text, type: "text" }], ...(isError ? { isError: true } : {}) };
+}
+
+function jsonResult(value) {
+  return textResult(JSON.stringify(value, null, 2));
+}
+
+const NO_PAT_GUIDE = "AIMAKEALL_PAT가 설정되지 않았습니다. aimakeall.com → API 키 설정 → MCP 토큰에서 발급한 뒤 MCP 설정의 env에 넣어주세요.";
+
+function describeLocalError(error) {
+  const code = String(error?.code || "");
+  const filePath = String(error?.path || "");
+  if (code === "ENOENT") return `파일을 찾을 수 없습니다: ${filePath}`;
+  if (code === "EACCES") return `파일을 읽을 수 없습니다(권한): ${filePath}`;
+  return String(error?.message || error);
+}
+
+export function wrapCloudHandler(config, handler) {
+  return async (args) => {
+    if (!config.pat) return textResult(NO_PAT_GUIDE, { isError: true });
+    try {
+      return await handler(args);
+    } catch (error) {
+      if (error instanceof AimakeallApiError) {
+        const retry = error.retryAfterSeconds ? ` (${error.retryAfterSeconds}초 후 재시도)` : "";
+        return textResult(`${error.message}${retry}`, { isError: true });
+      }
+      return textResult(`요청 실패: ${describeLocalError(error)}`, { isError: true });
+    }
+  };
+}
+
+// 씬 응답에서 모델 컨텍스트에 유용한 필드만 추린다 (base64/내부 필드 제외).
+function trimPlanScenes(scenes) {
+  return (Array.isArray(scenes) ? scenes : []).map((scene) => ({
+    durationSec: scene?.durationSec,
+    idx: scene?.idx,
+    imagePrompt: scene?.imagePrompt,
+    label: scene?.label,
+    ratio: scene?.ratio,
+    sceneNarration: scene?.sceneNarration,
+    scenePurpose: scene?.scenePurpose,
+  }));
+}
+
+// commerce 분석 응답에서 기획에 유용한 필드만 (usage/원문 등 컨텍스트 낭비 필드 제외).
+function trimAnalysis(analysis) {
+  if (!analysis || typeof analysis !== "object") return analysis;
+  const { colorPalette, materialFeel, productCategory, style, subjectType, visualCues } = analysis;
+  return { colorPalette, materialFeel, productCategory, style, subjectType, visualCues };
+}
+
+export function registerCloudTools(server, config, api) {
+  server.tool(
+    "get_usage",
+    "내 플랜과 기능별 렌더 쿼터 현황을 조회합니다. 생성 작업 전에 확인하세요.",
+    {},
+    wrapCloudHandler(config, async () => jsonResult(await api.request("/api/tracker/usage"))),
+  );
+
+  server.tool(
+    "plan_shorts_video",
+    "쇼츠 영상 기획(시나리오·씬별 이미지 프롬프트·내레이션)을 생성합니다. topic 또는 copy 중 하나는 필수. 결과 scenes의 imagePrompt는 generate_scene_image로, skill은 씬 영상 프롬프트의 videoStylePreset으로 이어집니다.",
+    {
+      topic: z.string().optional().describe("영상 주제"),
+      copy: z.string().optional().describe("핵심 카피/대사"),
+      categoryId: z.enum(["community-shorts", "viral-shorts"]).optional().describe("기본 community-shorts"),
+      targetCustomer: z.string().optional(),
+      tone: z.string().optional().describe("기본 '자동 추천'"),
+      sceneCount: z.number().int().min(1).max(10).optional().describe("기본 3"),
+    },
+    wrapCloudHandler(config, async ({ topic = "", copy = "", categoryId = "community-shorts", targetCustomer = "", tone = "자동 추천", sceneCount = 3 }) => {
+      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,
+          copy,
+          operationId: createUsageEventId("shorts-plan"),
+          sceneCount,
+          selectedCharacters: [],
+          skillOverride: null,
+          targetCustomer,
+          tone,
+          topic,
+        },
+        method: "POST",
+        timeoutMs: 240_000,
+      });
+      return jsonResult({
+        ctaText: payload?.ctaText,
+        narrationScript: payload?.narrationScript,
+        ok: payload?.ok,
+        scenes: trimPlanScenes(payload?.scenes),
+        skill: payload?.skill,
+        tagline: payload?.tagline,
+      });
+    }),
+  );
+
+  server.tool(
+    "plan_commerce_video",
+    "제품 홍보 영상 기획을 생성합니다. 제품 사진 파일 경로가 최소 1장 필요합니다 (이 PC의 로컬 경로).",
+    {
+      productName: z.string().describe("제품명 (필수)"),
+      productImagePaths: z.array(z.string()).min(1).describe("제품/자산 사진의 로컬 파일 경로 (1장 이상)"),
+      modelImagePath: z.string().optional().describe("모델 사진 로컬 경로 (선택)"),
+      description: z.string().optional(),
+      targetCustomer: z.string().optional(),
+      tone: z.string().optional().describe("기본 '자동 추천'"),
+      categoryId: z.string().optional().describe("기본 ecommerce"),
+      sceneCount: z.number().int().min(1).max(12).optional().describe("기본 6"),
+    },
+    wrapCloudHandler(config, async ({ productName, productImagePaths, modelImagePath = "", description = "", targetCustomer = "", tone = "자동 추천", categoryId = "ecommerce", sceneCount = 6 }) => {
+      // 확장자 검증(임의 파일 업로드 차단) + 합산 크기 예산(서버 413 사전 차단).
+      for (const filePath of productImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "이미지" });
+      if (modelImagePath) assertAllowedInputFile(modelImagePath, ALLOWED_IMAGE_EXTS, { kind: "모델 이미지" });
+      assertEncodedBudget([...productImagePaths, modelImagePath], { context: "제품/모델 사진" });
+
+      const payload = await api.request("/api/tracker/commerce-video/plan", {
+        body: {
+          categoryId,
+          description,
+          modelImage: modelImagePath ? fileToImagePayload(modelImagePath) : null,
+          operationId: createUsageEventId("commerce-plan"),
+          productImages: productImagePaths.map((filePath) => fileToImagePayload(filePath)),
+          productName,
+          sceneCount,
+          selectedCharacters: [],
+          skillOverride: null,
+          targetCustomer,
+          tone,
+        },
+        method: "POST",
+        timeoutMs: 300_000,
+      });
+      return jsonResult({
+        analysis: trimAnalysis(payload?.analysis),
+        ctaText: payload?.ctaText,
+        ok: payload?.ok,
+        scenes: trimPlanScenes(payload?.scenes),
+        skill: payload?.skill,
+        tagline: payload?.tagline,
+      });
+    }),
+  );
+
+  server.tool(
+    "generate_scene_image",
+    "씬 이미지를 생성합니다 (기획 결과의 imagePrompt 사용). 반환된 imageUrl을 씬 영상 생성의 입력으로 쓰세요. 캐릭터/앞씬 일관성이 필요하면 앞 씬의 imageUrl을 referenceImageUrls로 전달하세요.",
+    {
+      prompt: z.string().describe("이미지 프롬프트 (plan 결과의 imagePrompt)"),
+      aspectRatio: z.string().optional().describe("기본 9:16"),
+      model: z.string().optional().describe("기본 gpt-image-2-beta (대안: gemini-3.1-flash-image-preview, doubao-seedream-5.0-lite)"),
+      resolution: z.string().optional().describe("기본 1K"),
+      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 = [] }) => {
+      for (const filePath of referenceImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "참조 이미지" });
+      assertEncodedBudget(referenceImagePaths, { context: "참조 이미지" });
+      const referenceImages = [
+        ...referenceImagePaths.map((filePath) => ({
+          name: path.basename(filePath),
+          previewUrl: fileToDataUrl(filePath, { allowedExts: ALLOWED_IMAGE_EXTS, kind: "참조 이미지" }),
+        })),
+        ...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: {
+          aspectRatio,
+          model,
+          prompt,
+          referenceImages,
+          referenceSearchEnabled: true,
+          resolution,
+          webSearchEnabled: true,
+        },
+        method: "POST",
+        timeoutMs: 240_000,
+      });
+
+      let imageUrl = String(payload?.imageUrl || "");
+      let savedPath = "";
+      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;
+        }
+      }
+      return jsonResult({
+        imageUrl: imageUrl || undefined,
+        model: payload?.model,
+        savedPath: savedPath || undefined,
+        taskId: payload?.taskId,
+      });
+    }),
+  );
+
+  server.tool(
+    "generate_scene_video_prompt",
+    "씬 이미지 기반 영상 프롬프트를 생성합니다. 결과 videoPrompt를 generate_scene_video의 prompt로 넘기세요.",
+    {
+      imagePrompt: z.string().describe("씬의 이미지 프롬프트"),
+      sceneImageUrl: z.string().optional().describe("generate_scene_image가 반환한 imageUrl"),
+      sceneScript: z.string().optional().describe("씬 대사/설명 (plan 결과의 label)"),
+      sceneTitle: z.string().optional(),
+      aspectRatio: z.string().optional().describe("기본 9:16"),
+      durationSec: z.number().optional().describe("기본 8"),
+      videoStylePreset: z.string().optional().describe("plan 결과의 skill"),
+      kind: z.enum(["shorts_scene", "commerce_video_scene", "music_video_scene"]).optional(),
+      modelId: z.string().optional().describe("대상 영상 모델 (기본 kie-grok-imagine — generate_scene_video와 동일하게 맞추세요)"),
+    },
+    wrapCloudHandler(config, async ({ imagePrompt, sceneImageUrl = "", sceneScript = "", sceneTitle = "", aspectRatio = "9:16", durationSec = 8, videoStylePreset = "", kind = "shorts_scene", modelId = "kie-grok-imagine" }) => {
+      const payload = await api.request("/api/tracker/gemini/storyboard-video-prompt", {
+        body: {
+          aspectRatio,
+          durationLabel: `${Math.max(1, Math.round(durationSec))}s`,
+          generationPlan: {
+            hasSceneImage: Boolean(sceneImageUrl),
+            kind,
+            requestedInputMode: "image",
+            resolvedInputMode: "image",
+            resolvedRouteLabel: "i2v",
+            videoStylePreset: videoStylePreset || null,
+          },
+          imagePrompt,
+          referenceImage: sceneImageUrl ? { name: "scene-image", previewUrl: sceneImageUrl } : null,
+          sceneScript,
+          sceneTitle,
+          // 프롬프트가 대상 모델에 맞춰 작성되도록 — 미지정 시 서버가 Seedance 로 오해.
+          selectedVideoModel: { id: modelId },
+        },
+        method: "POST",
+        timeoutMs: 180_000,
+      });
+      return jsonResult({ model: payload?.model, videoPrompt: payload?.videoPrompt });
+    }),
+  );
+
+  server.tool(
+    "generate_scene_video",
+    "씬 영상을 생성합니다 (동기 호출, 최대 ~30분 — MCP 클라이언트의 툴 타임아웃(MCP_TIMEOUT)을 그 이상으로 늘려두세요. 타임아웃되면 이미 과금된 결과를 회수할 수 없으니 주의). 반환된 videoUrl을 stitch_timeline의 sceneVideos에 넣으세요.",
+    {
+      prompt: z.string().describe("영상 프롬프트 (generate_scene_video_prompt의 videoPrompt)"),
+      sceneImageUrl: z.string().optional().describe("씬 이미지 URL (i2v 입력)"),
+      aspectRatio: z.string().optional().describe("기본 9:16"),
+      durationSec: z.number().optional().describe("기본 8 (모델 상한으로 클램프됨)"),
+      modelId: z.string().optional().describe("기본 kie-grok-imagine (대안: seedance-2.0, kling-3.0)"),
+      quality: z.string().optional().describe("기본 720p"),
+    },
+    wrapCloudHandler(config, async ({ prompt, sceneImageUrl = "", aspectRatio = "9:16", durationSec = 8, modelId = "kie-grok-imagine", quality = "720p" }) => {
+      const payload = await api.request("/api/tracker/gemini/storyboard-scene-video", {
+        body: {
+          aspectRatio,
+          durationLabel: `${Math.max(1, Math.ceil(durationSec))}s`,
+          generationPlan: {
+            hasSceneImage: Boolean(sceneImageUrl),
+            kind: "shorts_scene",
+            requestedInputMode: sceneImageUrl ? "image" : "text",
+            resolvedInputMode: sceneImageUrl ? "image" : "text",
+            resolvedRouteLabel: sceneImageUrl ? "i2v" : "t2v",
+            videoStylePreset: null,
+          },
+          prompt,
+          sceneImage: sceneImageUrl ? { name: "scene-image", previewUrl: sceneImageUrl } : null,
+          selectedVideoModel: { id: modelId },
+          videoGenerationSettings: { inputMode: sceneImageUrl ? "image" : "text", quality },
+        },
+        method: "POST",
+        // 서버 최악 경로(KIE 900s + Evolink 폴백 3회×900s)를 넘겨 잡아 조기 abort 로 과금-미회수를 방지.
+        timeoutMs: 1_800_000,
+      });
+      return jsonResult({
+        durationLabel: payload?.durationLabel,
+        model: payload?.model,
+        resolvedRouteLabel: payload?.resolvedRouteLabel,
+        taskId: payload?.taskId,
+        videoUrl: payload?.videoUrl,
+      });
+    }),
+  );
+
+  server.tool(
+    "tts_narration",
+    "내레이션 TTS를 합성해 이 PC에 mp3로 저장하고 파일 경로를 반환합니다. stitch_timeline의 ttsAudioPath로 쓰세요.",
+    {
+      text: z.string().describe("내레이션 텍스트"),
+      provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
+      voice: z.string().optional().describe("보이스 이름(라벨)"),
+      speed: z.number().optional().describe("기본 1"),
+    },
+    wrapCloudHandler(config, async ({ text, provider = "typecast", voice = "", speed = 1 }) => {
+      const body = provider === "typecast"
+        ? {
+            breath: 0.3,
+            costEventId: createUsageEventId("mcp-tts-typecast"),
+            emotion: "neutral",
+            fileName: "mcp-narration",
+            language: "kor",
+            modelId: "",
+            pitch: 0,
+            smartEmotion: true,
+            speed,
+            text,
+            voice,
+            volume: 100,
+          }
+        : {
+            costEventId: createUsageEventId("mcp-tts-elevenlabs"),
+            fileName: "mcp-narration",
+            languageCode: "ko",
+            modelId: "",
+            similarityBoost: 0.8,
+            speakerBoost: true,
+            speed,
+            stability: 0.45,
+            style: 0.35,
+            text,
+            voice,
+          };
+      const result = await api.requestBinary(`/api/tracker/tts/${provider}`, {
+        body,
+        method: "POST",
+        timeoutMs: 120_000,
+      });
+      const saved = saveMediaBuffer(config.stateDir, "narration.mp3", result.buffer, { contentType: result.contentType });
+      return jsonResult({
+        bytes: saved.bytes,
+        // 실측 mp3 길이 — stitch_timeline 의 audioDurationSec 로 그대로 쓰면 타임라인이 정확하다.
+        durationSec: audioDurationSecFromFile(saved.filePath),
+        filePath: saved.filePath,
+        voiceName: decodeHeaderValue(
+          result.headers.get("x-typecast-voice-name") || result.headers.get("x-elevenlabs-voice-name") || "",
+        ),
+      });
+    }),
+  );
+
+  server.tool(
+    "suno_music_start",
+    "SUNO 음악 생성을 시작합니다 (taskId 반환 → suno_music_status로 폴링).",
+    {
+      title: z.string().describe("곡 제목 (필수)"),
+      stylePrompt: z.string().describe("스타일 프롬프트 (필수)"),
+      lyrics: z.string().optional().describe("가사 (instrumental=false면 필수)"),
+      instrumental: z.boolean().optional().describe("반주만 (BGM용). 기본 false"),
+      model: z.string().optional().describe("기본 V5.5"),
+    },
+    wrapCloudHandler(config, async ({ title, stylePrompt, lyrics = "", instrumental = false, model = "V5.5" }) => {
+      if (!instrumental && !String(lyrics).trim()) {
+        return textResult("instrumental=false면 lyrics가 필요합니다.", { isError: true });
+      }
+      const payload = await api.request("/api/tracker/suno/music", {
+        body: {
+          audioWeight: 0.5,
+          instrumental,
+          lyrics,
+          model,
+          negativeTags: "",
+          personaId: "",
+          personaModel: "",
+          stylePrompt,
+          styleWeight: 0.7,
+          title,
+          vocalGender: "",
+          weirdnessConstraint: 0.3,
+        },
+        method: "POST",
+        timeoutMs: 60_000,
+      });
+      return jsonResult({ model: payload?.model, taskId: payload?.id });
+    }),
+  );
+
+  server.tool(
+    "suno_music_status",
+    "SUNO 음악 태스크 상태를 조회합니다 (12초 간격 폴링 권장). 완료되면 tracks[].audioUrl이 옵니다.",
+    { taskId: z.string() },
+    wrapCloudHandler(config, async ({ taskId }) => {
+      const payload = await api.request(`/api/tracker/suno/tasks/${encodeURIComponent(taskId)}`, { timeoutMs: 30_000 });
+      return jsonResult({
+        errorMessage: payload?.errorMessage,
+        progress: payload?.progress,
+        status: payload?.status,
+        tracks: (Array.isArray(payload?.tracks) ? payload.tracks : []).map((track) => ({
+          audioUrl: track?.audioUrl,
+          durationSec: track?.durationSec,
+          title: track?.title,
+        })),
+      });
+    }),
+  );
+
+  server.tool(
+    "suno_music_download",
+    "완성된 SUNO 곡을 이 PC에 mp3로 저장하고 경로를 반환합니다. stitch_timeline의 bgmAudioPath로 쓰세요.",
+    { audioUrl: z.string().describe("suno_music_status의 tracks[].audioUrl") },
+    wrapCloudHandler(config, async ({ audioUrl }) => {
+      const result = await api.requestBinary(`/api/tracker/suno/download?url=${encodeURIComponent(audioUrl)}`, { timeoutMs: 300_000 });
+      const saved = saveMediaBuffer(config.stateDir, "suno-track.mp3", result.buffer, { contentType: result.contentType });
+      return jsonResult({ bytes: saved.bytes, filePath: saved.filePath });
+    }),
+  );
+
+  server.tool(
+    "stitch_timeline",
+    "씬 영상들과 오디오를 서버에서 타임라인 매니페스트로 합칩니다. 결과는 파일 핸들(payloadPath)로 반환되며, 이를 render_start에 넘기면 이 PC에서 mp4가 렌더됩니다. 서버는 렌더하지 않습니다.",
+    {
+      sceneVideos: z.array(z.object({
+        durationSec: z.number(),
+        idx: z.number().int(),
+        label: z.string().optional(),
+        url: z.string(),
+      })).min(1).describe("씬 순서대로 idx=0부터. url은 generate_scene_video의 videoUrl"),
+      featureKey: z.enum(["shortsVideo", "commerceVideo", "musicVideo"]).optional().describe("기본 commerceVideo"),
+      projectTitle: z.string().optional(),
+      aspectRatio: z.string().optional().describe("기본 9:16"),
+      ttsAudioPath: z.string().optional().describe("tts_narration이 반환한 mp3 경로"),
+      bgmAudioPath: z.string().optional().describe("suno_music_download가 반환한 mp3 경로"),
+      audioDurationSec: z.number().optional().describe("TTS 길이(초) — tts_narration의 durationSec (생략 시 ttsAudioPath에서 실측)"),
+      bgmVolume: z.number().nullable().optional().describe("null=자동(TTS 있으면 30, 없으면 100)"),
+      muteVideoAudio: z.boolean().optional().describe("기본 true (원본 씬 오디오 제거)"),
+      titleText: z.string().optional().describe("상단 고정 타이틀 (쇼츠)"),
+      subtitleLines: z.array(z.object({
+        endSec: z.number(),
+        startSec: z.number(),
+        text: z.string(),
+      })).optional().describe("자막 타이밍 (쇼츠)"),
+      transitionMode: z.enum(["fade", "none"]).optional().describe("기본 fade"),
+    },
+    wrapCloudHandler(config, async ({ sceneVideos, featureKey = "commerceVideo", projectTitle = "aimakeall-mcp", aspectRatio = "9:16", ttsAudioPath = "", bgmAudioPath = "", audioDurationSec = 0, bgmVolume = null, muteVideoAudio = true, titleText = "", subtitleLines = [], transitionMode = "fade" }) => {
+      // 오디오 확장자 검증 + 합산 크기 예산(서버 413 사전 차단).
+      if (ttsAudioPath) assertAllowedInputFile(ttsAudioPath, new Set([".mp3", ".wav"]), { kind: "TTS 오디오" });
+      if (bgmAudioPath) assertAllowedInputFile(bgmAudioPath, new Set([".mp3", ".wav"]), { kind: "BGM 오디오" });
+      assertEncodedBudget([ttsAudioPath, bgmAudioPath], { context: "오디오" });
+      // audioDurationSec 미지정 시 TTS 파일에서 실측 (CBR 추정 대신 프레임 합산).
+      const resolvedAudioDurationSec = audioDurationSec > 0
+        ? audioDurationSec
+        : (ttsAudioPath ? audioDurationSecFromFile(ttsAudioPath) : 0);
+      const body = {
+        aspectRatio,
+        audioDurationSec: resolvedAudioDurationSec,
+        bgmAudioUrl: bgmAudioPath ? fileToDataUrl(bgmAudioPath, { mimeType: "audio/mpeg" }) : "",
+        bgmVolume,
+        featureKey,
+        muteVideoAudio,
+        projectTitle,
+        sceneVideos: sceneVideos.map((scene, index) => ({
+          durationSec: scene.durationSec,
+          idx: index,
+          label: scene.label || `scene-${index + 1}`,
+          url: scene.url,
+        })),
+        subtitleLines,
+        titleText,
+        transitionMode,
+        ttsAudioUrl: ttsAudioPath ? fileToDataUrl(ttsAudioPath, { mimeType: "audio/mpeg" }) : "",
+      };
+      const response = await api.request("/api/tracker/commerce-video/stitch", {
+        body,
+        method: "POST",
+        timeoutMs: 180_000,
+      });
+      if (!response?.ok || !response?.payload) {
+        return textResult(`스티치 실패: ${response?.error || "매니페스트가 비어 있습니다."}`, { isError: true });
+      }
+      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에서 렌더하세요.",
+        payloadPath: handle.filePath,
+        projectTitle: response.payload.projectTitle,
+        sizeBytes: handle.bytes,
+      });
+    }),
+  );
+
+  server.tool(
+    "publish_auth_status",
+    "퍼블리시 플랫폼(YouTube 등) OAuth 연결 상태를 조회합니다. 연결은 aimakeall.com 웹에서 해야 합니다.",
+    {},
+    wrapCloudHandler(config, async () => jsonResult((await api.request("/api/upload/auth/status"))?.status || {})),
+  );
+
+  server.tool(
+    "youtube_categories",
+    "업로드 가능한 YouTube 카테고리 목록을 조회합니다 (YouTube 연결 필요).",
+    {},
+    wrapCloudHandler(config, async () => {
+      const payload = await api.request("/api/upload/youtube/categories?regionCode=KR&hl=ko");
+      return jsonResult({ categories: payload?.categories || [], source: payload?.source });
+    }),
+  );
+
+  server.tool(
+    "ai_publish_metadata",
+    "영상 제목·설명·태그를 AI로 생성합니다.",
+    {
+      title: z.string().optional().describe("제목 힌트"),
+      script: z.string().optional().describe("영상 대본/내레이션"),
+      description: z.string().optional(),
+      platforms: z.array(z.string()).optional().describe('기본 ["youtube"]'),
+    },
+    wrapCloudHandler(config, async ({ title = "", script = "", description = "", platforms = ["youtube"] }) => {
+      const payload = await api.request("/api/upload/ai/metadata", {
+        body: {
+          costEventId: createUsageEventId("upload-ai-metadata"),
+          description,
+          language: "한국어",
+          platforms,
+          script,
+          title,
+        },
+        method: "POST",
+        timeoutMs: 90_000,
+      });
+      return jsonResult({ description: payload?.description, tags: payload?.tags, title: payload?.title });
+    }),
+  );
+
+  server.tool(
+    "publish_youtube",
+    "이 PC의 mp4 파일을 YouTube에 업로드합니다 (YouTube OAuth 연결 필요). 기본은 비공개(private)이며, visibility=public/unlisted은 사용자가 명시적으로 요청한 경우에만 사용하세요.",
+    {
+      videoPath: z.string().describe("render_result가 저장한 mp4의 절대 경로"),
+      title: z.string().describe("영상 제목 (100자 이내)"),
+      description: z.string().optional(),
+      tags: z.array(z.string()).optional(),
+      categoryId: z.string().optional().describe("youtube_categories의 id"),
+      visibility: z.enum(["private", "unlisted", "public"]).optional().describe("기본 private"),
+      madeForKids: z.boolean().optional().describe("기본 false"),
+      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);
+      // 메타데이터가 쿼리스트링을 타므로 한국어 설명의 퍼센트 인코딩 팽창으로 헤더 상한(16KB)을
+      // 넘지 않도록 보수적으로 제한한다.
+      const safeTitle = title.slice(0, 100);
+      const safeDescription = description.slice(0, 1500);
+      const params = new URLSearchParams({
+        description: safeDescription,
+        language: "ko",
+        madeForKids: madeForKids ? "true" : "false",
+        notifySubscribers: notifySubscribers ? "true" : "false",
+        scheduleEnabled: "false",
+        tags: tags.join(","),
+        title: safeTitle,
+        visibility,
+      });
+      if (categoryId) {
+        params.set("categoryId", categoryId);
+        params.set("category", categoryId);
+      }
+      const payload = await api.requestStreamUpload(`/api/upload/youtube?${params.toString()}`, {
+        contentLength: stats.size,
+        contentType: "video/mp4",
+        stream: Readable.toWeb(createReadStream(videoPath)),
+        timeoutMs: 30 * 60_000,
+      });
+      // 무엇이 어떤 공개범위로 올라갔는지 결과에 명시 (사용자가 트랜스크립트로 확인 가능).
+      return jsonResult({
+        madeForKids,
+        ok: payload?.ok,
+        title: safeTitle,
+        videoId: payload?.videoId,
+        videoUrl: payload?.videoUrl,
+        visibility,
+      });
+    }),
+  );
+}