@instavar/mcp-server 0.2.1 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/instavar/mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/instavar/mcp-server/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/%40instavar%2Fmcp-server)](https://www.npmjs.com/package/@instavar/mcp-server)
-[![MCP server on Glama](https://glama.ai/mcp/servers/instavar/mcp-server/badge)](https://glama.ai/mcp/servers/instavar/mcp-server)
+[![Glama score](https://glama.ai/mcp/servers/instavar/mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/instavar/mcp-server)
 
 Drive the full [Instavar Studio](https://instavar.com) video workflow —
 **create → render → approve → publish → metrics** — from Claude Code or Codex,

package/dist/index.js

@@ -153,6 +153,7 @@ var briefSceneSchema = z.object({
     "custom"
   ]),
   durationInFrames: z.number().optional(),
+  narrationText: z.string().optional(),
   title: z.string().optional(),
   subtitle: z.string().optional(),
   text: z.string().optional(),
@@ -172,7 +173,13 @@ var briefSceneSchema = z.object({
   totalSteps: z.number().optional(),
   items: z.array(z.object({ label: z.string(), value: z.number() })).optional(),
   src: z.string().optional(),
-  caption: z.string().optional()
+  caption: z.string().optional(),
+  // A-roll generation (video-window scenes): source "generate" triggers
+  // flag-gated WaveSpeed image/video gen server-side from generatePrompt;
+  // "url" (default) uses src as-is. Kept in sync with the app's
+  // briefSceneSchema - see the parity test in the app suite.
+  source: z.enum(["url", "generate"]).optional(),
+  generatePrompt: z.string().optional()
 });
 var directionsBriefSchema = z.object({
   subtitle: z.string().optional(),
@@ -221,8 +228,15 @@ var createBriefShape = {
   lessonTitle: z.string().optional().describe("Display title rendered inside the video"),
   steps: z.array(briefStepSchema).optional().describe("Structured steps for educational content (LaTeX)"),
   scenes: z.array(briefSceneSchema).optional().describe("Scene graph for the UniversalVideo composition"),
-  aspectRatio: z.enum(ASPECT_RATIOS).default("9:16").describe("Aspect ratio (default 9:16)"),
+  // No zod .default() here: a default would materialize into the parsed tool
+  // arguments and relay to /api/v1/jobs as if the caller stated it, corrupting
+  // the resolution provenance the API echoes back. Unset must stay absent;
+  // the API re-applies 9:16 server-side.
+  aspectRatio: z.enum(ASPECT_RATIOS).optional().describe("Aspect ratio (defaults to 9:16 when omitted)"),
   compositionId: z.string().optional().describe("Remotion composition ID override (advanced)"),
+  voiceId: z.string().optional().describe(
+    "TTS narrator voice ID. Unknown IDs are rejected before rendering; when omitted, the org's saved voice preference or the system default is used and reported in the response's resolution block."
+  ),
   directions: directionsBriefSchema.optional().describe(
     "DirectionsWalkthrough 'find-us' payload: source clips (legs), decision-point cues on the realtime walk timeline, outro, and optional music. Set compositionId 'DirectionsWalkthrough' (or objective 'directions')."
   )
@@ -241,6 +255,9 @@ var editBriefShape = {
   ),
   publishTarget: z.enum(PUBLISH_TARGETS).optional().describe(
     "Updated target social platform. Distribution metadata only - does not trigger a re-render."
+  ),
+  voiceId: z.string().optional().describe(
+    "Updated TTS narrator voice ID. Triggers a re-render with the new voice."
   )
 };
 
@@ -258,7 +275,7 @@ function registerTools(server) {
     "list_jobs",
     {
       title: "List jobs",
-      description: "List recent video jobs for the current organization (newest first).",
+      description: "List recent video jobs for the current organization (newest first). Start here to discover job IDs; for one job's full detail use get_job_status.",
       inputSchema: {
         limit: z2.number().int().min(1).max(50).default(10).describe("Number of jobs to return (default 10, max 50)"),
         status: z2.enum([
@@ -284,7 +301,7 @@ function registerTools(server) {
     "get_job_status",
     {
       title: "Get job status",
-      description: "Get detailed status for a job: runs, artifacts, verifications, plus the current video and thumbnail URLs.",
+      description: "Get detailed status for a job: runs, artifacts, verifications, plus the current video and thumbnail URLs. The main polling target after create_video_brief or edit_video_brief; for post-publish engagement numbers use get_job_metrics instead.",
       inputSchema: { jobId: uuid("The job ID to check") },
       annotations: READ_ONLY
     },
@@ -294,7 +311,7 @@ function registerTools(server) {
     "get_video_state",
     {
       title: "Get video state",
-      description: "Get the materialized video state for a job (composition decisions: scenes, duration, aspect ratio, etc.).",
+      description: "Get the materialized video state for a job (composition decisions: scenes, duration, aspect ratio, etc.). Use it to inspect what the video contains; for pipeline progress and video URLs use get_job_status.",
       inputSchema: { jobId: uuid("The job ID") },
       annotations: READ_ONLY
     },
@@ -306,7 +323,7 @@ function registerTools(server) {
     "get_job_metrics",
     {
       title: "Get job metrics",
-      description: "Get the latest platform engagement metric snapshots for a published job (newest first). Read-only.",
+      description: "Get the latest platform engagement metric snapshots for a published job (newest first). Read-only. Only meaningful after publish_job; for render progress use get_job_status.",
       inputSchema: {
         jobId: uuid("The job ID"),
         limit: z2.number().int().min(1).max(20).default(10).describe("Max metric snapshots (default 10, max 20)")
@@ -323,7 +340,7 @@ function registerTools(server) {
     "get_cost_summary",
     {
       title: "Get cost summary",
-      description: "Query production infrastructure costs (Lambda, RunPod, R2, WaveSpeed, PoYo), optionally with reconciliation drift.",
+      description: "Query production infrastructure costs (Lambda, RunPod, R2, WaveSpeed, PoYo), optionally with reconciliation drift. This is spend data, not engagement \u2014 for a published job's audience numbers use get_job_metrics.",
       inputSchema: {
         since: z2.string().optional().describe("ISO date \u2014 only include events after this date"),
         provider: z2.enum(["runpod", "lambda", "r2", "wavespeed", "poyo", "all"]).default("all").describe("Filter by provider"),
@@ -343,7 +360,7 @@ function registerTools(server) {
     "create_video_brief",
     {
       title: "Create video brief",
-      description: "Create a new video job from a structured brief and trigger the render pipeline. Returns the job and run IDs.",
+      description: "Create a new video job from a structured brief and trigger the render pipeline. Returns the job and run IDs immediately; rendering continues asynchronously (typically a few minutes) \u2014 poll get_job_status until draft_ready. Requires a key with write scope. To change an existing job, use edit_video_brief instead of creating a duplicate.",
       inputSchema: createBriefShape,
       annotations: SAFE_WRITE
     },
@@ -353,7 +370,7 @@ function registerTools(server) {
     "edit_video_brief",
     {
       title: "Edit video brief",
-      description: "Edit an existing job's brief (only provided fields change). Changing the script, caption, title, lessonTitle, objective, steps, scenes or aspectRatio triggers a re-render and returns the new run ID; objective also re-routes the composition. Changing only publishTarget updates the job's target platform without re-rendering.",
+      description: "Edit an existing job's brief (only provided fields change). Changing the script, caption, title, lessonTitle, objective, steps, scenes, aspectRatio or voiceId triggers a re-render and returns the new run ID; objective also re-routes the composition. Changing only publishTarget updates the job's target platform without re-rendering. For a brand-new video use create_video_brief.",
       inputSchema: editBriefShape,
       annotations: SAFE_WRITE
     },
@@ -368,7 +385,7 @@ function registerTools(server) {
     "approve_job",
     {
       title: "Approve job",
-      description: "Approve a rendered job so it becomes publishable (draft_ready/awaiting_review/needs_changes -> approved) and revoke active review links.",
+      description: "Approve a rendered job so it becomes publishable (draft_ready/awaiting_review/needs_changes -> approved) and revoke active review links. Required before publish_job will accept the job.",
       inputSchema: { jobId: uuid("The job ID to approve") },
       annotations: {
         readOnlyHint: false,
@@ -386,7 +403,7 @@ function registerTools(server) {
     "publish_job",
     {
       title: "Publish job",
-      description: "Publish an APPROVED job to its connected social destination via the gated publish API. All production gates run (paid plan, ownership, abuse, QA, disclosure, destination, rights, moderation). For YouTube pass youtubePrivacyStatus:'private' for safe runs.",
+      description: "Publish an APPROVED job to its connected social destination via the gated publish API. All production gates run (paid plan, ownership, abuse, QA, disclosure, destination, rights, moderation). Requires a key with publish scope; the post goes live on the external platform and cannot be recalled by the API. For YouTube pass youtubePrivacyStatus:'private' for safe runs.",
       inputSchema: {
         jobId: uuid("The approved job to publish"),
         youtubePrivacyStatus: z2.enum(["private", "unlisted", "public"]).optional().describe("YouTube only. Use 'private' for safe dogfood runs."),
@@ -461,7 +478,7 @@ function registerTools(server) {
 // package.json
 var package_default = {
   name: "@instavar/mcp-server",
-  version: "0.2.1",
+  version: "0.3.0",
   mcpName: "com.instavar/mcp-server",
   description: "Instavar Studio MCP server \u2014 drive the full video create\u2192render\u2192approve\u2192publish\u2192metrics workflow from Claude Code or Codex with an API key.",
   type: "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instavar/mcp-server",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "mcpName": "com.instavar/mcp-server",
   "description": "Instavar Studio MCP server — drive the full video create→render→approve→publish→metrics workflow from Claude Code or Codex with an API key.",
   "type": "module",