@openvidstudio/mcp-server 0.1.0 → 1.3.1

package/docs/SCRIPT.md

@@ -44,6 +44,140 @@ whether it needs a real capture or an honest `dom-demo`. Don't write a
 claim the decision tree can't resolve to something real or
 explicitly-labeled-constructed.
 
+## Tone
+
+The claim-obligates-visual rule and the direct, confident voice above are non-negotiable
+in every tone. Tone changes energy and pacing, never honesty.
+
+- **default.** Direct, confident, plain. The baseline above with nothing added.
+- **release.** Terser still. Built for a changelog/what's-new cut: lead with the change,
+  name the beat that shows it, skip framing sentences like "here's what's new."
+- **walkthrough.** Slower, more explanatory. Full sentences, a beat's VO may explain why a
+  step matters, not just name it. For a docs/tutorial video where the viewer is following
+  along, not skimming.
+- **quiet.** Understated, almost dry. Short sentences, no adjectives doing marketing work
+  ("powerful", "seamless"), let the visual carry the excitement. Fits an audience that
+  already trusts the product and wants the facts.
+
+State the tone once at the top of a video's brief if it isn't `default`, so every beat's
+VO is written in the same register rather than drifting line to line.
+
+## Music-only videos (no narration)
+
+`beats.json` can carry a top-level `narration`:
+
+```json
+{ "narration": "none", "beats": [ ... ] }
+```
+
+Omit it and `"voice"` is assumed, matching every `beats.json` written before this existed:
+every beat needs `vo`, held to the pace budget above.
+
+Under `"none"`, `vo` is optional on every beat and, if present at all, is not held to that
+budget: nothing is going to speak it. A beat can instead carry `onScreenText`, checked
+against a reading-time budget instead of a spoken one:
+
+```
+duration_seconds >= (onScreenText word count / 3.5) + 0.8
+```
+
+3.5 words/sec is a faster ceiling than the spoken 2.3-2.9 range on purpose: a viewer reads
+faster than a narrator speaks, and the fixed 0.8s covers a card's own entrance. `onScreenText`
+is optional too: a beat can be pure visual-plus-music with nothing to read at all.
+
+`stitch_composition`'s `musicBed` defaults its volume to 1.0 (full level) when narration is
+`"none"`, instead of the 0.18 tuned for sitting quietly under a voice.
+
+## Lesson scripts (Supernova mode)
+
+A lesson video (production mode `"supernova"`, see PIPELINE.md) is won or lost on its script, and the
+visuals illustrate it. These rules are for a lesson, in addition to the pacing above (which still
+applies: 2.3 to 2.9 words per second, checked by `validate_beats`). `check_script` lints them.
+
+A lesson explains **one concept in up to two minutes**, and every lesson has the same shape so a viewer
+knows what is coming. A series (a channel, a course) keeps that shape constant; only the content changes.
+
+Start from a **concept card**, `src/videos/<name>/concept.json`:
+
+```json
+{
+  "goal": "explain why a projectile is two independent motions, and use that to find its range",
+  "terms": ["projectile", "components"],
+  "example": "a ball launched at 20 m/s at 30 degrees, with g = 9.81 m/s squared: it lands 35.3 m away",
+  "reference": "Physics A.1 Kinematics",
+  "referenceSpoken": "physics, topic A one, kinematics",
+  "maxSeconds": 120
+}
+```
+
+The goal is what the viewer can do afterwards, the terms are the two or three that need defining, and the
+example is the one thing the whole lesson keeps coming back to, with its real numbers. `reference` is
+where the lesson sits (a syllabus chapter code, "Part 2 of 4"), as it is written on screen, and
+`referenceSpoken` is how it is said; both are optional, and when they are set the opening beat has to say
+it. `maxSeconds` is the length budget and defaults to 120. Get the script approved before any scene is built.
+
+### The arc
+
+Seven beats, in this order. A beat can take more than one scene, and a lesson that has nothing to derive
+(a definition, a classification) replaces the derive beat with a second picture, but never reorders
+the others. The times are for a 120 second lesson; shrink them in proportion for a shorter one.
+
+| # | Beat | What it does | About |
+|---|---|---|---|
+| 1 | Hook | A question or a surprising fact a beginner can feel, in the first sentence. Then say where the lesson sits: the `referenceSpoken` | 10 s |
+| 2 | Picture | The diagram starts here, before any formula. Say what the viewer is looking at in everyday words, and define each new term at first use | 20 s |
+| 3 | Set up | Name the quantities with their symbols and units, and state the assumptions ("no air resistance", "level ground"). Label them on the diagram | 15 s |
+| 4 | Derive | Build the formula line by line from things the viewer has already accepted. One `Equation` per line, each with its `spoken` form, and say why each step is allowed | 35 s |
+| 5 | Use it | One worked example with the real numbers and their units | 20 s |
+| 6 | Aha | The result that generalises or surprises, and where it stops being true (the assumption that breaks) | 10 s |
+| 7 | Close | A one-line recap, then the check question. End on the question and let the last frame hold | 10 s |
+
+About 270 to 330 words fit (2.3 to 2.9 words per second on plain prose; maths-heavy lines are read slower,
+nearer 2.2). The viewer should never wait more than about 8 seconds without something on screen changing,
+and the diagram's first element is on screen inside the first 15 seconds.
+
+### Rules
+
+1. **Hook in the first sentence**: a question or a surprising fact, with a number if there is one. Never
+   "in this video".
+2. **Say where it sits** in the first beat, if the card has a `reference`.
+3. **Intuition and a concrete example before any formula.** The formula arrives as a shortcut for
+   something the viewer already sees.
+4. **Define every term in plain words at first use** ("a slope is how steep a line is"), at most two new
+   terms in a beat.
+5. **One idea per beat. Sentences of about 14 words or fewer**, in spoken English, at about grade 8 or
+   below. A lesson is heard once.
+6. **Write maths as it is spoken.** Each `Equation` carries a `spoken` string ("x squared plus one") that
+   must appear in the narration of its beat.
+7. **Derive, do not announce.** A derivation shows each step: what is assumed, what is substituted, what
+   cancels. "It can be shown that" is not a derivation. If a step cannot fit in the time, it is a
+   Part 2, not a faster voice.
+8. **End with a one-line recap, then a check question** the viewer can answer in their head. The last
+   beat ends with a question mark.
+
+### Correctness
+
+The linter counts and matches; it cannot tell that a formula is right. Before a script is approved:
+
+- Write the derivation in a file next to the script (`derivation.md`), one line per step with its reason.
+- Check every step and every number on screen with code (plain Python or sympy), not by hand: the
+  symbolic result, the worked example, and the units (does the result have the dimensions it should?).
+- Compute the numbers a scene shows from the same code that checked them, rather than typing them twice.
+- Name the assumptions and one place the result fails.
+- Have someone who knows the subject read the derivation and the script before a scene is built.
+
+### What `check_script` reports
+
+Each finding points at a beat: average sentence length (warning above 16 words), Flesch-Kincaid reading
+level (warning above grade 9), a term used with no definition beside it (note), more than two new terms in
+a beat (warning), an `Equation`'s `spoken` string missing from the narration (error), a hook that is not a
+question or does not hold a number (warning) or opens "in this video" (error), pace against the beat length
+(error, the same budget as `validate_beats`), a last beat that does not end with a question (error), the
+whole lesson running over `maxSeconds` (error), and a card `reference` that the first beat does not say
+(error; a warning when `referenceSpoken` is missing, because then it cannot be checked). It counts and
+matches; it cannot tell you the explanation is good or the derivation is correct, so listen to it, and
+check the maths as above.
+
 ## No em dashes
 
 No em dashes in any VO line, ever, same writing rule as every other doc in

