@vibeframe/mcp-server 0.108.0 → 0.109.0

package/README.md

@@ -41,7 +41,26 @@ args = ["-y", "@vibeframe/mcp-server"]
 enabled = true
 ```
 
-### Claude Desktop
+### Claude Desktop (recommended: extension)
+
+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).
+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,
+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`
+(output in `packages/mcp-server/dist-mcpb/`).
+
+#### Claude Desktop (manual JSON config)
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -64,6 +83,10 @@ config and may not preserve a raw `cwd` field. It anchors relative project paths
 so prompts like "create a project named launch" create `launch/` under your
 workspace instead of a temporary directory.
 
+Note: some Claude Desktop builds rewrite this file from memory and can mangle
+hand-edited entries (the entry comes back as `"command": "custom"`). The
+extension install above avoids that entirely and is the recommended path.
+
 ### Cursor
 
 Add to `.cursor/mcp.json`:

package/dist/index.js

@@ -4730,13 +4730,32 @@ async function loadKokoroFactory() {
     const mod = await import("kokoro-js");
     return mod.KokoroTTS;
   } catch (err) {
+    const fallback2 = await loadKokoroFromWorkspace();
+    if (fallback2)
+      return fallback2;
     throw mapKokoroImportError(err);
   }
 }
+async function loadKokoroFromWorkspace(baseDir = process.cwd()) {
+  try {
+    const { readFile: readFile45 } = await import("node:fs/promises");
+    const { join: join44, resolve: resolve79 } = await import("node:path");
+    const { pathToFileURL } = await import("node:url");
+    const pkgDir = resolve79(baseDir, "node_modules", "kokoro-js");
+    const pkg = JSON.parse(await readFile45(join44(pkgDir, "package.json"), "utf-8"));
+    const entry = pkg.exports?.node?.import ?? pkg.exports?.default ?? pkg.module ?? pkg.main;
+    if (!entry)
+      return null;
+    const mod = await import(pathToFileURL(join44(pkgDir, entry)).href);
+    return mod.KokoroTTS ?? null;
+  } 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`, or set ELEVENLABS_API_KEY to use the elevenlabs TTS provider instead.");
+    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 err instanceof Error ? err : new Error(String(err));
 }
@@ -25267,6 +25286,8 @@ imageProvider: openai
 
 Edit these beats before running \`vibe build\`. Each beat starts with
 YAML cues that drive narration, backdrop generation, and timing.
+Pacing: keep beats 6-15 seconds (split longer ones); a 90s video should
+have 6-8 beats, not 3 long ones.
 
 ## Beat hook \u2014 Hook
 
@@ -450075,6 +450096,29 @@ function filterSubCompFalsePositives(findings, isSubComposition) {
   if (!isSubComposition) return noEpsilon;
   return noEpsilon.filter((f2) => !SUB_COMP_FALSE_POSITIVES.has(f2.code));
 }
+function findInternalPhaseClipFindings(html) {
+  const findings = [];
+  for (const tagMatch of html.matchAll(/<[a-z][a-z0-9-]*\s[^>]*>/gi)) {
+    const tag = tagMatch[0];
+    if (!/class="[^"]*\bclip\b[^"]*"/i.test(tag)) continue;
+    const startAttr = tag.match(/data-start="([^"]+)"/i);
+    if (!startAttr) continue;
+    const start = Number(startAttr[1]);
+    if (!Number.isFinite(start) || start === 0) continue;
+    findings.push({
+      code: "internal_phase_clip_unsupported",
+      severity: "error",
+      message: `Inner .clip has data-start="${startAttr[1]}". The renderer does not toggle internal clip visibility inside sub-compositions, so phased clips render ALL phases at once (overlapping text).`,
+      fixHint: 'Give every inner .clip data-start="0" spanning the full beat, and drive phase changes with GSAP autoAlpha instead (animate the previous phase out, the next one in).',
+      snippet: tag.slice(0, 120)
+    });
+  }
+  return findings;
+}
+function withVibeframeSubCompFindings(findings, html, isSubComposition) {
+  if (!isSubComposition) return findings;
+  return [...findings, ...findInternalPhaseClipFindings(html)];
+}
 function applyMechanicalFixes(html, findings) {
   const fixedCodes = /* @__PURE__ */ new Set();
   let updated = html;
@@ -450120,7 +450164,11 @@ async function runProjectLint(opts) {
       source: "projectDir"
     };
     const raw2 = runHyperframeLint(prepared);
-    const findings = filterSubCompFalsePositives(raw2.findings, isSub);
+    const findings = withVibeframeSubCompFindings(
+      filterSubCompFalsePositives(raw2.findings, isSub),
+      html,
+      isSub
+    );
     if (opts.fix && findings.length > 0) {
       const { html: nextHtml, fixedCodes } = applyMechanicalFixes(html, findings);
       if (fixedCodes.length > 0) {
@@ -450130,7 +450178,11 @@ async function runProjectLint(opts) {
         files.push({
           file: rel,
           isSubComposition: isSub,
-          findings: filterSubCompFalsePositives(reLinted.findings, isSub)
+          findings: withVibeframeSubCompFindings(
+            filterSubCompFalsePositives(reLinted.findings, isSub),
+            nextHtml,
+            isSub
+          )
         });
         continue;
       }
@@ -469633,8 +469685,14 @@ ${finalDurationBullet}
   Animate the backdrop/media plane instead; let text enter briefly, then hold
   still at its final CSS position. Continuous transforms on text ancestors can
   create subpixel shimmer in screenshot-captured renders.
-- Timed children inside the composition have \`class="clip"\` plus
-  \`data-start\`, \`data-duration\`, \`data-track-index\`.
+- Inner \`.clip\` elements carry \`data-start\`, \`data-duration\`,
+  \`data-track-index\` \u2014 but **every inner clip MUST be full-window:
+  \`data-start="0"\` spanning the whole beat.** The renderer does NOT toggle
+  internal clip visibility inside sub-compositions, so "phase clips" with a
+  non-zero \`data-start\` render ALL phases at once and text stacks on top of
+  itself. For multi-phase beats, drive phase changes with GSAP \`autoAlpha\`
+  inside full-window clips: animate phase A out (\`autoAlpha: 0\`), then
+  phase B in, on the same timeline.
 - If \`assets/backdrop-${ctx.beat.id}.png\` exists, use that local file as the
   full-frame visual backdrop. The exact path string is
   \`assets/backdrop-${ctx.beat.id}.png\`; do NOT prefix it with \`../\` or \`./\`
@@ -469648,7 +469706,9 @@ ${finalDurationBullet}
   narration.
 - Keep a meaningful visual progression across the full beat duration: line
   tracing, gentle camera drift, staged labels, value cards, or parallax. Avoid
-  a completed static frame holding silently for most of the beat.
+  a completed static frame holding silently for most of the beat. For longer
+  beats, progress through content phases with GSAP autoAlpha (old phase out,
+  new phase in) \u2014 never with inner clip windows.
 - Do not import external font or image URLs. Use the project DESIGN.md font
   choice when explicit; otherwise use \`Inter\`, which is available in the
   deterministic render font map.
@@ -469823,7 +469883,11 @@ function lintBeatHtml(html, beatId) {
     source: "projectDir"
   };
   const raw2 = runHyperframeLint(prepared);
-  const findings = filterSubCompFalsePositives(raw2.findings, true);
+  const findings = withVibeframeSubCompFindings(
+    filterSubCompFalsePositives(raw2.findings, true),
+    html,
+    true
+  );
   return {
     errorCount: findings.filter((f2) => f2.severity === "error").length,
     warningCount: findings.filter((f2) => f2.severity === "warning").length,
@@ -470262,7 +470326,8 @@ function buildInstructions(args) {
   lines.push(`2. Read \`DESIGN.md\` for project-specific palette, typography, motion signature.`);
   lines.push(`3. For each beat in the \`beats\` array below, author HTML at \`outputPath\` matching the \`userPrompt\`. The beat \`body\` carries the narrative + visual + animation intent; \`cues\` carries machine-readable per-beat overrides (narration, duration, backdrop, voice).`);
   lines.push(`3b. Use each beat's \`finalDurationSec\` (narration-synced) for \`data-duration\` and timeline anchors when present \u2014 NOT the storyboard \`duration\`, which is only the minimum. Scenes composed at the storyboard duration end early and render black tails.`);
