aimakeall-mcp 0.4.3 → 0.6.0

package/README.md

@@ -16,7 +16,7 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
   "mcpServers": {
     "aimakeall": {
       "command": "npx",
-      "args": ["-y", "aimakeall-mcp@0.4.3"],
+      "args": ["-y", "aimakeall-mcp@0.6.0"],
       "env": { "AIMAKEALL_PAT": "aio_pat_..." }
     }
   }
@@ -36,13 +36,15 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
 
 ```
 plan_shorts_video → (씬마다) generate_scene_image → generate_scene_video_prompt → generate_scene_video
-→ tts_narration → stitch_timeline → render_start → render_status(폴링) → render_result
+→ (보이스 미지정 시) recommend_voice → tts_narration_with_captions(하단자막·강조용) 또는 tts_narration → stitch_timeline → render_start → render_status(폴링) → render_result
 → ai_publish_metadata → publish_youtube
 ```
 
 - 씬 영상 생성은 동기 호출로 최대 15분 걸립니다 — MCP 클라이언트의 툴 타임아웃(`MCP_TIMEOUT`)을 충분히 잡아주세요.
 - 렌더 잡은 `~/.aimakeall/render-jobs.json`에 기록되어 프록시 재시작 후 `list_render_jobs`로 복구할 수 있습니다.
 - 대용량 산출물(TTS mp3, 스티치 매니페스트)은 파일 경로로 주고받아 모델 컨텍스트를 오염시키지 않습니다.
+- `recommend_voice`는 주제·샘플 영상(유튜브)에 맞는 보이스를 자동 선정합니다 — 샘플 화자 분석은 컴패니언 앱이 실행 중일 때만 동작합니다.
+- 하단자막 강조: `tts_narration_with_captions`의 `subtitleLines`와 `plan_shorts_video`의 `emphasisKeywords`를 `stitch_timeline`에 함께 넘기면 자막 안 해당 단어만 노랑/큰 글씨로 강조됩니다(최신 컴패니언 런타임 필요 — 구버전은 일반 자막으로 안전 강등).
 
 ## 한도
 

package/lib/cloud-tools.mjs

@@ -6,6 +6,7 @@ import { Readable } from "node:stream";
 import { z } from "zod";
 
 import { AimakeallApiError } from "./api-client.mjs";