package/docs/STYLE.md

@@ -6,13 +6,18 @@ a rule here, it fails QC.
 ## What good cinematography for this pipeline looks like (decoded)
 
 1. **Camera lives INSIDE the UI.** Never show a flat full-screen
-   screenshot. The camera is always zoomed into a region (120-250% scale),
-   slightly tilted (1-4 degrees rotateZ, 2-8 degrees rotateX/Y
-   perspective), and moving (push-in, drift, pan). UI is rendered oversized
-   on a stage; the camera crops into it.
-2. **Shallow depth of field.** One focal plane per shot. Everything else
-   (background layers, edge regions, sidebars) carries gaussian blur.
-   Focus can rack between layers mid-shot.
+   screenshot. The camera is always zoomed into a region (105-160% scale
+   on a capture with text; constructed panels with nothing to read can go
+   further), slightly tilted (1-4 degrees rotateZ, 2-8 degrees rotateX/Y
+   perspective), and moving (push-in, drift, pan). Past 160% the product
+   text goes soft. UI is rendered oversized on a stage; the camera crops
+   into it.
+2. **Depth without blur.** One focal plane per shot. Depth comes from
+   parallax (`Layer` depth, `LayeredShot`), a slight tilt and handheld
+   sway, not from smearing the frame. Blur is opt-in (`depthOfField`
+   defaults to 0), is never applied to text the viewer has to read (list
+   those regions in `protect`), and stays under about 4px when used.
+   Focus can still rack from one point to another mid-shot (`rackTo`).
 3. **Low-key lighting.** Dark scenes: deep vignette, soft glow accents on
    the key element (accent-colored text-shadow/box-shadow). Light scenes:
    soft large-radius drop shadows, floating cards, generous negative