-  lines.push(`3c. If your environment cannot write files (e.g. Claude Desktop / MCP-only hosts), author each beat's HTML and submit it with the \`scene_submit\` tool (beat id + html). It validates with the same Hyperframes lint and writes the file for you; on lint errors it returns the findings without writing \u2014 fix and resubmit.`);
+  lines.push(`3c. Never give inner \`.clip\` elements a non-zero \`data-start\` \u2014 the renderer does not toggle internal clip visibility inside sub-compositions, so phased clips render all phases at once (overlapping text). Use full-window clips and GSAP autoAlpha phase transitions instead. Also keep beats 6-15s; split anything longer in the storyboard first.`);
+  lines.push(`3d. If your environment cannot write files (e.g. Claude Desktop / MCP-only hosts), author each beat's HTML and submit it with the \`scene_submit\` tool (beat id + html). It validates with the same Hyperframes lint and writes the file for you; on lint errors it returns the findings without writing \u2014 fix and resubmit.`);
   if (args.beatCount > 1) {
     lines.push(`4. After authoring all ${args.beatCount} beat(s), run \`vibe scene lint --fix\` to validate. Fix any remaining errors by editing the HTML directly.`);
   } else if (args.filtered) {
@@ -470584,7 +470649,11 @@ function lintHtml(html, rel, isSub) {
     source: "projectDir"
   };
   const raw2 = runHyperframeLint(prepared);
-  return filterSubCompFalsePositives(raw2.findings, isSub);
+  return withVibeframeSubCompFindings(
+    filterSubCompFalsePositives(raw2.findings, isSub),
+    html,
+    isSub
+  );
 }
 function lintFilesToIssues(files) {
   const issues = [];
@@ -471655,6 +471724,16 @@ function validateStoryboardMarkdown(markdown) {
       }
     }
   }
