aimakeall-mcp 0.1.0 → 0.3.0

package/README.md

@@ -16,7 +16,7 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
   "mcpServers": {
     "aimakeall": {
       "command": "npx",
-      "args": ["-y", "aimakeall-mcp@0.1.0"],
+      "args": ["-y", "aimakeall-mcp@0.3.0"],
       "env": { "AIMAKEALL_PAT": "aio_pat_..." }
     }
   }

package/lib/api-client.mjs

@@ -139,5 +139,77 @@ export function createApiClient({ apiBase, pat }) {
     return payload;
   }
 
-  return { request, requestBinary, requestStreamUpload };
+  // SSE(text/event-stream) 라우트 — `data: {json}` 프레임을 순서대로 파싱한다.
+  // 서버는 게이트(인증/플랜/기계정책) 실패는 SSE 이전 일반 JSON 으로, 그 이후의
+  // 실패는 HTTP 200 스트림 안 {type:"error"} 프레임으로 보낸다. 둘 다 예외로 변환.
+  async function requestSse(pathName, { body, timeoutMs = DEFAULT_TIMEOUT_MS, onEvent } = {}) {
+    const response = await fetch(`${apiBase}${pathName}`, {
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+      headers: {
+        Authorization: `Bearer ${pat}`,
+        "X-AImakeAll-MCP-Version": MCP_PROXY_VERSION,
+        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+      },
+      method: "POST",
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    const contentType = String(response.headers.get("content-type") || "");
+    if (!contentType.includes("text/event-stream")) {
+      const text = await response.text();
+      let payload = null;
+      try {
+        payload = text ? JSON.parse(text) : null;
+      } catch {
+        payload = null;
+      }
+      throw new AimakeallApiError(describeApiFailure(response.status, payload), {
+        errorCode: String(payload?.error || ""),
+        retryAfterSeconds: Number(payload?.retryAfterSeconds) || 0,
+        status: response.status,
+      });
+    }
+    const events = [];
+    let result = null;
+    let buffer = "";
+    const decoder = new TextDecoder();
+    try {
+    for await (const chunk of response.body) {
+      buffer += decoder.decode(chunk, { stream: true });
+      let frameEnd;
+      while ((frameEnd = buffer.indexOf("\n\n")) >= 0) {
+        const frame = buffer.slice(0, frameEnd);
+        buffer = buffer.slice(frameEnd + 2);
+        for (const line of frame.split("\n")) {
+          if (!line.startsWith("data:")) continue;
+          let payload = null;
+          try {
+            payload = JSON.parse(line.slice(5).trim());
+          } catch {
+            continue;
+          }
+          if (!payload || typeof payload !== "object") continue;
+          if (payload.type === "error") {
+            throw new AimakeallApiError(String(payload.message || payload.error || "스트리밍 생성 중 오류가 발생했습니다."), {
+              errorCode: "SSE_ERROR",
+              status: 200,
+            });
+          }
+          events.push(payload);
+          if (payload.type === "result") result = payload.result;
+          onEvent?.(payload);
+        }
+      }
+    }
+    } catch (error) {
+      if (error instanceof AimakeallApiError) throw error;
+      // 스트림 중단(idle timeout·네트워크) — 서버에서는 생성이 계속 완료·과금됐을 수 있다.
+      throw new AimakeallApiError(
+        "스트리밍 수신이 중단되었습니다. 서버에서는 생성이 계속 완료되어 과금됐을 수 있으니, 무작정 재시도하지 말고 계정 사용량/결과를 먼저 확인하세요.",
+        { errorCode: "SSE_INTERRUPTED", status: 0 },
+      );
+    }
+    return { events, result };
+  }
+
+  return { request, requestBinary, requestSse, requestStreamUpload };
 }

package/lib/cloud-tools.mjs

@@ -13,6 +13,7 @@ import {
   encodedDataUrlBytes,
   fileToDataUrl,
   fileToImagePayload,
+  guessMimeType,
   saveMediaBuffer,
   savePayloadHandle,
   SERVER_JSON_BODY_LIMIT_BYTES,
@@ -129,7 +130,7 @@ export function registerCloudTools(server, config, api) {
     {
       topic: z.string().optional().describe("영상 주제"),
       copy: z.string().optional().describe("핵심 카피/대사"),
-      categoryId: z.enum(["community-shorts", "viral-shorts"]).optional().describe("기본 community-shorts"),
+      categoryId: z.enum(["community-shorts", "viral-shorts", "insight"]).optional().describe("기본 community-shorts. insight=명언(통찰) 쇼츠"),
       targetCustomer: z.string().optional(),
       tone: z.string().optional().describe("기본 '자동 추천'"),
       sceneCount: z.number().int().min(1).max(10).optional().describe("기본 3"),
@@ -496,7 +497,7 @@ export function registerCloudTools(server, config, api) {
         endSec: z.number(),
         startSec: z.number(),
         text: z.string(),
-      })).optional().describe("자막 타이밍 (쇼츠)"),
+      })).optional().describe("자막 타이밍 (쇼츠 하단자막) — tts_narration_with_captions의 subtitleLines를 그대로 사용"),
       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" }) => {
@@ -641,4 +642,642 @@ export function registerCloudTools(server, config, api) {
       });
     }),
   );