@@ -27,8 +32,37 @@ a rule here, it fails QC.
 7. **Motion never stops.** Every shot has at least a subtle push-in (2-5%
    scale over the shot). Static frame = dead frame = QC fail.
 
+## Non-negotiables, and strong defaults
+
+This file has two kinds of rule.
+
+**Non-negotiable.** No brief overrides these, at any creative level:
+
+- Product UI and product text on screen come only from real captures or real tool output;
+  anything constructed is clearly non-product or disclosed. AI-generated clips never show
+  product UI. (A Supernova lesson has no product behind it, so everything in it is constructed on
+  purpose and the per-shot disclosure is replaced by one line in the description: the video is a
+  constructed explanation, not footage.)
+- Every claim in on-screen text or narration is backed by something shown in the same beat or an
+  adjacent one.
+- No em dashes on screen or in narration.
+- The quality gates pass before the final render: nothing cropped or outside the safe area, text
+  at or above the minimum size and on screen long enough to read, no dead frames (unless the brief
+  marks the hold as deliberate), contrast passing, loudness on target.
+- The user approves the brief and the beats before anything is written or rendered.
+
+**Strong defaults.** Everything else below (a camera that always moves, no linear easing, grain
+and vignette, the palette and type, cut rhythm, the SFX map) is how a video made with this
+pipeline looks unless the brief says otherwise. The brief may override any of them with a stated
+reason, recorded in its `styleOverrides` (`{ rule, reason }`), so the departure is a decision
+someone made and not an accident. At literal level, or without a brief, the defaults stand.
+
 ## Hard rules
 
+The rules in this section are the ones most often broken. They are QC failures. The provenance
+rule and the no-em-dash rule are non-negotiable; for the others, a brief may record an override
+with a reason.
+
 - NO linear easing. Ever. Use `@openvidstudio/core`'s `E.*` presets
   (cinematic bezier / springs).
 - Every scene wrapped in `CinematicScene` (grain + vignette + grade always
@@ -71,11 +105,42 @@ a rule here, it fails QC.
   #3ECF8E. Warn: #F5A623.
 - Light scenes: bg #F4F6F9, cards #FFFFFF, shadow rgba(15,23,42,0.12)
   large radius.
-- Fonts: Inter (UI), JetBrains Mono (terminal/code) via
-  `@remotion/google-fonts`.
+- Fonts: Inter (UI), JetBrains Mono (terminal/code), bundled locally (see
+  `packages/core/src/localFonts.ts`) rather than fetched from Google Fonts at render
+  time, so a render with no network access still gets the real glyphs.
 - Grain: 4-6% opacity, animated (re-seeded translate per frame). Vignette:
   25-40% edge darkening.
 
+## The hook
+
+The first 2 seconds decide whether anyone watches the rest. Plan the hook beat before any
+other beat, not last. It must be built from a real capture or a labeled `dom-demo`, same
+as every other beat: an exciting hook that overclaims fails the claim-obligates-visual
+rule (`SCRIPT.md`) just as much as a boring one would.
+
+No generic SaaS language anywhere in VO or on-screen text: "streamline your workflow,"
+"powerful," "seamless," "unlock." Use the product's own copy and claims instead. If the
+product's README doesn't say it that way, the video shouldn't either.
+
+## Beat-locked cuts
+
+When a video's music bed is a `compose_score` track (or any other track `plan_music_cues`
+has a grid for), scene cuts can land on the beat instead of at an arbitrary second. Read
+the `<stem>.cues.json` next to a composed track, or call `plan_music_cues` for any other
+track, before writing `beats.json`'s `start` values.
+
+- `strongCues` are the sparse, strong moments (bar downbeats for a composed score). Snap a
+  handful of major reveals here: a hard cut into a new scene, a hero reveal, the outro
+  logo landing. Shift the reveal's start to within about 0.15s of the nearest strong cue.
+- `beats` is the full beat grid. Snap sequential reveals here: cards or stats arriving one
+  after another, a list filling in. Snap each to within about 0.10s of a consecutive beat.
+- Lock at most a handful of moments per video, not every cut. A video where everything
+  is beat-locked reads as rigid, not musical.
+- Readability outranks the grid. If snapping to a cue would cut off a line of text before
+  it's readable, use the natural timing instead and skip that lock.
+- Mark a locked cut in the brief so a later edit doesn't silently drift off the beat:
+  `// beat-locked: 12.86s`.
+
 ## Deferred (do not attempt in pure Remotion)
 
 - Live-action beats (desk/keyboard shots, ambient texture): text-free, so

