@vibeframe/mcp-server 0.113.2 → 0.113.3

package/dist/index.js

@@ -471698,6 +471698,7 @@ var init_storyboard_edit = __esm({
       "narration",
       "backdrop",
       "video",
+      "keyframe",
       "motion",
       "voice",
       "music",
@@ -471707,7 +471708,7 @@ var init_storyboard_edit = __esm({
     HEADING_RE2 = /^##\s+(.+?)\s*$/gm;
     LEADING_CUE_RE = /^(\s*)```ya?ml\s*\n([\s\S]*?)\n```\s*(?:\n|$)/;
     ALLOWED_CUE_KEYS = new Set(STORYBOARD_CUE_KEYS);
-    STRING_CUE_KEYS = /* @__PURE__ */ new Set(["narration", "backdrop", "video", "motion", "voice", "music", "asset"]);
+    STRING_CUE_KEYS = /* @__PURE__ */ new Set(["narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset"]);
     MAX_RECOMMENDED_BEAT_SEC = 15;
   }
 });
@@ -472626,6 +472627,7 @@ var init_build_asset_reference = __esm({
       narration: [".mp3", ".wav", ".m4a"],
       backdrop: [".png", ".jpg", ".jpeg", ".webp"],
       character: [".png", ".jpg", ".jpeg", ".webp"],
+      keyframe: [".png", ".jpg", ".jpeg", ".webp"],
       video: [".mp4", ".mov", ".webm"],
       music: [".mp3", ".wav", ".m4a"]
     };
@@ -472673,6 +472675,18 @@ function characterCacheDescriptor(opts) {
     ext: "png"
   });
 }
+function keyframeCacheDescriptor(opts) {
+  return cacheAssetDescriptor("keyframe", {
+    beatId: opts.beatId,
+    cue: opts.cue,
+    provider: opts.provider,
+    quality: opts.quality,
+    size: opts.size,
+    ratio: opts.ratio,
+    characters: opts.characters && opts.characters.length > 0 ? opts.characters : void 0,
+    ext: "png"
+  });
+}
 function imageRatioForSize(size) {
   switch (size) {
     case "1024x1024":
@@ -472694,6 +472708,8 @@ function videoCacheDescriptor(opts) {
     ratio: "16:9",
     // Omit when empty so existing (character-less) clips keep their cache key.
     characters: opts.characters && opts.characters.length > 0 ? opts.characters : void 0,
+    // Omit when absent so existing (non-keyframe) clips keep their cache key.
+    keyframe: opts.keyframe || void 0,
     ext: "mp4"
   });
 }
