aimakeall-mcp 0.6.0 → 0.8.0

package/README.md

@@ -16,7 +16,7 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
   "mcpServers": {
     "aimakeall": {
       "command": "npx",
-      "args": ["-y", "aimakeall-mcp@0.6.0"],
+      "args": ["-y", "aimakeall-mcp@0.8.0"],
       "env": { "AIMAKEALL_PAT": "aio_pat_..." }
     }
   }
@@ -35,7 +35,7 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
 ## 기본 플로우 (쇼츠)
 
 ```
-plan_shorts_video → (씬마다) generate_scene_image → generate_scene_video_prompt → generate_scene_video
+plan_shorts_video → (씬마다) generate_scene_image → [QC: 동봉 이미지 직접 확인 또는 verify_scene_image] → generate_scene_video_prompt → generate_scene_video → [QC: 동봉 프레임 확인 또는 verify_scene_video]
 → (보이스 미지정 시) recommend_voice → tts_narration_with_captions(하단자막·강조용) 또는 tts_narration → stitch_timeline → render_start → render_status(폴링) → render_result
 → ai_publish_metadata → publish_youtube
 ```
@@ -44,7 +44,31 @@ plan_shorts_video → (씬마다) generate_scene_image → generate_scene_video_
 - 렌더 잡은 `~/.aimakeall/render-jobs.json`에 기록되어 프록시 재시작 후 `list_render_jobs`로 복구할 수 있습니다.
 - 대용량 산출물(TTS mp3, 스티치 매니페스트)은 파일 경로로 주고받아 모델 컨텍스트를 오염시키지 않습니다.
 - `recommend_voice`는 주제·샘플 영상(유튜브)에 맞는 보이스를 자동 선정합니다 — 샘플 화자 분석은 컴패니언 앱이 실행 중일 때만 동작합니다.
+- 자체검증(QC): 씬 이미지/영상 결과에 이미지·프레임 블록이 동봉되어 에이전트가 직접 보고 판정합니다. 비전 미지원 클라이언트는 `verify_scene_image`/`verify_scene_video`(서버 Gemini 판정)를 쓰세요 — 불합격 시 `regenerationHint`를 반영해 재생성.
 - 하단자막 강조: `tts_narration_with_captions`의 `subtitleLines`와 `plan_shorts_video`의 `emphasisKeywords`를 `stitch_timeline`에 함께 넘기면 자막 안 해당 단어만 노랑/큰 글씨로 강조됩니다(최신 컴패니언 런타임 필요 — 구버전은 일반 자막으로 안전 강등).
+- 렌더 영수증: `render_status`(완료 시)와 `render_result`가 산출물 실측(`summary.measured` — 길이·해상도·오디오·디코드 청결성·파일 크기)을 요청 규격과 대조해 `mismatches`로 알려줍니다. 불일치가 있으면 저장 전 원인을 확인하세요.
+- 원가 가시화: 생성 전 `estimate_video_cost`로 견적을 내고, 작업 후 `get_cost_report`로 실제 지출을 확인하세요. 어두운/검은 컷 의심 시 `verify_render_darkness`로 완성본 휘도를 실측할 수 있습니다.
+- 캐릭터 일관성: `plan_*`에 `characters`(이름·외모 앵커·의상 고정)를 넘기면 씬마다 identity lock 이 프롬프트에 강제 주입되고, `generate_scene_image`의 `identityLock`으로 재생성 시에도 유지됩니다.
+
+## 채널 규격 지문 (벤치마킹)
+
+```
+measure_channel_spec(벤치마크 영상 URL ≤5) → fingerprint → plan_shorts_video(channelFingerprint: fingerprint)
+```
+
+- 벤치마크 채널의 길이·컷/분·라우드니스·말끝 스타일을 **실측**해 숫자 규격으로 만들고, 대본 생성이 그 규격을 강제하게 합니다. 실측(샷 감지·오디오 추출)은 컴패니언 앱이 수행합니다.
+- 대본은 생성 후 규격 게이트(글자수·문장수·종결어미 교차·교훈조 아웃트로 금지)로 검증되며, 위반 시 1회 자동 리라이트 후 남은 위반을 `specWarnings`로 돌려줍니다.
+
+## 짜집기 (리메이크) 플로우
+
+```
+detect_shots(원본별, 컴패니언) → analyze_edit_points(videos + shotsFiles) → 에이전트가 sceneCatalog에서 컷 선별·내레이션 작성
+→ prepare_remake_timeline(sourceVideos + rows) → render_start(payloadPath) → render_status(폴링) → render_result
+```
+
+- 행(row) 모드: `[N]` TTS 내레이션(원본 무음) / `[S]` 원본 대사 유지 / `[A]` 현장음 유지 / `[SN]` 원본 대사 + TTS.
+- `analyze_edit_points`가 돌려주는 영상별 `burnedSubtitle`(박힌 자막 관측)을 `prepare_remake_timeline`의 `sourceVideos[].burnedSubtitle`로 그대로 넘기고 `subtitleCropMode: "auto"`를 주면 자막 박힌 소스만 하단 크롭됩니다.
+- `[N]`/`[SN]` 행의 `audioContent`는 유료 TTS로 합성됩니다 — 실행 전 사용자 확인을 받으세요. 원본 다운로드·렌더는 이 PC의 컴패니언이 수행합니다.
 
 ## 한도
 

package/lib/cloud-tools.mjs

@@ -29,6 +29,11 @@ import { trimWavToSeconds } from "./wav-trim.mjs";
 // 서버가 전체 업로드를 받은 뒤 413 을 내는 것을 막고 행동 가능한 한국어 안내를 준다.
 const BODY_BUDGET_BYTES = SERVER_JSON_BODY_LIMIT_BYTES - 512 * 1024; // 바디의 나머지 필드 여유
 