package/docs/SUPERNOVA.md

@@ -0,0 +1,153 @@
+# SUPERNOVA.md: short animated lessons
+
+Supernova is openvidstudio's second kind of production: a STEM concept explained in up to two minutes, vertical
+(1080x1920), narrated and captioned, with a script first and pictures that illustrate it. It is a production
+**mode** (`production.mode: "supernova"`), not a fourth creative level. The process is the `supernova` skill; the
+script rules are in [SCRIPT.md](SCRIPT.md); the primitives are in [API.md](API.md).
+
+Make a lesson project with `init_project` and `mode: "supernova"`. It stores the mode, defaults the frame to
+1080x1920, and installs `@openvidstudio/stem`, its display font and the maths renderer.
+
+## One concept in up to two minutes, a series for a big topic
+
+A lesson teaches one thing and takes **at most two minutes**. A big topic is a short series ("Part 2 of
+4") and each part ends on the question the next one answers. Every lesson has the same seven-beat shape
+(hook, picture, set up, derive, use it, aha, close), written out with times and rules in
+[SCRIPT.md](SCRIPT.md#the-arc), so a viewer, and a series, can rely on it.
+
+## The concept card
+
+`src/videos/<name>/concept.json`, next to `beats.json`. `check_script` reads it, and `validate_scenes` lets the
+numbers in its worked example appear on screen.
+
+```json
+{
+  "goal": "tell why a derivative is a slope",
+  "terms": ["slope", "derivative"],
+  "example": "a ball rolling down a hill, followed for one second",
+  "reference": "Calculus 5.1",
+  "referenceSpoken": "calculus, topic five point one",
+  "maxSeconds": 120
+}
+```
+
+`goal` is what the viewer can do afterwards, `terms` the two or three that need defining, `example` the one worked
+example the lesson keeps coming back to, with its real numbers. `reference` is where the lesson sits (a syllabus
+chapter, "Part 2 of 4"), `referenceSpoken` is how it is said, and the opening beat has to say it. Both are
+optional. `maxSeconds` is the length budget (default 120). A worked example, projectile motion:
+
+```json
+{
+  "goal": "work out how far and how high a launched ball goes, from its speed and angle",
+  "terms": ["projectile", "range"],
+  "example": "a ball launched at 20 m/s at 30 degrees, with g = 9.81 m/s squared: it flies for 2.04 s, lands 35.3 m away and peaks at 5.1 m",
+  "reference": "Kinematics, part 1 of 2",
+  "referenceSpoken": "kinematics, part one of two"
+}
+```
+
+Its script, in the shape SCRIPT.md asks for (each beat's duration comes from the measured voice, see
+NARRATION.md):
+
+| Beat | Narration |
+|---|---|
+| hook | How far does a thrown ball go? This is kinematics, part one of two. Throw it harder and it goes farther. But how much farther? |
+| picture | Picture a ball leaving your hand at an angle. A ball in flight like this is called a projectile. It rises, slows and falls. |
+| set-up | Say it leaves at a speed v and an angle theta. Ignore the air. Gravity pulls it down at g, and nothing pulls it sideways. |
+| derive | Split the launch in two. Sideways, x equals v cosine theta times t. Upward, y equals v sine theta times t, minus a half g t squared. It lands when y is zero again, at t equals two v sine theta over g. |
+| use-it | Use twenty metres a second at thirty degrees. That is two point oh four seconds in the air. The range is how far it lands: thirty-five point three metres. |
+| aha | Now change the angle. Forty-five degrees gives the longest range, and two angles that add to ninety land in the same spot. |
+| close | So: two separate motions, one steady, one pulled by gravity. At the very top of the path, what is the ball's acceleration? |
+
+This is a worked example of the format, not a lesson that has been built and listened to.
+
+## Design: Void + Spark
+
+The idea: **light is meaning.** Everything is dark and flat except the one thing the viewer must look at.
+
+| Token | Value |
+|---|---|
+| Void | `#07060B`, panels `#0E0C16`, hairline grid at 5% white |
+| Text | warm white `#F3EFE6` (never pure white), dim `#8C8799` |
+| Math | blue giant `#5CC8FF` |
+| Physics | solar amber `#FFB347`, ember `#FF7A3D` |
+| CS | nebula violet `#B58CFF` |
+| Chemistry | red dwarf `#FF4D5E` |
+| Biology | aurora `#7CFFB2` |
+
+One accent per subject, so a profile grid of lessons reads as a spectrum. `supernovaDesignSystem(subject)` builds it:
+`export const design = supernovaDesignSystem("physics")`. The display face is Space Grotesk, the body face Inter, both from
+local files. Equations are in sans-serif maths (MathJax with the Fira font; the comparison with KaTeX is in API.md).
+
+**Glow budget: one glowing element at a time.** The Spark is one; a Nova's flash is one. `validate_scenes` (render
+mode) counts them: more than one is a warning, more than two an error, except in a beat that holds a Nova.
+
+## The primitives
+
+All in `@openvidstudio/stem`, documented with stills in [API.md](API.md#supernova-openvidstudiostem):
+
+- `Spark`: the pen, the pointer and the particle. Traces curves, carries a value along a function, orbits, splits,
+  falls under gravity, walks pointers through arrays.
+- `Nova`: the payoff, once per video, on the aha sentence. Silence, a three-frame flash, a shockwave ring, the result
+  condenses from particles.
+- `Axes`, `Plot`, `NumberLine`: graphs, tangents, shaded area, intervals.
+- `Equation`: sans-serif maths revealed term by term, with a required `spoken` form that must match the narration.
+- `FreeBody`: forces as arrows whose length is exactly magnitude times the scale shown.
+- `ArrayViz`: cells, named pointers, a lit range and a dimmed one, a Spark-driven pointer.
+- `useNarrationWords(beatId)` (in core): when each word of the narration is said, so the Spark can point at it.
+
+One idea on screen at a time, at most two things moving.
+
+## The voice
+
+One fixed voice for the handle, so a viewer knows it by ear and lessons can be made in any order.
+
+| | |
+|---|---|
+| Engine | `edge-tts` 7.3 or newer (fast, and it gives word timings). It sends the script text to Microsoft, which is fine for public lesson scripts. Version 7.2.8 was refused with a 403 in October 2026: `pip install -U edge-tts` fixes it |
+| Voice | `en-US-AndrewNeural` |
+| Rate | the engine's default, `+0%`. Pace comes from the script (2.3 to 2.9 words per second); the stretch is clamped to 0.9 to 1.12 so it never sounds processed |
+| Final pass | `omnivoice` gives better control but runs about 40 times slower than real time on a CPU: use it for a last pass, never to iterate |
+
+This is a proposal, the default voice of the engine, chosen so there is one. Changing it is a decision for the handle's
+owner, made once and for every lesson: pass the same `voice` to `generate_narration` each time.
+
+### Fit the beats to the voice
+
+The voice reads plain prose at about 3 words per second and number-heavy lines at about 2.2, so a word count
+alone mis-sizes a beat. Write the beats with provisional lengths, run `generate_narration`, read each clip's
+`spokenSeconds`, and set each beat to about the spoken length plus half a second. `validate_beats` still wants
+2.3 to 2.9 words per second on the beat length, so a very short line ("Now the honest part.") needs a beat of about
+1.7 seconds, and a long maths line needs more words or a longer beat. Rewrite the beats and run `generate_narration`
+again with `overwrite: true`. NARRATION.md has the clamp.
+
+## Captions
+
+Burn captions in for silent autoplay. The word timings carry bare words with no punctuation, so take the text from
+the beat's `vo`: split it on spaces (it matches the timings one to one) and break the caption at sentence ends, so a
+caption never runs one sentence into the next. Keep them inside the safe zone below.
+
+```tsx
+const tokens = vo.split(/\s+/).filter(Boolean);           // the beat's narration text
+const shown = tokens.length === narr.words.length ? tokens : narr.words.map((w) => w.word);
+const breakAfter = (i, size) => /[.?!:]$/.test(shown[i]) || (/[,;]$/.test(shown[i]) && size >= 3) || size >= 6;
+```
+
+## Reels safe zones
+
+Instagram draws its own interface over a reel, so keep key content (text, the part of a diagram being explained) out of the
+top about 14% (270 px) and the bottom about 22% (420 px) of the 1080x1920 frame, and about 10% (108 px) off the right
+edge. `supernovaDesignSystem` sets its layout grid to exactly that (108 / 270 / 420).
+
+Checked against current guidance in October 2026: the top figure agrees with the one most sources cite (14%, about 269 px,
+from Meta's percentages for Reels ads). The bottom does not: sources give anywhere from about 340 px to 35% (672 px). The
+35% is for ads; 22% is a design choice for an organic reel and a minimum. If a lesson is also run as an ad, keep key content
+out of the bottom 35%. Meta publishes percentages, not pixels, and the interface changes, so look at a real upload before
+trusting any of these. Backgrounds can run to the edge; key content stays inside.
+
+## Checks
+
+`validate_beats` (pace), `check_script` (the script, the two-minute budget and the reference), `validate_scenes` with
+`render: true` (framing, numbers, glow), a contact sheet, then listen. `finalize_video` must report no `audio-tick`. See
+the skill for the order. `render_video` asks for a brand lock and a lesson has none, so pass `skipBrandLock: true`.
+`validate_scenes` warns "fewer than two camera keyframes" on lesson scenes, which are flat on purpose: ignore it.

package/docs/TOOLS.md

@@ -0,0 +1,52 @@
+# Tools
+
+GENERATED by `node scripts/generate-tool-docs.mjs` from the tools the server actually registers.
+Do not edit by hand: CI fails if this file is out of date. Each tool's own description (what it
+checks, what it returns, when to use it) is what an MCP client shows an agent; this page is the map.
+
+41 tools, 42 with the Higgsfield tier enabled.
+
+| Tool | What it does |
+| --- | --- |
+| `add_motion_primitive` | Copy a catalog motion primitive's source into the project. |
+| `capture_desktop` | Record a desktop application, window, or whole screen. |
+| `capture_mobile` | Record an Android device or iOS Simulator. |
+| `capture_screen_recording` | Capture a zoom-compensated, full-viewport screen recording. |
+| `capture_screenshot` | Capture a zoom-compensated, DOM-rect-cropped screenshot. |
+| `capture_terminal` | Record a real command run as timed, themeable text. |
+| `catalog_motion_primitives` | Search the motion primitives catalog. |
+| `check_script` | Lint a lesson script against its concept card. |
+| `collect_facts` | Merge a video's run records into facts.json. |
+| `compose_score` | Compose an original, arc-matched score. |
+| `contact_sheet` | Render one image showing every beat. |
+| `diff_beats` | Turn an edited beats.json draft into a per-beat rerun plan. |
+| `docs_drift` | Find the clips that no longer match the pages they document. |
+| `export_rendition` | Export the same beats as a GIF, a docs screenshot set, or store frames. |
+| `extract_brand` | Read a repo's own palette, fonts and logo, and theme the video with them. |
+| `finalize_video` | Final assembly: loudness target, poster frame, size-capped share copy. |
+| `find_music_bed` | Search public-domain music catalogs for a background track. |
+| `generate_narration` | Generate narration audio for every beat. |
+| `import_higgsfield_clip` | Import an already-generated Higgsfield clip into this project's asset convention. Only registered when `hasHiggsfield` is true in `openvidstudio.config.json`. |
+| `import_music_bed` | Download a CC0 track and shape it into a music bed. |
+| `init_project` | Initialize an openvidstudio project. |
+| `job_status` | Poll an async job's progress and result. |
+| `plan_beats` | Plan a beat skeleton with word budgets before writing narration. |
+| `plan_music_cues` | Detect or read beat and strong-cue timestamps for a music track. |
+| `plan_production` | Turn creative level + time budget into a concrete, time-estimated plan. |
+| `plan_shots` | Rank what a demo should show, from the repository's own emphasis. |
+| `plan_sound_effects` | Work out which sound effects are needed and where to get them. |
+| `preflight` | Check the machine can actually run the pipeline. |
+| `qc_capture` | Flag capture artifacts that are present but wrong. |
+| `qc_extract_frames` | Extract QC frames for every beat. |
+| `reformat_vertical` | Reformat a finished video to 9:16 using the manifest. |
+| `release_diff` | Two refs in, a what's-new clip's manifest out. |
+| `render_stills` | Render representative frames without a full video encode. |
+| `render_video` | Render a composition with the Remotion CLI. |
+| `scaffold_scene` | Scaffold a working scene for one beat. |
+| `stitch_composition` | Stitch a video's beats into a composition. |
+| `validate_beats` | Validate a drafted beats.json. |
+| `validate_scenes` | Check scenes for problems that render without erroring. |
+| `visual_regression` | Diff this render's beats against the last accepted one. |
+| `write_beats_file` | Write a validated beats.json to disk. |
+| `write_brief` | Write a validated creative brief (brief.md + brief.json) to disk. |
+| `write_description` | Write a video's description, with sample content disclosed. |

package/package.json

@@ -1,54 +1,60 @@
-{
-  "name": "@openvidstudio/mcp-server",
-  "version": "0.1.0",
-  "description": "MCP server exposing openvidstudio's mechanical pipeline tools: project scaffolding, beats validation, scene stubs, composition stitching, render, QC frame extraction, and zoom-compensated screenshot/screen-recording capture.",
-  "license": "Apache-2.0",
-  "type": "commonjs",
-  "bin": {
-    "openvidstudio-mcp": "dist/stdio.js"
-  },
-  "main": "./dist/server.js",
-  "types": "./dist/server.d.ts",
-  "files": [
-    "dist",
-    "templates",
-    "docs"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "playwright": "^1.48.0",
-    "sharp": "^0.33.5",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.5",
-    "typescript": "5.9.3"
-  },
-  "scripts": {
-    "build": "node scripts/copy-template.mjs && node scripts/copy-docs.mjs && tsc",
-    "prepublishOnly": "npm run build",
-    "typecheck": "tsc --noEmit",
-    "test": "node scripts/manual-test.mjs"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/AnayDhawan/openvidstudio.git",
-    "directory": "packages/mcp-server"
-  },
-  "homepage": "https://github.com/AnayDhawan/openvidstudio#readme",
-  "bugs": {
-    "url": "https://github.com/AnayDhawan/openvidstudio/issues"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "remotion",
-    "playwright",
-    "video",
-    "demo-video",
-    "claude"
-  ]
-}
+{
+  "name": "@openvidstudio/mcp-server",
+  "version": "1.3.1",
+  "description": "MCP server for openvidstudio: plan, capture, narrate, score, render and finalize a video of your real product, driven by an AI coding agent.",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "commonjs",
+  "bin": {
+    "openvidstudio-mcp": "dist/stdio.js"
+  },
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "files": [
+    "dist",
+    "templates",
+    "docs",
+    "py"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@remotion/bundler": "4.0.534",
+    "@remotion/renderer": "4.0.534",
+    "playwright": "^1.64.0",
+    "sharp": "^0.35.5",
+    "zod": "^4.6.6",
+    "@openvidstudio/capture": "1.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AnayDhawan/openvidstudio.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/AnayDhawan/openvidstudio#readme",
+  "bugs": {
+    "url": "https://github.com/AnayDhawan/openvidstudio/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "remotion",
+    "playwright",
+    "video",
+    "demo-video",
+    "claude"
+  ],
+  "scripts": {
+    "build": "node scripts/copy-template.mjs && node scripts/copy-docs.mjs && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node scripts/manual-test.mjs"
+  }
+}