@instavar/mcp-server 0.3.0 → 0.4.1

package/README.md

@@ -4,19 +4,58 @@
 [![npm](https://img.shields.io/npm/v/%40instavar%2Fmcp-server)](https://www.npmjs.com/package/@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,
-without leaving your terminal.
+Make local videos with Instavar's open-source Remotion templates from Claude
+Code or Codex. The public template, schema, scaffold, and troubleshooting tools
+work without an account or API key.
 
-The server is a thin HTTP client: it authenticates with a per-user API key and
-talks to the hosted Instavar API. It holds **no database connection** and stores
-no data of its own.
+Add an Instavar API key when you want the hosted workflow:
+**create → render → approve → publish → metrics**. The authenticated tools are
+thin HTTP clients to the hosted Instavar API. The package holds **no database
+connection** and stores no data of its own.
+
+## Which model runs?
+
+The MCP host supplies the general-purpose LLM.
+
+- In Claude Code, the selected Claude model interprets the request and calls
+  Instavar tools.
+- In Codex, the selected OpenAI model interprets the request and calls the same
+  tools.
+- Other compatible hosts use their own selected model and authentication.
+
+The MCP server does not provide Sonnet, GPT, or another general-purpose model.
+It exposes typed Instavar capabilities to the model already running in the
+user's host. Depending on the host and sign-in method, that model usage may draw
+from a personal or workspace subscription, separate usage credits, or API
+billing. Those provider rules can change.
+
+Local Remotion rendering uses your own machine. Instavar meters or charges its
+hosted services, including rendering,
+storage, specialist media generation, QA, publishing, and other declared job
+costs. Using a subscription-backed agent does not make those services free.
+
+For the full architecture, see
+[`docs/architecture/studio-agent-workflow-architecture.md`](../../docs/architecture/studio-agent-workflow-architecture.md).
+For dated provider evidence, see
+[`reports/research/subscription-backed-agent-runtime-2026-07-10.md`](../../reports/research/subscription-backed-agent-runtime-2026-07-10.md).
 
 ## Setup
 
-1. Create an API key at **https://instavar.com/studio/settings** (shown once —
-   copy it).
-2. Add the server to your MCP client config:
+Add the server to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "instavar": {
+      "command": "npx",
+      "args": ["-y", "@instavar/mcp-server"]
+    }
+  }
+}
+```
+
+This starts with the free local template tools. To unlock hosted Studio tools,
+create an API key at **https://instavar.com/studio/settings**, then add it:
 
 ```json
 {
@@ -30,17 +69,33 @@ no data of its own.
 }
 ```
 
-3. Restart the client. The `instavar` tools appear.
+Restart the client. The free tools appear in both modes. Hosted tools appear
+when the key is configured.
 
 ### Environment
 
-| Var                 | Required | Default                | Purpose                                                          |
-| ------------------- | -------- | ---------------------- | ---------------------------------------------------------------- |
-| `INSTAVAR_API_KEY`  | yes      | —                      | Your key from `/studio/settings`. Scoped to your org; revocable. |
-| `INSTAVAR_BASE_URL` | no       | `https://instavar.com` | Override the API host.                                           |
+| Var                 | Required | Default                | Purpose                                                     |
+| ------------------- | -------- | ---------------------- | ----------------------------------------------------------- |
+| `INSTAVAR_API_KEY`  | no       | —                      | Unlocks hosted Studio tools. Scoped to your org; revocable. |
+| `INSTAVAR_BASE_URL` | no       | `https://instavar.com` | Override the API host.                                      |
 
 ## Tools
 
+Free local tools:
+
+| Tool                      | What it does                                      |
+| ------------------------- | ------------------------------------------------- |
+| `get_capabilities`        | Reports free and optional account features.       |
+| `list_templates`          | Lists published Remotion template families.       |
+| `get_template`            | Returns one template contract.                    |
+| `get_video_schema`        | Returns the public VideoSpec JSON Schema.         |
+| `get_example`             | Returns a starter VideoSpec.                      |
+| `scaffold_video_spec`     | Creates a deterministic VideoSpec skeleton.       |
+| `get_render_instructions` | Returns the local validation and render workflow. |
+| `diagnose_render_error`   | Classifies common local render failures.          |
+
+Hosted tools, available when `INSTAVAR_API_KEY` is configured:
+
 | Tool                     | What it does                                                                                   |
 | ------------------------ | ---------------------------------------------------------------------------------------------- |
 | `list_jobs`              | List recent jobs (newest first).                                                               |
@@ -48,14 +103,31 @@ no data of its own.
 | `get_video_state`        | Materialized composition state for a job.                                                      |
 | `get_job_metrics`        | Platform engagement snapshots for a published job.                                             |
 | `get_cost_summary`       | Infra cost summary (Lambda / RunPod / R2 / WaveSpeed / PoYo).                                  |
+| `inspect_workflow`       | Read the current workflow and its version history.                                             |
 | `create_video_brief`     | Create a job from a structured brief and start rendering.                                      |
 | `edit_video_brief`       | Patch a brief (incl. objective / publishTarget); re-renders unless only publishTarget changed. |
+| `retry_video_qa`         | Retry degraded or unavailable QA against the same current frozen video artifact.               |
+| `audit_video_qa`         | Run an advisory Qwen3.6-Plus second opinion against the same frozen video.                     |
+| `regenerate_narration`   | Regenerate narration and its dependent video from the unchanged durable brief.                 |
+| `draft_workflow`         | Store a complete workflow using the inspected `expectedVersion` (`0` only when none exists).   |
+| `patch_workflow`         | Create a conflict-aware workflow version from a recursive patch.                               |
+| `validate_workflow`      | Validate and compile the inspected workflow version without rendering.                         |
+| `preview_workflow`       | Read the compiled UniversalVideo brief without rendering.                                      |
+| `compare_workflows`      | Compare two durable workflow versions field by field.                                          |
+| `approve_workflow`       | Approve the inspected valid version without approving or publishing the video job.             |
 | `approve_job`            | Approve a rendered job so it can be published.                                                 |
 | `publish_job`            | Publish an approved job to its connected social destination.                                   |
 | `connect_account`        | Start connecting a social account (headless OAuth pairing).                                    |
 | `connect_account_status` | Poll a pending account connection until it is connected.                                       |
 
