@instavar/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @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.
+
+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.
+
+## 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:
+
+```json
+{
+  "mcpServers": {
+    "instavar": {
+      "command": "npx",
+      "args": ["-y", "@instavar/mcp-server"],
+      "env": { "INSTAVAR_API_KEY": "ik_live_..." }
+    }
+  }
+}
+```
+
+3. Restart the client. The `instavar` tools appear.
+
+### 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.                                           |
+
+## Tools
+
+| Tool                 | What it does                                                    |
+| -------------------- | --------------------------------------------------------------- |
+| `list_jobs`          | List recent jobs (newest first).                                |
+| `get_job_status`     | Runs, artifacts, verifications, current video + thumbnail URLs. |
+| `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).   |
+| `create_video_brief` | Create a job from a structured brief and start rendering.       |
+| `edit_video_brief`   | Patch a brief and re-render.                                    |
+| `approve_job`        | Approve a rendered job so it can be published.                  |
+| `publish_job`        | Publish an approved job to its connected social destination.    |
+
+Writes require a key with the `write` scope; `publish_job` requires `publish`.
+
+## CLI
+
+```
+npx @instavar/mcp-server --version
+npx @instavar/mcp-server --help
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools.ts
+import { z as z2 } from "zod";
+
+// src/http.ts
+var API_KEY_HEADER = "x-api-key";
+function getApiKey() {
+  const key = process.env.INSTAVAR_API_KEY?.trim();
+  if (!key) {
+    throw new Error(
+      "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)."
+    );
+  }
+  return key;
+}
+function baseUrl() {
+  return (process.env.INSTAVAR_BASE_URL || "https://instavar.com").replace(
+    /\/+$/,
+    ""
+  );
+}
+function explain(status, body) {
+  if (status === 401) {
+    return "API key invalid or revoked (401). Check INSTAVAR_API_KEY or mint a new key at /studio/settings.";
+  }
+  if (status === 403) {
+    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.`;
+  }
+  return "";
+}
+async function parse(res) {
+  const text = await res.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function apiGet(path) {
+  const res = await fetch(`${baseUrl()}${path}`, {
+    headers: { [API_KEY_HEADER]: getApiKey() }
+  });
+  const body = await parse(res);
+  const hint = explain(res.status, body);
+  return { ok: res.ok, status: res.status, body: hint ? { error: hint, body } : body };
+}
+async function apiPost(path, payload) {
+  const clean = Object.fromEntries(
+    Object.entries(payload).filter(([, v]) => v !== void 0)
+  );
+  const res = await fetch(`${baseUrl()}${path}`, {
+    method: "POST",
+    headers: {
+      [API_KEY_HEADER]: getApiKey(),
+      "content-type": "application/json"
+    },
+    body: JSON.stringify(clean)
+  });
+  const body = await parse(res);
+  const hint = explain(res.status, body);
+  return { ok: res.ok, status: res.status, body: hint ? { error: hint, body } : body };
+}
+function toToolResult(result) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result.body, null, 2)
+      }
+    ],
+    isError: !result.ok
+  };
+}
+async function runTool(fn) {
+  try {
+    return toToolResult(await fn());
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: error instanceof Error ? error.message : String(error)
+        }
+      ],
+      isError: true
+    };
+  }
+}
+
+// src/brief-schema.ts
+import { z } from "zod";
+var PUBLISH_TARGETS = [
+  "linkedin",
+  "x",
+  "threads",
+  "instagram",
+  "tiktok",
+  "youtube",
+  "facebook",
+  "rednote",
+  "lemon8"
+];
+var BRIEF_OBJECTIVES = [
+  "build_log",
+  "product_update",
+  "launch_update",
+  "faq",
+  "explainer",
+  "customer_story",
+  "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 briefSceneSchema = z.object({
+  type: z.enum([
+    "hero",
+    "points",
+    "equation",
+    "metric-bars",
+    "metric-compare",
+    "timeline",
+    "limit-cards",
+    "slide",
+    "caption-overlay",
+    "cta",
+    "progress-ring",
+    "metric-counter",
+    "callout",
+    "step-pill",
+    "cta-pulse",
+    "video-window",
+    "custom"
+  ]),
+  durationInFrames: z.number().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()
+});
+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"),
+  aspectRatio: z.enum(ASPECT_RATIOS).default("9:16").describe("Aspect ratio (default 9:16)"),
+  compositionId: z.string().optional().describe("Remotion composition ID override (advanced)")
+};
+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")
+};
+
+// src/tools.ts
+var uuid = (desc) => z2.string().uuid().describe(desc);
+function registerTools(server) {
+  server.tool(
+    "list_jobs",
+    "List recent video jobs for the current organization (newest first).",
+    {
+      limit: z2.number().int().min(1).max(50).default(10).describe("Number of jobs to return (default 10, max 50)"),
+      status: z2.enum([
+        "queued",
+        "rendering",
+        "draft_ready",
+        "approved",
+        "publish_requested",
+        "publishing",
+        "published",
+        "failed"
+      ]).optional().describe("Filter by job status")
+    },
+    async ({ limit, status }) => {
+      const q = new URLSearchParams({ limit: String(limit) });
+      if (status) q.set("status", status);
+      return runTool(() => apiGet(`/api/v1/jobs?${q.toString()}`));
+    }
+  );
+  server.tool(
+    "get_job_status",
+    "Get detailed status for a job: runs, artifacts, verifications, plus the current video and thumbnail URLs.",
+    { jobId: uuid("The job ID to check") },
+    async ({ jobId }) => runTool(() => apiGet(`/api/v1/jobs/${encodeURIComponent(jobId)}`))
+  );
+  server.tool(
+    "get_video_state",
+    "Get the materialized video state for a job (composition decisions: scenes, duration, aspect ratio, etc.).",
+    { jobId: uuid("The job ID") },
+    async ({ jobId }) => runTool(
+      () => apiGet(`/api/v1/jobs/${encodeURIComponent(jobId)}/video-state`)
+    )
+  );
+  server.tool(
+    "get_job_metrics",
+    "Get the latest platform engagement metric snapshots for a published job (newest first). Read-only.",
+    {
+      jobId: uuid("The job ID"),
+      limit: z2.number().int().min(1).max(20).default(10).describe("Max metric snapshots (default 10, max 20)")
+    },
+    async ({ jobId, limit }) => runTool(
+      () => apiGet(
+        `/api/v1/jobs/${encodeURIComponent(jobId)}/metrics?limit=${limit}`
+      )
+    )
+  );
+  server.tool(
+    "get_cost_summary",
+    "Query production infrastructure costs (Lambda, RunPod, R2, WaveSpeed, PoYo), optionally with reconciliation drift.",
+    {
+      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")
+    },
+    async ({ since, provider, groupBy, includeReconciliation }) => {
+      const q = new URLSearchParams({ provider, groupBy });
+      if (since) q.set("since", since);
+      if (includeReconciliation) q.set("includeReconciliation", "true");
+      return runTool(() => apiGet(`/api/v1/cost-summary?${q.toString()}`));
+    }
+  );
+  server.tool(
+    "create_video_brief",
+    "Create a new video job from a structured brief and trigger the render pipeline. Returns the job and run IDs.",
+    createBriefShape,
+    async (input) => runTool(() => apiPost(`/api/v1/jobs`, input))
+  );
+  server.tool(
+    "edit_video_brief",
+    "Edit an existing job's brief (only provided fields change) and trigger a re-render. Returns the new run ID.",
+    editBriefShape,
+    async (input) => {
+      const { jobId, ...patch } = input;
+      return runTool(
+        () => apiPost(`/api/v1/jobs/${encodeURIComponent(jobId)}/brief`, patch)
+      );
+    }
+  );
+  server.tool(
+    "approve_job",
+    "Approve a rendered job so it becomes publishable (draft_ready/awaiting_review/needs_changes -> approved) and revoke active review links.",
+    { jobId: uuid("The job ID to approve") },
+    async ({ jobId }) => runTool(
+      () => apiPost(`/api/v1/jobs/${encodeURIComponent(jobId)}/approve`, {})
+    )
+  );
+  server.tool(
+    "publish_job",
+    "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.",
+    {
+      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(
+        "Specific destination when the org has multiple accounts for the provider."
+      ),
+      confirmSyntheticDisclosure: z2.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.")
+    },
+    async ({ jobId, ...rest }) => (
+      // NOTE: publish is NOT under /api/v1 — it is the gated /api/jobs route.
+      runTool(() => apiPost(`/api/jobs/${encodeURIComponent(jobId)}/publish`, rest))
+    )
+  );
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+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",
+  "  INSTAVAR_BASE_URL  (optional) defaults to https://instavar.com",
+  "",
+  "Flags: --version, --help",
+  ""
+].join("\n");
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--version") || argv.includes("-v")) {
+    process.stdout.write(`${VERSION}
+`);
+    return;
+  }
+  if (argv.includes("--help") || argv.includes("-h")) {
+    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);
+  await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+  process.stderr.write(
+    `instavar-mcp: fatal: ${error instanceof Error ? error.message : String(error)}
+`
+  );
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@instavar/mcp-server",
+  "version": "0.1.0",
+  "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",
+  "license": "MIT",
+  "homepage": "https://instavar.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cheeweijie/instavar-nextjs.git",
+    "directory": "packages/mcp-server"
+  },
+  "keywords": ["mcp", "model-context-protocol", "instavar", "video", "claude", "codex"],
+  "bin": {
+    "instavar-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.64"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "tsup": "^8.3.0",
+    "typescript": "5.8.3",
+    "vitest": "^3.2.4"
+  }
+}