@vibeframe/mcp-server 0.112.1 → 0.113.0

package/README.md

@@ -45,16 +45,17 @@ enabled = true
 
 Install the prebuilt Desktop Extension — no Node, npx, or JSON editing needed:
 
-1. Download `vibeframe-<version>.mcpb` from the
-   [latest GitHub Release](https://github.com/vericontext/vibeframe/releases/latest).
+1. Download the extension: [vibeframe.mcpb (always latest)](https://github.com/vericontext/vibeframe/releases/latest/download/vibeframe.mcpb)
+   — or pick a specific version from the [releases page](https://github.com/vericontext/vibeframe/releases).
 2. In Claude Desktop open **Settings → Extensions** and drag the `.mcpb` file in
    (or double-click the file).
 3. In the extension's settings pick your **Workspace folder** (projects are
    created there; a `.env` file in that folder is loaded for API keys) and
    optionally paste provider keys.
 
-Rendering still needs Google Chrome and `ffmpeg` on the machine. For free local
-Kokoro TTS, run `npm i kokoro-js` once inside the workspace folder. To update,
+Rendering still needs Google Chrome and `ffmpeg` on the machine. Free local
+Kokoro narration is bundled inside the extension — no install step; the first
+use downloads a ~90 MB voice model to `~/.cache/vibeframe/models`. To update,
 download the new release's `.mcpb` and install it over the old one.
 
 To build the bundle from source: `pnpm -F @vibeframe/mcp-server build:mcpb`
@@ -131,8 +132,9 @@ The server prefers asking over silently picking defaults:
 
 - On hosts that support **MCP elicitation** (Claude Code 2.1.76+), the `build`
   tool opens a native form before the build starts for any choice the call
-  left unspecified: narration provider (Kokoro free/local vs ElevenLabs),
-  backdrop image generation (skip vs paid OpenAI), and a max cost cap.
+  left unspecified: narration provider (Kokoro free/local, OpenAI's
+  gpt-4o-mini-tts, or ElevenLabs), backdrop image generation (skip vs paid
+  OpenAI), and a max cost cap.
   Declining cancels the build before any provider spend. Set
   `VIBE_MCP_ELICIT=off` in the server env to disable the form (headless and
   automation setups).

package/dist/index.js

@@ -192,8 +192,8 @@ var init_api_keys = __esm({
       envVar: "OPENAI_API_KEY",
       label: "OpenAI",
       showInSetup: true,
-      setupDescription: "gpt-image-2 image gen ($, default since v0.56), Whisper transcribe, Agent",
-      envExampleComment: "OpenAI API Key (Whisper transcription, gpt-image-2 \u2014 default text-to-image since v0.56)",
+      setupDescription: "gpt-image-2 image gen ($, default since v0.56), gpt-4o-mini-tts narration, Whisper transcribe, Agent",
+      envExampleComment: "OpenAI API Key (Whisper transcription, gpt-4o-mini-tts narration, gpt-image-2 \u2014 default text-to-image since v0.56)",
       envExampleUrl: "https://platform.openai.com/api-keys",
       keyFormat: { prefix: /^sk-/, example: "sk-..." }
     });
@@ -2300,8 +2300,8 @@ var init_openai = __esm({
       id: "openai",
       label: "OpenAI",
       apiKey: "openai",
-      kinds: ["llm", "image", "transcription"],
-      resolverPriority: { image: 1 },
+      kinds: ["llm", "image", "transcription", "speech"],
+      resolverPriority: { image: 1, speech: 2 },
       commandsUnlocked: [
         "agent -p openai",
         "generate image -p openai",
@@ -4723,16 +4723,19 @@ var init_elevenlabs = __esm({
 });
 
 // ../ai-providers/dist/kokoro/KokoroProvider.js
-async function loadKokoroFactory() {
+async function loadKokoroRuntime() {
   if (factoryOverride)
-    return factoryOverride;
+    return { factory: factoryOverride, device: "cpu" };
   try {
     const mod = await import("kokoro-js");
-    return mod.KokoroTTS;
+    return { factory: mod.KokoroTTS, device: "cpu" };
   } catch (err) {
-    const fallback2 = await loadKokoroFromWorkspace();
-    if (fallback2)
-      return fallback2;
+    const workspace = await loadKokoroFromWorkspace();
+    if (workspace)
+      return { factory: workspace, device: "cpu" };
+    const bundled = await loadBundledKokoroRuntime();
+    if (bundled)
+      return bundled;
     throw mapKokoroImportError(err);
   }
 }
@@ -4752,10 +4755,51 @@ async function loadKokoroFromWorkspace(baseDir = process.cwd()) {
     return null;
   }
 }
+async function loadBundledKokoroRuntime(runtimeDir = process.env.VIBE_KOKORO_RUNTIME) {
+  const base = runtimeDir?.trim();
+  if (!base)
+    return null;
+  try {
+    const { readFile: readFile46, writeFile: writeFile53, mkdir: mkdir30 } = await import("node:fs/promises");
+    const { join: join45, resolve: resolve80 } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const { homedir: homedir8 } = await import("node:os");
+    const transformersDir = resolve80(base, "node_modules", "@huggingface", "transformers");
+    const ortDistDir = resolve80(base, "node_modules", "onnxruntime-web", "dist");
+    const transformers = await import(pathToFileURL(join45(transformersDir, "dist", "transformers.web.js")).href);
+    const cacheRoot = join45(homedir8(), ".cache", "vibeframe", "models");
+    transformers.env.allowLocalModels = false;
+    transformers.env.useCustomCache = true;
+    transformers.env.customCache = {
+      async match(key2) {
+        try {
+          return new Response(await readFile46(join45(cacheRoot, encodeURIComponent(String(key2)))));
+        } catch {
+          return void 0;
+        }
+      },
+      async put(key2, response) {
+        try {
+          const buf = Buffer.from(await response.arrayBuffer());
+          await mkdir30(cacheRoot, { recursive: true });
+          await writeFile53(join45(cacheRoot, encodeURIComponent(String(key2))), buf);
+        } catch {
+        }
+      }
+    };
+    transformers.env.backends.onnx.wasm.wasmPaths = pathToFileURL(ortDistDir + "/").href;
+    const factory = await loadKokoroFromWorkspace(base);
+    if (!factory)
+      return null;
+    return { factory, device: "cpu" };
+  } catch {
+    return null;
+  }
+}
 function mapKokoroImportError(err) {
   const code = err instanceof Error && "code" in err ? err.code : void 0;
   if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
-    return new Error("Local Kokoro TTS is unavailable: optional dependency kokoro-js is not installed (its native dependencies may have failed to build on this platform). Install it with `npm i kokoro-js` \u2014 run it inside your workspace folder when using the Claude Desktop extension \u2014 or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
+    return new Error("Local Kokoro TTS is unavailable: kokoro-js could not be loaded from the npm install, the workspace node_modules, or the bundled extension runtime. Set OPENAI_API_KEY or ELEVENLABS_API_KEY to use a cloud voice instead (ttsProvider: openai / elevenlabs), or install the engine locally with `npm i kokoro-js` in your workspace folder.");
   }
   return err instanceof Error ? err : new Error(String(err));
 }
@@ -4763,10 +4807,12 @@ function loadModel(progress) {
   if (modelPromise)
     return modelPromise;
   modelPromise = (async () => {
-    const factory = await loadKokoroFactory();
-    return factory.from_pretrained(KOKORO_MODEL_ID, {
+    const runtime = await loadKokoroRuntime();
+    const override = process.env.VIBE_ONNX_DEVICE;
+    const device = override === "cpu" || override === "wasm" ? override : runtime.device;
+    return runtime.factory.from_pretrained(KOKORO_MODEL_ID, {
       dtype: "q8",
-      device: "cpu",
+      device,
       progress_callback: progress ? (raw2) => progress(normaliseEvent(raw2)) : void 0
     });
   })().catch((err) => {
@@ -4850,7 +4896,7 @@ var init_kokoro = __esm({
       label: "Kokoro (local)",
       apiKey: null,
       kinds: ["speech"],
-      resolverPriority: { speech: 2 }
+      resolverPriority: { speech: 3 }
     });
   }
 });
@@ -5122,12 +5168,119 @@ var init_openai_image = __esm({
   }
 });
 
+// ../ai-providers/dist/openai-tts/OpenAiTtsProvider.js
+var OPENAI_TTS_VOICES, DEFAULT_VOICE, DEFAULT_MODEL2, TTS_429_MAX_RETRIES2, TTS_429_RETRY_DELAY_MS2, OpenAiTtsProvider, openaiTtsProvider;
+var init_OpenAiTtsProvider = __esm({
+  "../ai-providers/dist/openai-tts/OpenAiTtsProvider.js"() {
+    "use strict";
+    OPENAI_TTS_VOICES = [
+      "alloy",
+      "ash",
+      "ballad",
+      "cedar",
+      "coral",
+      "echo",
+      "fable",
+      "marin",
+      "nova",
+      "onyx",
+      "sage",
+      "shimmer",
+      "verse"
+    ];
+    DEFAULT_VOICE = "marin";
+    DEFAULT_MODEL2 = "gpt-4o-mini-tts";
+    TTS_429_MAX_RETRIES2 = 1;
+    TTS_429_RETRY_DELAY_MS2 = 2e3;
+    OpenAiTtsProvider = class {
+      constructor() {
+        this.id = "openai";
+        this.name = "OpenAI TTS";
+        this.description = "OpenAI cloud text-to-speech (gpt-4o-mini-tts)";
+        this.capabilities = ["text-to-speech"];
+        this.isAvailable = true;
+        this.baseUrl = "https://api.openai.com/v1";
+      }
+      async initialize(config4) {
+        this.apiKey = config4.apiKey;
+        if (config4.baseUrl) {
+          this.baseUrl = config4.baseUrl;
+        }
+      }
+      isConfigured() {
+        return !!this.apiKey;
+      }
+      async textToSpeech(text, options = {}) {
+        if (!this.apiKey) {
+          return { success: false, error: "OpenAI API key not configured" };
+        }
+        const voice = (options.voice ?? DEFAULT_VOICE).toLowerCase();
+        if (!OPENAI_TTS_VOICES.includes(voice)) {
+          return {
+            success: false,
+            error: `Unknown OpenAI voice "${options.voice}". Available voices: ${OPENAI_TTS_VOICES.join(", ")}.`
+          };
+        }
+        try {
+          let response;
+          for (let attempt = 0; ; attempt++) {
+            response = await fetch(`${this.baseUrl}/audio/speech`, {
+              method: "POST",
+              headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json"
+              },
+              body: JSON.stringify({
+                model: options.model ?? DEFAULT_MODEL2,
+                input: text,
+                voice,
+                response_format: "mp3",
+                ...options.speed !== void 0 && { speed: options.speed },
+                ...options.instructions !== void 0 && { instructions: options.instructions }
+              })
+            });
+            if (response.status === 429 && attempt < TTS_429_MAX_RETRIES2) {
+              await new Promise((resolveDelay) => setTimeout(resolveDelay, TTS_429_RETRY_DELAY_MS2 * (attempt + 1)));
+              continue;
+            }
+            break;
+          }
+          if (!response.ok) {
+            const error = await response.text();
+            return { success: false, error: `OpenAI TTS failed: ${error}` };
+          }
+          const arrayBuffer = await response.arrayBuffer();
+          return {
+            success: true,
+            audioBuffer: Buffer.from(arrayBuffer),
+            characterCount: text.length
+          };
+        } catch (error) {
+          return {
+            success: false,
+            error: error instanceof Error ? error.message : "Unknown error"
+          };
+        }
+      }
+    };
+    openaiTtsProvider = new OpenAiTtsProvider();
+  }
+});
+
+// ../ai-providers/dist/openai-tts/index.js
+var init_openai_tts = __esm({
+  "../ai-providers/dist/openai-tts/index.js"() {
+    "use strict";
+    init_OpenAiTtsProvider();
+  }
+});
+
 // ../ai-providers/dist/runway/RunwayProvider.js
-var DEFAULT_MODEL2, RunwayProvider, runwayProvider;
+var DEFAULT_MODEL3, RunwayProvider, runwayProvider;
 var init_RunwayProvider = __esm({
   "../ai-providers/dist/runway/RunwayProvider.js"() {
     "use strict";
-    DEFAULT_MODEL2 = "gen4.5";
+    DEFAULT_MODEL3 = "gen4.5";
     RunwayProvider = class _RunwayProvider {
       constructor() {
         this.id = "runway";
@@ -5170,7 +5323,7 @@ var init_RunwayProvider = __esm({
             "1:1": "960:960"
           };
           const apiRatio = ratioMap[options?.aspectRatio || "16:9"] || "1280:720";
-          const model = options?.model || DEFAULT_MODEL2;
+          const model = options?.model || DEFAULT_MODEL3;
           if (!options?.referenceImage && model !== "gen4.5") {
             return {
               id: "",
@@ -5432,11 +5585,11 @@ var init_runway = __esm({
 
 // ../ai-providers/dist/kling/KlingProvider.js
 import { createHmac } from "node:crypto";
-var DEFAULT_MODEL3, STD_MODE_MODELS, KlingProvider, klingProvider;
+var DEFAULT_MODEL4, STD_MODE_MODELS, KlingProvider, klingProvider;
 var init_KlingProvider = __esm({
   "../ai-providers/dist/kling/KlingProvider.js"() {
     "use strict";
-    DEFAULT_MODEL3 = "kling-v2-5-turbo";
+    DEFAULT_MODEL4 = "kling-v2-5-turbo";
     STD_MODE_MODELS = ["kling-v2-5-turbo", "kling-v2-6", "kling-v3", "kling-v3-omni"];
     KlingProvider = class {
       constructor() {
@@ -5499,7 +5652,7 @@ var init_KlingProvider = __esm({
         }
         try {
           const token = this.generateToken();
-          const model = options?.model || DEFAULT_MODEL3;
+          const model = options?.model || DEFAULT_MODEL4;
           let mode = options?.mode || "std";
           if (!STD_MODE_MODELS.includes(model) && mode === "std") {
             mode = "pro";
@@ -5870,11 +6023,11 @@ var init_kling = __esm({
 });
 
 // ../ai-providers/dist/grok/GrokProvider.js
-var DEFAULT_MODEL4, GrokProvider, grokProvider;
+var DEFAULT_MODEL5, GrokProvider, grokProvider;
 var init_GrokProvider = __esm({
   "../ai-providers/dist/grok/GrokProvider.js"() {
     "use strict";
-    DEFAULT_MODEL4 = "grok-imagine-video";
+    DEFAULT_MODEL5 = "grok-imagine-video";
     GrokProvider = class {
       constructor() {
         this.id = "grok";
@@ -6041,7 +6194,7 @@ var init_GrokProvider = __esm({
         try {
           const duration = Math.round(Math.min(15, Math.max(1, options?.duration || 5)));
           const body = {
-            model: DEFAULT_MODEL4,
+            model: DEFAULT_MODEL5,
             prompt: prompt3,
             duration,
             aspect_ratio: options?.aspectRatio || "16:9"
@@ -11248,9 +11401,11 @@ __export(dist_exports, {
   KOKORO_MODEL_ID: () => KOKORO_MODEL_ID,
   KlingProvider: () => KlingProvider,
   KokoroProvider: () => KokoroProvider,
+  OPENAI_TTS_VOICES: () => OPENAI_TTS_VOICES,
   OllamaProvider: () => OllamaProvider,
   OpenAIImageProvider: () => OpenAIImageProvider,
   OpenAIProvider: () => OpenAIProvider,
+  OpenAiTtsProvider: () => OpenAiTtsProvider,
   ReplicateProvider: () => ReplicateProvider,
   RunwayProvider: () => RunwayProvider,
   WhisperProvider: () => WhisperProvider,
@@ -11274,9 +11429,12 @@ __export(dist_exports, {
   isGeminiTextModelAlias: () => isGeminiTextModelAlias,
   klingProvider: () => klingProvider,
   kokoroProvider: () => kokoroProvider,
+  loadBundledKokoroRuntime: () => loadBundledKokoroRuntime,
+  loadKokoroFromWorkspace: () => loadKokoroFromWorkspace,
   ollamaProvider: () => ollamaProvider,
   openaiImageProvider: () => openaiImageProvider,
   openaiProvider: () => openaiProvider,
+  openaiTtsProvider: () => openaiTtsProvider,
   providerRegistry: () => providerRegistry,
   replicateProvider: () => replicateProvider,
   resolveGeminiTextModel: () => resolveGeminiTextModel,
@@ -11299,6 +11457,7 @@ var init_dist = __esm({
     init_elevenlabs();
     init_kokoro();
     init_openai_image();
+    init_openai_tts();
     init_runway();
     init_kling();
     init_grok();
@@ -28714,10 +28873,22 @@ var init_esm = __esm({
 
 // ../cli/src/commands/_shared/tts-resolve.ts
 async function resolveTtsProvider(preferred = "auto") {
-  const choice = preferred === "auto" ? await getConfiguredApiKey("ELEVENLABS_API_KEY") ? "elevenlabs" : "kokoro" : preferred;
+  let choice = preferred;
+  if (choice === "auto") {
+    if (await getConfiguredApiKey("ELEVENLABS_API_KEY")) {
+      choice = "elevenlabs";
+    } else if (await getConfiguredApiKey("OPENAI_API_KEY")) {
+      choice = "openai";
+    } else {
+      choice = "kokoro";
+    }
+  }
   if (choice === "elevenlabs") {
     return buildElevenLabs();
   }
+  if (choice === "openai") {
+    return buildOpenAi();
+  }
   return buildKokoro();
 }
 async function buildElevenLabs() {
@@ -28733,6 +28904,19 @@ async function buildElevenLabs() {
   });
   return { provider: "elevenlabs", audioExtension: "mp3", call };
 }
+async function buildOpenAi() {
+  const key2 = await getApiKey("OPENAI_API_KEY", "OpenAI");
+  if (!key2) {
+    throw new TtsKeyMissingError("openai");
+  }
+  const provider = new OpenAiTtsProvider();
+  await provider.initialize({ apiKey: key2 });
+  const call = async (text, opts) => provider.textToSpeech(text, {
+    voice: opts?.voice,
+    speed: opts?.speed
+  });
+  return { provider: "openai", audioExtension: "mp3", call };
+}
 async function buildKokoro() {
   const provider = new KokoroProvider();
   await provider.initialize({});
@@ -28745,11 +28929,11 @@ async function buildKokoro() {
 }
 function parseTtsProviderName(value) {
   if (!value) return "auto";
-  if (value === "auto" || value === "elevenlabs" || value === "kokoro") {
+  if (value === "auto" || value === "elevenlabs" || value === "openai" || value === "kokoro") {
     return value;
   }
   throw new Error(
-    `Invalid --tts: ${value}. Valid: auto, elevenlabs, kokoro.`
+    `Invalid --tts: ${value}. Valid: auto, elevenlabs, openai, kokoro.`
   );
 }
 var TtsKeyMissingError;
@@ -28761,7 +28945,7 @@ var init_tts_resolve = __esm({
     TtsKeyMissingError = class extends Error {
       constructor(provider) {
         super(
-          provider === "elevenlabs" ? "ElevenLabs API key required (ELEVENLABS_API_KEY). Run 'vibe setup', set ELEVENLABS_API_KEY in .env, or pass --tts kokoro for local synthesis." : `Provider ${provider} is unavailable.`
+          provider === "elevenlabs" ? "ElevenLabs API key required (ELEVENLABS_API_KEY). Run 'vibe setup', set ELEVENLABS_API_KEY in .env, or pass --tts kokoro for local synthesis." : provider === "openai" ? "OpenAI API key required (OPENAI_API_KEY). Run 'vibe setup', set OPENAI_API_KEY in .env, or pass --tts kokoro for local synthesis." : `Provider ${provider} is unavailable.`
         );
         this.provider = provider;
         this.name = "TtsKeyMissingError";
@@ -472016,13 +472200,13 @@ async function createBuildPlan(opts) {
     const backdropCue = backdropPrompt ?? backdropReference?.raw;
     const videoCue = videoPrompt ?? videoReference?.raw;
     const musicCue = musicPrompt ?? musicReference?.raw;
-    const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : 0;
+    const narrationCost = resolved.narration.resolved === "elevenlabs" ? ELEVENLABS_NARRATION_COST_USD : resolved.narration.resolved === "openai" ? OPENAI_NARRATION_COST_USD : 0;
     const narrationCache = narrationText && !narrationReference ? narrationCacheDescriptor({
       beatId: beat.id,
       cue: narrationText,
       provider: resolved.narration.resolved,
       voice,
-      ext: resolved.narration.resolved === "elevenlabs" ? "mp3" : "wav"
+      ext: resolved.narration.resolved === "kokoro" ? "wav" : "mp3"
     }) : null;
     const backdropCache = augmentedBackdropPrompt && !backdropReference ? backdropCacheDescriptor({
       beatId: beat.id,
@@ -472440,17 +472624,20 @@ function providerInput(opts) {
 async function resolveNarrationProvider(input3, projectDir) {
   const requested = input3.value.toLowerCase();
   const hasElevenLabs = Boolean(await getApiKeyFromConfig("elevenlabs", { cwd: projectDir }));
-  const resolved = requested === "elevenlabs" ? "elevenlabs" : requested === "kokoro" ? "kokoro" : hasElevenLabs ? "elevenlabs" : "kokoro";
+  const hasOpenAi = Boolean(await getApiKeyFromConfig("openai", { cwd: projectDir }));
+  const resolved = requested === "elevenlabs" ? "elevenlabs" : requested === "openai" ? "openai" : requested === "kokoro" ? "kokoro" : hasElevenLabs ? "elevenlabs" : hasOpenAi ? "openai" : "kokoro";
+  const requiresKey = resolved !== "kokoro";
+  const hasKey = resolved === "elevenlabs" ? hasElevenLabs : resolved === "openai" ? hasOpenAi : true;
   return {
     kind: "narration",
     requested: input3.requested,
     resolved,
     source: input3.source,
-    requiresKey: resolved === "elevenlabs",
-    configured: resolved !== "elevenlabs" || hasElevenLabs,
-    ...resolved === "elevenlabs" ? { configKey: "elevenlabs" } : {},
-    ...resolved === "elevenlabs" && !hasElevenLabs ? { missingKey: providerEnvVar("elevenlabs") } : {},
-    retryWith: resolved === "elevenlabs" && !hasElevenLabs ? ["vibe setup --full"] : []
+    requiresKey,
+    configured: hasKey,
+    ...requiresKey ? { configKey: resolved } : {},
+    ...requiresKey && !hasKey ? { missingKey: providerEnvVar(resolved) } : {},
+    retryWith: requiresKey && !hasKey ? ["vibe setup --full"] : []
   };
 }
 async function keyedProviderResolution(opts, projectDir) {
@@ -472546,7 +472733,7 @@ function loadPlanEnv(projectDir) {
     dir = dirname17(dir);
   }
 }
-var import_dotenv2, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
+var import_dotenv2, VIDEO_COST_USD, MUSIC_COST_USD, ELEVENLABS_NARRATION_COST_USD, OPENAI_NARRATION_COST_USD, COMPOSE_COST_USD, SUPPORTED_BUILD_IMAGE_PROVIDERS;
 var init_build_plan = __esm({
   "../cli/src/commands/_shared/build-plan.ts"() {
     "use strict";
@@ -472564,6 +472751,7 @@ var init_build_plan = __esm({
     VIDEO_COST_USD = 5;
     MUSIC_COST_USD = 0.5;
     ELEVENLABS_NARRATION_COST_USD = 0.05;
+    OPENAI_NARRATION_COST_USD = 0.01;
     COMPOSE_COST_USD = 0.06;
     SUPPORTED_BUILD_IMAGE_PROVIDERS = ["openai", "gemini", "grok"];
   }
@@ -486565,7 +486753,7 @@ function pickOutputPath(data) {
 }
 
 // ../cli/src/tools/_shared/elicit.ts
-var NARRATION_CHOICES = ["kokoro", "elevenlabs"];
+var NARRATION_CHOICES = ["kokoro", "openai", "elevenlabs"];
 var BACKDROP_CHOICES = ["skip", "openai"];
 function planBuildElicitation(args) {
   const assetsWillRun = args.stage === void 0 || args.stage === "all" || args.stage === "assets";
@@ -486580,8 +486768,9 @@ function planBuildElicitation(args) {
       description: "Which TTS engine narrates the video?",
       enum: [...NARRATION_CHOICES],
       enumNames: [
-        "Kokoro \u2014 free, runs locally on this machine",
-        "ElevenLabs \u2014 cloud TTS, uses your ElevenLabs credits"
+        "Kokoro \u2014 free, runs on this machine (first use downloads a ~90 MB voice model; slower)",
+        "OpenAI \u2014 fast cloud voice, uses your OpenAI API key (~$0.02 per video)",
+        "ElevenLabs \u2014 premium cloud voices, uses your ElevenLabs credits"
       ]
     };
     required.push("narration");
@@ -487786,9 +487975,9 @@ sceneCommand.command("add").description("Add a new scene to a project: AI narrat
   "Image prompt \u2014 generates assets/scene-<id>.png via the configured image provider"
 ).option("--headline <text>", "Visible headline (defaults to the humanised scene name)").option("--kicker <text>", "Small label above the headline (explainer / product-shot)").option("--insert-into <path>", "Root composition file to update", "index.html").option("--project <dir>", "Project directory", ".").option("--image-provider <name>", "Image provider: gemini, openai", "gemini").option(
   "--tts <provider>",
-  "TTS provider: auto, elevenlabs, kokoro (default auto \u2014 picks ElevenLabs when key set, else Kokoro local)",
+  "TTS provider: auto, elevenlabs, openai, kokoro (default auto \u2014 ElevenLabs key > OpenAI key > Kokoro local)",
   "auto"
-).option("--voice <id>", "Voice id (ElevenLabs name/id, or Kokoro id like af_heart, am_michael)").option(
+).option("--voice <id>", "Voice id (ElevenLabs name/id, OpenAI voice like marin, or Kokoro id like af_heart)").option(
   "--no-audio",
   "Skip TTS even when --narration is provided (useful for tests/agent dry runs)"
 ).option("--no-image", "Skip image generation even when --visuals is provided").option(
@@ -488049,7 +488238,7 @@ async function executeSceneAdd(opts) {
       throw error;
     }
     opts.onProgress?.(
-      resolution.provider === "kokoro" ? "Generating narration with Kokoro (local \u2014 first run downloads ~330MB)..." : "Generating narration with ElevenLabs..."
+      resolution.provider === "kokoro" ? "Generating narration with Kokoro (local \u2014 first run downloads a ~90MB model)..." : resolution.provider === "openai" ? "Generating narration with OpenAI (gpt-4o-mini-tts)..." : "Generating narration with ElevenLabs..."
     );
     const tts = await resolution.call(narrationText, {
       voice: opts.voice,
@@ -488809,7 +488998,9 @@ var sceneBuildSchema = z2.object({
   skipVideo: z2.boolean().optional().describe("Skip video generation for every beat (use existing MP4 assets if present)."),
   skipMusic: z2.boolean().optional().describe("Skip music generation for every beat (use existing audio assets if present)."),
   skipRender: z2.boolean().optional().describe("Stop after compose \u2014 produces compositions/*.html but no final MP4."),
-  ttsProvider: z2.enum(["auto", "elevenlabs", "kokoro"]).optional().describe("TTS provider override. Default 'auto'."),
+  ttsProvider: z2.enum(["auto", "elevenlabs", "openai", "kokoro"]).optional().describe(
+    "TTS provider override. Default 'auto' (elevenlabs key > openai key > local kokoro)."
+  ),
   voice: z2.string().optional().describe("TTS voice id (provider-specific)."),
   imageProvider: z2.enum(["openai"]).optional().describe("Image provider for backdrops. Default 'openai' (gpt-image-2)."),
   videoProvider: z2.enum(["seedance", "grok", "kling", "runway", "veo"]).optional().describe("Video provider for per-beat video cues. Default seedance."),
@@ -492652,7 +492843,7 @@ var planTool = defineTool({
     skipBackdrop: z7.boolean().optional().describe("Don't include backdrop image generation in the plan."),
     skipVideo: z7.boolean().optional().describe("Don't include video generation in the plan."),
     skipMusic: z7.boolean().optional().describe("Don't include music generation in the plan."),
-    ttsProvider: z7.enum(["auto", "elevenlabs", "kokoro"]).optional().describe("TTS provider override."),
+    ttsProvider: z7.enum(["auto", "elevenlabs", "openai", "kokoro"]).optional().describe("TTS provider override."),
     voice: z7.string().optional().describe("Voice id."),
     imageProvider: z7.string().optional().describe("Image provider override."),
     imageQuality: z7.enum(["standard", "hd"]).optional().describe("Image quality override."),
@@ -498289,7 +498480,7 @@ function buildServerInstructions(cwd = resolveServerWorkspaceRoot()) {
     "When creating projects with init, use a project name or workspace-relative path under the workspace root.",
     "Do not create projects in /tmp, /home/claude, /workspace, or other synthetic roots unless the user explicitly asks.",
     "Before high or very-high cost provider work, run a dry-run or plan when available and ask the user to confirm provider spend.",
-    "When the user's request leaves them unspecified, ask the user before building instead of silently picking defaults: narration provider (kokoro = free local, elevenlabs = cloud credits), backdrop image generation (paid; skipping is free), and visual style (list options via scene_list_styles). Present the choices and wait for the answer.",
+    "When the user's request leaves them unspecified, ask the user before building instead of silently picking defaults: narration provider (kokoro = free, runs locally, first use downloads a ~90 MB voice model and synthesis is slower; openai = fast cloud voice using the OpenAI API key, roughly $0.02 per video; elevenlabs = premium cloud voices using ElevenLabs credits), backdrop image generation (paid; skipping is free), and visual style (list options via scene_list_styles). Present the choices and wait for the answer.",
     "Narration and backdrop choices are independent \u2014 kokoro narration with OpenAI backdrops is a common combination. Pass each answer explicitly to build (ttsProvider plus skipBackdrop/imageProvider); never let one choice imply the other."
   ].join("\n");
 }
@@ -498316,7 +498507,7 @@ var server2 = new Server(
   {
     name: "vibeframe",
     // Stamped with the package version by build.js at bundle time.
-    version: "0.112.1"
+    version: "0.113.0"
   },
   {
     capabilities: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/mcp-server",
-  "version": "0.112.1",
+  "version": "0.113.0",
   "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.112.1",
-    "@vibeframe/core": "0.112.1"
+    "@vibeframe/cli": "0.113.0",
+    "@vibeframe/core": "0.113.0"
   },
   "engines": {
     "node": ">=20"