-Writes require a key with the `write` scope; `publish_job` requires `publish`.
+Workflow inspection, preview, and comparison require `read`. Workflow draft,
+patch, validation, and approval require `write`. `publish_job` requires
+`publish`.
+
+Workflow tools reject unknown arguments instead of silently discarding them.
+API calls time out after 15 seconds. A stale-version `409` tells the caller to
+inspect the latest version, while an unavailable upload or other dependency
+conflict tells the caller to resolve that dependency before retrying.
 
 ### Connecting a social account from the terminal
 

package/dist/index.js

@@ -4,12 +4,354 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/public-templates.ts
+import { z } from "zod";
+var TEMPLATE_REPOSITORY = "https://github.com/instavar/remotion-templates";
+var TEMPLATE_ENDPOINT = "https://instavar.com/api/mcp/templates";
+var templateIds = [
+  "qa-ad",
+  "proof-walkthrough",
+  "announcement-brief",
+  "social-remix",
+  "finance-brief"
+];
+var templateIdSchema = z.enum(templateIds);
+var aspectSchema = z.enum(["9:16", "4:5", "1:1"]);
+var templates = [
+  {
+    id: "qa-ad",
+    name: "Question and answer ad",
+    description: "A short video with a hook, source-video window, explanation points, and call to action.",
+    aspects: ["9:16", "4:5", "1:1"]
+  },
+  {
+    id: "proof-walkthrough",
+    name: "Proof walkthrough",
+    description: "A paced explanation for equations, worked reasoning, and a final takeaway.",
+    aspects: ["9:16", "4:5", "1:1"]
+  },
+  {
+    id: "announcement-brief",
+    name: "Announcement brief",
+    description: "A concise announcement with a headline, supporting points, optional media, and next action.",
+    aspects: ["9:16", "4:5", "1:1"]
+  },
+  {
+    id: "social-remix",
+    name: "Social remix",
+    description: "A caption-forward treatment that frames an existing clip with a hook, context, and call to action.",
+    aspects: ["9:16", "4:5", "1:1"]
+  },
+  {
+    id: "finance-brief",
+    name: "Data and finance brief",
+    description: "An editorial brief for comparisons, numeric highlights, evidence, caveats, and a recommendation.",
+    aspects: ["9:16", "4:5", "1:1"]
+  }
+];
+var videoSpecSchema = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://instavar.com/schemas/video-spec-1.0.json",
+  title: "Instavar VideoSpec",
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "schemaVersion",
+    "id",
+    "templateFamily",
+    "meta",
+    "target",
+    "scenes"
+  ],
+  properties: {
+    schemaVersion: { const: "1.0" },
+    id: { type: "string", pattern: "^[a-z0-9][a-z0-9-]{2,80}$" },
+    templateFamily: { enum: templateIds },
+    meta: {
+      type: "object",
+      required: ["title"],
+      properties: {
+        title: { type: "string", minLength: 1 },
+        description: { type: "string" },
+        tags: { type: "array", items: { type: "string" } }
+      }
+    },
+    target: {
+      type: "object",
+      required: ["aspect", "fps", "durationMode"],
+      properties: {
+        aspect: { enum: ["9:16", "4:5", "1:1"] },
+        fps: { type: "integer", minimum: 1 },
+        durationMode: { enum: ["auto", "fixed"] },
+        fixedDurationSec: { type: "number", exclusiveMinimum: 0 }
+      }
+    },
+    scenes: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        required: ["id", "kind", "content"],
+        properties: {
+          id: { type: "string", minLength: 1 },
+          kind: {
+            enum: [
+              "hero",
+              "points",
+              "equation",
+              "video-window",
+              "cta",
+              "custom"
+            ]
+          },
+          content: { type: "object" },
+          timing: { type: "object" }
+        }
+      }
+    }
+  }
+};
+var annotations = {
+  readOnlyHint: true,
+  openWorldHint: false,
+  destructiveHint: false
+};
+function result(value, summary) {
+  return {
+    structuredContent: value,
+    content: [{ type: "text", text: summary }]
+  };
+}
+function slugify(value) {
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 72);
+  return slug.length >= 3 ? slug : "new-video";
+}
+function scaffoldVideoSpec(args) {
+  const scenes = [
+    {
+      id: "hero",
+      kind: "hero",
+      content: {
+        title: args.title,
+        subtitle: "Replace with a concise promise"
+      }
+    }
+  ];
+  if (args.templateId === "qa-ad" || args.templateId === "social-remix") {
+    scenes.push({
+      id: "source-video",
+      kind: "video-window",
+      content: { src: args.mediaSrc ?? "public/replace-with-your-video.mp4" }
+    });
+  }
+  scenes.push({
+    id: args.templateId === "proof-walkthrough" ? "working" : "key-points",
+    kind: args.templateId === "proof-walkthrough" ? "equation" : "points",
+    content: args.templateId === "proof-walkthrough" ? {
+      title: "Work through the idea",
+      latexBlocks: ["x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}"]
+    } : {
+      title: "Key points",
+      points: [
+        "Replace with evidence",
+        "Replace with explanation",
+        "Replace with takeaway"
+      ]
+    }
+  });
+  scenes.push({
+    id: "cta",
+    kind: "cta",
+    content: { line1: "Replace with the next action" }
+  });
+  return {
+    schemaVersion: "1.0",
+    id: slugify(args.title),
+    templateFamily: args.templateId,
+    meta: { title: args.title, tags: [] },
+    target: { aspect: args.aspect, fps: 30, durationMode: "auto" },
+    style: {
+      theme: "default",
+      variant: "default",
+      safeAreaProfile: "metaSafe"
+    },
+    audio: { ducking: true },
+    assets: {},
+    scenes
+  };
+}
+function registerPublicTemplateTools(server) {
+  server.registerTool(
+    "get_capabilities",
+    {
+      title: "Get video capabilities",
+      description: "Call first. Reports free local features and optional account features.",
+      inputSchema: {},
+      annotations
+    },
+    async () => result(
+      {
+        authentication: "optional",
+        apiKeyConfigured: Boolean(process.env.INSTAVAR_API_KEY?.trim()),
+        repository: TEMPLATE_REPOSITORY,
+        endpoint: TEMPLATE_ENDPOINT,
+        localFeatures: [
+          "template discovery",
+          "VideoSpec schema and examples",
+          "deterministic scaffolding",
+          "local render instructions",
+          "render error diagnosis"
+        ],
+        accountFeatures: [
+          "managed rendering and storage",
+          "workflow review and approval",
+          "social publishing and metrics"
+        ]
+      },
+      process.env.INSTAVAR_API_KEY?.trim() ? "Free local tools and authenticated Instavar Studio tools are available." : "Free local tools are available. Add INSTAVAR_API_KEY to unlock hosted Studio tools."
+    )
+  );
+  server.registerTool(
+    "list_templates",
+    {
+      title: "List Remotion templates",
+      description: "List public templates, optionally filtered by aspect ratio.",
+      inputSchema: { aspect: aspectSchema.optional() },
+      annotations
+    },
+    async ({ aspect }) => {
+      const filtered = aspect ? templates.filter((template) => template.aspects.includes(aspect)) : templates;
+      return result(
+        { templates: filtered },
+        filtered.map((template) => `${template.id}: ${template.description}`).join("\n")
+      );
+    }
+  );
+  server.registerTool(
+    "get_template",
+    {
+      title: "Get Remotion template",
+      description: "Get one public template contract.",
+      inputSchema: { templateId: templateIdSchema },
+      annotations
+    },
+    async ({ templateId }) => {
+      const template = templates.find((item) => item.id === templateId);
+      return result(
+        { template },
+        `${template?.name ?? templateId}
+${template?.description ?? ""}`
+      );
+    }
+  );
+  server.registerTool(
+    "get_video_schema",
+    {
+      title: "Get VideoSpec schema",
+      description: "Return the public VideoSpec JSON Schema.",
+      inputSchema: {},
+      annotations
+    },
+    async () => result(
+      { schemaVersion: "1.0", jsonSchema: videoSpecSchema },
+      "VideoSpec schema version 1.0."
+    )
+  );
+  server.registerTool(
+    "get_example",
+    {
+      title: "Get VideoSpec example",
+      description: "Return a starter example for one template.",
+      inputSchema: { templateId: templateIdSchema },
+      annotations
+    },
+    async ({ templateId }) => result(
+      {
+        templateId,
+        spec: scaffoldVideoSpec({
+          templateId,
+          title: `Example ${templateId}`,
+          aspect: "9:16"
+        })
+      },
+      `Example VideoSpec for ${templateId}.`
+    )
+  );
+  server.registerTool(
+    "scaffold_video_spec",
+    {
+      title: "Scaffold VideoSpec",
+      description: "Return a deterministic VideoSpec skeleton without writing files.",
+      inputSchema: {
+        templateId: templateIdSchema,
+        title: z.string().min(1).max(160),
+        aspect: aspectSchema.default("9:16"),
+        mediaSrc: z.string().min(1).max(500).optional()
+      },
+      annotations
+    },
+    async (args) => {
+      const spec = scaffoldVideoSpec(args);
+      return result(
+        { spec, filename: `${String(spec.id)}.video.json` },
+        "Starter VideoSpec created. Replace placeholder copy and media."
+      );
+    }
+  );
+  server.registerTool(
+    "get_render_instructions",
+    {
+      title: "Get local render instructions",
+      description: "Return clone, install, validate, preview, and render commands.",
+      inputSchema: {
+        client: z.enum(["codex", "claude-code", "manual"]).default("manual")
+      },
+      annotations
+    },
+    async ({ client }) => {
+      const commands = [
+        `git clone ${TEMPLATE_REPOSITORY}.git`,
+        "cd remotion-templates",
+        "npm install",
+        "npm run video:validate -- path/to/video.video.json",
+        "npm run video:preview -- path/to/video.video.json",
+        "npm run video:render -- path/to/video.video.json"
+      ];
+      return result(
+        { repository: TEMPLATE_REPOSITORY, client, commands },
+        commands.join("\n")
+      );
+    }
+  );
+  server.registerTool(
+    "diagnose_render_error",
+    {
+      title: "Diagnose render error",
+      description: "Classify a local validation or render error.",
+      inputSchema: { errorText: z.string().min(1).max(1e4) },
+      annotations
+    },
+    async ({ errorText }) => {
+      const text = errorText.toLowerCase();
+      const code = text.includes("enoent") || text.includes("not found") ? "missing-file" : text.includes("ffmpeg") || text.includes("codec") ? "media-codec" : text.includes("schema") || text.includes("invalid") || text.includes("zod") ? "invalid-video-spec" : text.includes("chrome") || text.includes("browser") ? "browser-runtime" : "unknown-render-error";
+      return result(
+        {
+          code,
+          nextStep: "Run validation first, confirm Node 22 or newer, and retry with the smallest included example."
+        },
+        `Diagnosis: ${code}.`
+      );
+    }
+  );
+}
+
 // src/tools.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/http.ts
 import { randomUUID } from "crypto";
 var API_KEY_HEADER = "x-api-key";