@@ -472844,6 +472860,7 @@ async function createBuildPlan(opts) {
     const backdropPrompt = stringOrUndefined3(cue.backdrop);
     const augmentedBackdropPrompt = backdropPrompt ? augmentBackdropPrompt(backdropPrompt) : null;
     const videoPrompt = stringOrUndefined3(cue.video);
+    const keyframePrompt = stringOrUndefined3(cue.keyframe);
     const musicPrompt = stringOrUndefined3(cue.music);
     const genericReference = resolveGenericAssetReference(projectDir, cue.asset);
     const narrationReference = resolveTypedAssetReference(projectDir, "narration", cue.narration);
@@ -472852,7 +472869,7 @@ async function createBuildPlan(opts) {
     const musicReference = resolveTypedAssetReference(projectDir, "music", cue.music) ?? (!musicPrompt && genericReference?.kind === "music" ? genericReference : null);
     const narrationCue = narrationText ?? narrationReference?.raw;
     const backdropCue = backdropPrompt ?? backdropReference?.raw;
-    const videoCue = videoPrompt ?? videoReference?.raw;
+    const videoCue = videoPrompt ?? videoReference?.raw ?? keyframePrompt;
     const musicCue = musicPrompt ?? musicReference?.raw;
     const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : resolved.narration.resolved === "openai" ? OPENAI_NARRATION_COST_USD : 0;
     const narrationCache = narrationText && !narrationReference ? narrationCacheDescriptor({
@@ -472870,11 +472887,12 @@ async function createBuildPlan(opts) {
       size: imageSize2,
       ratio: imageRatio
     }) : null;
-    const videoCache = videoPrompt && !videoReference ? videoCacheDescriptor({
+    const videoCache = (videoPrompt || keyframePrompt) && !videoReference ? videoCacheDescriptor({
       beatId: beat.id,
-      cue: videoPrompt,
+      cue: videoPrompt ?? keyframePrompt,
       provider: resolved.video.resolved,
-      duration: beat.duration
+      duration: beat.duration,
+      keyframe: keyframePrompt
     }) : null;
     const musicCache = musicPrompt && !musicReference ? musicCacheDescriptor({
       beatId: beat.id,
@@ -472969,6 +472987,12 @@ async function createBuildPlan(opts) {
     if (backdrop?.willGenerate && isSupportedBuildImageProvider(resolved.image.resolved))
       noteProviderNeed(resolved.image, "Backdrop generation");
     if (video?.willGenerate) noteProviderNeed(resolved.video, "Video generation");
+    if (keyframePrompt && video?.willGenerate) {
+      estimatedCostUsd += backdropCostUsd(imageQuality);
+      providers.add(resolved.image.resolved);
+      if (isSupportedBuildImageProvider(resolved.image.resolved))
+        noteProviderNeed(resolved.image, "Keyframe generation");
+    }
     if (music?.willGenerate) noteProviderNeed(resolved.music, "Music generation");
     if (!compositionExists) missing.add("compositions");
     if (includeCompose && !compositionExists && mode !== "agent") {
@@ -474379,6 +474403,8 @@ async function buildBeatPrimitives(beat, ctx) {
       videoMetadataPath: video.metadataPath,
       videoFreshness: video.freshness,
       videoSourcePath: video.sourcePath,
+      keyframeStatus: video.keyframeStatus,
+      keyframePath: video.keyframePath,
       musicStatus: music.status,
       musicPath: music.path,
       musicJobId: music.job?.id,
@@ -474823,6 +474849,112 @@ async function generateBackdropImage(prompt3, ctx, ratio) {
   });
   return imageBufferFromResult(result);
 }
+async function editKeyframeImage(prompt3, sheetBuffers, ctx, ratio) {
+  loadSceneBuildEnv(ctx.projectDir);
+  const keyInfo = imageProviderKeyInfo(ctx.imageProvider);
+  const apiKey = await getApiKeyFromConfig(keyInfo.configKey, { cwd: ctx.projectDir }) ?? process.env[keyInfo.envVar] ?? "";
+  if (!apiKey) {
+    return {
+      success: false,
+      error: `${keyInfo.envVar} not set \u2014 cannot generate keyframe with ${ctx.imageProvider}`
+    };
+  }
+  if (ctx.imageProvider === "openai") {
+    const provider2 = new OpenAIImageProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.editImage(sheetBuffers, prompt3);
+    return imageBufferFromResult(result2);
+  }
+  if (ctx.imageProvider === "gemini") {
+    const provider2 = new GeminiProvider();
+    await provider2.initialize({ apiKey });
+    const result2 = await provider2.editImage(sheetBuffers, prompt3, {
+      model: "flash",
+      aspectRatio: ratio
+    });
+    return imageBufferFromResult(result2);
+  }
+  const provider = new GrokProvider();
+  await provider.initialize({ apiKey });
+  const result = await provider.editImage(sheetBuffers[0], prompt3, { aspectRatio: ratio });
+  return imageBufferFromResult(result);
+}
+async function ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel) {
+  const rel = `assets/keyframe-${beat.id}.png`;
+  const abs = join31(ctx.projectDir, rel);
+  const size = ctx.imageSize ?? "1536x1024";
+  const ratio = imageRatioForSize(size);
+  const metadataOptions = { quality: ctx.imageQuality, size, ratio };
+  const cache = keyframeCacheDescriptor({
+    beatId: beat.id,
+    cue: keyframeCue,
+    provider: ctx.imageProvider,
+    quality: ctx.imageQuality,
+    size,
+    ratio,
+    characters: characterRefsRel
+  });
+  if (existsSync35(abs) && !ctx.force) {
+    const metadata = readAssetMetadata(ctx.projectDir, "keyframe", beat.id);
+    if (!metadata || isFreshCanonicalAsset({
+      projectDir: ctx.projectDir,
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframeCue,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key
+    })) {
+      return { status: "cached", rel };
+    }
+  }
+  const cacheAbs = join31(ctx.projectDir, cache.path);
+  if (existsSync35(cacheAbs) && !ctx.force) {
+    await mkdir13(dirname18(abs), { recursive: true });
+    await copyFile4(cacheAbs, abs);
+    await writeAssetMetadata({
+      projectDir: ctx.projectDir,
+      kind: "keyframe",
+      beatId: beat.id,
+      cue: keyframeCue,
+      provider: ctx.imageProvider,
+      options: metadataOptions,
+      cacheKey: cache.key,
+      canonicalPath: rel,
+      cachePath: cache.path
+    });
+    return { status: "cached", rel };
+  }
+  const sheetBuffers = [];
+  for (const relPath of characterRefsRel) {
+    const sheetAbs = join31(ctx.projectDir, relPath);
+    if (existsSync35(sheetAbs)) sheetBuffers.push(await readFile18(sheetAbs));
+  }
+  const imgCtx = {
+    projectDir: ctx.projectDir,
+    imageProvider: ctx.imageProvider,
+    imageSize: size,
+    imageQuality: ctx.imageQuality
+  };
+  const generated = sheetBuffers.length > 0 ? await editKeyframeImage(keyframeCue, sheetBuffers, imgCtx, ratio) : await generateBackdropImage(keyframeCue, imgCtx, ratio);
+  if (!generated.success) return { status: "failed", error: generated.error };
+  await mkdir13(dirname18(abs), { recursive: true });
+  await writeFile20(abs, generated.buffer);
+  await mkdir13(dirname18(cacheAbs), { recursive: true });
+  await writeFile20(cacheAbs, generated.buffer);
+  await writeAssetMetadata({
+    projectDir: ctx.projectDir,
+    kind: "keyframe",
+    beatId: beat.id,
+    cue: keyframeCue,
+    provider: ctx.imageProvider,
+    options: metadataOptions,
+    cacheKey: cache.key,
+    canonicalPath: rel,
+    cachePath: cache.path
+  });
+  return { status: "generated", rel };
+}
 async function imageBufferFromResult(result) {
   const image = result.images?.[0];
   if (!result.success || !image) {
@@ -474846,7 +474978,8 @@ function imageProviderKeyInfo(provider) {
 async function dispatchVideo(beat, ctx) {
   const reference = assetReferenceForBeat(ctx.projectDir, "video", beat);
   if (reference) return referencePrimitiveOutcome("video", beat, ctx, reference);
-  const prompt3 = stringOrUndefined4(beat.cues?.video);
+  const keyframeCue = stringOrUndefined4(beat.cues?.keyframe);
+  const prompt3 = stringOrUndefined4(beat.cues?.video) ?? keyframeCue;
   if (!prompt3) return { status: "no-cue" };
   const characterRefsRel = beatCharacterNames(beat.cues).map((name) => ctx.characterPaths?.get(name)).filter((p2) => typeof p2 === "string");
   const characterRefsAbs = characterRefsRel.map((p2) => join31(ctx.projectDir, p2));
@@ -474857,7 +474990,10 @@ async function dispatchVideo(beat, ctx) {
     cue: prompt3,
     provider: ctx.videoProvider,
     duration: normalizeVideoDuration(beat.duration),
-    characters: characterRefsRel
+    // Keyframe mode keys the clip to the keyframe prompt; refs feed the keyframe,
+    // not the clip directly.
+    characters: keyframeCue ? void 0 : characterRefsRel,
+    keyframe: keyframeCue
   });
   const metadataPath = assetMetadataPath("video", beat.id);
   if (existsSync35(abs) && !ctx.force) {
@@ -474910,6 +475046,19 @@ async function dispatchVideo(beat, ctx) {
     };
   }
   loadSceneBuildEnv(ctx.projectDir);
+  let keyframeStatus;
+  let keyframeRel;
+  let keyframeImageAbs;
+  if (keyframeCue) {
+    const kf = await ensureKeyframe(beat, ctx, keyframeCue, characterRefsRel);
+    if (kf.status === "failed") {
+      ctx.onProgress({ type: "video-failed", beatId: beat.id, error: kf.error });
+      return { status: "failed", error: kf.error };
+    }
+    keyframeStatus = kf.status;
+    keyframeRel = kf.rel;
+    keyframeImageAbs = join31(ctx.projectDir, kf.rel);
+  }
   const result = await executeVideoGenerate({
     prompt: prompt3,
     provider: ctx.videoProvider,
@@ -474917,7 +475066,10 @@ async function dispatchVideo(beat, ctx) {
     ratio: "16:9",
     output: abs,
     wait: false,
-    refImages: characterRefsAbs.length > 0 ? characterRefsAbs : void 0,
+    // Keyframe mode → single init frame (image-to-video); otherwise character
+    // reference-to-video.
+    image: keyframeImageAbs,
+    refImages: keyframeImageAbs ? void 0 : characterRefsAbs.length > 0 ? characterRefsAbs : void 0,
     apiKey: await apiKeyForVideoProvider(ctx.videoProvider, ctx.projectDir)
   });
   if (!result.success || !result.taskId) {
@@ -474952,14 +475104,16 @@ async function dispatchVideo(beat, ctx) {
       cachePath: cache.path,
       cacheKey: cache.key,
       metadataPath,
-      freshness: "fresh"
+      freshness: "fresh",
+      keyframeStatus,
+      keyframePath: keyframeRel
     };
   }
   const job = await createAndWriteJobRecord({
     jobType: "generate-video",
     provider: result.provider ?? ctx.videoProvider,
     providerTaskId: result.taskId,
-    providerTaskType: "text2video",
+    providerTaskType: keyframeImageAbs ? "image2video" : "text2video",
     status: "running",
     projectDir: ctx.projectDir,
     workingDirectory: ctx.projectDir,
@@ -474984,7 +475138,9 @@ async function dispatchVideo(beat, ctx) {
     provider: job.provider,
     cachePath: cache.path,
     cacheKey: cache.key,
-    metadataPath
+    metadataPath,
+    keyframeStatus,
+    keyframePath: keyframeRel
   };
 }
 async function dispatchMusic(beat, ctx) {
@@ -475286,6 +475442,7 @@ function estimateActualAssetCost(outcomes, imageQuality) {
   for (const outcome of outcomes) {
     if (outcome.narrationStatus === "generated") cost += 0.05;
     if (outcome.backdropStatus === "generated") cost += backdropCostUsd(imageQuality);
+    if (outcome.keyframeStatus === "generated") cost += backdropCostUsd(imageQuality);
     if (outcome.videoStatus === "generated" || outcome.videoStatus === "pending") {
       cost += outcome.videoProvider === "seedance" || outcome.videoProvider === "fal" ? estimateSeedanceVideoCostUsd({
         durationSec: normalizeVideoDuration(outcome.sceneDurationSec),
@@ -499542,7 +499699,7 @@ var server2 = new Server(
   {
     name: "vibeframe",
     // Stamped with the package version by build.js at bundle time.
-    version: "0.113.2"
+    version: "0.113.3"
   },
   {
     capabilities: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/mcp-server",
-  "version": "0.113.2",
+  "version": "0.113.3",
   "description": "VibeFrame MCP Server - AI-native video editing via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -60,8 +60,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/cli": "0.113.2",
-    "@vibeframe/core": "0.113.2"
+    "@vibeframe/cli": "0.113.3",
+    "@vibeframe/core": "0.113.3"
   },
   "engines": {
     "node": ">=20"