+// 컴패니언 계약 상수 — companion/index.cjs 의 MAX_SHOT_COUNT 및 오디오 추출 포맷과 맞춘다.
+// 오디오는 extractCompanionAudio 기본값(16kHz)·16bit·모노 = 초당 32,000 바이트.
+const COMPANION_MAX_SHOTS = 18;
+const COMPANION_AUDIO_BYTES_PER_SECOND = 16_000 * 2;
+
 function assertEncodedBudget(filePaths, { context = "요청" } = {}) {
   let total = 0;
   for (const filePath of filePaths.filter(Boolean)) {
@@ -95,6 +100,49 @@ function jsonResult(value) {
   return textResult(JSON.stringify(value, null, 2));
 }
 
+// JSON + 이미지 블록 결과 — 비전 지원 클라이언트의 에이전트가 산출물을 "직접 보고"
+// QC(1층 검증)할 수 있게 한다. 비전 미지원 클라이언트는 이미지 블록을 무시한다.
+function jsonWithImagesResult(value, images = []) {
+  return {
+    content: [
+      { text: JSON.stringify(value, null, 2), type: "text" },
+      ...images
+        .filter((image) => image?.base64)
+        .map((image) => ({ data: image.base64, mimeType: image.mimeType || "image/jpeg", type: "image" })),
+    ],
+  };
+}
+
+// 인라인 이미지 블록에 허용하는 MIME — MCP SDK 안전 목록(png/jpeg/webp/gif)만.
+const ALLOWED_INLINE_IMAGE_MIME = new Set(["image/gif", "image/jpeg", "image/jpg", "image/png", "image/webp"]);
+// 모델 API 의 이미지당 한도(약 5MB)를 넘지 않게 — 초과분은 동봉 생략(검증 도구 폴백 안내).
+const MAX_INLINE_IMAGE_BYTES = 4 * 1024 * 1024;
+
+// 결과 이미지 다운로드 — research_product 이미지 가드와 동일 규칙
+// (공개 URL만, redirect 미추적, image/* 검증, 8MB 스트리밍 캡).
+async function downloadImageAsBase64(imageUrl) {
+  if (!isSafePublicImageUrl(imageUrl)) return null;
+  try {
+    const response = await fetch(imageUrl, { redirect: "manual", signal: AbortSignal.timeout(30_000) });
+    if (!response.ok) return null;
+    const contentType = String(response.headers.get("content-type") || "").toLowerCase().split(";")[0].trim();
+    if (!ALLOWED_INLINE_IMAGE_MIME.has(contentType)) return null;
+    if (!response.body) return null;
+    const parts = [];
+    let received = 0;
+    for await (const chunk of response.body) {
+      const piece = Buffer.from(chunk);
+      received += piece.length;
+      if (received > MAX_INLINE_IMAGE_BYTES) return null;
+      parts.push(piece);
+    }
+    if (!received) return null;
+    return { base64: Buffer.concat(parts).toString("base64"), mimeType: contentType };
+  } catch {
+    return null;
+  }
+}
+
 const NO_PAT_GUIDE = "AIMAKEALL_PAT가 설정되지 않았습니다. aimakeall.com → API 키 설정 → MCP 토큰에서 발급한 뒤 MCP 설정의 env에 넣어주세요.";
 
 function describeLocalError(error) {
@@ -130,6 +178,9 @@ function trimPlanScenes(scenes) {
     ratio: scene?.ratio,
     sceneNarration: scene?.sceneNarration,
     scenePurpose: scene?.scenePurpose,
+    visibleCharacterSlots: Array.isArray(scene?.visibleCharacterSlots) && scene.visibleCharacterSlots.length
+      ? scene.visibleCharacterSlots
+      : undefined,
   }));
 }
 
@@ -148,6 +199,51 @@ export function registerCloudTools(server, config, api) {
     wrapCloudHandler(config, async () => jsonResult(await api.request("/api/tracker/usage"))),
   );
 
