@vibeframe/mcp-server 0.109.1 → 0.110.0

package/README.md

@@ -125,6 +125,21 @@ Claude Code drives `vibe` natively via shell + the scaffolded `AGENTS.md` / `CLA
 claude mcp add vibeframe --scope project -- npx -y @vibeframe/mcp-server
 ```
 
+## Human-in-the-Loop Choices
+
+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.
+  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).
+- On hosts without elicitation (Claude Desktop today), the server
+  instructions tell the agent to present the same choices in chat and wait
+  for your answer.
+
 ## What You Can Do
 
 Once connected, your MCP host can resolve prompts like these into typed tool calls:

package/dist/index.js

@@ -469537,6 +469537,7 @@ function isComposerProvider(value) {
   return value === "claude" || value === "openai" || value === "gemini";
 }
 function resolveComposer(explicit) {
+  loadEnv();
   if (explicit) {
     const key2 = readKey(explicit);
     if (!key2) {
@@ -469561,6 +469562,7 @@ var ENV_VAR, PROVIDER_LABEL, ComposerResolveError;
 var init_composer_resolve = __esm({
   "../cli/src/commands/_shared/composer-resolve.ts"() {
     "use strict";
+    init_api_key();
     ENV_VAR = {
       claude: "ANTHROPIC_API_KEY",
       openai: "OPENAI_API_KEY",
@@ -486484,6 +486486,76 @@ function pickOutputPath(data) {
   return typeof candidate === "string" ? candidate : void 0;
 }
 
+// ../cli/src/tools/_shared/elicit.ts
+var NARRATION_CHOICES = ["kokoro", "elevenlabs"];
+var BACKDROP_CHOICES = ["skip", "openai"];
+function planBuildElicitation(args) {
+  const assetsWillRun = args.stage === void 0 || args.stage === "all" || args.stage === "assets";
+  if (!assetsWillRun) return null;
+  const properties = {};
+  const required = [];
+  const narrationUndecided = !args.skipNarration && (args.ttsProvider === void 0 || args.ttsProvider === "auto");
+  if (narrationUndecided) {
+    properties.narration = {
+      type: "string",
+      title: "Narration voice-over",
+      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"
+      ]
+    };
+    required.push("narration");
+  }
+  if (args.skipBackdrop === void 0 && args.imageProvider === void 0) {
+    properties.backdrop_images = {
+      type: "string",
+      title: "Backdrop images",
+      description: "Generate AI background images for each scene?",
+      enum: [...BACKDROP_CHOICES],
+      enumNames: [
+        "Skip \u2014 free, pure typographic scenes",
+        "OpenAI \u2014 paid image generation (roughly $1-3 per video)"
+      ]
+    };
+    required.push("backdrop_images");
+  }
+  if (args.maxCostUsd === void 0) {
+    properties.max_cost_usd = {
+      type: "number",
+      title: "Max provider spend (USD)",
+      description: "Abort before any paid provider call when the estimate exceeds this cap. Leave empty for no cap.",
+      minimum: 0
+    };
+  }
+  if (Object.keys(properties).length === 0) return null;
+  return {
+    message: "VibeFrame is about to build this video. Choose how the assets are generated:",
+    requestedSchema: { type: "object", properties, required }
+  };
+}
+function applyElicitationAnswers(args, content) {
+  if (!content) return args;
+  const next = { ...args };
+  const narration = content.narration;
+  if (typeof narration === "string" && NARRATION_CHOICES.includes(narration)) {
+    next.ttsProvider = narration;
+  }
+  const backdrop = content.backdrop_images;
+  if (backdrop === "skip") {
+    next.skipBackdrop = true;
+  } else if (backdrop === "openai") {
+    next.skipBackdrop = false;
+    next.imageProvider = "openai";
+  }
+  const cap = content.max_cost_usd;
+  if (typeof cap === "number" && Number.isFinite(cap) && cap >= 0) {
+    next.maxCostUsd = cap;
+  }
+  return next;
+}
+
 // ../cli/src/commands/_shared/visual-styles.ts
 var STYLES = [
   {
@@ -488722,9 +488794,32 @@ var sceneBuildTool = defineTool({
   name: "build",
   category: "scene",
   cost: "high",
-  description: "v0.60 one-shot orchestrator: read STORYBOARD.md per-beat YAML cues (narration / backdrop / duration), dispatch TTS + image generation per beat, compose scene HTML via the compose-scenes-with-skills pipeline, then render to MP4. Use this instead of chaining init + scene_add + render manually. Caches by SHA256 of (DESIGN.md + cue body) so re-runs are idempotent and cheap. Long runs: over MCP, calls exceeding ~45s return immediately with { promoted: true, jobId, status: 'running' } \u2014 poll status_job every 15-30s until completed/failed instead of re-invoking build. Emits MCP progress notifications when the client supplies a progressToken.",
+  description: "v0.60 one-shot orchestrator: read STORYBOARD.md per-beat YAML cues (narration / backdrop / duration), dispatch TTS + image generation per beat, compose scene HTML via the compose-scenes-with-skills pipeline, then render to MP4. Use this instead of chaining init + scene_add + render manually. Caches by SHA256 of (DESIGN.md + cue body) so re-runs are idempotent and cheap. Long runs: over MCP, calls exceeding ~45s return immediately with { promoted: true, jobId, status: 'running' } \u2014 poll status_job every 15-30s until completed/failed instead of re-invoking build. Emits MCP progress notifications when the client supplies a progressToken. When the MCP host supports elicitation, unspecified asset choices (narration provider, backdrop images, cost cap) are confirmed with the user via a form before the build starts.",
   schema: sceneBuildSchema,
   async execute(args, ctx) {
+    let warnings;
+    if (ctx.surface === "mcp" && ctx.elicit) {
+      const form = planBuildElicitation(args);
+      if (form) {
+        const outcome = await ctx.elicit(form).catch(() => null);
+        if (outcome === null) {
+          warnings = ["Asset-choice elicitation failed or timed out; proceeding with defaults."];
+        } else if (outcome.action === "accept") {
+          args = applyElicitationAnswers(args, outcome.content);
+        } else {
+          return {
+            success: false,
+            error: "Build cancelled \u2014 the user declined the asset choices.",
+            data: {
+              cancelled: true,
+              retryWith: [
+                `build { projectDir: "${args.projectDir ?? "."}", ttsProvider: "kokoro", skipBackdrop: true }`
+              ]
+            }
+          };
+        }
+      }
+    }
     const projectDir = args.projectDir ? resolve34(ctx.workingDirectory, args.projectDir) : ctx.workingDirectory;
     const runBuild = (report) => executeSceneBuild({
       projectDir,
@@ -488752,7 +488847,9 @@ var sceneBuildTool = defineTool({
         ctx.onProgress?.({ message: update2.message ?? update2.stage });
         report(update2);
       }
-    }).then(mapBuildResultToToolResult);
+    }).then(mapBuildResultToToolResult).then(
+      (result) => warnings === void 0 ? result : { ...result, data: { ...result.data, elicitationWarnings: warnings } }
+    );
     if (ctx.surface !== "mcp") {
       return runBuild(() => void 0);
     }
@@ -497250,7 +497347,8 @@ function buildMcpDispatcher(manifest2) {
         () => tool.execute(parsed.data, {
           workingDirectory: process.cwd(),
           surface: "mcp",
-          ...extra?.onProgress ? { onProgress: sink.send } : {}
+          ...extra?.onProgress ? { onProgress: sink.send } : {},
+          ...extra?.elicit ? { elicit: extra.elicit } : {}
         })
       );
       const text = result.success ? JSON.stringify({ success: true, ...result.data }) : result.data ? JSON.stringify({
@@ -497745,10 +497843,22 @@ function buildServerInstructions(cwd = resolveServerWorkspaceRoot()) {
     "For args named dir, projectDir, output, videoPath, or source, prefer workspace-relative paths unless the user explicitly provides an absolute path.",
     "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."
+    "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."
   ].join("\n");
 }
 
+// src/elicit.ts
+var ELICIT_TIMEOUT_MS = 6e5;
+function makeElicitFn(server3, env4 = process.env) {
+  if ((env4.VIBE_MCP_ELICIT ?? "").toLowerCase() === "off") return void 0;
+  if (!server3.getClientCapabilities()?.elicitation) return void 0;
+  return (form) => server3.elicitInput(
+    { mode: "form", message: form.message, requestedSchema: form.requestedSchema },
+    { timeout: ELICIT_TIMEOUT_MS }
+  );
+}
+
 // src/index.ts
 console.log = (...args) => console.error(...args);
 console.info = (...args) => console.error(...args);
@@ -497759,7 +497869,7 @@ var server2 = new Server(
   {
     name: "vibeframe",
     // Stamped with the package version by build.js at bundle time.
-    version: "0.109.1"
+    version: "0.110.0"
   },
   {
     capabilities: {
@@ -497776,20 +497886,28 @@ server2.setRequestHandler(ListToolsRequestSchema, async () => {
 server2.setRequestHandler(CallToolRequestSchema, async (request5, extra) => {
   const { name, arguments: args } = request5.params;
   const progressToken = request5.params._meta?.progressToken;
+  const elicit = makeElicitFn(server2);
   return handleToolCall(
     name,
     args || {},
-    progressToken === void 0 ? void 0 : {
-      onProgress: ({ progress, total, message }) => {
-        void extra.sendNotification({
-          method: "notifications/progress",
-          params: {
-            progressToken,
-            progress: progress ?? 0,
-            ...total !== void 0 ? { total } : {},
-            ...message ? { message } : {}
-          }
-        }).catch(() => void 0);
+    progressToken === void 0 && elicit === void 0 ? void 0 : {
+      ...elicit ? { elicit } : {},
+      ...progressToken === void 0 ? {} : {
+        onProgress: ({
+          progress,
+          total,
+          message
+        }) => {
+          void extra.sendNotification({
+            method: "notifications/progress",
+            params: {
+              progressToken,
+              progress: progress ?? 0,
+              ...total !== void 0 ? { total } : {},
+              ...message ? { message } : {}
+            }
+          }).catch(() => void 0);
+        }
       }
     }
   );

package/package.json

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