+  for (const beat of parsed.beats) {
+    if (beat.duration !== void 0 && beat.duration > MAX_RECOMMENDED_BEAT_SEC) {
+      issues.push({
+        severity: "warning",
+        code: "BEAT_DURATION_TOO_LONG",
+        beatId: beat.id,
+        message: `Beat "${beat.id}" is ${beat.duration}s \u2014 beats longer than ${MAX_RECOMMENDED_BEAT_SEC}s render static and overstuffed. Split it into 6-15s beats (a 90s video should have 6-8 beats).`
+      });
+    }
+  }
   return {
     ok: !issues.some((i2) => i2.severity === "error"),
     beats: parsed.beats,
@@ -471753,7 +471832,7 @@ function readLeadingCueBlock(body) {
     return { full: match2[0], error: error instanceof Error ? error.message : String(error) };
   }
 }
-var import_yaml5, STORYBOARD_CUE_KEYS, HEADING_RE2, LEADING_CUE_RE, ALLOWED_CUE_KEYS, STRING_CUE_KEYS;
+var import_yaml5, STORYBOARD_CUE_KEYS, HEADING_RE2, LEADING_CUE_RE, ALLOWED_CUE_KEYS, STRING_CUE_KEYS, MAX_RECOMMENDED_BEAT_SEC;
 var init_storyboard_edit = __esm({
   "../cli/src/commands/_shared/storyboard-edit.ts"() {
     "use strict";
@@ -471773,6 +471852,7 @@ var init_storyboard_edit = __esm({
     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"]);
+    MAX_RECOMMENDED_BEAT_SEC = 15;
   }
 });
 
@@ -491942,7 +492022,8 @@ function revisionMessages(opts) {
     "The JSON object must have: storyboardMd string, summary string, changedBeats string[], warnings string[].",
     "Preserve existing frontmatter, beat ids, cue YAML keys, and useful prose unless the user asks to change structure.",
     "Keep cue YAML valid. Allowed cue keys are duration, narration, backdrop, video, motion, voice, music, asset.",
-    "If a target duration is supplied, every beat must have a positive duration cue and durations must sum to that target."
+    "If a target duration is supplied, every beat must have a positive duration cue and durations must sum to that target.",
+    "Aim for 6-15 seconds per beat and never exceed ~15s \u2014 long beats render as static, overstuffed scenes. A 90-second video should have 6-8 beats."
   ].join("\n");
   const repairBlock = opts.invalidStoryboard ? [
     "The previous revision failed validation. Repair it.",
@@ -497625,7 +497706,23 @@ This creates a music video-style edit where cuts happen in rhythm with the music
 }
 
 // src/instructions.ts
+import { mkdirSync as mkdirSync13 } from "node:fs";
 import { isAbsolute as isAbsolute9, resolve as resolve78 } from "node:path";
+function applyWorkspaceEnv(env4 = process.env, chdir = (dir) => process.chdir(dir)) {
+  const raw2 = env4.VIBE_MCP_WORKSPACE?.trim();
+  if (!raw2) return null;
+  const dir = resolve78(raw2);
+  try {
+    mkdirSync13(dir, { recursive: true });
+    chdir(dir);
+    return dir;
+  } catch (error) {
+    console.error(
+      `[vibeframe] Could not use VIBE_MCP_WORKSPACE=${raw2} (${error instanceof Error ? error.message : String(error)}); staying in ${process.cwd()}`
+    );
+    return null;
+  }
+}
 function resolveServerWorkspaceRoot(env4 = process.env, cwd = process.cwd()) {
   const initCwd = env4.INIT_CWD?.trim();
   if (!initCwd) return cwd;
@@ -497645,10 +497742,12 @@ function buildServerInstructions(cwd = resolveServerWorkspaceRoot()) {
 console.log = (...args) => console.error(...args);
 console.info = (...args) => console.error(...args);
 console.debug = (...args) => console.error(...args);
+applyWorkspaceEnv();
 var server2 = new Server(
   {
     name: "vibeframe",
-    version: "0.1.0"
+    // Stamped with the package version by build.js at bundle time.
+    version: "0.109.0"
   },
   {
     capabilities: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/mcp-server",
-  "version": "0.108.0",
+  "version": "0.109.0",
   "description": "VibeFrame MCP Server - AI-native video editing via Model Context Protocol",
   "type": "module",
   "bin": {
@@ -60,14 +60,15 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/cli": "0.108.0",
-    "@vibeframe/core": "0.108.0"
+    "@vibeframe/core": "0.109.0",
+    "@vibeframe/cli": "0.109.0"
   },
   "engines": {
     "node": ">=20"
   },
   "scripts": {
     "build": "node build.js",
+    "build:mcpb": "node build-mcpb.js",
     "build:types": "tsc --emitDeclarationOnly",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",