+
+  // ── 대본(Script Studio) — 스타일별 지침 자동 적용 ────────────────────────────
+  server.tool(
+    "write_script",
+    "대본을 생성합니다 (스크립트 스튜디오). 스타일별 전용 지침이 자동 적용됩니다: standard(스탠다드)/senior(시니어)/insight(명언·통찰)/webnovel(웹소설)/christian(기독교)/community-shorts/viral-shorts. 스탠다드·시니어·명언은 실시간 리서치가 함께 수행됩니다. 부동산·상권 분석 대본은 전용 도구(write_real_estate_report/write_market_analysis)를 쓰세요.",
+    {
+      title: z.string().describe("영상 제목/주제"),
+      storyText: z.string().optional().describe("핵심 줄거리·내용 브리프"),
+      styleId: z.enum(["standard", "senior", "insight", "webnovel", "christian", "community-shorts", "viral-shorts"]).optional().describe("기본 standard. senior=시니어(쉽고 친절), insight=명언(통찰)"),
+      model: z.enum(["gemini", "opus", "sonnet"]).optional().describe("기본 gemini(가성비). opus/sonnet=Claude"),
+      targetLength: z.number().int().min(500).max(20000).optional().describe("목표 글자수, 기본 5000"),
+      targetLanguageLabel: z.string().optional().describe("출력 언어 라벨, 기본 '한국 (한국어)'"),
+      contentFormat: z.enum(["longform", "shortform"]).optional().describe("기본 longform (standard/senior/insight는 항상 longform)"),
+      webnovelSubtypeId: z.enum(["modern-webnovel", "regression-fantasy", "romance-fantasy", "martial-arts", "light-novel", "hunter-fantasy", "revenge-soda", "healing-daily", "relationship-drama", "literary-serial"]).optional().describe("styleId=webnovel일 때 장르"),
+      christianContentType: z.enum(["youtube-narration", "prayer", "devotional", "comfort-message"]).optional().describe("styleId=christian일 때 유형"),
+      insightFigureNames: z.string().optional().describe("styleId=insight일 때 인물명(쉼표 구분)"),
+      userOpinion: z.string().optional().describe("본문에 자연스럽게 녹일 작성자 의견"),
+    },
+    wrapCloudHandler(config, async ({
+      title,
+      storyText = "",
+      styleId = "standard",
+      model = "gemini",
+      targetLength = 5000,
+      targetLanguageLabel = "한국 (한국어)",
+      contentFormat = "longform",
+      webnovelSubtypeId = "modern-webnovel",
+      christianContentType = "youtube-narration",
+      insightFigureNames = "",
+      userOpinion = "",
+    }) => {
+      const SCRIPT_MODEL_MAP = { gemini: "gemini-3.5-flash", opus: "claude-opus-4-8", sonnet: "claude-sonnet-5" };
+      const payload = await api.request("/api/tracker/ai/script", {
+        body: {
+          apiModel: SCRIPT_MODEL_MAP[model] || SCRIPT_MODEL_MAP.gemini,
+          channelStyleProfile: null,
+          channelStyleReferenceText: "",
+          christianContentType,
+          contentFormat,
+          generationIntent: "new",
+          insightFigureMode: insightFigureNames.trim() ? "blend" : "auto",
+          insightFigureNames,
+          insightToneMode: "warm",
+          modelKey: model,
+          personas: [],
+          previousScript: "",
+          selectedStyleId: styleId,
+          storyMemory: null,
+          storyText,
+          targetLanguageLabel,
+          targetLength,
+          title,
+          userOpinion,
+          webnovelSubtypeId,
+        },
+        method: "POST",
+        timeoutMs: 240_000,
+      });
+      const text = String(payload?.text || "").trim();
+      if (!text) return textResult("대본 생성 결과가 비어 있습니다. 제목/브리프를 보강해 다시 시도하세요.", { isError: true });
+      return jsonResult({ model: payload?.model, styleId, text });
+    }),
+  );
+
+  server.tool(
+    "write_real_estate_report",
+    "부동산(아파트/빌라/지역) 종합분석 나레이션 대본을 생성합니다 (Gemini 검색 리서치 기반). primaryTarget/region/title/storyText 중 하나 이상은 필수입니다.",
+    {
+      analysisType: z.enum(["apartment-report", "region-recommend", "comparison", "price-check", "outlook", "policy", "villa", "fact-check"]).optional().describe("기본 apartment-report"),
+      primaryTarget: z.string().optional().describe("주요 대상 단지/지역"),
+      secondaryTarget: z.string().optional().describe("비교 대상 (analysisType=comparison이면 필수)"),
+      region: z.string().optional().describe("지역/생활권"),
+      title: z.string().optional().describe("브리프 제목"),
+      storyText: z.string().optional().describe("핵심 브리프"),
+      purpose: z.enum(["investment", "owner-occupancy", "move-up", "verification"]).optional().describe("기본 investment"),
+      budget: z.string().optional().describe("예산/가격대"),
+      notes: z.string().optional(),
+      targetLength: z.number().int().min(500).max(20000).optional().describe("목표 글자수, 기본 5000"),
+      targetLanguageLabel: z.string().optional().describe("기본 '한국 (한국어)'"),
+    },
+    wrapCloudHandler(config, async ({ analysisType = "apartment-report", primaryTarget = "", secondaryTarget = "", region = "", title = "", storyText = "", purpose = "investment", budget = "", notes = "", targetLength = 5000, targetLanguageLabel = "한국 (한국어)" }) => {
+      if (![primaryTarget, region, title, storyText].some((value) => String(value).trim())) {
+        return textResult("primaryTarget/region/title/storyText 중 하나는 입력해야 합니다.", { isError: true });
+      }
+      if (analysisType === "comparison" && !String(secondaryTarget).trim()) {
+        return textResult("analysisType=comparison에는 secondaryTarget(비교 대상)이 필수입니다.", { isError: true });
+      }
+      const payload = await api.request("/api/tracker/ai/real-estate-report", {
+        body: {
+          analysisType,
+          apiModel: "gemini-3.5-flash",
+          budget,
+          channelStyleProfile: null,
+          channelStyleReferenceText: "",
+          modelKey: "gemini",
+          notes,
+          personas: [],
+          primaryTarget,
+          purpose,
+          region,
+          secondaryTarget,
+          storyText,
+          targetLanguageLabel,
+          targetLength,
+          title,
+        },
+        method: "POST",
+        timeoutMs: 240_000,
+      });
+      const text = String(payload?.text || "").trim();
+      if (!text) return textResult("부동산 분석 대본 결과가 비어 있습니다.", { isError: true });
+      return jsonResult({ analysisType, model: payload?.model, researchQueries: payload?.research?.performedQueryCount, text });
+    }),
+  );
+
+  server.tool(
+    "write_market_analysis",
+    "상권 분석 나레이션 대본을 생성합니다 (Gemini 검색 리서치 기반). primaryTarget/businessType/title/storyText 중 하나 이상은 필수입니다.",
+    {
+      analysisType: z.string().optional().describe("기본 commercial-district-report"),
+      primaryTarget: z.string().optional().describe("주요 상권/지역"),
+      secondaryTarget: z.string().optional().describe("비교 상권 (comparison이면 필수)"),
+      businessType: z.string().optional().describe("업종/업태 (예: 카페, 편의점)"),
+      title: z.string().optional().describe("브리프 제목"),
+      storyText: z.string().optional().describe("핵심 브리프"),
+      purpose: z.enum(["startup", "investment", "site-selection", "verification"]).optional().describe("기본 startup"),
+      budget: z.string().optional().describe("예산/운영 여력"),
+      notes: z.string().optional(),
+      targetLength: z.number().int().min(500).max(20000).optional().describe("목표 글자수, 기본 5000"),
+      targetLanguageLabel: z.string().optional().describe("기본 '한국 (한국어)'"),
+    },
+    wrapCloudHandler(config, async ({ analysisType = "commercial-district-report", primaryTarget = "", secondaryTarget = "", businessType = "", title = "", storyText = "", purpose = "startup", budget = "", notes = "", targetLength = 5000, targetLanguageLabel = "한국 (한국어)" }) => {
+      if (![primaryTarget, businessType, title, storyText].some((value) => String(value).trim())) {
+        return textResult("primaryTarget/businessType/title/storyText 중 하나는 입력해야 합니다.", { isError: true });
+      }
+      if (analysisType === "comparison" && !String(secondaryTarget).trim()) {
+        return textResult("analysisType=comparison에는 secondaryTarget(비교 상권)이 필수입니다.", { isError: true });
+      }
+      const payload = await api.request("/api/tracker/ai/market-analysis", {
+        body: {
+          analysisType,
+          apiModel: "gemini-3.5-flash",
+          budget,
+          businessType,
+          channelStyleProfile: null,
+          channelStyleReferenceText: "",
+          modelKey: "gemini",
+          notes,
+          personas: [],
+          primaryTarget,
+          purpose,
+          secondaryTarget,
+          storyText,
+          targetLanguageLabel,
+          targetLength,
+          title,
+        },
+        method: "POST",
+        timeoutMs: 240_000,
+      });
+      const text = String(payload?.text || "").trim();
+      if (!text) return textResult("상권 분석 대본 결과가 비어 있습니다.", { isError: true });
+      return jsonResult({ analysisType, model: payload?.model, researchQueries: payload?.research?.performedQueryCount, text });
+    }),
+  );
+
+  // ── 뮤직비디오 기획 ──────────────────────────────────────────────────────────
+  server.tool(
+    "plan_music_video",
+    "뮤직비디오 씬 플랜을 생성합니다. suno_music_download로 받은 곡의 가사·길이(durationSec)를 입력하세요. 결과 scenes의 imagePrompt는 generate_scene_image로 이어집니다.",
+    {
+      durationSec: z.number().min(10).describe("곡 길이(초) — suno_music_download 결과의 durationSec"),
+      lyrics: z.string().optional().describe("가사 전체 (instrumental이면 생략 가능)"),
+      conceptBrief: z.string().optional().describe("영상 컨셉 브리프"),
+      instrumental: z.boolean().optional().describe("연주곡 여부, 기본 false"),
+      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"),
+      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" }) => {
+      if (!instrumental && !String(lyrics).trim()) {
+        return textResult("lyrics를 입력하거나 instrumental=true로 지정하세요.", { isError: true });
+      }
+      const payload = await api.request("/api/tracker/music-video/plan", {
+        body: {
+          alignedLines: [],
+          aspectRatio,
+          conceptBrief,
+          durationSec,
+          instrumental,
+          lyrics,
+          sceneSeconds,
+          selectedCharacters: [],
+          songMeta: {},
+          splitMode,
+          videoStylePreset,
+        },
+        method: "POST",
+        timeoutMs: 240_000,
+      });
+      // usage/원장 이벤트 등 컨텍스트 낭비 필드는 제거하고 기획 본문만 돌려준다.
+      const { accountCostEvents, providerUsage, usage, ...plan } = payload && typeof payload === "object" ? payload : {};
+      return jsonResult(plan);
+    }),
+  );
+
+  // ── 짜집기 편집점 분석 (티키타카 편집점 지침) ────────────────────────────────
+  server.tool(
+    "analyze_edit_points",
+    "짜집기(리메이크)용 편집점 분석 — 티키타카 편집점 지침으로 원본 YouTube 영상의 장면 카탈로그(sceneCatalog)를 만듭니다. 전사는 자동 확보합니다. 컷 정확도를 높이려면 detect_shots(로컬 컴패니언)로 만든 shotsFile 경로를 videoId별로 넘기세요.",
+    {
+      videos: z.array(z.object({
+        id: z.string().describe("YouTube video id"),
+        title: z.string().optional(),
+        channel: z.string().optional(),
+        durationSeconds: z.number().optional(),
+      })).min(1).max(5).describe("분석할 원본 영상 (최대 5편)"),
+      shotsFiles: z.record(z.string()).optional().describe("videoId → detect_shots가 저장한 shots JSON 파일 경로"),
+    },
+    wrapCloudHandler(config, async ({ videos, shotsFiles = {} }) => {
+      // 1) 실제 오디오 전사 확보 — 편집점 분류([N]/[S]/[A])의 핵심 신호.
+      // 서버가 오디오 다운로드+Gemini 전사를 수행하므로 영상당 수 분 걸릴 수 있다.
+      const transcriptPayload = await api.request("/api/tracker/youtube/transcripts", {
+        body: { videos: videos.map((video) => ({ channel: video.channel || "", id: video.id, title: video.title || "" })) },
+        method: "POST",
+        timeoutMs: 600_000,
+      });
+      const transcriptMap = new Map(
+        (transcriptPayload?.items || []).map((item) => [item.videoId, Array.isArray(item.segments) ? item.segments : []]),
+      );
+
+      // 2) 컴패니언 샷 파일 로드 (imageBase64 포함) — 있으면 서버가 실제 컷 기준으로 분석.
+      const preDetectedShots = {};
+      for (const [videoId, filePath] of Object.entries(shotsFiles)) {
+        const parsed = JSON.parse(readFileSync(String(filePath), "utf8"));
+        const shots = Array.isArray(parsed) ? parsed : Array.isArray(parsed?.shots) ? parsed.shots : [];
+        if (shots.length) preDetectedShots[videoId] = shots;
+      }
+
+      const body = {
+        preDetectedShots: Object.keys(preDetectedShots).length ? preDetectedShots : null,
+        videos: videos.map((video) => ({
+          channel: video.channel || "",
+          durationSeconds: Number(video.durationSeconds) || 0,
+          frameSamples: [],
+          id: video.id,
+          title: video.title || "",
+          transcriptSegments: transcriptMap.get(video.id) || [],
+        })),
+      };
+      if (Buffer.byteLength(JSON.stringify(body), "utf8") > BODY_BUDGET_BYTES) {
+        return textResult("샷 이미지 총량이 서버 상한을 초과합니다. 영상 수 또는 detect_shots의 maxShots를 줄이세요.", { isError: true });
+      }
+
+      const payload = await api.request("/api/tracker/gemini/video-analysis", { body, method: "POST", timeoutMs: 240_000 });
+      const hadShots = Object.keys(preDetectedShots).length > 0;
+      // 이미지/전사 원문은 빼고 편집점 정보만 컨텍스트로 반환.
+      // sceneCatalog 필드명은 서버 sanitizeSceneCatalogItem 과 정확히 일치해야 한다.
+      return jsonResult({
+        summaryBody: payload?.summaryBody,
+        summaryHeadline: payload?.summaryHeadline,
+        videos: (payload?.videos || []).map((video) => ({
+          angle: video?.angle,
+          hook: video?.hook,
+          id: video?.id,
+          keywords: video?.keywords,
+          recommendedPreset: video?.recommendedPreset,
+          sceneCatalog: (video?.sceneCatalog || []).map((scene) => ({
+            actionTags: scene?.actionTags,
+            ambienceScore: scene?.ambienceScore,
+            dialogueVisualScore: scene?.dialogueVisualScore,
+            emotionTags: scene?.emotionTags,
+            endMs: scene?.endMs,
+            moodTags: scene?.moodTags,
+            narrationFit: scene?.narrationFit,
+            narrationFitScore: scene?.narrationFitScore,
+            shotId: scene?.shotId,
+            shortLabel: scene?.shortLabel,
+            startMs: scene?.startMs,
+            timecodeLabel: scene?.timecodeLabel,
+            visualSummary: scene?.visualSummary,
+          })),
+        })),
+        ...(hadShots ? {} : {
+          warning: "shotsFiles 없이 분석했습니다 — 장면 타임스탬프는 추정치입니다. 정확한 컷 기준 편집점이 필요하면 detect_shots(로컬 컴패니언)로 샷을 감지해 shotsFiles로 넘기세요.",
+        }),
+      });
+    }),
+  );
+
+  // ── 시간 동기 자막 TTS — 쇼츠 하단자막용 ─────────────────────────────────────
+  server.tool(
+    "tts_narration_with_captions",
+    "ElevenLabs TTS를 char-level 타이밍과 함께 합성해 mp3 파일 + 시간 동기 자막 라인(subtitleLines)을 만듭니다. 쇼츠 하단자막이 필요하면 tts_narration 대신 이걸 쓰고, 결과 subtitleLines·durationSec·filePath를 stitch_timeline에 그대로 넘기세요 (웹 쇼츠 스튜디오와 동일한 정렬 방식).",
+    {
+      text: z.string().describe("내레이션 텍스트"),
+      voice: z.string().optional().describe("보이스 이름 또는 ID (생략 시 기본 보이스)"),
+      speed: z.number().optional().describe("기본 1 (0.7~1.2)"),
+    },
+    wrapCloudHandler(config, async ({ text, voice = "", speed = 1 }) => {
+      const payload = await api.request("/api/tracker/tts/elevenlabs-with-timestamps", {
+        body: {
+          costEventId: createUsageEventId("mcp-tts-elevenlabs-ts"),
+          languageCode: "ko",
+          speed,
+          text,
+          voice,
+        },
+        method: "POST",
+        timeoutMs: 180_000,
+      });
+      const audioBase64 = String(payload?.audioBase64 || "");
+      if (!audioBase64) {
+        return textResult("TTS 합성 결과가 비어 있습니다. ElevenLabs API 키 연결 여부를 확인하세요.", { isError: true });
+      }
+      const saved = saveMediaBuffer(config.stateDir, "narration-captions.mp3", Buffer.from(audioBase64, "base64"), { contentType: "audio/mpeg" });
+      const subtitleLines = (Array.isArray(payload?.alignedLines) ? payload.alignedLines : [])
+        .map((line) => ({
+          endSec: Number(line?.endSec) || 0,
+          startSec: Number(line?.startSec) || 0,
+          text: String(line?.text || "").trim(),
+        }))
+        .filter((line) => line.text && line.endSec > line.startSec);
+      const charEnds = payload?.alignment?.character_end_times_seconds;
+      const durationSec = Array.isArray(charEnds) && charEnds.length
+        ? Math.round(Number(charEnds[charEnds.length - 1]) * 10) / 10
+        : audioDurationSecFromFile(saved.filePath);
+      return jsonResult({
+        durationSec,
+        filePath: saved.filePath,
+        lineCount: subtitleLines.length,
+        subtitleLines,
+      });
+    }),
+  );
+
+  // ── TTS 보이스 카탈로그 ──────────────────────────────────────────────────────
+  server.tool(
+    "tts_list_voices",
+    "TTS 보이스 목록을 조회합니다. tts_narration의 voice에 넣을 이름을 고를 때 사용하세요. (voice를 생략하면 서버가 기본 보이스로 합성합니다)",
+    {
+      provider: z.enum(["typecast", "elevenlabs"]).optional().describe("기본 typecast"),
+    },
+    wrapCloudHandler(config, async ({ provider = "typecast" }) => {
+      const payload = await api.request(`/api/tracker/tts/${provider}/voices`, { method: "GET", timeoutMs: 30_000 });
+      // ElevenLabs 는 gender/age 가 labels 객체 안에 있다 — 두 공급자 형태 모두 지원.
+      const voices = (Array.isArray(payload?.voices) ? payload.voices : []).slice(0, 80).map((voice) => ({
+        age: voice?.age || voice?.labels?.age,
+        description: voice?.description || undefined,
+        gender: voice?.gender || voice?.labels?.gender,
+        name: voice?.voiceName || voice?.name,
+        nameKo: voice?.voiceNameKo,
+        voiceId: voice?.voiceId,
+      }));
+      return jsonResult({ count: voices.length, provider, voices });
+    }),
+  );
+
+  // ── 인플루언서(소울) 스튜디오 ────────────────────────────────────────────────
+  server.tool(
+    "create_influencer_character",
+    "참조 사진으로 인플루언서(소울) 캐릭터를 학습 등록합니다. 학습 비용 $2.50(1회성) — 실패 시 자동 재시도 금지(중복 과금). 등록 후 influencer_character_status로 completed까지 10초 간격 폴링하세요 (수 분 소요).",
+    {
+      name: z.string().min(1).describe("캐릭터 이름"),
+      photoPaths: z.array(z.string()).min(5).max(18).describe("동일 인물 사진 로컬 경로 5~18장 (jpg/png/webp)"),
+    },
+    wrapCloudHandler(config, async ({ name, photoPaths }) => {
+      for (const filePath of photoPaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "참조 사진" });
+      const publicUrls = [];
+      // 업로드 URL 발급은 사진 수만큼 쓰기 슬롯(20/분)을 쓰므로, 분당 한도에 걸리면
+      // retryAfterSeconds 만큼 대기 후 이어서 진행한다(발급된 URL 은 보존).
+      const issueUploadUrl = async (mime) => {
+        for (let attempt = 0; ; attempt += 1) {
+          try {
+            return await api.request("/api/tracker/higgsfield/files/generate-upload-url", {
+              body: { content_type: mime },
+              method: "POST",
+              timeoutMs: 30_000,
+            });
+          } catch (error) {
+            if (error instanceof AimakeallApiError && error.errorCode === "MACHINE_RATE_LIMITED" && attempt < 3) {
+              await new Promise((resolve) => setTimeout(resolve, Math.max(1, error.retryAfterSeconds || 10) * 1000));
+              continue;
+            }
+            throw error;
+          }
+        }
+      };
+      // presigned PUT(직접) — 컴패니언 불필요.
+      for (const filePath of photoPaths) {
+        const mime = guessMimeType(filePath, "image/jpeg");
+        const issued = await issueUploadUrl(mime);
+        const uploadUrl = String(issued?.upload_url || "");
+        const publicUrl = String(issued?.public_url || "");
+        if (!uploadUrl || !publicUrl) {
+          return textResult("업로드 URL 발급에 실패했습니다. Higgsfield API 키 연결을 확인하세요.", { isError: true });
+        }
+        const put = await fetch(uploadUrl, {
+          body: readFileSync(filePath),
+          headers: { "Content-Type": mime },
+          method: "PUT",
+          signal: AbortSignal.timeout(120_000),
+        });
+        if (!put.ok) {
+          return textResult(`사진 업로드 실패 (HTTP ${put.status}): ${path.basename(filePath)}`, { isError: true });
+        }
+        publicUrls.push(publicUrl);
+      }
+      let payload;
+      try {
+        // 서버의 업스트림 창(90s)보다 길게 잡아, 클라이언트가 먼저 끊어 "성공했는데
+        // 실패로 오인 → 재시도 → 중복 과금($2.50)" 되는 상황을 방지한다.
+        payload = await api.request("/api/tracker/higgsfield/v1/custom-references", {
+          body: { input_images: publicUrls.map((url) => ({ image_url: url, type: "image_url" })), name },
+          method: "POST",
+          timeoutMs: 120_000,
+        });
+      } catch (error) {
+        const reason = String(error?.message || error);
+        return textResult(
+          `캐릭터 학습 등록 요청이 실패했습니다: ${reason}\n재시도 전에 반드시 list_influencer_characters로 캐릭터가 이미 생성됐는지 확인하세요 — 생성돼 있다면 재시도는 중복 과금($2.50)입니다.`,
+          { isError: true },
+        );
+      }
+      const referenceId = String(payload?.id || payload?.reference_id || "");
+      if (!referenceId) return textResult("캐릭터 학습 등록 응답에 ID가 없습니다. list_influencer_characters로 생성 여부를 확인하세요.", { isError: true });
+      return jsonResult({
+        costUsd: payload?.costUsd,
+        next: "influencer_character_status를 10초 간격으로 폴링해 completed를 기다리세요. 이 호출을 재시도하면 중복 과금됩니다.",
+        photoCount: publicUrls.length,
+        referenceId,
+        status: payload?.status,
+      });
+    }),
+  );
+
+  server.tool(
+    "influencer_character_status",
+    "소울 캐릭터 학습 상태를 조회합니다 (terminal: completed | failed).",
+    { referenceId: z.string().min(1) },
+    wrapCloudHandler(config, async ({ referenceId }) => {
+      const payload = await api.request(`/api/tracker/higgsfield/v1/custom-references/${encodeURIComponent(referenceId)}`, {
+        method: "GET",
+        timeoutMs: 30_000,
+      });
+      return jsonResult({
+        name: payload?.name,
+        referenceId,
+        status: payload?.status,
+        thumbnailUrl: payload?.thumbnail_url,
+      });
+    }),
+  );
+
+  server.tool(
+    "list_influencer_characters",
+    "등록된 소울 캐릭터 목록을 조회합니다. (machine 토큰은 서버 경유로 만든 캐릭터만 상세 조회·생성에 사용 가능)",
+    { page: z.number().int().min(1).optional().describe("기본 1") },
+    wrapCloudHandler(config, async ({ page = 1 }) => {
+      const payload = await api.request(`/api/tracker/higgsfield/v1/custom-references/list?page=${page}&page_size=50`, {
+        method: "GET",
+        timeoutMs: 30_000,
+      });
+      return jsonResult({
+        characters: (Array.isArray(payload?.items) ? payload.items : []).map((item) => ({
+          id: item?.id,
+          name: item?.name,
+          status: item?.status,
+        })),
+        page,
+        totalPages: payload?.total_pages,
+      });
+    }),
+  );
+
+  server.tool(
+    "suggest_influencer_prompts",
+    "소울 이미지용 연출·프롬프트 10종을 추천받습니다. 반환 prompt는 부정규칙까지 완성형이므로 generate_influencer_image에 그대로 쓰세요.",
+    {
+      gender: z.enum(["여자", "남자"]),
+      ageRange: z.enum(["10대", "20대", "30대", "40대", "50대", "60대"]),
+      keyword: z.string().min(1).describe("장면 키워드 (예: 카페에서 책 읽는 모습)"),
+    },
+    wrapCloudHandler(config, async ({ gender, ageRange, keyword }) => {
+      const { events } = await api.requestSse("/api/tracker/gemini/soul-prompts", {
+        body: { ageRange, gender, imageModel: "soul", keyword },
+        timeoutMs: 180_000,
+      });
+      const items = events
+        .filter((event) => event?.type === "item" && event.item)
+        .map((event) => ({ directing: event.item.directing, id: event.item.id, prompt: event.item.prompt }));
+      if (!items.length) return textResult("프롬프트 추천 결과가 비어 있습니다.", { isError: true });
+      return jsonResult({ count: items.length, items });
+    }),
+  );
+
+  server.tool(
+    "generate_influencer_image",
+    "학습 완료(completed)된 소울 캐릭터로 인플루언서 이미지를 생성합니다 (720p $0.094/장, 1080p $0.19/장). 반환 requestId를 influencer_image_status로 폴링하세요 (~30초).",
+    {
+      prompt: z.string().min(1).describe("영문 프롬프트 (suggest_influencer_prompts 결과 그대로 권장)"),
+      referenceId: z.string().min(1).describe("completed 상태의 캐릭터 referenceId"),
+      aspectRatio: z.enum(["9:16", "16:9", "4:3", "3:4", "1:1", "2:3", "3:2"]).optional().describe("기본 4:3"),
+      resolution: z.enum(["720p", "1080p"]).optional().describe("기본 720p"),
+      imageReferenceUrl: z.string().optional().describe("구도/씬 참조 이미지 URL (선택)"),
+      seed: z.number().int().optional().describe("재현용 시드 (선택)"),
+    },
+    wrapCloudHandler(config, async ({ prompt, referenceId, aspectRatio = "4:3", resolution = "720p", imageReferenceUrl = "", seed }) => {
+      const payload = await api.request("/api/tracker/higgsfield/higgsfield-ai/soul/character", {
+        body: {
+          aspect_ratio: aspectRatio,
+          batch_size: 1,
+          custom_reference_id: referenceId,
+          custom_reference_strength: 1,
+          enhance_prompt: false,
+          ...(imageReferenceUrl ? { image_reference_url: imageReferenceUrl } : {}),
+          prompt,
+          resolution,
+          ...(seed !== undefined ? { seed } : {}),
+        },
+        method: "POST",
+        timeoutMs: 60_000,
+      });
+      const requestId = String(payload?.request_id || payload?.id || "");
+      if (!requestId) return textResult("이미지 생성 요청 응답에 request_id가 없습니다.", { isError: true });
+      return jsonResult({ costUsd: payload?.costUsd, requestId, status: payload?.status });
+    }),
+  );
+
+  server.tool(
+    "influencer_image_status",
+    "소울 이미지 생성 상태를 조회합니다 (terminal: completed | failed | nsfw | canceled). 결과 이미지는 만료 없는 공개 URL입니다.",
+    { requestId: z.string().min(1) },
+    wrapCloudHandler(config, async ({ requestId }) => {
+      const payload = await api.request(`/api/tracker/higgsfield/requests/${encodeURIComponent(requestId)}/status`, {
+        method: "GET",
+        timeoutMs: 30_000,
+      });
+      return jsonResult({
+        error: payload?.error || payload?.message || undefined,
+        imageUrls: (Array.isArray(payload?.images) ? payload.images : []).map((image) => image?.url).filter(Boolean),
+        progress: payload?.progress,
+        requestId,
+        status: payload?.status,
+      });
+    }),
+  );
+
+  // ── 상세페이지(PDP) ─────────────────────────────────────────────────────────
+  server.tool(
+    "generate_pdp",
+    "상품 사진으로 상세페이지(PDP) HTML을 생성합니다. 분석→카피→라이프스타일 컷 8장→조립까지 서버가 한 번에 처리하며 3~6분 걸립니다. 결과는 HTML 파일 경로로 반환됩니다 (Pro 스튜디오 기능).",
+    {
+      productName: z.string().min(1).describe("상품명"),
+      productImagePaths: z.array(z.string()).min(2).max(5).describe("상품 사진 로컬 경로 2~5장 (첫 장이 메인)"),
+      modelImagePath: z.string().optional().describe("모델 사진 로컬 경로 (선택 — 사용 장면 컷 레퍼런스)"),
+      description: z.string().optional().describe("부가 설명"),
+      targetCustomer: z.string().optional(),
+      priceRange: z.enum(["~1만원", "1~5만원", "5~10만원", "10~30만원", "30~100만원", "100만원~"]).optional(),
+      coreUsp: z.string().optional().describe("핵심 USP — 한 줄씩 줄바꿈 구분"),
+      tone: z.enum(["자동 추천", "프리미엄·럭셔리", "친근·일상적", "전문적·신뢰", "감성·스토리", "트렌디·MZ"]).optional().describe("기본 자동 추천"),
+      usePersonaReviews: z.boolean().optional().describe("기본 false. true면 한국인 페르소나 후기 5건으로 대체 (+30초)"),
+      downloadImages: z.boolean().optional().describe("기본 true — 라이프스타일 컷을 로컬 저장하고 HTML src를 로컬 경로로 재작성(원격 URL 만료 대비)"),
+    },
+    wrapCloudHandler(config, async ({
+      productName,
+      productImagePaths,
+      modelImagePath = "",
+      description = "",
+      targetCustomer = "",
+      priceRange = "",
+      coreUsp = "",
+      tone = "자동 추천",
+      usePersonaReviews = false,
+      downloadImages = true,
+    }) => {
+      for (const filePath of productImagePaths) assertAllowedInputFile(filePath, ALLOWED_IMAGE_EXTS, { kind: "상품 사진" });
+      if (modelImagePath) assertAllowedInputFile(modelImagePath, ALLOWED_IMAGE_EXTS, { kind: "모델 사진" });
+      assertEncodedBudget([...productImagePaths, modelImagePath], { context: "상품/모델 사진" });
+
+      const { result } = await api.requestSse("/api/tracker/pdp/generate", {
+        body: {
+          coreUsp,
+          description,
+          modelImage: modelImagePath ? fileToImagePayload(modelImagePath) : null,
+          priceRange,
+          productImages: productImagePaths.map((filePath) => fileToImagePayload(filePath)),
+          productName,
+          targetCustomer,
+          tone,
+          usePersonaReviews,
+        },
+        timeoutMs: 900_000,
+      });
+      if (!result?.html) return textResult("PDP 생성 결과가 비어 있습니다. 잠시 후 다시 시도하세요.", { isError: true });
+
+      let html = String(result.html);
+      const savedImages = [];
+      if (downloadImages) {
+        // 렌더러가 URL 을 HTML 이스케이프(&→&amp; 등)해 넣었을 수 있으므로 두 형태 모두 치환.
+        const escapeHtml = (value) => value
+          .replaceAll("&", "&amp;")
+          .replaceAll("<", "&lt;")
+          .replaceAll(">", "&gt;")
+          .replaceAll('"', "&quot;")
+          .replaceAll("'", "&#39;");
+        for (const image of Array.isArray(result.lifestyleImages) ? result.lifestyleImages : []) {
+          const url = String(image?.url || "");
+          if (!url) continue;
+          try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+            if (!res.ok) continue;
+            const buf = Buffer.from(await res.arrayBuffer());
+            const ext = String(res.headers.get("content-type") || "").includes("png") ? "png" : "jpg";
+            const saved = saveMediaBuffer(config.stateDir, `pdp-image-${image?.idx ?? savedImages.length + 1}.${ext}`, buf);
+            // HTML 은 같은 디렉터리에 저장되므로 상대경로 치환으로 자립형 유지.
+            const local = `./${path.basename(saved.filePath)}`;
+            const before = html;
+            html = html.split(url).join(local).split(escapeHtml(url)).join(local);
+            if (html !== before) savedImages.push(saved.filePath);
+          } catch {
+            // 다운로드 실패한 컷은 원격 URL 유지
+          }
+        }
+      }
+      const savedHtml = saveMediaBuffer(config.stateDir, "pdp.html", Buffer.from(html, "utf8"), { contentType: "text/html" });
+      return jsonResult({
+        analysis: trimAnalysis(result.analysis),
+        heroHeadline: result?.copy?.heroHeadline,
+        htmlPath: savedHtml.filePath,
+        imageCount: (Array.isArray(result.lifestyleImages) ? result.lifestyleImages : []).filter((image) => image?.url).length,
+        localImages: savedImages.length,
+        note: "htmlPath와 로컬 이미지들은 48시간 뒤 자동 정리되는 스테이징 폴더에 있습니다. 보존하려면 같은 폴더의 이미지들과 함께 원하는 위치로 복사하세요.",
+        tagline: result?.copy?.tagline,
+      });
+    }),
+  );
 }