+import { extractCompanionAudio } from "./companion-client.mjs";
 import {
   ALLOWED_IMAGE_EXTS,
   ALLOWED_VIDEO_EXTS,
@@ -20,7 +21,9 @@ import {
   SERVER_JSON_BODY_LIMIT_BYTES,
 } from "./media-store.mjs";
 import { mp3DurationSec } from "./mp3-duration.mjs";
+import { canonicalYoutubeWatchUrl } from "./payload-guard.mjs";
 import { createUsageEventId } from "./usage-event.mjs";
+import { trimWavToSeconds } from "./wav-trim.mjs";
 
 // 여러 파일을 base64 로 싣는 요청의 인코딩 크기 합이 서버 JSON 상한을 넘지 않게 사전 검사.
 // 서버가 전체 업로드를 받은 뒤 413 을 내는 것을 막고 행동 가능한 한국어 안내를 준다.
@@ -147,7 +150,7 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "plan_shorts_video",
-    "쇼츠 영상 기획(시나리오·씬별 이미지 프롬프트·내레이션)을 생성합니다. topic 또는 copy 중 하나는 필수. 결과 scenes의 imagePrompt는 generate_scene_image로, skill은 씬 영상 프롬프트의 videoStylePreset으로 이어집니다.",
+    "쇼츠 영상 기획(시나리오·씬별 이미지 프롬프트·내레이션)을 생성합니다. topic 또는 copy 중 하나는 필수. 결과 scenes의 imagePrompt는 generate_scene_image로, skill은 씬 영상 프롬프트의 videoStylePreset으로, emphasisKeywords는 stitch_timeline의 emphasisKeywords로 이어집니다(하단자막 단어 강조).",
     {
       topic: z.string().optional().describe("영상 주제"),
       copy: z.string().optional().describe("핵심 카피/대사"),
@@ -177,6 +180,7 @@ export function registerCloudTools(server, config, api) {
       });
       return jsonResult({
         ctaText: payload?.ctaText,
+        emphasisKeywords: Array.isArray(payload?.emphasisKeywords) ? payload.emphasisKeywords : [],
         narrationScript: payload?.narrationScript,
         ok: payload?.ok,
         scenes: trimPlanScenes(payload?.scenes),
@@ -454,7 +458,7 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "tts_narration",
-    "내레이션 TTS를 합성해 이 PC에 mp3로 저장하고 파일 경로를 반환합니다. stitch_timeline의 ttsAudioPath로 쓰세요.",
+    "내레이션 TTS를 합성해 이 PC에 mp3로 저장하고 파일 경로를 반환합니다. stitch_timeline의 ttsAudioPath로 쓰세요. 사용자가 보이스를 직접 지정하지 않았다면 먼저 recommend_voice로 주제·샘플 영상에 맞는 보이스를 자동 선정해 voice에 넣으세요.",
     {
       text: z.string().describe("내레이션 텍스트"),
       provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
@@ -576,7 +580,7 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "stitch_timeline",
-    "씬 영상들과 오디오를 서버에서 타임라인 매니페스트로 합칩니다. 결과는 파일 핸들(payloadPath)로 반환되며, 이를 render_start에 넘기면 이 PC에서 mp4가 렌더됩니다. 서버는 렌더하지 않습니다.",
+    "씬 영상들과 오디오를 서버에서 타임라인 매니페스트로 합칩니다. 결과는 파일 핸들(payloadPath)로 반환되며, 이를 render_start에 넘기면 이 PC에서 mp4가 렌더됩니다. 서버는 렌더하지 않습니다. 하단자막 강조: emphasisKeywords 를 주면 자막 라인 안의 해당 단어만 다른 색/크기로 강조되고, subtitleLines[].style 로 라인별 디자인도 바꿀 수 있습니다.",
     {
       sceneVideos: z.array(z.object({
         durationSec: z.number(),
@@ -597,10 +601,24 @@ 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("이 라인만의 디자인 오버라이드 (내용에 따라 라인별 디자인을 달리할 때)"),
       })).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 노랑)"),
+      emphasisSizeScale: z.number().optional().describe("강조 크기 배율 0.5~2 (기본 1.2)"),
       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" }) => {
+    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 = "fade" }) => {
       // 오디오 확장자 검증 + 합산 크기 예산(서버 413 사전 차단).
       if (ttsAudioPath) assertAllowedInputFile(ttsAudioPath, new Set([".mp3", ".wav"]), { kind: "TTS 오디오" });
       if (bgmAudioPath) assertAllowedInputFile(bgmAudioPath, new Set([".mp3", ".wav"]), { kind: "BGM 오디오" });
@@ -623,6 +641,9 @@ export function registerCloudTools(server, config, api) {
           label: scene.label || `scene-${index + 1}`,
           url: scene.url,
         })),
+        emphasisColor,
+        emphasisKeywords,
+        emphasisSizeScale,
         subtitleLines,
         titleText,
         transitionMode,
@@ -1036,7 +1057,7 @@ export function registerCloudTools(server, config, api) {
   // ── 시간 동기 자막 TTS — 쇼츠 하단자막용 ─────────────────────────────────────
   server.tool(
     "tts_narration_with_captions",
-    "ElevenLabs TTS를 char-level 타이밍과 함께 합성해 mp3 파일 + 시간 동기 자막 라인(subtitleLines)을 만듭니다. 쇼츠 하단자막이 필요하면 tts_narration 대신 이걸 쓰고, 결과 subtitleLines·durationSec·filePath를 stitch_timeline에 그대로 넘기세요 (웹 쇼츠 스튜디오와 동일한 정렬 방식).",
+    "ElevenLabs TTS를 char-level 타이밍과 함께 합성해 mp3 파일 + 시간 동기 자막 라인(subtitleLines)을 만듭니다. 쇼츠 하단자막이 필요하면 tts_narration 대신 이걸 쓰고, 결과 subtitleLines·durationSec·filePath를 stitch_timeline에 그대로 넘기세요 (웹 쇼츠 스튜디오와 동일한 정렬 방식). 사용자가 보이스를 지정하지 않았다면 먼저 recommend_voice(provider=elevenlabs)로 자동 선정하세요.",
     {
       text: z.string().describe("내레이션 텍스트"),
       voice: z.string().optional().describe("보이스 이름 또는 ID (생략 시 기본 보이스)"),
@@ -1082,7 +1103,7 @@ export function registerCloudTools(server, config, api) {
   // ── TTS 보이스 카탈로그 ──────────────────────────────────────────────────────
   server.tool(
     "tts_list_voices",
-    "TTS 보이스 목록을 조회합니다. tts_narration의 voice에 넣을 이름을 고를 때 사용하세요. (voice를 생략하면 서버가 기본 보이스로 합성합니다)",
+    "TTS 보이스 목록을 조회합니다. 사용자가 목록에서 직접 고르고 싶어할 때 쓰세요 — 주제·샘플 영상 기반 자동 선정은 recommend_voice가 담당합니다. (voice를 생략하면 서버가 기본 보이스로 합성합니다)",
     {
       provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
     },
@@ -1101,6 +1122,66 @@ export function registerCloudTools(server, config, api) {
     }),
   );
 
+  server.tool(
+    "recommend_voice",
+    "주제·대본과 사용자가 샘플로 지정한 영상(유튜브)에 어울리는 TTS 보이스를 LLM이 자동 선정합니다. 사용자가 보이스를 직접 지정하지 않았다면 tts_narration/tts_narration_with_captions 전에 이 도구를 호출해 recommendations[0].voiceId를 voice로 쓰세요. 샘플 영상이 있으면 컴패니언 앱이 화자 음성을 추출·분석해 가장 비슷한 보이스를 우선합니다(컴패니언 미실행 시 주제 기반으로만 추천).",
+    {
+      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 = "" }) => {
+      const notes = [];
+      let sampleAudioBase64 = "";
+      const rawSample = String(sampleVideoUrl || "").trim();
+      if (rawSample) {
+        // 모바일/뮤직/shorts/youtu.be 변형을 표준 watch URL 로 정규화 — 컴패니언의
+        // 유튜브 전용 처리(봇 우회)가 표준 형태에서만 발동한다.
+        const watchUrl = canonicalYoutubeWatchUrl(rawSample);
+        if (!watchUrl) {
+          return textResult("sampleVideoUrl은 유튜브 영상 URL 또는 11자 영상 ID여야 합니다.", { isError: true });
+        }
+        try {
+          // 컴패니언(사용자 PC)이 오디오를 추출 — 90초로 잘라 서버 본문 상한·분석 비용을 지킨다.
+          const wav = await extractCompanionAudio(config.companionUrl, { url: watchUrl });
+          sampleAudioBase64 = trimWavToSeconds(wav, 90).toString("base64");
+        } catch (error) {
+          notes.push(
+            `샘플 오디오 추출 실패(${String(error?.message || error)}) — 컴패니언 앱 실행 여부를 확인하세요. 주제 기반으로만 추천합니다.`,
+          );
+        }
+      }
+      if (!topic && !scriptExcerpt && !sampleVoiceHints && !sampleAudioBase64) {
+        // 샘플만 줬는데 추출이 실패한 경우: 누락 안내가 아니라 실패 사유를 그대로 전달한다.
+        if (notes.length) {
+          return textResult(`${notes.join("\n")}\n주제(topic)를 함께 주면 샘플 없이도 추천할 수 있습니다.`, { isError: true });
+        }
+        return textResult("topic, scriptExcerpt, sampleVoiceHints, sampleVideoUrl 중 하나는 필요합니다.", { isError: true });
+      }
+      const payload = await api.request("/api/tracker/tts/recommend-voice", {
+        body: { provider, sampleAudioBase64, sampleVoiceHints, scriptExcerpt, topic },
+        method: "POST",
+        timeoutMs: 180_000,
+      });
+      if (payload?.ok === false) {
+        return textResult(
+          `보이스 추천 실패: ${payload?.error || "알 수 없는 오류"}\n${payload?.guidance || ""}`.trim(),
+          { isError: true },
+        );
+      }
+      return jsonResult({
+        next: "recommendations[0].voiceId를 tts_narration 또는 tts_narration_with_captions의 voice로 사용하세요.",
+        notes: [...notes, ...(Array.isArray(payload?.notes) ? payload.notes : [])],
+        provider: payload?.provider || provider,
+        recommendations: Array.isArray(payload?.recommendations) ? payload.recommendations : [],
+        sampleAnalyzed: Boolean(sampleAudioBase64 && payload?.sampleVoiceProfile),
+        sampleVoiceProfile: payload?.sampleVoiceProfile || null,
+      });
+    }),
+  );
+
   // ── 상세페이지(PDP) ─────────────────────────────────────────────────────────
   server.tool(
     "generate_pdp",

package/lib/companion-client.mjs

@@ -69,6 +69,62 @@ export async function triageCompanion(companionUrl) {
   };
 }
 
+// 유튜브 URL에서 16kHz mono PCM WAV 를 추출한다 — 보이스 샘플 분석용.
+// 컴패니언이 로컬(사용자 PC)에서 yt-dlp+ffmpeg 를 돌리므로 서버측 유튜브 차단을 우회한다.
+// 컴패니언은 영상 전체 오디오를 반환(긴 영상이면 시간당 ~115MB WAV)하므로,
+// 앞 maxBytes 만 스트리밍으로 받고 끊는다 — 필요한 건 앞 90초뿐이다.
+export async function extractCompanionAudio(
+  companionUrl,
+  { url, sampleRate = 16000, timeoutMs = 180_000, maxBytes = 8 * 1024 * 1024 } = {},
+) {
+  const response = await fetch(`${companionUrl}/api/audio/extract`, {
+    body: JSON.stringify({ filenameHint: "voice-sample", sampleRate, url }),
+    headers: { "Content-Type": "application/json" },
+    method: "POST",
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) {
+    // 컴패니언은 실패 사유를 JSON {error}로 준다 — yt-dlp 차단/URL 문제를 행동 가능하게 전달.
+    let detail = "";
+    try {
+      const text = await response.text();
+      try {
+        detail = String(JSON.parse(text)?.error || "").trim();
+      } catch {
+        detail = text.slice(0, 200).trim();
+      }
+    } catch {
+      detail = "";
+    }
+    throw new Error(`컴패니언 오디오 추출 실패 (HTTP ${response.status}${detail ? `: ${detail}` : ""})`);
+  }
+  if (!response.body) {
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (!buffer.length) throw new Error("컴패니언이 빈 오디오를 반환했습니다.");
+    return buffer.subarray(0, maxBytes);
+  }
+  const reader = response.body.getReader();
+  const parts = [];
+  let received = 0;
+  try {
+    while (received < maxBytes) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (value?.length) {
+        parts.push(Buffer.from(value));
+        received += value.length;
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => {});
+  }
+  const buffer = Buffer.concat(parts).subarray(0, maxBytes);
+  if (!buffer.length) {
+    throw new Error("컴패니언이 빈 오디오를 반환했습니다.");
+  }
+  return buffer;
+}
+
 export async function createRenderJob(companionUrl, payload) {
   return requestJson(companionUrl, "/api/moviepy/render-jobs", {
     body: payload,

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.4.3";
+export const MCP_PROXY_VERSION = "0.6.0";
 
 export const DEFAULT_API_BASE = "https://aimakeall.com";
 export const DEFAULT_COMPANION_URL = "http://127.0.0.1:9876";

package/lib/payload-guard.mjs

@@ -23,6 +23,44 @@ export function isAllowedYoutubeUrl(value) {
   }
 }
 
+const YOUTUBE_VIDEO_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
+
+/**
+ * 유튜브 입력(11자 ID·youtu.be·모바일/뮤직 호스트·shorts/live/embed 경로)을
+ * 표준 www.youtube.com/watch URL 로 정규화한다. 컴패니언의 유튜브 전용 처리(봇 우회 전략)는
+ * 표준 호스트/경로에서만 발동하므로, 변형 URL 을 그대로 넘기면 조용히 품질이 떨어진다.
+ * 유튜브 영상으로 해석할 수 없으면 "" 반환.
+ */
+export function canonicalYoutubeWatchUrl(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  if (YOUTUBE_VIDEO_ID_PATTERN.test(raw)) {
+    return `https://www.youtube.com/watch?v=${raw}`;
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return "";
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return "";
+  const host = url.hostname.toLowerCase();
+  if (!ALLOWED_YOUTUBE_HOSTS.has(host)) return "";
+
+  let videoId = "";
+  if (host === "youtu.be") {
+    videoId = url.pathname.split("/").filter(Boolean)[0] || "";
+  } else {
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (url.pathname === "/watch" || url.pathname === "/watch/") {
+      videoId = url.searchParams.get("v") || "";
+    } else if (segments.length === 2 && ["shorts", "live", "embed", "v"].includes(segments[0])) {
+      videoId = segments[1];
+    }
+  }
+  return YOUTUBE_VIDEO_ID_PATTERN.test(videoId) ? `https://www.youtube.com/watch?v=${videoId}` : "";
+}
+
 function isHttpsUrl(value) {
   try {
     return new URL(String(value || "")).protocol === "https:";

package/lib/payload-guard.test.mjs

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import {
+  canonicalYoutubeWatchUrl,
   checkRenderPayloadSize,
   COMPANION_RENDER_BODY_LIMIT_BYTES,
   isAllowedYoutubeUrl,
@@ -74,3 +75,24 @@ test("출력 파일명 정화 — 금지문자 치환·길이 상한·확장자
   assert.ok(long.length <= 120);
   assert.ok(long.endsWith(".mp4"));
 });
+
+test("canonicalYoutubeWatchUrl — 변형 입력을 표준 watch URL 로 정규화", () => {
+  const canonical = "https://www.youtube.com/watch?v=jNQXAC9IVRw";
+  assert.equal(canonicalYoutubeWatchUrl("jNQXAC9IVRw"), canonical);
+  assert.equal(canonicalYoutubeWatchUrl("https://youtu.be/jNQXAC9IVRw?si=abc"), canonical);
+  assert.equal(canonicalYoutubeWatchUrl("https://www.youtube.com/watch?v=jNQXAC9IVRw&t=10s"), canonical);
+  assert.equal(canonicalYoutubeWatchUrl("https://m.youtube.com/watch?v=jNQXAC9IVRw"), canonical);
+  assert.equal(canonicalYoutubeWatchUrl("https://music.youtube.com/watch?v=jNQXAC9IVRw"), canonical);
+  assert.equal(canonicalYoutubeWatchUrl("https://www.youtube.com/shorts/jNQXAC9IVRw"), canonical);
+  assert.equal(canonicalYoutubeWatchUrl("https://www.youtube.com/live/jNQXAC9IVRw"), canonical);
+  assert.equal(canonicalYoutubeWatchUrl("https://www.youtube.com/embed/jNQXAC9IVRw"), canonical);
+});
+
+test("canonicalYoutubeWatchUrl — 유튜브가 아니거나 ID 불명이면 빈 문자열", () => {
+  assert.equal(canonicalYoutubeWatchUrl(""), "");
+  assert.equal(canonicalYoutubeWatchUrl("https://evil.com/watch?v=jNQXAC9IVRw"), "");
+  assert.equal(canonicalYoutubeWatchUrl("https://www.youtube.com/channel/UCabc"), "");
+  assert.equal(canonicalYoutubeWatchUrl("https://www.youtube.com/watch?v=short"), "");
+  assert.equal(canonicalYoutubeWatchUrl("file:///etc/passwd"), "");
+  assert.equal(canonicalYoutubeWatchUrl("그냥 텍스트"), "");
+});

package/lib/wav-trim.mjs

@@ -0,0 +1,80 @@
+// PCM WAV 앞부분 트림 — 컴패니언 /api/audio/extract 가 주는 오디오를 서버 전송 전에
+// 90초 이내로 잘라 JSON 본문 상한과 Gemini 오디오 비용을 지킨다.
+// (서버 server/voice-recommendation.mjs 의 동일 로직과 독립 구현 — 이 패키지는 npm 단독 배포)
+
+export function trimWavToSeconds(buffer, maxSeconds = 90) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 44) {
+    throw new Error("WAV 버퍼가 아닙니다.");
+  }
+  if (buffer.toString("ascii", 0, 4) !== "RIFF" || buffer.toString("ascii", 8, 12) !== "WAVE") {
+    throw new Error("RIFF/WAVE 형식이 아닙니다.");
+  }
+
+  let offset = 12;
+  let fmt = null;
+  let dataOffset = -1;
+  let dataSize = 0;
+  while (offset + 8 <= buffer.length) {
+    const chunkId = buffer.toString("ascii", offset, offset + 4);
+    const chunkSize = buffer.readUInt32LE(offset + 4);
+    const body = offset + 8;
+    if (chunkId === "fmt " && body + 16 <= buffer.length) {
+      fmt = {
+        audioFormat: buffer.readUInt16LE(body),
+        bitsPerSample: buffer.readUInt16LE(body + 14),
+        blockAlign: buffer.readUInt16LE(body + 12),
+        byteRate: buffer.readUInt32LE(body + 8),
+        numChannels: buffer.readUInt16LE(body + 2),
+        sampleRate: buffer.readUInt32LE(body + 4),
+      };
+    } else if (chunkId === "data" && dataOffset < 0) {
+      dataOffset = body;
+      dataSize = Math.min(chunkSize, buffer.length - body);
+    }
+    // 청크는 워드 정렬 — 홀수 크기면 패딩 1바이트.
+    offset = body + chunkSize + (chunkSize % 2);
+  }
+
+  if (!fmt || dataOffset < 0) {
+    throw new Error("WAV fmt/data 청크를 찾지 못했습니다.");
+  }
+  if (fmt.audioFormat !== 1) {
+    throw new Error("PCM WAV 만 지원합니다.");
+  }
+  // 헤더 필드 신뢰 범위 검증 — 조작된 byteRate 로 트림 상한을 우회하거나
+  // 파생 계산이 고정폭 헤더 쓰기를 넘치게(RangeError) 만드는 것을 차단한다.
+  if (!Number.isInteger(fmt.sampleRate) || fmt.sampleRate < 4000 || fmt.sampleRate > 192000) {
+    throw new Error(`지원하지 않는 WAV 샘플레이트입니다: ${fmt.sampleRate}`);
+  }
+  if (![8, 16, 24, 32].includes(fmt.bitsPerSample)) {
+    throw new Error(`지원하지 않는 WAV 비트수입니다: ${fmt.bitsPerSample}`);
+  }
+  if (!Number.isInteger(fmt.numChannels) || fmt.numChannels < 1 || fmt.numChannels > 8) {
+    throw new Error(`지원하지 않는 WAV 채널 수입니다: ${fmt.numChannels}`);
+  }
+
+  // byteRate 는 헤더의 자기신고 값을 무시하고 sampleRate×blockAlign 으로 파생한다 —
+  // 디코더도 같은 식으로 길이를 해석하므로, 트림 결과의 실제 재생 길이가 항상 상한 이내가 된다.
+  const blockAlign = fmt.numChannels * Math.ceil(fmt.bitsPerSample / 8);
+  const byteRate = fmt.sampleRate * blockAlign;
+  const seconds = Number.isFinite(Number(maxSeconds)) && Number(maxSeconds) > 0 ? Number(maxSeconds) : 90;
+  const rawBytes = Math.floor(byteRate * seconds);
+  const alignedBytes = Math.max(blockAlign, rawBytes - (rawBytes % blockAlign));
+  const keep = Math.min(dataSize, alignedBytes);
+
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0, "ascii");
+  header.writeUInt32LE(36 + keep, 4);
+  header.write("WAVE", 8, "ascii");
+  header.write("fmt ", 12, "ascii");
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(fmt.numChannels, 22);
+  header.writeUInt32LE(fmt.sampleRate, 24);
+  header.writeUInt32LE(byteRate, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(fmt.bitsPerSample, 34);
+  header.write("data", 36, "ascii");
+  header.writeUInt32LE(keep, 40);
+  return Buffer.concat([header, buffer.subarray(dataOffset, dataOffset + keep)]);
+}

package/lib/wav-trim.test.mjs

@@ -0,0 +1,89 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { trimWavToSeconds } from "./wav-trim.mjs";
+
+function buildTestWav({ seconds = 3, sampleRate = 16000, numChannels = 1, extraChunk = false } = {}) {
+  const blockAlign = numChannels * 2;
+  const byteRate = sampleRate * blockAlign;
+  const dataBytes = Math.floor(seconds * byteRate);
+  const chunks = [];
+
+  const fmt = Buffer.alloc(24);
+  fmt.write("fmt ", 0, "ascii");
+  fmt.writeUInt32LE(16, 4);
+  fmt.writeUInt16LE(1, 8);
+  fmt.writeUInt16LE(numChannels, 10);
+  fmt.writeUInt32LE(sampleRate, 12);
+  fmt.writeUInt32LE(byteRate, 16);
+  fmt.writeUInt16LE(blockAlign, 20);
+  fmt.writeUInt16LE(16, 22);
+  chunks.push(fmt);
+
+  if (extraChunk) {
+    const listBody = Buffer.from("INFOxyz", "ascii");
+    const list = Buffer.alloc(8 + listBody.length + (listBody.length % 2));
+    list.write("LIST", 0, "ascii");
+    list.writeUInt32LE(listBody.length, 4);
+    listBody.copy(list, 8);
+    chunks.push(list);
+  }
+
+  const data = Buffer.alloc(8 + dataBytes);
+  data.write("data", 0, "ascii");
+  data.writeUInt32LE(dataBytes, 4);
+  chunks.push(data);
+
+  const body = Buffer.concat(chunks);
+  const header = Buffer.alloc(12);
+  header.write("RIFF", 0, "ascii");
+  header.writeUInt32LE(4 + body.length, 4);
+  header.write("WAVE", 8, "ascii");
+  return Buffer.concat([header, body]);
+}
+
+function wavSeconds(buffer) {
+  return buffer.readUInt32LE(40) / buffer.readUInt32LE(28);
+}
+
+test("긴 WAV 를 지정 초로 자르고 헤더를 재구성한다", () => {
+  const wav = buildTestWav({ seconds: 300 });
+  const trimmed = trimWavToSeconds(wav, 90);
+  assert.ok(trimmed.length < wav.length);
+  assert.equal(trimmed.toString("ascii", 0, 4), "RIFF");
+  assert.ok(Math.abs(wavSeconds(trimmed) - 90) < 0.01);
+});
+
+test("짧은 WAV·부가 청크·스테레오도 안전하게 처리한다", () => {
+  const short = trimWavToSeconds(buildTestWav({ seconds: 2 }), 90);
+  assert.ok(Math.abs(wavSeconds(short) - 2) < 0.01);
+
+  const listed = trimWavToSeconds(buildTestWav({ seconds: 5, extraChunk: true }), 2);
+  assert.ok(Math.abs(wavSeconds(listed) - 2) < 0.01);
+
+  const stereo = trimWavToSeconds(buildTestWav({ seconds: 6, numChannels: 2 }), 2);
+  assert.equal(stereo.readUInt32LE(40) % 4, 0);
+});
+
+test("비정상 입력은 명시적으로 거부한다", () => {
+  assert.throws(() => trimWavToSeconds(Buffer.from("nope"), 90), /WAV/);
+  assert.throws(() => trimWavToSeconds(Buffer.alloc(100), 90), /RIFF/);
+  const nonPcm = buildTestWav({ seconds: 1 });
+  nonPcm.writeUInt16LE(3, 20);
+  assert.throws(() => trimWavToSeconds(nonPcm, 90), /PCM/);
+});
+
+test("조작된 byteRate 로 트림 상한을 우회할 수 없고, 범위 밖 헤더는 한국어 오류", () => {
+  const lying = buildTestWav({ seconds: 300 });
+  lying.writeUInt32LE(0xffffffff, 28); // byteRate 거짓 신고
+  const trimmed = trimWavToSeconds(lying, 90);
+  assert.equal(trimmed.readUInt32LE(40), 90 * 16000 * 2, "파생 byteRate 기준 90초로 잘려야 한다");
+
+  const badRate = buildTestWav({ seconds: 1 });
+  badRate.writeUInt32LE(0xffffffff, 24);
+  assert.throws(() => trimWavToSeconds(badRate, 90), /샘플레이트/);
+
+  const badChannels = buildTestWav({ seconds: 1 });
+  badChannels.writeUInt16LE(65535, 22);
+  assert.throws(() => trimWavToSeconds(badChannels, 90), /채널/);
+});

package/package.json

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