@instavar/mcp-server 0.2.0 → 0.2.2

package/README.md

@@ -1,5 +1,9 @@
 # @instavar/mcp-server
 
+[![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)
+[![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.

package/dist/index.js

@@ -246,22 +246,33 @@ var editBriefShape = {
 
 // src/tools.ts
 var uuid = (desc) => z2.string().uuid().describe(desc);
+var READ_ONLY = { readOnlyHint: true, openWorldHint: false };
+var SAFE_WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false
+};
 function registerTools(server) {
-  server.tool(
+  server.registerTool(
     "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")
+      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([
+          "queued",
+          "rendering",
+          "draft_ready",
+          "approved",
+          "publish_requested",
+          "publishing",
+          "published",
+          "failed"
+        ]).optional().describe("Filter by job status")
+      },
+      annotations: READ_ONLY
     },
     async ({ limit, status }) => {
       const q = new URLSearchParams({ limit: String(limit) });
@@ -269,26 +280,38 @@ function registerTools(server) {
       return runTool(() => apiGet(`/api/v1/jobs?${q.toString()}`));
     }
   );
-  server.tool(
+  server.registerTool(
     "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") },
+    {
+      title: "Get job status",
+      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
+    },
     async ({ jobId }) => runTool(() => apiGet(`/api/v1/jobs/${encodeURIComponent(jobId)}`))
   );
-  server.tool(
+  server.registerTool(
     "get_video_state",
-    "Get the materialized video state for a job (composition decisions: scenes, duration, aspect ratio, etc.).",
-    { jobId: uuid("The job ID") },
+    {
+      title: "Get video state",
+      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
+    },
     async ({ jobId }) => runTool(
       () => apiGet(`/api/v1/jobs/${encodeURIComponent(jobId)}/video-state`)
     )
   );
-  server.tool(
+  server.registerTool(
     "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)")
+      title: "Get job metrics",
+      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)")
+      },
+      annotations: READ_ONLY
     },
     async ({ jobId, limit }) => runTool(
       () => apiGet(
@@ -296,14 +319,18 @@ function registerTools(server) {
       )
     )
   );
-  server.tool(
+  server.registerTool(
     "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")
+      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")
+      },
+      annotations: READ_ONLY
     },
     async ({ since, provider, groupBy, includeReconciliation }) => {
       const q = new URLSearchParams({ provider, groupBy });
@@ -312,16 +339,24 @@ function registerTools(server) {
       return runTool(() => apiGet(`/api/v1/cost-summary?${q.toString()}`));
     }
   );
-  server.tool(
+  server.registerTool(
     "create_video_brief",
-    "Create a new video job from a structured brief and trigger the render pipeline. Returns the job and run IDs.",
-    createBriefShape,
+    {
+      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 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
+    },
     async (input) => runTool(() => apiPost(`/api/v1/jobs`, input))
   );
-  server.tool(
+  server.registerTool(
     "edit_video_brief",
-    "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.",
-    editBriefShape,
+    {
+      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. For a brand-new video use create_video_brief.",
+      inputSchema: editBriefShape,
+      annotations: SAFE_WRITE
+    },
     async (input) => {
       const { jobId, ...patch } = input;
       return runTool(
@@ -329,52 +364,92 @@ function registerTools(server) {
       );
     }
   );
-  server.tool(
+  server.registerTool(
     "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") },
+    {
+      title: "Approve job",
+      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,
+        destructiveHint: false,
+        // Approving an already-approved job does not change state further.
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
     async ({ jobId }) => runTool(
       () => apiPost(`/api/v1/jobs/${encodeURIComponent(jobId)}/approve`, {})
     )
   );
-  server.tool(
+  server.registerTool(
     "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.")
+      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). 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(
+          "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.")
+      },
+      annotations: {
+        readOnlyHint: false,
+        // A live post on an external platform cannot be recalled by the API.
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      }
     },
     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))
+      runTool(
+        () => apiPost(`/api/jobs/${encodeURIComponent(jobId)}/publish`, rest)
+      )
     )
   );
-  server.tool(
+  server.registerTool(
     "connect_account",
-    "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'.",
     {
-      provider: z2.enum([
-        "youtube",
-        "x",
-        "tiktok",
-        "linkedin",
-        "facebook",
-        "instagram",
-        "threads"
-      ]).describe("The social platform to connect")
+      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([
+          "youtube",
+          "x",
+          "tiktok",
+          "linkedin",
+          "facebook",
+          "instagram",
+          "threads"
+        ]).describe("The social platform to connect")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        // The pairing hands off to the platform's own OAuth flow.
+        openWorldHint: true
+      }
     },
     async ({ provider }) => runTool(() => apiPost(`/api/v1/connect/start`, { provider }))
   );
-  server.tool(
+  server.registerTool(
     "connect_account_status",
-    "Poll a pending account connection started by connect_account. Returns status 'pending' | 'connected' | 'expired', plus the connected account label once connected.",
-    { pairingId: uuid("The pairingId returned by connect_account") },
+    {
+      title: "Check account connection",
+      description: "Poll a pending account connection started by connect_account. Returns status 'pending' | 'connected' | 'expired', plus the connected account label once connected.",
+      inputSchema: {
+        pairingId: uuid("The pairingId returned by connect_account")
+      },
+      annotations: READ_ONLY
+    },
     async ({ pairingId }) => runTool(
       () => apiGet(
         `/api/v1/connect/poll?pairingId=${encodeURIComponent(pairingId)}`
@@ -386,7 +461,7 @@ function registerTools(server) {
 // package.json
 var package_default = {
   name: "@instavar/mcp-server",
-  version: "0.2.0",
+  version: "0.2.2",
   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.0",
+  "version": "0.2.2",
   "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",