package/lib/companion-tools.mjs

@@ -7,7 +7,7 @@ import {
   triageCompanion,
 } from "./companion-client.mjs";
 import { detectRemoteEnvironment } from "./config.mjs";
-import { readPayloadHandle } from "./media-store.mjs";
+import { readPayloadHandle, saveMediaBuffer } from "./media-store.mjs";
 import {
   checkRenderPayloadSize,
   sanitizeRenderPayload,
@@ -58,6 +58,55 @@ export function registerCompanionTools(server, config) {
     },
   );
 
+  server.tool(
+    "detect_shots",
+    "이 PC의 컴패니언으로 YouTube 영상의 컷(샷) 경계와 대표 프레임을 감지해 shots JSON 파일로 저장합니다. 저장된 파일 경로를 analyze_edit_points의 shotsFiles에 넘기면 실제 컷 기준의 편집점 분석이 됩니다. (다운로드+ffmpeg — 수십 초 걸릴 수 있음)",
+    {
+      videoId: z.string().describe("YouTube video id"),
+      maxShots: z.number().int().min(3).max(18).optional().describe("최대 샷 수, 기본 15 (컴패니언 상한 18)"),
+      sceneThreshold: z.number().min(0.08).max(0.9).optional().describe("장면 전환 감도, 기본 0.22"),
+    },
+    async ({ videoId, maxShots = 15, sceneThreshold = 0.22 }) => {
+      try {
+        const response = await fetch(`${config.companionUrl}/api/shots`, {
+          body: JSON.stringify({
+            maxShots,
+            minGapMs: 1400,
+            sceneThreshold,
+            url: `https://www.youtube.com/watch?v=${videoId}`,
+            width: 720,
+          }),
+          headers: { "Content-Type": "application/json" },
+          method: "POST",
+          signal: AbortSignal.timeout(240_000),
+        });
+        if (!response.ok) {
+          return textResult(`샷 감지 실패 (HTTP ${response.status}). 컴패니언 상태를 companion_status로 확인하세요.`, { isError: true });
+        }
+        const payload = await response.json();
+        const shots = Array.isArray(payload?.shots) ? payload.shots : [];
+        if (!shots.length) {
+          return textResult("샷 감지 결과가 없습니다. sceneThreshold를 낮추거나 다른 영상으로 시도하세요.", { isError: true });
+        }
+        // 대표 프레임 base64 는 모델 컨텍스트로 돌려주지 않고 파일 핸들로만 전달.
+        const saved = saveMediaBuffer(config.stateDir, `shots-${videoId}.json`, Buffer.from(JSON.stringify(shots)));
+        const lastEndMs = Number(shots[shots.length - 1]?.endMs) || 0;
+        return textResult(JSON.stringify({
+          durationSecApprox: lastEndMs ? Math.round(lastEndMs / 100) / 10 : undefined,
+          shotCount: shots.length,
+          shotsFile: saved.filePath,
+          videoId,
+        }, null, 2));
+      } catch (error) {
+        const triage = await triageCompanion(config.companionUrl).catch(() => ({ detail: "", state: "not-running" }));
+        if (triage.state !== "ready") {
+          return textResult(describeCompanionState(triage, remoteEnv), { isError: true });
+        }
+        return textResult(`샷 감지 오류: ${error?.name === "TimeoutError" ? "시간 초과(4분)" : String(error?.message || error)}`, { isError: true });
+      }
+    },
+  );
+
   server.tool(
     "render_start",
     "타임라인 페이로드를 로컬 컴패니언에 제출해 mp4 렌더를 시작합니다. stitch_timeline이 반환한 payloadPath를 넘기는 것이 표준 경로입니다. 즉시 jobId를 반환하며, render_status로 폴링하고 render_result로 파일을 저장하세요. 렌더는 이 PC에서 수행됩니다.",

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.1.0";
+export const MCP_PROXY_VERSION = "0.3.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.1.0",
+  "version": "0.3.0",
   "description": "AImakeAll MCP 서버 — Claude Code/Codex에서 자연어로 영상 기획·생성·렌더·퍼블리시 (렌더는 로컬 컴패니언)",
   "type": "module",
   "bin": {