+  server.tool(
+    "get_cost_report",
+    "내 계정의 AI 원가 원장을 요약 조회합니다 — 총 지출, 모델별 상위 지출, 최근 이벤트. 여러 씬을 생성/재생성하기 전후로 호출해 실제 지출 델타를 확인하세요 (추측 과금 방지).",
+    {
+      limit: z.number().int().min(10).max(120).optional().describe("최근 이벤트 조회 수, 기본 60"),
+    },
+    wrapCloudHandler(config, async ({ limit = 60 }) => {
+      const payload = await api.request(`/api/tracker/account/cost-ledger?limit=${limit}`, { method: "GET", timeoutMs: 30_000 });
+      const ai = payload?.productionCost?.ai || {};
+      const byModel = ai?.byModel && typeof ai.byModel === "object" ? ai.byModel : {};
+      const topModels = Object.entries(byModel)
+        .map(([modelKey, row]) => ({ calls: row?.calls || 0, modelKey, usd: row?.usd || 0 }))
+        .sort((left, right) => right.usd - left.usd)
+        .slice(0, 8);
+      const recent = (Array.isArray(ai?.history) ? ai.history : []).slice(0, 15)
+        .map((event) => ({ at: event?.createdAt, kind: event?.kind, label: event?.label, modelKey: event?.modelKey, usd: event?.usd }));
+      return jsonResult({
+        recent,
+        topModels,
+        totalCalls: ai?.calls ?? payload?.summary?.calls,
+        totalUsd: ai?.totalUsd ?? payload?.summary?.totalUsd,
+      });
+    }),
+  );
+
+  server.tool(
+    "estimate_video_cost",
+    "생성 파이프라인 비용을 실행 전에 견적냅니다 (공급자 호출·과금 없음, 단가표 계산). 씬 수를 늘리거나 재생성 루프를 돌기 전에 호출해 예상 지출을 확인하세요.",
+    {
+      sceneCount: z.number().int().min(0).max(60).describe("씬 수"),
+      imageModel: z.string().optional().describe("기본 gpt-image-2-beta"),
+      imagesPerScene: z.number().int().min(0).max(4).optional().describe("씬당 이미지 수, 기본 1"),
+      referenceImageCount: z.number().int().min(0).max(6).optional().describe("이미지당 참조 장수 (일부 모델 단가 가산)"),
+      videoModel: z.string().optional().describe("기본 kie-grok-imagine"),
+      videoSecondsPerScene: z.number().min(0).max(30).optional().describe("씬당 영상 초 (0이면 영상 미포함)"),
+      videoQuality: z.string().optional().describe("기본 720p"),
+      ttsProvider: z.enum(["typecast", "elevenlabs", "supertone"]).optional().describe("기본 typecast"),
+      ttsChars: z.number().int().min(0).max(20000).optional().describe("내레이션 글자 수"),
+    },
+    wrapCloudHandler(config, async (input) => {
+      const payload = await api.request("/api/tracker/cost/estimate", { body: input, method: "POST", timeoutMs: 30_000 });
+      return jsonResult(payload);
+    }),
+  );
+
   server.tool(
     "plan_shorts_video",
     "쇼츠 영상 기획(시나리오·씬별 이미지 프롬프트·내레이션)을 생성합니다. topic 또는 copy 중 하나는 필수. 결과 scenes의 imagePrompt는 generate_scene_image로, skill은 씬 영상 프롬프트의 videoStylePreset으로, emphasisKeywords는 stitch_timeline의 emphasisKeywords로 이어집니다(하단자막 단어 강조).",
@@ -158,17 +254,40 @@ export function registerCloudTools(server, config, api) {
       targetCustomer: z.string().optional(),
       tone: z.string().optional().describe("기본 '자동 추천'"),
       sceneCount: z.number().int().min(1).max(10).optional().describe("기본 3"),
+      channelFingerprint: z.object({
+        sampleSize: z.number().optional(),
+        durationTargetSec: z.number().nullable().optional(),
+        cutIntervalSec: z.number().nullable().optional(),
+        cutsPerMin: z.number().nullable().optional(),
+        cpsTarget: z.number().nullable().optional(),
+        loudnessDbfs: z.number().nullable().optional(),
+        silenceRatio: z.number().nullable().optional(),
+        subtitleYPct: z.number().nullable().optional(),
+        subtitleLines: z.number().nullable().optional(),
+        endingStyle: z.string().nullable().optional(),
+        emphasisCount: z.number().nullable().optional(),
+        hasBgm: z.boolean().nullable().optional(),
+      }).passthrough().optional().describe("measure_channel_spec 이 반환한 fingerprint — 대본이 실측 규격을 강제하게 함"),
+      characters: z.array(z.object({
+        name: z.string().describe("캐릭터 이름"),
+        appearance: z.string().optional().describe("외모 앵커 (얼굴형·헤어·피부톤·의상 등)"),
+        role: z.string().optional(),
+        outfitLock: z.string().optional().describe("의상 고정 (예: navy hoodie)"),
+        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 = 3 }) => {
+    wrapCloudHandler(config, async ({ topic = "", copy = "", categoryId = "community-shorts", targetCustomer = "", tone = "자동 추천", sceneCount = 3, characters = [], channelFingerprint = null }) => {
       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,
+          channelFingerprint,
           copy,
           operationId: createUsageEventId("shorts-plan"),
           sceneCount,
+          characters,
           selectedCharacters: [],
           skillOverride: null,
           targetCustomer,
@@ -179,12 +298,14 @@ export function registerCloudTools(server, config, api) {
         timeoutMs: 240_000,
       });
       return jsonResult({
+        charactersUsed: Array.isArray(payload?.charactersUsed) ? payload.charactersUsed : undefined,
         ctaText: payload?.ctaText,
         emphasisKeywords: Array.isArray(payload?.emphasisKeywords) ? payload.emphasisKeywords : [],
         narrationScript: payload?.narrationScript,
         ok: payload?.ok,
         scenes: trimPlanScenes(payload?.scenes),
         skill: payload?.skill,
+        specWarnings: Array.isArray(payload?.specWarnings) && payload.specWarnings.length ? payload.specWarnings : undefined,
         tagline: payload?.tagline,
       });
     }),
@@ -280,8 +401,15 @@ export function registerCloudTools(server, config, api) {
       categoryId: z.string().optional().describe("기본 ecommerce"),
       sceneCount: z.number().int().min(1).max(12).optional().describe("기본 6"),
       researchBrief: z.string().optional().describe("research_product 결과의 planBrief — 불만·후킹·경쟁공백이 기획에 반영됨"),
+      characters: z.array(z.object({
+        name: z.string().describe("캐릭터 이름"),
+        appearance: z.string().optional().describe("외모 앵커 (얼굴형·헤어·피부톤·의상 등)"),
+        role: z.string().optional(),
+        outfitLock: z.string().optional().describe("의상 고정 (예: navy hoodie)"),
+        forbidden: z.string().optional().describe("금지 변형 (기본: different face, different hairstyle)"),
+      })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
     },
-    wrapCloudHandler(config, async ({ productName, productImagePaths, modelImagePath = "", description = "", targetCustomer = "", tone = "자동 추천", categoryId = "ecommerce", sceneCount = 6, researchBrief = "" }) => {
+    wrapCloudHandler(config, async ({ productName, productImagePaths, modelImagePath = "", description = "", targetCustomer = "", tone = "자동 추천", categoryId = "ecommerce", sceneCount = 6, researchBrief = "" , characters = [] }) => {
       // 확장자 검증(임의 파일 업로드 차단) + 합산 크기 예산(서버 413 사전 차단).
       for (const filePath of productImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "이미지" });
       if (modelImagePath) assertAllowedInputFile(modelImagePath, ALLOWED_IMAGE_EXTS, { kind: "모델 이미지" });
@@ -297,6 +425,7 @@ export function registerCloudTools(server, config, api) {
           productName,
           researchBrief,
           sceneCount,
+          characters,
           selectedCharacters: [],
           skillOverride: null,
           targetCustomer,
@@ -318,16 +447,21 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "generate_scene_image",
-    "씬 이미지를 생성합니다 (기획 결과의 imagePrompt 사용). 반환된 imageUrl을 씬 영상 생성의 입력으로 쓰세요. 인물·제품 일관성은 이 참조 방식이 권장 경로입니다: 첫 씬(또는 캐릭터 시트/제품 사진)의 이미지를 referenceImageUrls·referenceImagePaths로 모든 씬에 앵커로 전달하세요.",
+    "씬 이미지를 생성합니다 (기획 결과의 imagePrompt 사용). 반환된 imageUrl을 씬 영상 생성의 입력으로 쓰세요. 인물·제품 일관성은 이 참조 방식이 권장 경로입니다: 첫 씬(또는 캐릭터 시트/제품 사진)의 이미지를 referenceImageUrls·referenceImagePaths로 모든 씬에 앵커로 전달하세요. 결과에 이미지 블록이 동봉됩니다 — 반드시 직접 보고 QC(캐릭터 앵커·왜곡·지시 이행) 후 불합격 시 재생성하세요. 이미지를 볼 수 없으면 verify_scene_image 사용.",
     {
       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"),
+      returnImage: z.boolean().optional().describe("기본 true — 결과 이미지를 직접 보고 QC 할 수 있게 이미지 블록으로 함께 반환"),
+      identityLock: z.string().optional().describe("plan 응답 charactersUsed[].identityLock 을 그대로 — 프롬프트 말미에 리터럴 부착해 캐릭터 일관성 잠금 (paraphrase 금지)"),
       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 = [] }) => {
+    wrapCloudHandler(config, async ({ 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}`;
       for (const filePath of referenceImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "참조 이미지" });
       assertEncodedBudget(referenceImagePaths, { context: "참조 이미지" });
       const referenceImages = [
@@ -354,6 +488,7 @@ export function registerCloudTools(server, config, api) {
 
       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);
@@ -361,14 +496,24 @@ export function registerCloudTools(server, config, api) {
           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);
       }
-      return jsonResult({
+      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);
     }),
   );
 
@@ -415,7 +560,7 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "generate_scene_video",
-    "씬 영상을 생성합니다 (동기 호출, 최대 ~30분 — MCP 클라이언트의 툴 타임아웃(MCP_TIMEOUT)을 그 이상으로 늘려두세요. 타임아웃되면 이미 과금된 결과를 회수할 수 없으니 주의). 반환된 videoUrl을 stitch_timeline의 sceneVideos에 넣으세요.",
+    "씬 영상을 생성합니다 (동기 호출, 최대 ~30분 — MCP 클라이언트의 툴 타임아웃(MCP_TIMEOUT)을 그 이상으로 늘려두세요. 타임아웃되면 이미 과금된 결과를 회수할 수 없으니 주의). 반환된 videoUrl을 stitch_timeline의 sceneVideos에 넣으세요. 결과에 대표 프레임 3장이 동봉됩니다 — 반드시 직접 보고 QC 후 불합격 시 재생성하세요. 볼 수 없으면 verify_scene_video 사용.",
     {
       prompt: z.string().describe("영상 프롬프트 (generate_scene_video_prompt의 videoPrompt)"),
       sceneImageUrl: z.string().optional().describe("씬 이미지 URL (i2v 입력)"),
@@ -423,8 +568,9 @@ export function registerCloudTools(server, config, api) {
       durationSec: z.number().optional().describe("기본 8 (모델 상한으로 클램프됨)"),
       modelId: z.enum(["kie-grok-imagine", "seedance-2.0", "seedance-2.0-mini", "kling-3.0"]).optional().describe("i2v 영상 모델, 기본 kie-grok-imagine"),
       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" }) => {
+    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: {
           aspectRatio,
@@ -446,13 +592,31 @@ export function registerCloudTools(server, config, api) {
         // 서버 최악 경로(KIE 900s + Evolink 폴백 3회×900s)를 넘겨 잡아 조기 abort 로 과금-미회수를 방지.
         timeoutMs: 1_800_000,
       });
-      return jsonResult({
+      // 대표 프레임 동봉(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);
     }),
   );
 
@@ -941,9 +1105,16 @@ export function registerCloudTools(server, config, api) {
       sceneSeconds: z.number().int().min(3).max(8).optional().describe("씬 길이(초), 기본 5"),
       splitMode: z.enum(["fixed", "auto"]).optional().describe("씬 분할, 기본 fixed"),
       videoStylePreset: z.string().optional().describe("기본 seedance-music-video"),
+      characters: z.array(z.object({
+        name: z.string().describe("캐릭터 이름"),
+        appearance: z.string().optional().describe("외모 앵커 (얼굴형·헤어·피부톤·의상 등)"),
+        role: z.string().optional(),
+        outfitLock: z.string().optional().describe("의상 고정 (예: navy hoodie)"),
+        forbidden: z.string().optional().describe("금지 변형 (기본: different face, different hairstyle)"),
+      })).max(4).optional().describe("등장 캐릭터 — 서버가 씬마다 identity_lock 을 imagePrompt 에 강제 주입해 캐릭터 일관성을 잠급니다"),
       aspectRatio: z.string().optional().describe("기본 9:16"),
     },
-    wrapCloudHandler(config, async ({ durationSec, lyrics = "", conceptBrief = "", instrumental = false, sceneSeconds = 5, splitMode = "fixed", videoStylePreset = "seedance-music-video", aspectRatio = "9:16" }) => {
+    wrapCloudHandler(config, async ({ durationSec, lyrics = "", conceptBrief = "", instrumental = false, sceneSeconds = 5, splitMode = "fixed", videoStylePreset = "seedance-music-video", aspectRatio = "9:16" , characters = [] }) => {
       if (!instrumental && !String(lyrics).trim()) {
         return textResult("lyrics를 입력하거나 instrumental=true로 지정하세요.", { isError: true });
       }
@@ -956,6 +1127,7 @@ export function registerCloudTools(server, config, api) {
           instrumental,
           lyrics,
           sceneSeconds,
+          characters,
           selectedCharacters: [],
           songMeta: {},
           splitMode,
@@ -1031,6 +1203,9 @@ export function registerCloudTools(server, config, api) {
           id: video?.id,
           keywords: video?.keywords,
           recommendedPreset: video?.recommendedPreset,
+          // 박힌(하드섭) 자막 관측 — prepare_remake_timeline 의 sourceVideos[].burnedSubtitle 에
+          // 그대로 넘기면 subtitleCropMode:"auto" 가 해당 소스만 하단 크롭한다.
+          burnedSubtitle: video?.burnedSubtitle,
           sceneCatalog: (video?.sceneCatalog || []).map((scene) => ({
             actionTags: scene?.actionTags,
             ambienceScore: scene?.ambienceScore,
@@ -1054,6 +1229,85 @@ export function registerCloudTools(server, config, api) {
     }),
   );
 
+  // ── 짜집기 렌더 준비 — 컷 세트 → TTS + 타임라인 페이로드 ────────────────────
+  server.tool(
+    "prepare_remake_timeline",
+    "짜집기(리메이크) 렌더 준비 — analyze_edit_points 의 sceneCatalog 에서 고른 컷들로 구성한 컷 세트를 서버에 보내 TTS 합성 + 렌더 타임라인을 만듭니다. 반환된 payloadPath 를 render_start 에 넘기면 이 PC 에서 원본 다운로드 + 렌더가 수행됩니다. [N]/[SN] 행의 audioContent 는 유료 TTS 로 합성되므로 실행 전 사용자 확인을 받으세요.",
+    {
+      title: z.string().optional().describe("영상 상단 타이틀 텍스트 (없으면 생략)"),
+      sourceVideos: z.array(z.object({
+        id: z.string().describe("YouTube video id (11자)"),
+        title: z.string().optional(),
+        burnedSubtitle: z.object({
+          present: z.boolean(),
+          position: z.string().optional().describe("bottom/top/center/none"),
+          bandPercent: z.number().optional().describe("자막 세로 점유율(%) — 보통 12~22"),
+        }).optional().describe("analyze_edit_points 가 반환한 관측값을 그대로 — subtitleCropMode:auto 판단 근거"),
+      })).min(1).max(5).describe("컷을 가져올 원본 영상 목록"),
+      rows: z.array(z.object({
+        mode: z.enum(["N", "S", "A", "SN"]).describe("N=TTS 내레이션(원본 무음) / S=원본 대사 유지 / A=현장음 유지 / SN=원본 대사+TTS"),
+        durationSec: z.number().describe("행 길이(초) — S/A 는 클립 자연 길이가 우선"),
+        audioContent: z.string().optional().describe("N/SN 의 내레이션 텍스트 (하단 자막으로도 burn-in)"),
+        effectSubtitle: z.string().optional().describe("효과 자막 (짧은 박스 자막, 예: 팩트 폭행)"),
+        clipRefs: z.array(z.object({
+          videoId: z.string().describe("sourceVideos 의 id"),
+          startMs: z.number().describe("원본에서 자를 시작(ms) — sceneCatalog 의 startMs"),
+          endMs: z.number().describe("원본에서 자를 끝(ms)"),
+        })).min(1).max(6).describe("이 행에 이어 붙일 원본 구간들"),
+      })).min(1).max(40).describe("타임라인 행 — 순서대로 이어 붙습니다"),
+      provider: z.enum(["typecast", "elevenlabs", "supertone"]).optional().describe("TTS 공급자, 기본 typecast (recommend_voice 로 보이스를 먼저 고르세요)"),
+      voiceId: z.string().optional().describe("보이스 ID (생략 시 공급자 기본)"),
+      aspectRatio: z.enum(["9:16", "16:9", "1:1"]).optional().describe("기본 9:16"),
+      subtitleCropMode: z.enum(["off", "always", "auto"]).optional().describe("원본 박힌 자막 하단 크롭 — auto 는 burnedSubtitle.present 소스만"),
+    },
+    wrapCloudHandler(config, async ({ title = "", sourceVideos, rows, provider = "typecast", voiceId = "", aspectRatio = "9:16", subtitleCropMode = "off" }) => {
+      const sourceIds = new Set(sourceVideos.map((source) => source.id));
+      const badRef = rows.flatMap((row) => row.clipRefs).find((ref) => !sourceIds.has(ref.videoId));
+      if (badRef) {
+        return textResult(`clipRefs 의 videoId "${badRef.videoId}" 가 sourceVideos 에 없습니다.`, { isError: true });
+      }
+      const version = {
+        id: "mcp-remake",
+        title,
+        sourceVideos,
+        rows: rows.map((row) => ({
+          ...row,
+          clipRefs: row.clipRefs.map((ref) => ({
+            ...ref,
+            durationSec: Math.max(0.3, (ref.endMs - ref.startMs) / 1000),
+          })),
+        })),
+      };
+      const payload = await api.request("/api/tracker/remake/prepare", {
+        body: {
+          aspectRatio,
+          costEventId: createUsageEventId("mcp-remake-tts"),
+          provider,
+          subtitleCropMode,
+          version,
+          voiceId,
+        },
+        method: "POST",
+        timeoutMs: 300_000,
+      });
+      if (!payload?.payload) {
+        return textResult(`짜집기 준비 실패: ${payload?.error || "타임라인이 비어 있습니다."}`, { isError: true });
+      }
+      const handle = savePayloadHandle(config.stateDir, payload.payload, "remake");
+      return jsonResult({
+        costUsd: payload.costUsd ?? 0,
+        next: "render_start 에 payloadPath 를 넘겨 이 PC 에서 렌더하세요 (원본 다운로드 포함 — 수 분 걸릴 수 있음).",
+        payloadPath: handle.filePath,
+        sizeBytes: handle.bytes,
+        totalDurationMs: payload.totalDurationMs ?? 0,
+        ttsAttempted: payload.ttsAttempted ?? 0,
+        ttsCharCount: payload.ttsCharCount ?? 0,
+        ...(payload.ttsLastError ? { ttsLastError: payload.ttsLastError } : {}),
+        ttsSucceeded: payload.ttsSucceeded ?? 0,
+      });
+    }),
+  );
+
   // ── 시간 동기 자막 TTS — 쇼츠 하단자막용 ─────────────────────────────────────
   server.tool(
     "tts_narration_with_captions",
@@ -1182,6 +1436,205 @@ export function registerCloudTools(server, config, api) {
     }),
   );
 
+  server.tool(
+    "measure_channel_spec",
+    "벤치마크 채널의 영상 표본(유튜브 URL ≤5)을 실측해 채널 규격 지문(길이·컷간격·컷/분·라우드니스·무음비율·자막 위치·말끝 스타일)을 만듭니다. 컴패니언 앱이 다운로드·샷감지·오디오 추출을 수행하고 서버가 집계합니다. 반환된 fingerprint 를 plan_shorts_video 의 channelFingerprint 로 넘기면 대본이 그 규격을 강제합니다.",
+    {
+      videoUrls: z.array(z.string()).min(1).max(5).describe("표본 유튜브 URL 또는 11자 ID (조회수 상위 영상 권장)"),
+    },
+    wrapCloudHandler(config, async ({ videoUrls }) => {
+      const specs = [];
+      const notes = [];
+      // 서버 채널지문 라우트의 본문 상한은 16MB. 표본당 120초 WAV(16kHz·16bit 모노)는
+      // base64 ~5.1MB 라 표본 3개만 넘어도 합산이 상한을 넘겨 전체 413 으로 죽는다.
+      // 표본 수에 맞춰 오디오 트림 길이를 나눠 갖고, 누적 크기도 방어적으로 감시한다.
+      const audioBudgetChars = 9_000_000;
+      const base64CharsPerAudioSecond = Math.ceil(COMPANION_AUDIO_BYTES_PER_SECOND * 4 / 3);
+      const audioTrimSeconds = Math.max(20, Math.min(120, Math.floor(audioBudgetChars / videoUrls.length / base64CharsPerAudioSecond)));
+      let audioCharsUsed = 0;
+      for (const [index, rawUrl] of videoUrls.entries()) {
+        const watchUrl = canonicalYoutubeWatchUrl(rawUrl);
+        if (!watchUrl) {
+          notes.push(`표본 ${index + 1}: 유튜브 URL 아님 — 건너뜀`);
+          continue;
+        }
+        try {
+          // 샷 감지 (컷수·길이·프레임) — 컴패니언 로컬 ffmpeg.
+          const shotsResp = await fetch(`${config.companionUrl}/api/shots`, {
+            body: JSON.stringify({ maxShots: COMPANION_MAX_SHOTS, minGapMs: 1400, sceneThreshold: 0.22, url: watchUrl, width: 480 }),
+            headers: { "Content-Type": "application/json" },
+            method: "POST",
+            signal: AbortSignal.timeout(240_000),
+          });
+          const shotsPayload = await shotsResp.json().catch(() => null);
+          if (!shotsResp.ok || !Array.isArray(shotsPayload?.shots) || !shotsPayload.shots.length) {
+            notes.push(`표본 ${index + 1}: 샷 감지 실패(${shotsPayload?.error || shotsResp.status})`);
+            continue;
+          }
+          const shots = shotsPayload.shots;
+          const durationSec = Math.round((shots.at(-1)?.endMs || 0) / 100) / 10;
+          const frames = shots
+            .filter((shot) => shot?.imageBase64)
+            .slice(0, 8)
+            .map((shot) => `data:${shot?.mimeType || "image/jpeg"};base64,${shot.imageBase64}`);
+          // 컴패니언은 감지된 컷을 maxShots 개로 다운샘플해 돌려준다(downsampleShotStarts).
+          // 상한에 걸린 목록의 길이는 컷 수의 하한일 뿐이라 "실측"으로 쓸 수 없다 —
+          // 빠른 컷 채널일수록 컷/분이 심하게 낮게 잡혀 대본 지시문을 오염시킨다.
+          // 지어낸 숫자를 보내느니 축을 비우고 사유를 남긴다.
+          const cutCountClamped = shots.length >= COMPANION_MAX_SHOTS;
+          if (cutCountClamped) {
+            notes.push(`표본 ${index + 1}: 감지 컷이 컴패니언 상한(${COMPANION_MAX_SHOTS})에 도달 — 컷 수는 하한값이라 컷 리듬 축에서 제외`);
+          }
+          // 오디오 — 라우드니스/무음은 서버가 검증된 DSP 로 실측.
+          let audioBase64 = "";
+          try {
+            const wav = await extractCompanionAudio(config.companionUrl, { url: watchUrl });
+            const encoded = trimWavToSeconds(wav, audioTrimSeconds).toString("base64");
+            if (audioCharsUsed + encoded.length > audioBudgetChars) {
+              notes.push(`표본 ${index + 1}: 본문 예산 초과로 오디오 제외 — 라우드니스 축 제외`);
+            } else {
+              audioBase64 = encoded;
+              audioCharsUsed += encoded.length;
+            }
+          } catch (error) {
+            notes.push(`표본 ${index + 1}: 오디오 추출 실패(${String(error?.message || error).slice(0, 80)}) — 라우드니스 축 제외`);
+          }
+          specs.push({
+            audioBase64,
+            ...(cutCountClamped ? {} : { cutCount: shots.length }),
+            durationSec,
+            frames,
+            videoId: watchUrl.slice(-11),
+          });
+        } catch (error) {
+          notes.push(`표본 ${index + 1}: ${String(error?.message || error).slice(0, 100)}`);
+        }
+      }
+      if (!specs.length) {
+        return textResult(`표본 실측에 모두 실패했습니다. 컴패니언 앱 실행 여부를 확인하세요.\n${notes.join("\n")}`, { isError: true });
+      }
+      const payload = await api.request("/api/tracker/gemini/channel-fingerprint", {
+        body: { measuredAt: new Date().toISOString(), videos: specs },
+        method: "POST",
+        timeoutMs: 300_000,
+      });
+      if (payload?.ok === false || !payload?.fingerprint) {
+        return textResult(`지문 집계 실패: ${payload?.error || "알 수 없는 오류"}`, { isError: true });
+      }
+      return jsonResult({
+        fingerprint: payload.fingerprint,
+        next: "이 fingerprint 객체를 plan_shorts_video 의 channelFingerprint 로 그대로 넘기세요 — 대본이 실측 규격(길이·컷·말속도·말끝)을 따르게 됩니다.",
+        notes: notes.length ? notes : undefined,
+        sampleCount: specs.length,
+      });
+    }),
+  );
+
+  server.tool(
+    "verify_scene_image",
+    "생성된 키프레임 이미지를 서버 비전(Gemini)이 QC 판정합니다 — 캐릭터 참조 대조·아티팩트·프롬프트 이행. 이미지 블록을 직접 볼 수 없는 클라이언트의 폴백이며, 판정 JSON(pass/violations/regenerationHint)만 읽으면 됩니다. 불합격이면 regenerationHint 를 프롬프트에 반영해 generate_scene_image 를 재호출하세요.",
+    {
+      imageUrl: z.string().optional().describe("generate_scene_image 가 반환한 imageUrl"),
+      imagePath: z.string().optional().describe("imageUrl 이 없을 때 — 생성 결과의 savedPath (로컬 파일)"),
+      prompt: z.string().optional().describe("기대 내용(생성에 쓴 프롬프트 요약)"),
+      referenceImagePaths: z.array(z.string()).max(4).optional().describe("참조 캐릭터 이미지 로컬 경로 (생성에 쓴 것과 동일하게)"),
+      checklist: z.array(z.string()).max(8).optional().describe("추가 검수 항목 (예: 후드티는 남색)"),
+    },
+    wrapCloudHandler(config, async ({ imageUrl = "", imagePath = "", prompt = "", referenceImagePaths = [], checklist = [] }) => {
+      if (!imageUrl && !imagePath) {
+        return textResult("imageUrl 또는 imagePath 중 하나는 필요합니다.", { isError: true });
+      }
+      if (imagePath) {
+        assertAllowedInputFile(imagePath, ALLOWED_IMAGE_EXTS, { kind: "검증 대상 이미지" });
+      }
+      for (const filePath of referenceImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "참조 이미지" });
+      assertEncodedBudget([imagePath, ...referenceImagePaths].filter(Boolean), { context: "검증 이미지" });
+      const candidateUrl = imageUrl || fileToDataUrl(imagePath, { allowedExts: ALLOWED_IMAGE_EXTS, kind: "검증 대상 이미지" });
+      const payload = await api.request("/api/tracker/gemini/verify-scene", {
+        body: {
+          checklist,
+          imageUrl: candidateUrl,
+          kind: "image",
+          prompt,
+          referenceImages: referenceImagePaths.map((filePath) => ({
+            name: path.basename(filePath),
+            previewUrl: fileToDataUrl(filePath, { allowedExts: ALLOWED_IMAGE_EXTS, kind: "참조 이미지" }),
+          })),
+        },
+        method: "POST",
+        timeoutMs: 300_000,
+      });
+      if (payload?.ok === false) {
+        return textResult(`씬 검증 실패: ${payload?.error || "알 수 없는 오류"}\n${payload?.guidance || ""}`.trim(), { isError: true });
+      }
+      return jsonResult({ referenceLoaded: payload?.referenceLoaded, verdict: payload?.verdict || null });
+    }),
+  );
+
+  server.tool(
+    "verify_scene_video",
+    "생성된 씬 영상을 서버가 대표 프레임으로 QC 판정합니다 (Gemini 비전) — 캐릭터 참조 대조·붕괴/왜곡·프롬프트 이행. 프레임 블록을 직접 볼 수 없는 클라이언트의 폴백. 불합격이면 regenerationHint 를 반영해 generate_scene_video 를 재호출하세요.",
+    {
+      videoUrl: z.string().describe("generate_scene_video 가 반환한 videoUrl"),
+      prompt: z.string().optional().describe("기대 내용(생성에 쓴 프롬프트 요약)"),
+      referenceImagePaths: z.array(z.string()).max(4).optional().describe("참조 캐릭터 이미지 로컬 경로"),
+      checklist: z.array(z.string()).max(8).optional().describe("추가 검수 항목"),
+      frameCount: z.number().int().min(2).max(4).optional().describe("판정에 쓸 프레임 수, 기본 3"),
+    },
+    wrapCloudHandler(config, async ({ videoUrl, prompt = "", referenceImagePaths = [], checklist = [], frameCount = 3 }) => {
+      for (const filePath of referenceImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "참조 이미지" });
+      assertEncodedBudget(referenceImagePaths, { context: "참조 이미지" });
+      const payload = await api.request("/api/tracker/gemini/verify-scene", {
+        body: {
+          checklist,
+          frameCount,
+          kind: "video",
+          prompt,
+          referenceImages: referenceImagePaths.map((filePath) => ({
+            name: path.basename(filePath),
+            previewUrl: fileToDataUrl(filePath, { allowedExts: ALLOWED_IMAGE_EXTS, kind: "참조 이미지" }),
+          })),
+          videoUrl,
+        },
+        method: "POST",
+        timeoutMs: 600_000, // 다운로드 120s + ffmpeg + Gemini 최악 경로 여유
+      });
+      if (payload?.ok === false) {
+        return textResult(`씬 검증 실패: ${payload?.error || "알 수 없는 오류"}\n${payload?.guidance || ""}`.trim(), { isError: true });
+      }
+      return jsonResult({ referenceLoaded: payload?.referenceLoaded, verdict: payload?.verdict || null });
+    }),
+  );
+
+  server.tool(
+    "verify_render_darkness",
+    "렌더된 mp4 의 검은 프레임(검은컷)을 휘도 실측으로 잡습니다 — 컷 경계 시각들을 넘기면 그 지점만, 생략하면 1초 간격 전수 샘플. darkCount>0 이면 해당 시각의 씬 전환/소스를 점검하세요. AI 호출 없음(무과금).",
+    {
+      videoUrl: z.string().describe("검사할 mp4 URL (렌더 결과 업로드본 또는 씬 videoUrl)"),
+      timestamps: z.array(z.number().min(0)).max(120).optional().describe("검사 시각(초) — 컷 경계 ±0.15s 권장. 생략 시 1초 간격 자동"),
+      darkThreshold: z.number().int().min(1).max(80).optional().describe("검정 판정 휘도 상한(0~255), 기본 16"),
+    },
+    wrapCloudHandler(config, async ({ videoUrl, timestamps = [], darkThreshold = 16 }) => {
+      const payload = await api.request("/api/tracker/video/darkness", {
+        body: { darkThreshold, timestamps, videoUrl },
+        method: "POST",
+        timeoutMs: 300_000,
+      });
+      if (payload?.ok === false) {
+        return textResult(`휘도 측정 실패: ${payload?.error || "알 수 없는 오류"}`, { isError: true });
+      }
+      return jsonResult({
+        darkCount: payload?.darkCount,
+        darkSamples: payload?.darkSamples,
+        pass: (payload?.darkCount || 0) === 0,
+        sampleCount: payload?.sampleCount,
+        verdictNote: (payload?.darkCount || 0) > 0
+          ? "검은 프레임 검출 — 해당 시각의 씬 소스/전환을 점검하고 재스티치하세요 (transitionMode fade 사용 여부 확인)."
+          : "검은컷 없음.",
+      });
+    }),
+  );
+
   // ── 상세페이지(PDP) ─────────────────────────────────────────────────────────
   server.tool(
     "generate_pdp",

package/lib/companion-tools.mjs

@@ -42,6 +42,36 @@ export function describeCompanionState(triage, remoteEnv) {
   return `컴패니언은 실행 중이지만 렌더 런타임이 없습니다 (${triage.detail}). 컴패니언 앱에서 렌더 런타임 설치를 실행하세요.`;
 }
 
+// 렌더 영수증 대조 — 브리지가 실측한 summary.measured 를 요청 규격과 비교해 불일치를 나열한다.
+// 구버전 컴패니언(브리지에 measured 없음)은 빈 배열 + receipt 없음으로 안전 강등.
+function computeRenderMismatches(summary) {
+  const requested = summary?.requested;
+  const measured = summary?.measured;
+  if (!requested || !measured) return [];
+  const mismatches = [];
+  const reqDuration = Number(requested.durationSec);
+  const gotDuration = Number(measured.durationSec);
+  if (Number.isFinite(reqDuration) && Number.isFinite(gotDuration)
+    && Math.abs(reqDuration - gotDuration) > Math.max(0.5, reqDuration * 0.03)) {
+    mismatches.push(`길이 불일치: 요청 ${reqDuration}s vs 실측 ${gotDuration}s`);
+  }
+  for (const axis of ["width", "height"]) {
+    if (Number.isFinite(Number(measured[axis])) && Number(requested[axis]) !== Number(measured[axis])) {
+      mismatches.push(`${axis} 불일치: 요청 ${requested[axis]} vs 실측 ${measured[axis]}`);
+    }
+  }
+  if (requested.hasAudio === true && measured.hasAudio === false) {
+    mismatches.push("오디오 누락: 오디오 트랙을 요청했지만 산출물에 없습니다");
+  }
+  if (summary?.decodeClean === false) {
+    mismatches.push(`디코드 오류 감지${measured.decodeErrorSample ? `: ${measured.decodeErrorSample}` : ""}`);
+  }
+  if (Number(summary?.fileBytes) === 0) {
+    mismatches.push("산출물 파일이 0바이트입니다");
+  }
+  return mismatches;
+}
+
 export function registerCompanionTools(server, config) {
   const remoteEnv = detectRemoteEnvironment();
 
@@ -209,11 +239,21 @@ export function registerCompanionTools(server, config) {
       } catch {
         // 영속화 실패는 무시
       }
+      const receipt = job.status === "succeeded" && job.summary
+        ? { mismatches: computeRenderMismatches(job.summary), summary: job.summary }
+        : null;
       return textResult(JSON.stringify({
         etaSec: job.progress?.etaSec ?? null,
         percent: job.progress?.percent ?? 0,
         stage: job.stage || "",
         status: job.status || "",
+        ...(receipt ? {
+          ...(receipt.mismatches.length ? {
+            mismatches: receipt.mismatches,
+            warning: "렌더 영수증 불일치 — 저장 전 원인을 확인하고 필요하면 다시 렌더하세요.",
+          } : {}),
+          summary: receipt.summary,
+        } : {}),
       }, null, 2));
     },
   );
@@ -226,6 +266,13 @@ export function registerCompanionTools(server, config) {
       fileName: z.string().optional().describe("저장할 파일명 (생략 시 서버 제안 이름)"),
     },
     async ({ jobId, fileName }) => {
+      // 출력은 저장 성공 시 컴패니언에서 삭제되므로 영수증은 다운로드 전에 읽는다.
+      let receiptSummary = null;
+      try {
+        receiptSummary = (await getRenderJob(config.companionUrl, jobId))?.payload?.summary || null;
+      } catch {
+        // 영수증 조회 실패가 다운로드를 막지 않는다 (구버전 컴패니언 호환).
+      }
       const saved = await downloadRenderOutput(config.companionUrl, jobId, config.outputDir, {
         suggestedName: fileName || "",
       });
@@ -242,10 +289,16 @@ export function registerCompanionTools(server, config) {
       } catch {
         // 영속화 실패는 무시
       }
+      const mismatches = receiptSummary ? computeRenderMismatches(receiptSummary) : [];
       return textResult(JSON.stringify({
         bytes: saved.bytes,
         filePath: saved.filePath,
+        ...(mismatches.length ? {
+          mismatches,
+          warning: "렌더 영수증 불일치 — 파일을 확인하고 필요하면 다시 렌더하세요.",
+        } : {}),
         note: "파일은 이 PC에 저장되었습니다.",
+        ...(receiptSummary ? { summary: receiptSummary } : {}),
       }, null, 2));
     },
   );

package/lib/config.mjs

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 
 // 프록시 버전 — 서버가 X-AImakeAll-MCP-Version 으로 하한을 강제(426)할 수 있다.
-export const MCP_PROXY_VERSION = "0.6.0";
+export const MCP_PROXY_VERSION = "0.8.0";
 
 export const DEFAULT_API_BASE = "https://aimakeall.com";
 export const DEFAULT_COMPANION_URL = "http://127.0.0.1:9876";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aimakeall-mcp",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "AImakeAll MCP 서버 — Claude Code/Codex에서 자연어로 영상 기획·생성·렌더·퍼블리시 (렌더는 로컬 컴패니언)",
   "type": "module",
   "bin": {