+var API_REQUEST_TIMEOUT_MS = 15e3;
 function getApiKey() {
   const key = process.env.INSTAVAR_API_KEY?.trim();
   if (!key) {
@@ -33,8 +375,22 @@ function explain(status, body) {
     const reason = body && typeof body === "object" && "reason" in body ? String(body.reason) : "insufficient scope";
     return `Forbidden (403): ${reason}. The key lacks the required scope for this action.`;
   }
+  if (status === 409) {
+    const reason = body && typeof body === "object" && "error" in body ? String(body.error) : "The requested change conflicts with the current server state";
+    const recovery = /workflow changed/i.test(reason) ? "Inspect the latest workflow state before retrying." : "Resolve the reported conflict before retrying.";
+    return `Conflict (409): ${reason}. ${recovery}`;
+  }
   return "";
 }
+function requestFailure(error) {
+  if (error instanceof DOMException && (error.name === "AbortError" || error.name === "TimeoutError")) {
+    return "The Instavar API request timed out. Retry the tool call.";
+  }
+  if (error instanceof TypeError) {
+    return "The Instavar API request failed before a response arrived. Check connectivity and retry the tool call.";
+  }
+  return error instanceof Error ? error.message : String(error);
+}
 async function parse(res) {
   const text = await res.text();
   try {
@@ -45,11 +401,16 @@ async function parse(res) {
 }
 async function apiGet(path) {
   const res = await fetch(`${baseUrl()}${path}`, {
-    headers: { [API_KEY_HEADER]: getApiKey() }
+    headers: { [API_KEY_HEADER]: getApiKey() },
+    signal: AbortSignal.timeout(API_REQUEST_TIMEOUT_MS)
   });
   const body = await parse(res);
   const hint = explain(res.status, body);
-  return { ok: res.ok, status: res.status, body: hint ? { error: hint, body } : body };
+  return {
+    ok: res.ok,
+    status: res.status,
+    body: hint ? { error: hint, body } : body
+  };
 }
 async function apiPost(path, payload) {
   const clean = Object.fromEntries(
@@ -61,11 +422,16 @@ async function apiPost(path, payload) {
       [API_KEY_HEADER]: getApiKey(),
       "content-type": "application/json"
     },
-    body: JSON.stringify(clean)
+    body: JSON.stringify(clean),
+    signal: AbortSignal.timeout(API_REQUEST_TIMEOUT_MS)
   });
   const body = await parse(res);
   const hint = explain(res.status, body);
-  return { ok: res.ok, status: res.status, body: hint ? { error: hint, body } : body };
+  return {
+    ok: res.ok,
+    status: res.status,
+    body: hint ? { error: hint, body } : body
+  };
 }
 function fenceForModel(json) {
   const nonce = randomUUID();
@@ -76,15 +442,15 @@ ${open}
 ${json}
 ${close}`;
 }
-function toToolResult(result) {
+function toToolResult(result2) {
   return {
     content: [
       {
         type: "text",
-        text: fenceForModel(JSON.stringify(result.body, null, 2))
+        text: fenceForModel(JSON.stringify(result2.body, null, 2))
       }
     ],
-    isError: !result.ok
+    isError: !result2.ok
   };
 }
 async function runTool(fn) {
@@ -95,7 +461,7 @@ async function runTool(fn) {
       content: [
         {
           type: "text",
-          text: error instanceof Error ? error.message : String(error)
+          text: requestFailure(error)
         }
       ],
       isError: true
@@ -104,7 +470,7 @@ async function runTool(fn) {
 }
 
 // src/brief-schema.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 var PUBLISH_TARGETS = [
   "linkedin",
   "x",
@@ -127,13 +493,108 @@ var BRIEF_OBJECTIVES = [
   "other"
 ];
 var ASPECT_RATIOS = ["9:16", "4:5", "1:1", "16:9"];
-var briefStepSchema = z.object({
-  label: z.string(),
-  latex: z.string().optional(),
-  explanation: z.string().optional()
+var REFERENCE_ROLES = [
+  "identity",
+  "appearance",
+  "motion",
+  "composition",
+  "camera",
+  "environment",
+  "style"
+];
+var optionalDirectionText = z2.string().trim().min(1).max(500).optional();
+var visualDirectionSchema = z2.object({
+  communicationJob: optionalDirectionText,
+  emotionalTarget: optionalDirectionText,
+  attentionPath: z2.object({
+    first: optionalDirectionText,
+    next: optionalDirectionText,
+    proof: optionalDirectionText
+  }).optional(),
+  visualLanguage: z2.object({
+    space: optionalDirectionText,
+    line: optionalDirectionText,
+    shape: optionalDirectionText,
+    tone: optionalDirectionText,
+    color: optionalDirectionText,
+    movement: optionalDirectionText,
+    rhythm: optionalDirectionText
+  }).optional(),
+  camera: z2.object({
+    shotSize: optionalDirectionText,
+    angle: optionalDirectionText,
+    movement: optionalDirectionText,
+    lens: optionalDirectionText
+  }).optional()
+});
+var generationContractSchema = z2.object({
+  globalInvariants: z2.array(z2.string().trim().min(1).max(300)).max(20).optional(),
+  shotDelta: z2.string().trim().min(1).max(500).optional(),
+  referenceBindings: z2.array(
+    z2.object({
+      assetId: z2.string().trim().min(1).max(200),
+      roles: z2.array(z2.enum(REFERENCE_ROLES)).min(1).max(7)
+    })
+  ).max(20).optional(),
+  prohibitedChanges: z2.array(z2.string().trim().min(1).max(300)).max(20).optional(),
+  reviewCriteria: z2.array(z2.string().trim().min(1).max(300)).max(20).optional()
+});
+var REGION_NAMES = [
+  "background",
+  "left-half",
+  "right-half",
+  "figure-center",
+  "corner-inset",
+  "lower-third"
+];
+var ASSET_ROLES = [
+  "background",
+  "figure",
+  "inset",
+  "lower-third",
+  "diagram-node"
+];
+var assetSlotStyleSchema = z2.object({
+  opacity: z2.number().min(0).max(1).optional(),
+  fit: z2.enum(["cover", "contain"]).optional(),
+  z: z2.number().optional()
+}).strict();
+var assetSlotSchema = z2.object({
+  id: z2.string().min(1),
+  sceneId: z2.string().min(1).optional(),
+  region: z2.enum(REGION_NAMES),
+  role: z2.enum(ASSET_ROLES),
+  kind: z2.enum(["image", "video"]),
+  source: z2.enum(["auto", "stock", "generate"]),
+  intent: z2.string(),
+  style: assetSlotStyleSchema.optional(),
+  timing: z2.object({
+    fromPct: z2.number().min(0).max(1).optional(),
+    toPct: z2.number().min(0).max(1).optional()
+  }).strict().optional(),
+  url: z2.string().url().optional()
+}).strict();
+var briefStepSchema = z2.object({
+  label: z2.string(),
+  latex: z2.string().optional(),
+  explanation: z2.string().optional()
 });
-var briefSceneSchema = z.object({
-  type: z.enum([
+var briefAudioLayerSchema = z2.object({
+  id: z2.string().min(1),
+  src: z2.string().url(),
+  startFrame: z2.number().int().nonnegative().default(0),
+  durationInFrames: z2.number().int().positive().optional(),
+  volume: z2.number().min(0).max(1).default(1),
+  fadeFrames: z2.number().int().nonnegative().default(0),
+  role: z2.enum(["music", "foley", "transition", "effect"])
+});
+var beatVisualRequestSchema = z2.object({
+  intent: z2.string().trim().min(1).optional(),
+  media: z2.enum(["still", "motion"]).default("still"),
+  source: z2.enum(["auto", "stock", "generate"]).default("auto")
+}).strict();
+var briefSceneSchema = z2.object({
+  type: z2.enum([
     "hero",
     "points",
     "equation",
@@ -149,120 +610,160 @@ var briefSceneSchema = z.object({
     "callout",
     "step-pill",
     "cta-pulse",
+    "source-clip",
+    "source-image",
+    "route-card",
     "video-window",
+    "image-window",
     "custom"
   ]),
-  durationInFrames: z.number().optional(),
-  narrationText: z.string().optional(),
-  title: z.string().optional(),
-  subtitle: z.string().optional(),
-  text: z.string().optional(),
-  points: z.array(z.string()).optional(),
-  latex: z.string().optional(),
-  value: z.union([z.string(), z.number()]).optional(),
-  max: z.number().optional(),
-  label: z.string().optional(),
-  unit: z.string().optional(),
-  prefix: z.string().optional(),
-  suffix: z.string().optional(),
-  decimals: z.number().optional(),
-  color: z.string().optional(),
-  tone: z.string().optional(),
-  iconKey: z.string().optional(),
-  stepNumber: z.number().optional(),
-  totalSteps: z.number().optional(),
-  items: z.array(z.object({ label: z.string(), value: z.number() })).optional(),
-  src: z.string().optional(),
-  caption: z.string().optional(),
+  durationInFrames: z2.number().optional(),
+  narrationText: z2.string().optional(),
+  visualResolution: beatVisualRequestSchema.optional(),
+  title: z2.string().optional(),
+  subtitle: z2.string().optional(),
+  text: z2.string().optional(),
+  points: z2.array(z2.string()).optional(),
+  latex: z2.string().optional(),
+  value: z2.union([z2.string(), z2.number()]).optional(),
+  max: z2.number().optional(),
+  label: z2.string().optional(),
+  unit: z2.string().optional(),
+  prefix: z2.string().optional(),
+  suffix: z2.string().optional(),
+  decimals: z2.number().optional(),
+  color: z2.string().optional(),
+  tone: z2.string().optional(),
+  iconKey: z2.string().optional(),
+  stepNumber: z2.number().optional(),
+  totalSteps: z2.number().optional(),
+  items: z2.array(z2.object({ label: z2.string(), value: z2.number() })).optional(),
+  src: z2.string().optional(),
+  caption: z2.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()
+  source: z2.enum(["url", "generate"]).optional(),
+  generatePrompt: z2.string().optional(),
+  generationContract: generationContractSchema.optional(),
+  trimStartSeconds: z2.number().nonnegative().optional(),
+  trimEndSeconds: z2.number().positive().optional(),
+  playbackRate: z2.number().min(0.25).max(8).optional(),
+  objectFit: z2.enum(["cover", "contain"]).optional(),
+  objectPosition: z2.string().optional(),
+  scaleFrom: z2.number().min(0.5).max(2).optional(),
+  scaleTo: z2.number().min(0.5).max(2).optional(),
+  panFromX: z2.number().min(-50).max(50).optional(),
+  panToX: z2.number().min(-50).max(50).optional(),
+  panFromY: z2.number().min(-50).max(50).optional(),
+  panToY: z2.number().min(-50).max(50).optional(),
+  routeFrom: z2.string().optional(),
+  routeTo: z2.string().optional(),
+  routeLabel: z2.string().optional(),
+  overlayKind: z2.enum(["none", "hook", "stage", "end-card"]).optional(),
+  overlayPosition: z2.enum(["center", "top", "bottom"]).optional(),
+  accentColor: z2.string().optional(),
+  overlayBackgroundColor: z2.string().optional(),
+  cutFlash: z2.boolean().optional(),
+  muted: z2.boolean().optional()
 });
-var directionsBriefSchema = z.object({
-  subtitle: z.string().optional(),
-  unitLabel: z.string().optional(),
-  distanceTimeChip: z.string().optional(),
-  clips: z.array(
-    z.object({
-      src: z.string(),
-      trimStartSeconds: z.number().optional(),
-      trimEndSeconds: z.number(),
-      speed: z.number().optional(),
-      mirrorFlip: z.boolean().optional()
+var directionsBriefSchema = z2.object({
+  subtitle: z2.string().optional(),
+  unitLabel: z2.string().optional(),
+  distanceTimeChip: z2.string().optional(),
+  clips: z2.array(
+    z2.object({
+      src: z2.string(),
+      trimStartSeconds: z2.number().optional(),
+      trimEndSeconds: z2.number(),
+      speed: z2.number().optional(),
+      mirrorFlip: z2.boolean().optional()
     })
   ).min(1),
-  cues: z.array(
-    z.object({
-      atSeconds: z.number(),
-      text: z.string(),
-      arrow: z.enum(["left", "right", "forward"]).optional(),
-      step: z.number().optional()
+  cues: z2.array(
+    z2.object({
+      atSeconds: z2.number(),
+      text: z2.string(),
+      arrow: z2.enum(["left", "right", "forward"]).optional(),
+      step: z2.number().optional()
     })
   ),
-  outro: z.object({
-    heading: z.string().optional(),
-    body: z.array(z.string()).optional(),
-    seconds: z.number().optional()
+  outro: z2.object({
+    heading: z2.string().optional(),
+    body: z2.array(z2.string()).optional(),
+    seconds: z2.number().optional()
   }).optional(),
-  music: z.object({
-    perSegment: z.array(
-      z.object({
-        src: z.string(),
-        clipIndexStart: z.number().optional(),
-        hotOffsetSeconds: z.number().optional(),
-        volume: z.number().optional()
+  music: z2.object({
+    perSegment: z2.array(
+      z2.object({
+        src: z2.string(),
+        clipIndexStart: z2.number().optional(),
+        hotOffsetSeconds: z2.number().optional(),
+        volume: z2.number().optional()
       })
     ).optional(),
-    crossfadeSeconds: z.number().optional()
+    crossfadeSeconds: z2.number().optional()
   }).optional()
 });
 var createBriefShape = {
-  title: z.string().min(1).max(120).describe("Short title (max 120 chars)"),
-  script: z.string().min(1).describe("Full narration script (sent to TTS)"),
-  caption: z.string().min(1).describe("Social caption with hooks, hashtags, CTA"),
-  publishTarget: z.enum(PUBLISH_TARGETS).describe("Target social platform"),
-  objective: z.enum(BRIEF_OBJECTIVES).describe("Content objective (drives composition routing)"),
-  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"),
+  title: z2.string().min(1).max(120).describe("Short title (max 120 chars)"),
+  script: z2.string().min(1).describe("Full narration script (sent to TTS)"),
+  caption: z2.string().min(1).describe("Social caption with hooks, hashtags, CTA"),
+  publishTarget: z2.enum(PUBLISH_TARGETS).describe("Target social platform"),
+  objective: z2.enum(BRIEF_OBJECTIVES).describe("Content objective (drives composition routing)"),
+  lessonTitle: z2.string().optional().describe("Display title rendered inside the video"),
+  visualDirection: visualDirectionSchema.optional().describe(
+    "Whole-video communication, attention, visual-language, and camera direction."
+  ),
+  steps: z2.array(briefStepSchema).optional().describe("Structured steps for educational content (LaTeX)"),
+  scenes: z2.array(briefSceneSchema).optional().describe("Scene graph for the UniversalVideo composition"),
   // 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(
+  aspectRatio: z2.enum(ASPECT_RATIOS).optional().describe("Aspect ratio (defaults to 9:16 when omitted)"),
+  compositionId: z2.string().optional().describe("Remotion composition ID override (advanced)"),
+  voiceId: z2.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')."
-  )
+  ),
+  assetSlots: z2.array(assetSlotSchema).optional().describe(
+    "Optional storyboard asset slots: region-placed image/video assets or placeholders attached to the whole video or a specific scene."
+  ),
+  audioLayers: z2.array(briefAudioLayerSchema).optional().describe("Optional typed music, Foley, transition, and effect layers.")
 };
 var editBriefShape = {
-  jobId: z.string().uuid().describe("The job to edit"),
-  title: z.string().optional().describe("Updated title"),
-  script: z.string().optional().describe("Updated narration script"),
-  caption: z.string().optional().describe("Updated social caption"),
-  lessonTitle: z.string().optional().describe("Updated lesson title"),
-  steps: z.array(briefStepSchema).optional().describe("Updated steps (replaces the array)"),
-  scenes: z.array(briefSceneSchema).optional().describe("Updated scenes (replaces the array)"),
-  aspectRatio: z.enum(ASPECT_RATIOS).optional().describe("Updated aspect ratio"),
-  objective: z.enum(BRIEF_OBJECTIVES).optional().describe(
+  jobId: z2.string().uuid().describe("The job to edit"),
+  title: z2.string().optional().describe("Updated title"),
+  script: z2.string().optional().describe("Updated narration script"),
+  caption: z2.string().optional().describe("Updated social caption"),
+  lessonTitle: z2.string().optional().describe("Updated lesson title"),
+  visualDirection: visualDirectionSchema.optional().describe("Updated whole-video visual direction"),
+  steps: z2.array(briefStepSchema).optional().describe("Updated steps (replaces the array)"),
+  scenes: z2.array(briefSceneSchema).optional().describe("Updated scenes (replaces the array)"),
+  aspectRatio: z2.enum(ASPECT_RATIOS).optional().describe("Updated aspect ratio"),
+  objective: z2.enum(BRIEF_OBJECTIVES).optional().describe(
     "Updated content objective. Re-routes the composition and triggers a re-render."
   ),
-  publishTarget: z.enum(PUBLISH_TARGETS).optional().describe(
+  publishTarget: z2.enum(PUBLISH_TARGETS).optional().describe(
     "Updated target social platform. Distribution metadata only - does not trigger a re-render."
   ),
-  voiceId: z.string().optional().describe(
+  voiceId: z2.string().optional().describe(
     "Updated TTS narrator voice ID. Triggers a re-render with the new voice."
+  ),
+  assetSlots: z2.array(assetSlotSchema).optional().describe(
+    "Replacement storyboard asset slots. Omit to preserve existing slots; pass [] to clear them."
+  ),
+  audioLayers: z2.array(briefAudioLayerSchema).optional().describe(
+    "Replacement typed audio layers. Omit to preserve existing layers; pass [] to clear them."
   )
 };
 
 // src/tools.ts
-var uuid = (desc) => z2.string().uuid().describe(desc);
+var uuid = (desc) => z3.string().uuid().describe(desc);
 var READ_ONLY = { readOnlyHint: true, openWorldHint: false };
 var SAFE_WRITE = {
   readOnlyHint: false,
@@ -277,8 +778,8 @@ function registerTools(server) {
       title: "List jobs",
       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([
+        limit: z3.number().int().min(1).max(50).default(10).describe("Number of jobs to return (default 10, max 50)"),
+        status: z3.enum([
           "queued",
           "rendering",
           "draft_ready",
@@ -326,7 +827,7 @@ function registerTools(server) {
       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)")
+        limit: z3.number().int().min(1).max(20).default(10).describe("Max metric snapshots (default 10, max 20)")
       },
       annotations: READ_ONLY
     },
@@ -342,10 +843,10 @@ function registerTools(server) {
       title: "Get cost summary",
       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"),
-        groupBy: z2.enum(["provider", "job", "day"]).default("provider").describe("How to aggregate the summary"),
-        includeReconciliation: z2.boolean().default(false).describe("Include account-wide reconciliation events")
+        since: z3.string().optional().describe("ISO date \u2014 only include events after this date"),
+        provider: z3.enum(["runpod", "lambda", "r2", "wavespeed", "poyo", "all"]).default("all").describe("Filter by provider"),
+        groupBy: z3.enum(["provider", "job", "day"]).default("provider").describe("How to aggregate the summary"),
+        includeReconciliation: z3.boolean().default(false).describe("Include account-wide reconciliation events")
       },
       annotations: READ_ONLY
     },
@@ -356,6 +857,18 @@ function registerTools(server) {
       return runTool(() => apiGet(`/api/v1/cost-summary?${q.toString()}`));
     }
   );
+  server.registerTool(
+    "inspect_workflow",
+    {
+      title: "Inspect workflow",
+      description: "Inspect the current Studio workflow and its version history for a job.",
+      inputSchema: z3.object({ jobId: uuid("The job ID") }).strict(),
+      annotations: READ_ONLY
+    },
+    async ({ jobId }) => runTool(
+      () => apiGet(`/api/v1/jobs/${encodeURIComponent(jobId)}/workflow`)
+    )
+  );
   server.registerTool(
     "create_video_brief",
     {
@@ -381,6 +894,169 @@ function registerTools(server) {
       );
     }
   );
+  const workflowWrite = (operation, jobId, payload = {}) => runTool(
+    () => apiPost(`/api/v1/jobs/${encodeURIComponent(jobId)}/workflow`, {
+      operation,
+      ...payload
+    })
+  );
+  server.registerTool(
+    "draft_workflow",
+    {
+      title: "Draft workflow",
+      description: "Create a durable Documentary Journey or Transformation Montage workflow version. Inspect first and pass its current version, or 0 only when no workflow exists.",
+      inputSchema: z3.object({
+        jobId: uuid("The job ID"),
+        expectedVersion: z3.number().int().nonnegative().describe("Use 0 when no workflow exists yet"),
+        document: z3.unknown().describe("The complete Studio workflow document")
+      }).strict(),
+      annotations: SAFE_WRITE
+    },
+    async ({ jobId, expectedVersion, document }) => workflowWrite("draft", jobId, { expectedVersion, document })
+  );
+  server.registerTool(
+    "patch_workflow",
+    {
+      title: "Patch workflow",
+      description: "Create a new workflow version by recursively merging a patch into the current version.",
+      inputSchema: z3.object({
+        jobId: uuid("The job ID"),
+        expectedVersion: z3.number().int().positive(),
+        patch: z3.record(z3.string(), z3.unknown())
+      }).strict(),
+      annotations: SAFE_WRITE
+    },
+    async ({ jobId, expectedVersion, patch }) => workflowWrite("patch", jobId, { expectedVersion, patch })
+  );
+  server.registerTool(
+    "validate_workflow",
+    {
+      title: "Validate workflow",
+      description: "Validate and compile the inspected workflow version without rendering or publishing it.",
+      inputSchema: z3.object({
+        jobId: uuid("The job ID"),
+        expectedVersion: z3.number().int().positive()
+      }).strict(),
+      annotations: SAFE_WRITE
+    },
+    async ({ jobId, expectedVersion }) => workflowWrite("validate", jobId, { expectedVersion })
+  );
+  server.registerTool(
+    "preview_workflow",
+    {
+      title: "Preview workflow",
+      description: "Return the current workflow's compiled UniversalVideo brief for a safe pre-render preview.",
+      inputSchema: z3.object({ jobId: uuid("The job ID") }).strict(),
+      annotations: READ_ONLY
+    },
+    async ({ jobId }) => runTool(
+      () => apiGet(
+        `/api/v1/jobs/${encodeURIComponent(jobId)}/workflow?operation=preview`
+      )
+    )
+  );
+  server.registerTool(
+    "compare_workflows",
+    {
+      title: "Compare workflow versions",
+      description: "Compare two durable workflow versions field by field.",
+      inputSchema: z3.object({
+        jobId: uuid("The job ID"),
+        fromVersion: z3.number().int().positive(),
+        toVersion: z3.number().int().positive()
+      }).strict(),
+      annotations: READ_ONLY
+    },
+    async ({ jobId, fromVersion, toVersion }) => {
+      const query = new URLSearchParams({
+        operation: "compare",
+        fromVersion: String(fromVersion),
+        toVersion: String(toVersion)
+      });
+      return runTool(
+        () => apiGet(
+          `/api/v1/jobs/${encodeURIComponent(
+            jobId
+          )}/workflow?${query.toString()}`
+        )
+      );
+    }
+  );
+  server.registerTool(
+    "approve_workflow",
+    {
+      title: "Approve workflow",
+      description: "Validate and approve the inspected workflow version. This does not approve or publish the video job.",
+      inputSchema: z3.object({
+        jobId: uuid("The job ID"),
+        expectedVersion: z3.number().int().positive()
+      }).strict(),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ jobId, expectedVersion }) => workflowWrite("approve", jobId, { expectedVersion })
+  );
+  server.registerTool(
+    "retry_video_qa",
+    {
+      title: "Retry video QA",
+      description: "Retry the default QA evaluator against the same current frozen video. Use only when get_job_status recommends retryTarget qa_only, or when QA is missing, unavailable, or parse-degraded. This does not regenerate media and cannot clear publish gates by itself.",
+      inputSchema: {
+        jobId: uuid("The current job ID"),
+        runId: uuid("The current render run ID"),
+        videoArtifactId: uuid("The current frozen video artifact ID")
+      },
+      annotations: SAFE_WRITE
+    },
+    async ({ jobId, runId, videoArtifactId }) => runTool(
+      () => apiPost(`/api/v1/jobs/${encodeURIComponent(jobId)}/qa/retry`, {
+        runId,
+        videoArtifactId
+      })
+    )
+  );
+  server.registerTool(
+    "audit_video_qa",
+    {
+      title: "Audit video QA",
+      description: "Run Qwen3.6-Plus as an advisory second evaluator against the same current frozen video. Use only on an explicit request for another model, second opinion, or evaluator escalation. The result is separate from default QA and has no publish-gate effect.",
+      inputSchema: {
+        jobId: uuid("The current job ID"),
+        runId: uuid("The current render run ID"),
+        videoArtifactId: uuid("The current frozen video artifact ID")
+      },
+      annotations: SAFE_WRITE
+    },
+    async ({ jobId, runId, videoArtifactId }) => runTool(
+      () => apiPost(`/api/v1/jobs/${encodeURIComponent(jobId)}/qa/audit`, {
+        runId,
+        videoArtifactId
+      })
+    )
+  );
+  server.registerTool(
+    "regenerate_narration",
+    {
+      title: "Regenerate narration",
+      description: "Regenerate narration from the unchanged durable brief and then regenerate its dependent video in a paid adaptation run. Use only on an explicit user request or when get_job_status recommends retryTarget tts. This is an audio_and_video cascade, consumes rerender quota, and requires fresh QA.",
+      inputSchema: {
+        jobId: uuid("The current job ID"),
+        sourceRunId: uuid("The current run ID"),
+        trigger: z3.enum(["user_requested", "verifier_recommendation"])
+      },
+      annotations: SAFE_WRITE
+    },
+    async ({ jobId, sourceRunId, trigger }) => runTool(
+      () => apiPost(
+        `/api/v1/jobs/${encodeURIComponent(jobId)}/narration/regenerate`,
+        { sourceRunId, trigger }
+      )
+    )
+  );
   server.registerTool(
     "approve_job",
     {
@@ -406,15 +1082,15 @@ function registerTools(server) {
       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."),
-        tiktokPostMode: z2.enum(["direct_publish", "draft_upload"]).optional().describe("TikTok only. Use 'draft_upload' for safe dogfood runs."),
-        connectedAccountDestinationId: z2.string().uuid().optional().describe(
+        youtubePrivacyStatus: z3.enum(["private", "unlisted", "public"]).optional().describe("YouTube only. Use 'private' for safe dogfood runs."),
+        tiktokPostMode: z3.enum(["direct_publish", "draft_upload"]).optional().describe("TikTok only. Use 'draft_upload' for safe dogfood runs."),
+        connectedAccountDestinationId: z3.string().uuid().optional().describe(
           "Specific destination when the org has multiple accounts for the provider."
         ),
-        confirmSyntheticDisclosure: z2.boolean().optional().describe(
+        confirmSyntheticDisclosure: z3.boolean().optional().describe(
           "Set true when the job requires an AI synthetic-media disclosure."
         ),
-        confirmQaOverride: z2.boolean().optional().describe("Set true to override a non-passing QA gate.")
+        confirmQaOverride: z3.boolean().optional().describe("Set true to override a non-passing QA gate.")
       },
       annotations: {
         readOnlyHint: false,
@@ -437,7 +1113,7 @@ function registerTools(server) {
       title: "Connect social account",
       description: "Start connecting a social account headlessly (no local browser needed). Returns an approve URL + a short confirm code: open the URL in a browser signed in to Instavar, check the code matches THIS terminal, and approve. Then poll connect_account_status with the returned pairingId until it reports 'connected'.",
       inputSchema: {
-        provider: z2.enum([
+        provider: z3.enum([
           "youtube",
           "x",
           "tiktok",
@@ -475,12 +1151,20 @@ function registerTools(server) {
   );
 }
 
+// src/configured-tools.ts
+function registerConfiguredTools(server, apiKey = process.env.INSTAVAR_API_KEY) {
+  registerPublicTemplateTools(server);
+  if (apiKey?.trim()) {
+    registerTools(server);
+  }
+}
+
 // package.json
 var package_default = {
   name: "@instavar/mcp-server",
-  version: "0.3.0",
+  version: "0.4.1",
   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.",
+  description: "Make local videos with Instavar Remotion templates for free, then add an API key for hosted Studio workflows.",
   type: "module",
   license: "MIT",
   homepage: "https://instavar.com",
@@ -491,7 +1175,14 @@ var package_default = {
   bugs: {
     url: "https://github.com/instavar/mcp-server/issues"
   },
-  keywords: ["mcp", "model-context-protocol", "instavar", "video", "claude", "codex"],
+  keywords: [
+    "mcp",
+    "model-context-protocol",
+    "instavar",
+    "video",
+    "claude",
+    "codex"
+  ],
   bin: {
     "instavar-mcp": "dist/index.js"
   },
@@ -525,8 +1216,10 @@ var VERSION = package_default.version;
 var HELP = [
   "instavar-mcp \u2014 Instavar Studio MCP server",
   "",
-  "Runs over stdio (launched by Claude Code / Codex). Configure via env:",
-  "  INSTAVAR_API_KEY   (required) your key from https://instavar.com/studio/settings",
+  "Runs over stdio (launched by Claude Code / Codex).",
+  "Public template tools work without configuration.",
+  "Optional env:",
+  "  INSTAVAR_API_KEY   unlocks hosted Studio tools",
   "  INSTAVAR_BASE_URL  (optional) defaults to https://instavar.com",
   "",
   "Flags: --version, --help",
@@ -543,14 +1236,8 @@ async function main() {
     process.stdout.write(HELP);
     return;
   }
-  if (!process.env.INSTAVAR_API_KEY?.trim()) {
-    process.stderr.write(
-      "instavar-mcp: INSTAVAR_API_KEY is not set. Create a key at https://instavar.com/studio/settings and add it to the MCP server env block (env.INSTAVAR_API_KEY).\n"
-    );
-    process.exit(1);
-  }
   const server = new McpServer({ name: "instavar", version: VERSION });
-  registerTools(server);
+  registerConfiguredTools(server);
   await server.connect(new StdioServerTransport());
 }
 main().catch((error) => {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@instavar/mcp-server",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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.",
+  "description": "Make local videos with Instavar Remotion templates for free, then add an API key for hosted Studio workflows.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://instavar.com",
@@ -13,7 +13,14 @@
   "bugs": {
     "url": "https://github.com/instavar/mcp-server/issues"
   },
-  "keywords": ["mcp", "model-context-protocol", "instavar", "video", "claude", "codex"],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "instavar",
+    "video",
+    "claude",
+    "codex"
+  ],
   "bin": {
     "instavar-mcp": "dist/index.js"
   },