@wevi/mcp 0.1.1 → 0.2.1

package/dist/index.js

@@ -6,6 +6,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import dotenv from "dotenv";
 
 // src/client/wevi-api-client.ts
+var USER_AGENT = "Wevi-MCP-Server/0.2.1";
+function toObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  return value;
+}
 var WeviApiClient = class {
   apiKey;
   baseUrl;
@@ -13,12 +18,16 @@ var WeviApiClient = class {
     this.apiKey = config.apiKey.trim();
     this.baseUrl = config.apiUrl.replace(/\/+$/, "");
   }
+  /** True when the configured key is a `wevi_test_` sandbox key. */
+  get isSandbox() {
+    return this.apiKey.startsWith("wevi_test_");
+  }
   get headers() {
     return {
       "Content-Type": "application/json",
       "X-API-Key": this.apiKey,
       Authorization: `Bearer ${this.apiKey}`,
-      "User-Agent": "Wevi-MCP-Server/0.1.0"
+      "User-Agent": USER_AGENT
     };
   }
   async request(endpoint, options = {}) {
@@ -27,16 +36,11 @@ var WeviApiClient = class {
     try {
       response = await fetch(url, {
         ...options,
-        headers: {
-          ...this.headers,
-          ...options.headers || {}
-        }
+        headers: { ...this.headers, ...options.headers || {} }
       });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      throw new Error(
-        `Failed to connect to Wevi API at ${this.baseUrl}: ${msg}`
-      );
+      throw new Error(`Failed to connect to Wevi API at ${this.baseUrl}: ${msg}`);
     }
     if (!response.ok) {
       let errorBody = {};
@@ -45,18 +49,26 @@ var WeviApiClient = class {
       } catch {
       }
       const errObj = errorBody.error;
-      const message = typeof errorBody.message === "string" && errorBody.message || typeof errObj === "string" && errObj || typeof errObj === "object" && errObj !== null && typeof errObj.message === "string" && errObj.message || `Wevi API error (${response.status} ${response.statusText})`;
+      const rawMessage = typeof errorBody.message === "string" && errorBody.message || Array.isArray(errorBody.message) && errorBody.message.join("; ") || typeof errObj === "string" && errObj || typeof errObj === "object" && errObj !== null && typeof errObj.message === "string" && errObj.message || `Wevi API error (${response.status} ${response.statusText})`;
+      const message = String(rawMessage);
       if (response.status === 402) {
+        const topUpUrl = typeof errorBody.topUpUrl === "string" ? errorBody.topUpUrl : "https://app.wevi.ai/app/profile?id=api-keys&topup=1";
+        const required = errorBody.creditsRequired;
+        const available = errorBody.creditsAvailable;
+        const detail = typeof required === "number" && typeof available === "number" ? ` Needs ${required} credit${required === 1 ? "" : "s"}, ${available} available.` : "";
         throw new Error(
-          `[402 Payment Required] Render credit limit reached. Please upgrade your plan at https://app.wevi.ai/settings/billing to continue rendering.
+          `[402 Payment Required] Not enough API credits.${detail} Buy a credit pack or upgrade at ${topUpUrl}. Call wevi_get_credits to see the balance.
 Details: ${message}`
         );
       }
       if (response.status === 401) {
         throw new Error(
-          `[401 Unauthorized] Invalid or revoked Wevi API key. Please check your WEVI_API_KEY in settings at https://app.wevi.ai/settings/api-keys.`
+          `[401 Unauthorized] Invalid or revoked Wevi API key. Check WEVI_API_KEY at https://app.wevi.ai/app/profile?id=api-keys.`
         );
       }
+      if (response.status === 429) {
+        throw new Error(`[429 Too Many Requests] Slow down: ${message}`);
+      }
       throw new Error(`[Wevi API Error ${response.status}] ${message}`);
     }
     if (response.status === 204) {
@@ -65,34 +77,89 @@ Details: ${message}`
     return await response.json();
   }
   /**
-   * Lists published templates with optional filtering.
+   * Lists published, active templates. The API already restricts API-key
+   * callers to published templates; we also send `status=PUBLISHED` so the
+   * intent is explicit in logs.
    */
   async listTemplates(params) {
     const query = new URLSearchParams();
+    query.set("status", "PUBLISHED");
     if (params?.category) query.set("category", params.category);
     if (params?.aspectRatio) query.set("aspectRatio", params.aspectRatio);
     if (params?.search) query.set("search", params.search);
     if (params?.limit) query.set("limit", String(params.limit));
     if (params?.page) query.set("page", String(params.page));
-    const qs = query.toString();
-    const endpoint = `/templates${qs ? `?${qs}` : ""}`;
-    const result = await this.request(endpoint);
-    const rawData = result?.data ?? result;
-    const items = Array.isArray(rawData) ? rawData : Array.isArray(rawData?.templates) ? rawData.templates : Array.isArray(rawData?.items) ? rawData.items : [];
-    const total = rawData?.meta?.total ?? result?.total ?? rawData?.total ?? items.length;
-    return { items, total };
+    const result = await this.request(`/templates?${query.toString()}`);
+    const data = toObject(result?.data ?? result);
+    const items = Array.isArray(data.templates) ? data.templates : [];
+    const meta = toObject(data.meta);
+    const total = typeof meta.total === "number" ? meta.total : items.length;
+    const categories = Array.isArray(data.categories) ? data.categories.filter((c) => typeof c === "string") : [];
+    return { items, total, categories };
   }
-  /**
-   * Retrieves full template details including editable dynamic layers.
-   */
   async getTemplate(templateId) {
     const res = await this.request(
       `/templates/${encodeURIComponent(templateId)}`
     );
     return res?.data ?? res;
   }
+  /** Guidance an agent needs to place a template in the right scene role. */
+  static extractGuidance(template) {
+    const meta = template.semanticMeta ?? null;
+    const instructions = meta?.instructions ?? {};
+    const guide = template.smartGuide ?? meta?.smartGuide ?? null;
+    return {
+      purpose: instructions.purpose ?? null,
+      sceneIntent: instructions.designProtocol?.sceneIntent ?? [],
+      avoid: instructions.designProtocol?.avoid ?? [],
+      tone: instructions.scriptGuidelines?.tone ?? null,
+      onScreenTextFormat: instructions.scriptGuidelines?.onScreenTextFormat ?? null,
+      do: guide?.do ?? [],
+      dont: guide?.dont ?? []
+    };
+  }
+  /**
+   * Flattens the template's `layerMeta` into the editable parameters an agent
+   * can set. Hidden and protected layers are omitted.
+   */
+  static extractEditableLayers(template) {
+    const layerMeta = toObject(template.layerMeta);
+    const rawLayers = Array.isArray(template.layers) ? template.layers : [];
+    const orderedKeys = [];
+    for (const raw of rawLayers) {
+      const key = toObject(raw).key;
+      if (typeof key === "string" && key && !orderedKeys.includes(key)) orderedKeys.push(key);
+    }
+    for (const key of Object.keys(layerMeta)) {
+      if (!orderedKeys.includes(key)) orderedKeys.push(key);
+    }
+    const layers = [];
+    for (const key of orderedKeys) {
+      if (key.startsWith("__ui")) continue;
+      const meta = toObject(layerMeta[key]);
+      if (meta.hidden === true || meta.isProtected === true) continue;
+      const control = toObject(meta.control);
+      const options = Array.isArray(control.options) ? control.options.filter((o) => typeof o === "string") : [];
+      const validation = toObject(meta.validation);
+      const rawLayer = toObject(rawLayers.find((raw) => toObject(raw).key === key));
+      layers.push({
+        key,
+        label: String(meta.humanLabel || meta.label || rawLayer.label || key),
+        type: String(meta.type || rawLayer.type || "text").toLowerCase(),
+        role: typeof meta.role === "string" ? meta.role : void 0,
+        description: typeof meta.description === "string" ? meta.description : void 0,
+        aiHint: typeof meta.aiHint === "string" ? meta.aiHint : void 0,
+        required: meta.required === true,
+        defaultValue: meta.defaultValue ?? rawLayer.defaultValue ?? null,
+        ...options.length ? { options } : {},
+        ...Object.keys(validation).length ? { validation } : {}
+      });
+    }
+    return layers;
+  }
   /**
-   * Creates a draft video project with template parameters.
+   * Creates a render-ready project. All scenes land in ONE project so the
+   * publish step exports a single concatenated video.
    */
   async createProject(data) {
     const res = await this.request("/projects", {
@@ -101,118 +168,133 @@ Details: ${message}`
     });
     return res?.data ?? res;
   }
-  /**
-   * Retrieves project details and current render state.
-   */
   async getProject(projectId) {
-    const res = await this.request(
-      `/projects/${encodeURIComponent(projectId)}`
-    );
-    return res?.data?.project ?? res?.data ?? res;
+    const res = await this.request(`/projects/${encodeURIComponent(projectId)}`);
+    const data = toObject(res?.data ?? res);
+    return toObject(data.project) && Object.keys(toObject(data.project)).length ? toObject(data.project) : data;
   }
-  /**
-   * Triggers a high-definition video render export.
-   */
-  async triggerRender(projectId) {
+  /** Renders every scene and queues one concatenated export. */
+  async publishProject(projectId, options) {
     const res = await this.request(
-      `/exports/projects/${encodeURIComponent(projectId)}`,
-      {
-        method: "POST",
-        body: JSON.stringify({ quality: "1080p" })
-      }
+      `/projects/${encodeURIComponent(projectId)}/publish`,
+      { method: "POST", body: JSON.stringify(options ?? {}) }
     );
-    const exportData = res?.data?.export ?? res?.export ?? res?.data ?? res;
-    const exportId = exportData?.id ?? exportData?.exportId ?? "";
-    const status = exportData?.status ?? "QUEUED";
-    return {
-      id: exportId,
-      exportId,
-      status
-    };
+    return res?.data ?? res;
   }
-  /**
-   * Checks the status of an ongoing render export.
-   */
-  async getRenderStatus(exportId) {
+  async getPublishStatus(projectId) {
     const res = await this.request(
-      `/exports/${encodeURIComponent(exportId)}`
+      `/projects/${encodeURIComponent(projectId)}/publish/status`
     );
-    return res?.data?.export ?? res?.data ?? res;
+    return res?.data ?? res;
   }
   /**
-   * Polls render export status until complete (SUCCESS or FAILED) or timed out.
+   * Polls publish status until the video is ready, a failure is reported, or
+   * the time budget is spent. Returns the last status either way.
    */
-  async pollRenderUntilComplete(exportId, timeoutSeconds = 90, pollIntervalMs = 3e3) {
-    const startTime = Date.now();
-    const maxDurationMs = timeoutSeconds * 1e3;
-    while (Date.now() - startTime < maxDurationMs) {
-      const status = await this.getRenderStatus(exportId);
-      if (status.status === "SUCCESS" || status.status === "FAILED") {
-        return status;
-      }
+  async waitForPublish(projectId, waitSeconds, pollIntervalMs = 5e3) {
+    const deadline = Date.now() + waitSeconds * 1e3;
+    let status = await this.getPublishStatus(projectId);
+    while (Date.now() < deadline && (status.phase === "rendering" || status.phase === "exporting")) {
       await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      status = await this.getPublishStatus(projectId);
     }
-    const lastStatus = await this.getRenderStatus(exportId);
-    return lastStatus;
+    return status;
+  }
+  async getRenderStatus(exportId) {
+    const res = await this.request(`/exports/${encodeURIComponent(exportId)}`);
+    const data = toObject(res?.data ?? res);
+    return Object.keys(toObject(data.export)).length ? data.export : data;
+  }
+  /** Credit balance for live keys, plus the packs on sale and per-action costs. */
+  async getCredits() {
+    const res = await this.request("/billing/credits");
+    return res?.data ?? res;
   }
-  /**
-   * Generates an AI storyboard / copy for a template given a prompt.
-   */
   async generateStoryboard(data) {
     const res = await this.request("/ai/storyboard/draft", {
       method: "POST",
       body: JSON.stringify(data)
     });
-    return res?.data?.draft ?? res?.data ?? res;
+    const payload = toObject(res?.data ?? res);
+    return Object.keys(toObject(payload.draft)).length ? toObject(payload.draft) : payload;
   }
-  /**
-   * Captures a high-resolution screenshot from a live URL.
-   */
   async captureWebUi(data) {
-    const res = await this.request(
-      "/browse/capture",
-      {
-        method: "POST",
-        body: JSON.stringify(data)
-      }
-    );
-    return res?.data ?? res;
+    const res = await this.request("/browse/capture", {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+    return toObject(res?.data ?? res);
   }
 };
 
 // src/tools/templates.tools.ts
 import { z } from "zod";
+
+// src/types/index.ts
+var WEVI_ASPECT_RATIOS = ["16:9", "16:12"];
+
+// src/tools/templates.tools.ts
+function errorResult(prefix, err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  return {
+    isError: true,
+    content: [{ type: "text", text: `${prefix}: ${msg}` }]
+  };
+}
 function registerTemplateTools(server2, client2) {
   server2.tool(
     "wevi_list_templates",
-    "List and search available video templates on Wevi with category, aspect ratio, and keyword filters.",
+    [
+      "List PUBLISHED Wevi video templates (only published templates can be used in projects).",
+      "Filter by aspect ratio, category or keyword. Every scene in one project must share the same aspectRatio,",
+      "so pick all templates for a video from a single aspectRatio group.",
+      "Templates with requiresUiCapture=true need an interactive screen capture in the Wevi app and cannot be rendered from MCP yet."
+    ].join(" "),
     {
-      category: z.string().optional().describe("Category filter (e.g., 'SaaS', 'E-commerce', 'Social Media', 'Product Promo')"),
-      aspectRatio: z.enum(["16:9", "16:12", "4:3"]).optional().describe("Target video aspect ratio: '16:9' (Widescreen landscape 1920x1080) or '16:12' (Desktop app focus frame 1920x1440 / 4:3)"),
-      search: z.string().optional().describe("Search keyword matching template titles, tags, or descriptions"),
-      limit: z.number().min(1).max(50).optional().default(20).describe("Number of templates to return (default: 20)")
+      category: z.string().optional().describe("Category filter (e.g. 'SaaS', 'CTA', 'Problem', 'Solution', 'Motion')"),
+      aspectRatio: z.enum(WEVI_ASPECT_RATIOS).optional().describe(
+        "'16:9' = widescreen 1920x1080 (default for most videos). '16:12' = 1920x1440 desktop-app focus frame."
+      ),
+      search: z.string().optional().describe("Keyword matched against template names, slugs and descriptions"),
+      limit: z.number().min(1).max(50).optional().default(20).describe("Number of templates to return (default 20, max 50)"),
+      page: z.number().min(1).optional().describe("Page number for pagination (default 1)")
     },
     async (args) => {
       try {
         const result = await client2.listTemplates(args);
+        const usable = result.items.filter((t) => t.requiresUiCapture !== true);
         return {
           content: [
             {
               type: "text",
               text: JSON.stringify(
                 {
-                  totalTemplates: result.total,
-                  templates: result.items.map((t) => ({
-                    id: t.id,
-                    name: t.name,
-                    slug: t.slug,
-                    description: t.description,
-                    aspectRatio: t.aspectRatio,
-                    durationSeconds: t.durationSeconds,
-                    tags: t.tags,
-                    previewVideoUrl: t.previewVideoUrl,
-                    thumbnailUrl: t.thumbnailUrl
-                  }))
+                  totalPublishedTemplates: result.total,
+                  returned: result.items.length,
+                  usableFromMcp: usable.length,
+                  categories: result.categories,
+                  sandbox: client2.isSandbox,
+                  templates: result.items.map((t) => {
+                    const guidance = WeviApiClient.extractGuidance(t);
+                    return {
+                      id: t.id,
+                      slug: t.slug,
+                      name: t.displayName || t.name,
+                      description: t.aiDescription || t.description || null,
+                      purpose: guidance.purpose,
+                      bestForScenes: guidance.sceneIntent,
+                      avoid: guidance.avoid,
+                      tone: guidance.tone,
+                      category: t.category ?? null,
+                      aspectRatio: t.aspectRatio,
+                      durationSeconds: t.durationSeconds ?? null,
+                      requiresUiCapture: t.requiresUiCapture === true,
+                      tags: t.tags ?? [],
+                      previewVideoUrl: t.previewUrl ?? null,
+                      thumbnailUrl: t.thumbnailUrl ?? null
+                    };
+                  }),
+                  hint: "Match bestForScenes to the video's structure (hook \u2192 feature/solution \u2192 proof \u2192 cta). Respect each template's avoid list. Keep every scene in one aspectRatio."
                 },
                 null,
                 2
@@ -221,23 +303,24 @@ function registerTemplateTools(server2, client2) {
           ]
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-          isError: true,
-          content: [{ type: "text", text: `Error listing templates: ${msg}` }]
-        };
+        return errorResult("Error listing templates", err);
       }
     }
   );
   server2.tool(
     "wevi_get_template_schema",
-    "Inspect the dynamic layer variables for a specific Wevi video template (e.g. text variables, color variables, logos, background videos). Use this before creating a project to know what parameters the template expects.",
+    [
+      "Inspect the editable parameters (layer keys) of a published template: text, colors, sliders, toggles, dropdown options, media.",
+      "Call this before wevi_create_project so the `parameters` you pass use exact layer keys and valid values."
+    ].join(" "),
     {
-      templateId: z.string().describe("The unique ID or slug of the Wevi video template")
+      templateId: z.string().describe("Template ID or slug")
     },
     async (args) => {
       try {
         const template = await client2.getTemplate(args.templateId);
+        const editableLayers = WeviApiClient.extractEditableLayers(template);
+        const guidance = WeviApiClient.extractGuidance(template);
         return {
           content: [
             {
@@ -245,12 +328,17 @@ function registerTemplateTools(server2, client2) {
               text: JSON.stringify(
                 {
                   id: template.id,
-                  name: template.name,
                   slug: template.slug,
+                  name: template.displayName || template.name,
+                  description: template.aiDescription || template.description || null,
+                  category: template.category ?? null,
                   aspectRatio: template.aspectRatio,
-                  durationSeconds: template.durationSeconds,
-                  description: template.description,
-                  editableLayers: template.layers || []
+                  durationSeconds: template.durationSeconds ?? null,
+                  requiresUiCapture: template.requiresUiCapture === true,
+                  usableFromMcp: template.requiresUiCapture !== true,
+                  guidance,
+                  editableLayers,
+                  usage: "Pass values as { parameters: { [layerKey]: value } } inside a scene of wevi_create_project. Colors are hex strings, sliders are numbers within validation.min/max, toggles are booleans, dropdowns must use one of `options`."
                 },
                 null,
                 2
@@ -259,11 +347,7 @@ function registerTemplateTools(server2, client2) {
           ]
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-          isError: true,
-          content: [{ type: "text", text: `Error fetching template schema: ${msg}` }]
-        };
+        return errorResult("Error fetching template schema", err);
       }
     }
   );
@@ -271,14 +355,26 @@ function registerTemplateTools(server2, client2) {
 
 // src/tools/projects.tools.ts
 import { z as z2 } from "zod";
+var parameterValue = z2.union([z2.string(), z2.number(), z2.boolean(), z2.null()]);
+var sceneSchema = z2.object({
+  templateId: z2.string().describe("Published template ID or slug for this scene"),
+  title: z2.string().max(120).optional().describe("Optional scene title"),
+  voiceoverText: z2.string().max(600).optional().describe("Optional narration for this scene (voiceover is generated at export when enabled)"),
+  parameters: z2.record(z2.string(), parameterValue).optional().describe("Layer key \u2192 value map from wevi_get_template_schema (e.g. { TXTTYPINGVAR: 'Ship faster', CLRTEXTTYPINGVAR: '#F8FAFC' })")
+});
 function registerProjectTools(server2, client2) {
   server2.tool(
     "wevi_create_project",
-    "Create a new video project on Wevi using a chosen template ID and initial layer parameters (such as headlines, descriptions, colors, logos, and animation settings).",
+    [
+      "Create a Wevi video project from one or more published templates.",
+      "Pass ALL scenes of the video in `scenes` (in order) \u2014 they are rendered and exported together as ONE concatenated video.",
+      "Do not create one project per scene. All templates must share the same aspectRatio and must not require UI capture.",
+      "The aspect ratio is taken from the templates automatically."
+    ].join(" "),
     {
-      templateId: z2.string().describe("The ID of the template to base the project on"),
-      title: z2.string().optional().describe("Optional project title (e.g., 'Product Promo Q3')"),
-      parameters: z2.record(z2.string(), z2.any()).optional().describe("Dynamic parameter key-value pairs matching the template's editable layers (e.g. { TXTTYPINGVAR: 'New AI Features', CLRTEXTTYPINGVAR: '#F8FAFC' })")
+      title: z2.string().max(160).optional().describe("Project title (e.g. 'Q3 Product Launch')"),
+      scenes: z2.array(sceneSchema).min(1).max(12).describe("Ordered scenes; each maps to one template with its parameters"),
+      brandId: z2.string().uuid().optional().describe("Optional Wevi brand ID. Defaults to your latest brand.")
     },
     async (args) => {
       try {
@@ -289,12 +385,14 @@ function registerProjectTools(server2, client2) {
               type: "text",
               text: JSON.stringify(
                 {
-                  message: "Project created successfully",
+                  message: `Project created with ${project.sceneCount ?? project.scenes?.length ?? 0} scene(s).`,
                   projectId: project.id,
                   title: project.title,
                   status: project.status,
                   aspectRatio: project.aspectRatio,
-                  parameters: project.parameters
+                  sandbox: project.sandbox === true,
+                  scenes: project.scenes ?? [],
+                  nextStep: project.nextStep ?? "Call wevi_trigger_render with this projectId to render and export one video."
                 },
                 null,
                 2
@@ -313,20 +411,15 @@ function registerProjectTools(server2, client2) {
   );
   server2.tool(
     "wevi_get_project",
-    "Inspect an existing Wevi project's details, configuration parameters, and status.",
+    "Inspect an existing Wevi project: scenes, layer values, lifecycle status and render state.",
     {
-      projectId: z2.string().describe("The unique ID of the Wevi project")
+      projectId: z2.string().describe("Wevi project ID")
     },
     async (args) => {
       try {
         const project = await client2.getProject(args.projectId);
         return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(project, null, 2)
-            }
-          ]
+          content: [{ type: "text", text: JSON.stringify(project, null, 2) }]
         };
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -341,75 +434,137 @@ function registerProjectTools(server2, client2) {
 
 // src/tools/renders.tools.ts
 import { z as z3 } from "zod";
+var DEFAULT_WAIT_SECONDS = 45;
+var MAX_WAIT_SECONDS = 55;
+function formatPublishStatus(status, projectId) {
+  const base = {
+    projectId,
+    phase: status.phase,
+    message: status.message,
+    sandbox: status.sandbox,
+    render: status.render ? {
+      state: status.render.state,
+      progressPercent: status.render.progressPercent,
+      doneScenes: status.render.doneScenes,
+      sceneCount: status.render.sceneCount,
+      failedScenes: status.render.failedScenes,
+      failures: status.render.failures
+    } : null,
+    export: status.export ? {
+      id: status.export.id,
+      status: status.export.status,
+      progress: status.export.progress,
+      currentStep: status.export.currentStep,
+      quality: status.export.quality,
+      errorMessage: status.export.errorMessage
+    } : null
+  };
+  if (status.phase === "completed") {
+    return {
+      ...base,
+      videoUrl: status.videoUrl,
+      thumbnailUrl: status.thumbnailUrl,
+      durationSeconds: status.export?.durationSeconds ?? null,
+      note: status.sandbox ? "Sandbox (wevi_test_ key): this video is watermarked and capped at 720p. Use a wevi_live_ key for production output." : void 0
+    };
+  }
+  if (status.phase === "rendering" || status.phase === "exporting") {
+    return {
+      ...base,
+      nextStep: `Still ${status.phase}. Call wevi_get_render_status with projectId "${projectId}" again in ~10 seconds.`
+    };
+  }
+  return base;
+}
 function registerRenderTools(server2, client2) {
   server2.tool(
     "wevi_trigger_render",
-    "Trigger high-quality video rendering for a Wevi project. Supports auto-polling so the tool can wait and return the final MP4 video link directly in one step.",
+    [
+      "Render every scene of a project and export them as ONE concatenated MP4 (music + voiceover mixed in).",
+      "Waits up to `waitSeconds` for completion; if the video is not ready yet it returns the current phase and you should poll wevi_get_render_status.",
+      "Sandbox keys (wevi_test_) produce watermarked 720p videos without using credits, capped at 20 scene renders and 5 exports per key per UTC day and 4 scenes per project."
+    ].join(" "),
     {
-      projectId: z3.string().describe("The ID of the project to render"),
-      pollUntilComplete: z3.boolean().optional().default(true).describe("If true (default), waits for the render to complete before returning the final MP4 download URL."),
-      timeoutSeconds: z3.number().min(10).max(300).optional().default(90).describe("Maximum seconds to wait if pollUntilComplete is true (default: 90)")
+      projectId: z3.string().describe("Project ID from wevi_create_project"),
+      quality: z3.enum(["720p", "1080p", "4K"]).optional().default("1080p").describe("Export quality. Free plans and sandbox keys are capped at 720p."),
+      includeMusic: z3.boolean().optional().default(true).describe("Mix background music"),
+      includeVoiceover: z3.boolean().optional().default(true).describe("Generate and mix voiceover from each scene's voiceoverText"),
+      waitSeconds: z3.number().min(0).max(MAX_WAIT_SECONDS).optional().default(DEFAULT_WAIT_SECONDS).describe(`Seconds to wait in this call before returning progress (0-${MAX_WAIT_SECONDS}, default ${DEFAULT_WAIT_SECONDS})`)
     },
     async (args) => {
       try {
-        const triggerRes = await client2.triggerRender(args.projectId);
-        const exportId = triggerRes.exportId || triggerRes.id;
-        if (!exportId) {
+        let status = await client2.publishProject(args.projectId, {
+          quality: args.quality,
+          includeMusic: args.includeMusic,
+          includeVoiceover: args.includeVoiceover
+        });
+        if (args.waitSeconds > 0 && (status.phase === "rendering" || status.phase === "exporting")) {
+          status = await client2.waitForPublish(args.projectId, args.waitSeconds);
+        }
+        const isFailure = status.phase === "failed" || status.phase === "render_failed";
+        return {
+          ...isFailure ? { isError: true } : {},
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(formatPublishStatus(status, args.projectId), null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [{ type: "text", text: `Error triggering render: ${msg}` }]
+        };
+      }
+    }
+  );
+  server2.tool(
+    "wevi_get_render_status",
+    [
+      "Check render + export progress for a project started with wevi_trigger_render and get the final video URL when ready.",
+      "Optionally waits up to `waitSeconds` before returning. Pass `exportId` instead to look up a single export record."
+    ].join(" "),
+    {
+      projectId: z3.string().optional().describe("Project ID (preferred)"),
+      exportId: z3.string().optional().describe("Export ID (legacy lookup of one export record)"),
+      waitSeconds: z3.number().min(0).max(MAX_WAIT_SECONDS).optional().default(0).describe(`Seconds to wait for completion before returning (0-${MAX_WAIT_SECONDS})`)
+    },
+    async (args) => {
+      try {
+        if (args.projectId) {
+          const status = args.waitSeconds > 0 ? await client2.waitForPublish(args.projectId, args.waitSeconds) : await client2.getPublishStatus(args.projectId);
+          const isFailure = status.phase === "failed" || status.phase === "render_failed";
           return {
+            ...isFailure ? { isError: true } : {},
             content: [
               {
                 type: "text",
-                text: JSON.stringify(triggerRes, null, 2)
+                text: JSON.stringify(formatPublishStatus(status, args.projectId), null, 2)
               }
             ]
           };
         }
-        if (args.pollUntilComplete) {
-          const finalStatus = await client2.pollRenderUntilComplete(
-            exportId,
-            args.timeoutSeconds
-          );
-          if (finalStatus.status === "SUCCESS") {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify(
-                    {
-                      status: "SUCCESS",
-                      message: "Video rendered successfully!",
-                      exportId: finalStatus.id,
-                      videoUrl: finalStatus.videoUrl,
-                      thumbnailUrl: finalStatus.thumbnailUrl,
-                      completedAt: finalStatus.completedAt
-                    },
-                    null,
-                    2
-                  )
-                }
-              ]
-            };
-          }
-          if (finalStatus.status === "FAILED") {
-            return {
-              isError: true,
-              content: [
-                {
-                  type: "text",
-                  text: `Render failed: ${finalStatus.errorMessage || "Unknown render error"}`
-                }
-              ]
-            };
-          }
+        if (args.exportId) {
+          const record = await client2.getRenderStatus(args.exportId);
           return {
             content: [
               {
                 type: "text",
                 text: JSON.stringify(
                   {
-                    status: finalStatus.status,
-                    message: "Render is still processing in background. You can check status later using wevi_get_render_status.",
-                    exportId: finalStatus.id
+                    exportId: record.id,
+                    projectId: record.projectId,
+                    status: record.status,
+                    progress: record.progress ?? null,
+                    currentStep: record.currentStep ?? null,
+                    quality: record.quality ?? null,
+                    sandbox: record.sandbox === true,
+                    videoUrl: record.status === "SUCCESS" ? record.outputUrl ?? null : null,
+                    thumbnailUrl: record.thumbnailUrl ?? null,
+                    errorMessage: record.errorMessage ?? null,
+                    completedAt: record.completedAt ?? null
                   },
                   null,
                   2
@@ -419,79 +574,156 @@ function registerRenderTools(server2, client2) {
           };
         }
         return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(
-                {
-                  message: "Render queued successfully",
-                  exportId,
-                  status: triggerRes.status || "QUEUED"
-                },
-                null,
-                2
-              )
-            }
-          ]
+          isError: true,
+          content: [{ type: "text", text: "Provide projectId (preferred) or exportId." }]
         };
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         return {
           isError: true,
-          content: [{ type: "text", text: `Error triggering render: ${msg}` }]
+          content: [{ type: "text", text: `Error checking render status: ${msg}` }]
         };
       }
     }
   );
+}
+
+// src/tools/ai.tools.ts
+import { z as z4 } from "zod";
+
+// src/capabilities.ts
+var WEVI_CAPABILITIES = {
+  summary: "Wevi turns published motion templates into short marketing videos for software products: launch videos, feature explainers, product showcases, social promos, and call-to-action outros. Each scene is a pre-designed motion template (roughly 3 to 15 seconds) whose text, colors, logos, sliders and image slots you fill in. Wevi renders every scene in the cloud and joins them into one MP4 with background music and an AI voiceover.",
+  canDo: [
+    "Multi-scene videos where every scene is a published Wevi template with your copy, brand colors and logo.",
+    "16:9 (1920x1080) widescreen videos and 16:12 (1920x1440) desktop-app frame videos. All scenes in one video must share one ratio.",
+    "AI voiceover generated from each scene's voiceoverText, mixed with a music track at export.",
+    "Web screenshots (wevi_capture_web_ui) used as image layers in templates that accept an image.",
+    "AI storyboard drafts (wevi_generate_storyboard) to plan scenes, copy and narration from a brief.",
+    "Exports at 720p, 1080p or 4K, quality permitting by plan."
+  ],
+  cannotDo: [
+    "Generate free-form or generative video: no dance videos, people, characters, animals, scenery, or anything not built from a template.",
+    "Upload or edit the user's own video footage, or stitch external clips.",
+    "Change a template's animation, layout, duration or camera motion; only its exposed layers are editable.",
+    "Render templates that need an interactive screen capture (requiresUiCapture = true) from the API. Those work only in the Wevi web app.",
+    "Mix aspect ratios in one video, or output vertical 9:16 video.",
+    "Clone a specific voice; voiceover uses Wevi's voice library."
+  ],
+  askBeforeBuilding: [
+    "What is the product or brand, and is there a website to pull colors and a logo from?",
+    "What is the goal of the video: launch, feature explainer, social promo, or a call to action?",
+    "Who is the audience and what tone fits (confident, playful, technical)?",
+    "How long, or how many scenes? Typical videos are 3 to 6 scenes, 15 to 45 seconds.",
+    "Key messages or on-screen text for each scene, if the user has them; otherwise draft with wevi_generate_storyboard and confirm.",
+    "Should there be a voiceover, and any brand colors (hex) to apply?",
+    "Which aspect ratio: 16:9 for general use, 16:12 for desktop-app focused frames."
+  ],
+  workflow: [
+    "1. wevi_list_templates to see what exists; group by aspect ratio and read purpose, sceneIntent and avoid to match scenes to roles (hook, feature, proof, CTA).",
+    "2. wevi_get_template_schema for each chosen template to get exact layer keys and constraints.",
+    "3. wevi_create_project with ALL scenes in one project. Never one project per scene.",
+    "4. wevi_trigger_render, then wevi_get_render_status until phase is completed; share videoUrl.",
+    "Before large batches, wevi_get_credits. Sandbox keys (wevi_test_) are free, watermarked, 720p, and capped daily."
+  ],
+  limits: {
+    aspectRatios: ["16:9", "16:12"],
+    maxScenesPerProject: 12,
+    sandbox: { sceneRendersPerDay: 20, exportsPerDay: 5, maxScenesPerProject: 4 },
+    credits: { sceneRender: 1, export720p: 1, export1080p: 2, export4K: 4, storyboardDraft: 1, webCapture: 1 }
+  }
+};
+function buildServerInstructions() {
+  const c = WEVI_CAPABILITIES;
+  return [
+    c.summary,
+    "",
+    "Wevi CAN: " + c.canDo.map((line) => `- ${line}`).join("\n"),
+    "",
+    "Wevi CANNOT: " + c.cannotDo.map((line) => `- ${line}`).join("\n"),
+    "",
+    "If a request is outside these capabilities (e.g. a dance video, editing the user's footage, vertical video), say so plainly and offer what Wevi can do instead. Do not attempt it.",
+    "",
+    "Before building, ask the user what is missing from: " + c.askBeforeBuilding.map((q) => `- ${q}`).join("\n"),
+    "",
+    "Workflow: " + c.workflow.map((step) => `- ${step}`).join("\n")
+  ].join("\n");
+}
+
+// src/tools/ai.tools.ts
+function registerAiTools(server2, client2) {
+  server2.tool(
+    "wevi_get_capabilities",
+    [
+      "What Wevi can and cannot make, the questions to ask the user before building, supported aspect ratios, sandbox limits and credit costs.",
+      "Call this first in a new conversation, and whenever a request sounds outside Wevi's scope (e.g. 'make a dance video', 'edit my footage', 'vertical video'). No API call is made."
+    ].join(" "),
+    {},
+    async () => ({
+      content: [{ type: "text", text: JSON.stringify({ ...WEVI_CAPABILITIES, sandboxKey: client2.isSandbox }, null, 2) }]
+    })
+  );
   server2.tool(
-    "wevi_get_render_status",
-    "Check the real-time status and download URL of an active or completed video export.",
-    {
-      exportId: z3.string().describe("The unique ID of the export render")
-    },
-    async (args) => {
+    "wevi_get_credits",
+    [
+      "Show the API credit balance for this key: plan allowance used/remaining, purchased credits, what each action costs, and the top-up link.",
+      "Call it before a large batch, or when a tool fails with 402. Sandbox keys (wevi_test_) do not use credits."
+    ].join(" "),
+    {},
+    async () => {
       try {
-        const status = await client2.getRenderStatus(args.exportId);
+        const balance = await client2.getCredits();
+        const unlimited = balance.totalAvailable === null;
         return {
           content: [
             {
               type: "text",
-              text: JSON.stringify(status, null, 2)
+              text: JSON.stringify(
+                {
+                  sandboxKey: client2.isSandbox,
+                  plan: balance.plan,
+                  purchasedCredits: balance.purchased.balance,
+                  totalAvailable: unlimited ? "unlimited" : balance.totalAvailable,
+                  costs: balance.costs,
+                  packs: balance.packs.map((pack) => ({
+                    id: pack.id,
+                    name: pack.name,
+                    credits: pack.credits,
+                    price: `$${(pack.priceCents / 100).toFixed(2)}`
+                  })),
+                  topUpUrl: balance.topUpUrl,
+                  note: client2.isSandbox ? "This is a sandbox key: renders are free, watermarked and capped daily. Credits shown apply to your live keys." : "A 3-scene 1080p video costs 5 credits (3 renders + 2 export)."
+                },
+                null,
+                2
+              )
             }
           ]
         };
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        return {
-          isError: true,
-          content: [{ type: "text", text: `Error checking render status: ${msg}` }]
-        };
+        return { isError: true, content: [{ type: "text", text: `Error fetching credits: ${msg}` }] };
       }
     }
   );
-}
-
-// src/tools/ai.tools.ts
-import { z as z4 } from "zod";
-function registerAiTools(server2, client2) {
   server2.tool(
     "wevi_generate_storyboard",
-    "Generate tailored video script, headline, and copywriting variables for a Wevi template based on a user prompt or product URL.",
+    [
+      "Draft a multi-scene storyboard (scene titles, purposes, on-screen text and voiceover) from a brief.",
+      "Use the draft to choose templates with wevi_list_templates and fill their parameters in wevi_create_project."
+    ].join(" "),
     {
-      prompt: z4.string().describe("The marketing goal, product description, or topic for the video (e.g. '30-second SaaS promo highlighting AI-powered email writing')"),
-      templateId: z4.string().optional().describe("Optional template ID to shape the storyboard to specific scene layers"),
-      brandUrl: z4.string().url().optional().describe("Optional website URL to extract brand context from")
+      prompt: z4.string().describe("Marketing goal, product description, audience and tone (e.g. '30-second SaaS promo for an AI email writer')"),
+      brandName: z4.string().optional().describe("Brand or product name"),
+      brandUrl: z4.string().url().optional().describe("Website URL used for brand context"),
+      brandVoice: z4.string().optional().describe("Tone of voice (e.g. 'confident, modern, energetic')"),
+      maxScenes: z4.number().int().min(3).max(12).optional().describe("Soft cap on scene count (3-12)")
     },
     async (args) => {
       try {
         const result = await client2.generateStoryboard(args);
         return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
-            }
-          ]
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
         };
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -559,10 +791,22 @@ var client = new WeviApiClient({
   apiKey: apiKey || "",
   apiUrl
 });
-var server = new McpServer({
-  name: "wevi",
-  version: "0.1.0"
-});
+if (client.isSandbox) {
+  process.stderr.write(
+    "[Wevi MCP] Sandbox key detected (wevi_test_): renders are watermarked, capped at 720p and do not use credits.\n"
+  );
+}
+var server = new McpServer(
+  {
+    name: "wevi",
+    version: "0.2.1"
+  },
+  {
+    // Sent to the client on connect; assistants that honour MCP instructions
+    // learn what Wevi can and cannot make before the first tool call.
+    instructions: buildServerInstructions()
+  }
+);
 registerAllTools(server, client);
 async function main() {
   const transport = new StdioServerTransport();