@clipform/mcp-server 1.47.0 → 1.48.0

package/dist/{chunk-KP64A2KW.js → chunk-3MTEM3VC.js}

@@ -6,7 +6,7 @@ import {
   getWorkflowText,
   objectType,
   registerPrompts
-} from "./chunk-L3YIUY5R.js";
+} from "./chunk-BBNREY2Q.js";
 import {
   GUIDE_TYPES,
   QUIZ_VARIANTS,
@@ -14,7 +14,7 @@ import {
   getGuideUri,
   guideFallbackText,
   registerResources
-} from "./chunk-MOKUP5DR.js";
+} from "./chunk-WUORO245.js";
 import {
   ACTIVE_NODE_TYPES,
   BUSINESS,
@@ -33,8 +33,9 @@ import {
   callApi,
   errorResult,
   resolveFormType,
+  structuredResult,
   textResult
-} from "./chunk-F2JA2N5N.js";
+} from "./chunk-4CY5EJCR.js";
 import {
   __commonJS,
   __export,
@@ -17325,6 +17326,21 @@ function registerListFormsTool(server) {
         sort: external_exports.enum(["created_at", "updated_at"]).optional().describe("Sort field (default: created_at)"),
         order: external_exports.enum(["asc", "desc"]).optional().describe("Sort order (default: desc, newest first)")
       },
+      outputSchema: {
+        forms: external_exports.array(
+          external_exports.object({
+            id: external_exports.string(),
+            title: external_exports.string(),
+            share_id: external_exports.string(),
+            is_live: external_exports.boolean(),
+            has_unpublished_changes: external_exports.boolean(),
+            created_at: external_exports.string(),
+            updated_at: external_exports.string(),
+            tags: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), color: external_exports.string().nullable() }))
+          })
+        ).describe("Matching forms (empty if none)"),
+        next_cursor: external_exports.string().nullable().describe("Pass as cursor to fetch the next page, or null when no more")
+      },
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -17346,8 +17362,21 @@ function registerListFormsTool(server) {
         return errorResult(result.error);
       }
       const data = result.data;
+      const structured = {
+        forms: data.forms.map((f) => ({
+          id: f.id,
+          title: f.title,
+          share_id: f.share_id,
+          is_live: f.is_live,
+          has_unpublished_changes: f.has_unpublished_changes,
+          created_at: f.created_at,
+          updated_at: f.updated_at,
+          tags: f.tags.map((t) => ({ id: t.id, name: t.name, color: t.color }))
+        })),
+        next_cursor: data.next_cursor
+      };
       if (data.forms.length === 0) {
-        return textResult("No forms found matching the criteria.");
+        return structuredResult("No forms found matching the criteria.", structured);
       }
       const lines = [`Found ${data.forms.length} form(s):
 `];
@@ -17361,14 +17390,36 @@ function registerListFormsTool(server) {
           `More results available. Pass cursor: "${data.next_cursor}" to get the next page.`
         );
       }
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), structured);
     }
   );
 }
 
 // src/lib/format-form.ts
+function getFormNodes(data) {
+  return data.node ?? data.nodes ?? [];
+}
+function projectFormState(data) {
+  return {
+    form_id: String(data.form_id ?? ""),
+    title: String(data.title ?? ""),
+    is_live: Boolean(data.is_live),
+    has_unpublished_changes: Boolean(data.has_unpublished_changes),
+    nodes: getFormNodes(data).map((q) => {
+      const options = q.node_options ?? q.options;
+      return {
+        id: q.id,
+        type: q.type,
+        prompt: q.prompt ?? "",
+        required: Boolean(q.required),
+        ...q.config && Object.keys(q.config).length > 0 ? { config: q.config } : {},
+        ...options && options.length > 0 ? { options: options.map((o) => ({ id: o.id, content: o.content })) } : {}
+      };
+    })
+  };
+}
 function formatFormState(data) {
-  const nodes = data.node ?? data.nodes ?? [];
+  const nodes = getFormNodes(data);
   const lines = [
     `Form: ${data.title}`,
     `Form ID: ${data.form_id}`,
@@ -17408,6 +17459,22 @@ function registerGetFormTool(server) {
       inputSchema: {
         form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)")
       },
+      outputSchema: {
+        form_id: external_exports.string().describe("Form UUID"),
+        title: external_exports.string().describe("Form title"),
+        is_live: external_exports.boolean().describe("Whether the form is published"),
+        has_unpublished_changes: external_exports.boolean().describe("Live form has edits not yet republished"),
+        nodes: external_exports.array(
+          external_exports.object({
+            id: external_exports.string(),
+            type: external_exports.string(),
+            prompt: external_exports.string(),
+            required: external_exports.boolean(),
+            config: external_exports.record(external_exports.unknown()).optional(),
+            options: external_exports.array(external_exports.object({ id: external_exports.string(), content: external_exports.string() })).optional()
+          })
+        ).describe("Nodes in sequential order - IDs for update_node / upload_node_media")
+      },
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -17420,7 +17487,7 @@ function registerGetFormTool(server) {
       if (!result.ok) {
         return errorResult(result.error);
       }
-      return textResult(formatFormState(result.data));
+      return structuredResult(formatFormState(result.data), projectFormState(result.data));
     }
   );
 }
@@ -17597,6 +17664,10 @@ function registerAddNodeTool(server) {
           "Insert after this node ID. Omit to append before the end screen."
         )
       },
+      outputSchema: {
+        node_id: external_exports.string().describe("ID of the created node - pass to update_node / upload_node_media"),
+        type: external_exports.string().describe("Node type that was added")
+      },
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -17615,8 +17686,10 @@ function registerAddNodeTool(server) {
       if (!result.ok) {
         return errorResult(result.error);
       }
-      return textResult(
-        `Node added. ID: ${result.data.node_id} | Type: ${node.type}`
+      const nodeId = result.data.node_id;
+      return structuredResult(
+        `Node added. ID: ${nodeId} | Type: ${node.type}`,
+        { node_id: nodeId, type: node.type }
       );
     }
   );
@@ -17644,6 +17717,16 @@ function registerUpdateNodeTool(server) {
         form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)"),
         updates: external_exports.array(NodeUpdateSchema).min(1).max(20).describe("One or more node updates to apply")
       },
+      outputSchema: {
+        results: external_exports.array(
+          external_exports.object({
+            node_id: external_exports.string(),
+            ok: external_exports.boolean(),
+            warnings: external_exports.array(external_exports.string()).optional(),
+            error: external_exports.string().optional()
+          })
+        ).describe("One result per requested update, in order")
+      },
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -17653,6 +17736,7 @@ function registerUpdateNodeTool(server) {
     },
     async ({ form_id, updates }) => {
       const allLines = [];
+      const results = [];
       for (const { node_id, prompt, label, type, required: required2, config: config2, options } of updates) {
         const body = {};
         if (prompt !== void 0) body.prompt = prompt;
@@ -17667,6 +17751,7 @@ function registerUpdateNodeTool(server) {
         );
         if (!result.ok) {
           allLines.push(`Node ${node_id}: FAILED \u2014 ${result.error}`);
+          results.push({ node_id, ok: false, error: result.error });
           continue;
         }
         const changes = [];
@@ -17682,8 +17767,9 @@ function registerUpdateNodeTool(server) {
         if (warnings?.length) {
           for (const w of warnings) allLines.push(`Node ${node_id} warning: ${w}`);
         }
+        results.push({ node_id, ok: true, ...warnings?.length ? { warnings } : {} });
       }
-      return textResult(allLines.join("\n"));
+      return structuredResult(allLines.join("\n"), { results });
     }
   );
 }
@@ -17749,7 +17835,7 @@ var MediaItemSchema = external_exports.object({
       ).optional().describe("Per-word timestamps within the segment")
     })
   ).optional().describe("Word-level captions from clipform_generate_tts. Required for per-word highlighting - pass the full objects including 'words' arrays."),
-  show_captions: external_exports.boolean().optional().default(true).describe("Display captions/subtitles on the node"),
+  show_captions: external_exports.boolean().optional().describe("Display captions/subtitles on the node. Defaults to on; pass false to hide them."),
   fit_media: external_exports.boolean().optional().describe("Show the whole frame (contain) instead of cover-cropping. ALWAYS set true when attaching renders from clipform_render_composition or clipform_generate_video - they are composed 9:16 frames that must never be cropped. Leave unset for user-supplied media (arbitrary aspect ratios want the cover default).")
 });
 function registerUploadNodeMediaTool(server) {
@@ -17759,11 +17845,23 @@ function registerUploadNodeMediaTool(server) {
       title: "Upload Node Media",
       description: `Upload media for one or more nodes. Pass one item or many (max 10). Multiple items upload sequentially.
 
-When a public URL is provided, the media is fetched and stored automatically. Only works on node types that support media (${MEDIA_SUPPORTED_TYPES.join(", ")}). For video: ingested via Mux. For image: stored in Supabase. Captions from clipform_generate_tts enable per-word highlighting in the viewer. When attaching renders from clipform_render_composition or clipform_generate_video, set fit_media: true on each item.`,
+When a public URL is provided, the media is fetched and stored automatically. Only works on node types that support media (${MEDIA_SUPPORTED_TYPES.join(", ")}). For video: ingested via Mux. For image: stored in Supabase. Each upload lands in your workspace media library and is then attached to the node (so it is reusable across nodes), matching the builder. Captions from clipform_generate_tts enable per-word highlighting in the viewer. When attaching renders from clipform_render_composition or clipform_generate_video, set fit_media: true on each item.`,
       inputSchema: {
         form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)"),
         items: external_exports.array(MediaItemSchema).min(1).max(10).describe("One or more media items to upload")
       },
+      outputSchema: {
+        results: external_exports.array(
+          external_exports.object({
+            node_id: external_exports.string(),
+            ok: external_exports.boolean(),
+            stored: external_exports.boolean().describe("Bytes already stored (URL-based); false when an upload_url is pending"),
+            upload_url: external_exports.string().optional(),
+            upload_method: external_exports.string().optional(),
+            error: external_exports.string().optional()
+          })
+        ).describe("One result per item, in order")
+      },
       annotations: {
         readOnlyHint: false,
         destructiveHint: false,
@@ -17772,42 +17870,89 @@ When a public URL is provided, the media is fetched and stored automatically. On
       }
     },
     async ({ form_id, items }) => {
+      const workspaceId = getMcpAuth()?.workspace_id;
       const lines = [];
+      const results = [];
       let successCount = 0;
       for (let i = 0; i < items.length; i++) {
         const item = items[i];
         if (items.length > 1) lines.push(`--- Item ${i + 1} (node ${item.node_id}) ---`);
-        const body = {
+        if (!workspaceId) {
+          const error2 = "no workspace in context - reconnect the MCP or set CLIPFORM_API_KEY so media can land in your library.";
+          lines.push(`FAILED: ${error2}`);
+          lines.push("");
+          results.push({ node_id: item.node_id, ok: false, stored: false, error: error2 });
+          continue;
+        }
+        const createBody = {
           media_type: item.media_type,
           media_source: item.media_source
         };
-        if (item.url) body.url = item.url;
-        if (item.captions) body.captions = item.captions;
-        if (item.show_captions !== void 0) body.show_captions = item.show_captions;
-        if (item.fit_media !== void 0) body.fit_media = item.fit_media;
-        const result = await callApi(
-          `/forms/${form_id}/nodes/${item.node_id}/media`,
-          { method: "POST", body }
-        );
-        if (result.ok) {
-          successCount++;
-          const resultLines = [];
-          if (result.data.upload_url) {
-            resultLines.push(
-              `Upload URL: ${result.data.upload_url}`,
-              `Upload method: ${result.data.upload_method}`,
-              `Upload the file directly to the upload URL using ${result.data.upload_method === "tus" ? "TUS resumable upload" : "HTTP PUT"}.`
-            );
-          } else {
-            resultLines.push(`Media stored.`);
-          }
-          if (item.captions) {
-            resultLines.push(`Captions: ${item.captions.length} segments saved`);
+        if (item.url) createBody.url = item.url;
+        if (item.captions) createBody.captions = item.captions;
+        const created = await callApi(`/workspaces/${workspaceId}/media`, { method: "POST", body: createBody });
+        if (!created.ok) {
+          lines.push(`FAILED: ${created.error}`);
+          lines.push("");
+          results.push({ node_id: item.node_id, ok: false, stored: false, error: created.error });
+          continue;
+        }
+        const mediaAssetId = created.data.media_asset_id;
+        if (!mediaAssetId) {
+          const error2 = `upload did not return a media asset id (route ${String(created.data.route ?? "unknown")}).`;
+          lines.push(`FAILED: ${error2}`);
+          lines.push("");
+          results.push({ node_id: item.node_id, ok: false, stored: false, error: error2 });
+          continue;
+        }
+        const attached = await callApi(`/forms/${form_id}/nodes/${item.node_id}/media/attach`, {
+          method: "POST",
+          body: { media_asset_id: mediaAssetId }
+        });
+        if (!attached.ok) {
+          lines.push(`FAILED to attach the uploaded media to the node: ${attached.error}`);
+          lines.push("");
+          results.push({ node_id: item.node_id, ok: false, stored: false, error: attached.error });
+          continue;
+        }
+        const presentation = {};
+        if (item.fit_media !== void 0) presentation.fit_media = item.fit_media;
+        if (item.show_captions !== void 0) presentation.show_captions = item.show_captions;
+        let presentationNote = "";
+        if (Object.keys(presentation).length > 0) {
+          const patched = await callApi(`/forms/${form_id}/nodes/${item.node_id}/media`, {
+            method: "PATCH",
+            body: presentation
+          });
+          if (!patched.ok) {
+            presentationNote = `Note: media attached, but display settings were not applied: ${patched.error}`;
           }
-          lines.push(resultLines.join("\n"));
+        }
+        successCount++;
+        const uploadUrl = created.data.upload_url;
+        const uploadMethod = created.data.upload_method;
+        results.push({
+          node_id: item.node_id,
+          ok: true,
+          stored: !uploadUrl,
+          ...uploadUrl ? { upload_url: uploadUrl } : {},
+          ...uploadUrl && uploadMethod ? { upload_method: uploadMethod } : {}
+        });
+        const resultLines = [];
+        if (created.data.upload_url) {
+          resultLines.push(
+            `Upload URL: ${created.data.upload_url}`,
+            `Upload method: ${created.data.upload_method}`,
+            `Upload the file directly to the upload URL using ${created.data.upload_method === "tus" ? "TUS resumable upload" : "HTTP PUT"}.`
+          );
         } else {
-          lines.push(`FAILED: ${result.error}`);
+          resultLines.push(`Media stored in the workspace library and attached to the node.`);
         }
+        if (item.captions) {
+          resultLines.push(`Captions: ${item.captions.length} segments saved`);
+        }
+        if (presentationNote) resultLines.push(presentationNote);
+        lines.push(resultLines.join("\n"));
         lines.push("");
       }
       if (items.length > 1) {
@@ -17815,7 +17960,7 @@ When a public URL is provided, the media is fetched and stored automatically. On
 `);
       }
       if (successCount === 0) return errorResult(lines.join("\n"));
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { results });
     }
   );
 }
@@ -17831,6 +17976,14 @@ function registerGetNodeMediaTool(server) {
         form_id: external_exports.string().uuid().describe("The form UUID (returned by clipform_create_form, not the short share_id from the URL)"),
         node_id: external_exports.string().describe("The node ID")
       },
+      outputSchema: {
+        media: external_exports.object({
+          media_type: external_exports.string(),
+          status: external_exports.string(),
+          duration: external_exports.number().optional(),
+          transcription_status: external_exports.string().nullable().optional()
+        }).nullable().describe("Attached media (null if the node has none)")
+      },
       annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -17847,15 +18000,22 @@ function registerGetNodeMediaTool(server) {
       }
       const media = result.data.media;
       if (!media) {
-        return textResult("No media attached to this node.");
+        return structuredResult("No media attached to this node.", { media: null });
       }
-      return textResult(
+      const projected = {
+        media_type: String(media.media_type),
+        status: String(media.status),
+        ...typeof media.duration === "number" ? { duration: media.duration } : {},
+        transcription_status: media.transcription_status == null ? null : String(media.transcription_status)
+      };
+      return structuredResult(
         [
           `Type: ${media.media_type}`,
           `Status: ${media.status}`,
           media.duration ? `Duration: ${media.duration}s` : "",
           `Transcription: ${media.transcription_status}`
-        ].filter(Boolean).join("\n")
+        ].filter(Boolean).join("\n"),
+        { media: projected }
       );
     }
   );
@@ -18009,6 +18169,20 @@ Returns: article title, source, author, date, URL, description, and image URL pe
         query: external_exports.string().describe("News search query (e.g. 'Iran war 2026', 'Australian Open final', 'UK election')"),
         count: external_exports.number().min(1).max(15).default(5).optional().describe("Max results per provider (default 5)")
       },
+      outputSchema: {
+        query: external_exports.string(),
+        articles: external_exports.array(
+          external_exports.object({
+            title: external_exports.string().optional(),
+            source: external_exports.string().optional(),
+            description: external_exports.string().optional(),
+            author: external_exports.string().optional(),
+            published_at: external_exports.string().optional(),
+            url: external_exports.string(),
+            image_url: external_exports.string().optional()
+          })
+        ).describe("Matching articles (empty if none)")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ query, count }) => {
@@ -18017,7 +18191,16 @@ Returns: article title, source, author, date, URL, description, and image URL pe
       });
       if (!result.ok) return errorResult(result.error);
       const results = result.data.results;
-      if (!results.length) return textResult(`No news articles found for "${query}".`);
+      if (!results.length) return structuredResult(`No news articles found for "${query}".`, { query, articles: [] });
+      const articles = results.map((article) => ({
+        ...article.title ? { title: article.title } : {},
+        ...article.source ? { source: article.source } : {},
+        ...article.description ? { description: article.description } : {},
+        ...article.author ? { author: article.author } : {},
+        ...article.publishedAt ? { published_at: article.publishedAt } : {},
+        url: article.url,
+        ...article.imageUrl ? { image_url: article.imageUrl } : {}
+      }));
       const lines = [`Found ${results.length} articles for "${query}":
 `];
       for (const article of results) {
@@ -18029,7 +18212,7 @@ Returns: article title, source, author, date, URL, description, and image URL pe
         if (article.imageUrl) lines.push(`  Image: ${article.imageUrl}`);
         lines.push("");
       }
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { query, articles });
     }
   );
 }
@@ -18085,6 +18268,12 @@ Supports any public YouTube video with captions enabled. Does NOT work for priva
 }
 
 // src/tools/generate-tts.ts
+var CaptionSchema = external_exports.object({
+  start: external_exports.number(),
+  end: external_exports.number(),
+  text: external_exports.string(),
+  words: external_exports.array(external_exports.object({ word: external_exports.string(), start: external_exports.number(), end: external_exports.number() })).optional()
+});
 var TtsItemSchema = external_exports.object({
   text: external_exports.string().min(1).max(5e3).describe("Narration text"),
   voice: external_exports.enum(["ryan", "sonia", "andrew", "ava", "guy"]).optional().default("ryan").describe("Voice: ryan (British male, clear/articulate), sonia (British female, warm/bright), andrew (American male, smooth/neutral), ava (American female, vibrant/friendly), guy (American male, deep/authoritative). Pick based on the form's topic and audience."),
@@ -18105,6 +18294,16 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
       inputSchema: {
         items: external_exports.array(TtsItemSchema).min(1).max(10).describe("One or more TTS items to generate")
       },
+      outputSchema: {
+        results: external_exports.array(
+          external_exports.object({
+            ok: external_exports.boolean(),
+            audio_url: external_exports.string().optional(),
+            captions: external_exports.array(CaptionSchema).optional().describe("Pass as the captions param to upload_node_media"),
+            error: external_exports.string().optional()
+          })
+        ).describe("One result per item, in order")
+      },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
     },
     async ({ items }) => {
@@ -18118,6 +18317,7 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
         )
       );
       const lines = [];
+      const structured = [];
       let successCount = 0;
       for (let i = 0; i < results.length; i++) {
         const r = results[i];
@@ -18134,11 +18334,17 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
             ...Array.isArray(c.words) ? { words: c.words.map((w) => ({ word: w.word, start: w.start, end: w.end })) } : {}
           }));
           lines.push(`Captions: ${JSON.stringify(captions)}`);
+          structured.push({
+            ok: true,
+            ...data.audioUrl ? { audio_url: String(data.audioUrl) } : {},
+            captions
+          });
         } else {
           const error2 = r.status === "rejected" ? r.reason?.message || String(r.reason) : r.value.error;
           const status = r.status === "fulfilled" ? r.value.status : 0;
           const hint = status === 500 || status === 0 ? " (transient - retrying may help)" : "";
           lines.push(`FAILED: ${error2}${hint}`);
+          structured.push({ ok: false, error: String(error2) });
         }
         lines.push("");
       }
@@ -18148,7 +18354,7 @@ Pass one item or many (max 10) - multiple items run in parallel. Returns audio U
       }
       lines.push(`Pass the complete Captions JSON as the "captions" parameter when uploading.`);
       if (successCount === 0) return errorResult(lines.join("\n"));
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { results: structured });
     }
   );
 }
@@ -18172,10 +18378,30 @@ Example: { queries: [{ query: "saturn rings" }, { query: "mars surface", count:
           })
         ).min(1).max(10).describe("One or more search queries to run")
       },
+      outputSchema: {
+        searches: external_exports.array(
+          external_exports.object({
+            query: external_exports.string(),
+            kind: external_exports.enum(["image", "video"]),
+            items: external_exports.array(
+              external_exports.object({
+                title: external_exports.string().optional(),
+                url: external_exports.string(),
+                width: external_exports.number().optional(),
+                height: external_exports.number().optional(),
+                duration: external_exports.number().optional(),
+                source: external_exports.string().optional(),
+                attribution: external_exports.string().optional()
+              })
+            )
+          })
+        ).describe("Results grouped by query (items empty if a query found nothing or failed)")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ queries }) => {
       const allLines = [];
+      const searches = [];
       for (const q of queries) {
         const { query, count, orientation } = q;
         const kind = q.kind ?? "image";
@@ -18185,16 +18411,32 @@ Example: { queries: [{ query: "saturn rings" }, { query: "mars surface", count:
         if (queries.length > 1) allLines.push(`--- "${query}" (${kind}) ---`);
         if (!result.ok) {
           allLines.push(`FAILED: ${result.error}`, "");
+          searches.push({ query, kind, items: [] });
           continue;
         }
         const results = result.data.results;
         if (!results.length) {
           allLines.push(`No ${kind}s found.`, "");
+          searches.push({ query, kind, items: [] });
           continue;
         }
+        const shown = results.slice(0, 10);
+        searches.push({
+          query,
+          kind,
+          items: shown.map((item) => ({
+            ...item.title ? { title: item.title } : {},
+            url: item.url,
+            ...typeof item.width === "number" ? { width: item.width } : {},
+            ...typeof item.height === "number" ? { height: item.height } : {},
+            ...kind === "video" && typeof item.duration === "number" ? { duration: item.duration } : {},
+            ...item.source ? { source: item.source } : {},
+            ...item.attribution ? { attribution: item.attribution } : {}
+          }))
+        });
         allLines.push(`Found ${results.length} ${kind}s:
 `);
-        for (const item of results.slice(0, 10)) {
+        for (const item of shown) {
           allLines.push(`- ${item.title}`);
           allLines.push(`  URL: ${item.url}`);
           const meta = [];
@@ -18209,7 +18451,7 @@ Example: { queries: [{ query: "saturn rings" }, { query: "mars surface", count:
           allLines.push("");
         }
       }
-      return textResult(allLines.join("\n"));
+      return structuredResult(allLines.join("\n"), { searches });
     }
   );
 }
@@ -18345,6 +18587,17 @@ For multi-render builds (e.g. one clip per quiz question), pass everything in ON
         wait: external_exports.boolean().optional().default(true).describe("Single render only: true (default) blocks until the render is ready and returns its URL; false returns a job ID for clipform_check_render. Batch items always run fire-and-poll."),
         items: external_exports.array(RenderItemSchema).min(1).max(10).optional().describe("Batch mode: multiple renders in one call. All fire in parallel; returns one job ID per item - collect with clipform_check_render (job_ids). Use this whenever rendering more than one clip.")
       },
+      outputSchema: {
+        jobs: external_exports.array(
+          external_exports.object({
+            status: external_exports.enum(["rendering", "complete"]),
+            job_id: external_exports.string().optional().describe("Present when status is 'rendering' - pass to check_render"),
+            public_url: external_exports.string().optional().describe("Present when status is 'complete' - attach via upload_node_media (fit_media: true)"),
+            composition_id: external_exports.string().optional(),
+            output_format: external_exports.string().optional()
+          })
+        ).describe("One entry per render (single or batch)")
+      },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
     },
     async ({ compositionId, outputFormat, inputProps, wait, items }) => {
@@ -18360,23 +18613,34 @@ For multi-render builds (e.g. one clip per quiz question), pass everything in ON
       }
       if (items?.length) {
         const jobs2 = items.map((item) => ({ item, job: fireRender(item) }));
-        return textResult(
+        return structuredResult(
           [
             `${jobs2.length} renders started in parallel:`,
             ...jobs2.map(({ item, job }) => `- ${item.compositionId} (${item.outputFormat}): job ${job.id}`),
             ``,
             `Collect with ONE clipform_check_render call (job_ids: [...]). Renders typically take ${RENDER_TIMING.expectedRange}.`
-          ].join("\n")
+          ].join("\n"),
+          {
+            jobs: jobs2.map(({ item, job }) => ({
+              status: "rendering",
+              job_id: job.id,
+              composition_id: item.compositionId,
+              output_format: item.outputFormat
+            }))
+          }
         );
       }
       if (wait === false) {
         const job = fireRender({ compositionId, outputFormat, inputProps });
-        return textResult(
+        return structuredResult(
           [
             `Render started (${compositionId}).`,
             `Job ID: ${job.id}`,
             `Fire any remaining renders now, then poll clipform_check_render. Renders typically take ${RENDER_TIMING.expectedRange}.`
-          ].join("\n")
+          ].join("\n"),
+          {
+            jobs: [{ status: "rendering", job_id: job.id, composition_id: compositionId, output_format: outputFormat }]
+          }
         );
       }
       const result = await callApi("/internal/render", {
@@ -18385,11 +18649,21 @@ For multi-render builds (e.g. one clip per quiz question), pass everything in ON
       });
       if (!result.ok) return errorResult(result.error);
       const data = result.data;
-      return textResult(
+      return structuredResult(
         [
           `Render complete. Public URL: ${data.public_url}`,
           `Attach via clipform_upload_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
-        ].join("\n")
+        ].join("\n"),
+        {
+          jobs: [
+            {
+              status: "complete",
+              ...data.public_url ? { public_url: data.public_url } : {},
+              composition_id: compositionId,
+              output_format: outputFormat
+            }
+          ]
+        }
       );
     }
   );
@@ -18410,6 +18684,19 @@ function registerSearchMusicTool(server) {
         maxDuration: external_exports.number().optional().describe("Maximum duration in seconds"),
         tags: external_exports.array(external_exports.string()).optional().describe("Genre/mood tags to filter by")
       },
+      outputSchema: {
+        query: external_exports.string(),
+        tracks: external_exports.array(
+          external_exports.object({
+            title: external_exports.string().optional(),
+            artist: external_exports.string().optional(),
+            url: external_exports.string(),
+            duration: external_exports.number().optional(),
+            source: external_exports.string().optional(),
+            license: external_exports.string().optional()
+          })
+        ).describe("Matching tracks (empty if none); pass a url as the audio track to generate_video")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ query, count, instrumentalOnly, minDuration, maxDuration, tags }) => {
@@ -18418,7 +18705,15 @@ function registerSearchMusicTool(server) {
       });
       if (!result.ok) return errorResult(result.error);
       const results = result.data.results;
-      if (!results.length) return textResult(`No music found for "${query}".`);
+      if (!results.length) return structuredResult(`No music found for "${query}".`, { query, tracks: [] });
+      const tracks = results.map((item) => ({
+        ...item.title ? { title: item.title } : {},
+        ...item.artist ? { artist: item.artist } : {},
+        url: item.url,
+        ...typeof item.duration === "number" ? { duration: item.duration } : {},
+        ...item.source ? { source: item.source } : {},
+        ...item.license ? { license: item.license } : {}
+      }));
       const lines = [`Found ${results.length} tracks for "${query}":
 `];
       for (const item of results) {
@@ -18429,7 +18724,7 @@ function registerSearchMusicTool(server) {
         if (item.license) lines.push(`  License: ${item.license}`);
         lines.push("");
       }
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), { query, tracks });
     }
   );
 }
@@ -18470,6 +18765,19 @@ function registerListCompositionsTool(server) {
       title: "List Compositions",
       description: `Browse available video compositions and their expected props schemas. Call this before using clipform_render_composition to discover visual styles and their input props. For narrated slideshows from images, use clipform_generate_video instead.`,
       inputSchema: {},
+      outputSchema: {
+        compositions: external_exports.array(
+          external_exports.object({
+            id: external_exports.string(),
+            width: external_exports.number(),
+            height: external_exports.number(),
+            fps: external_exports.number(),
+            durationInFrames: external_exports.number(),
+            props: external_exports.string().describe("Compact props summary (name*: type)"),
+            propsSchema: external_exports.record(external_exports.unknown()).optional().describe("Full JSON Schema for inputProps")
+          })
+        ).describe("Available compositions - pass an id to render_composition")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async () => {
@@ -18484,7 +18792,18 @@ function registerListCompositionsTool(server) {
       }
       const all = result.data.compositions;
       const compositions = all.filter((c) => EXPOSED_COMPOSITIONS.includes(c.id));
-      if (!compositions.length) return textResult("No compositions found.");
+      if (!compositions.length) return structuredResult("No compositions found.", { compositions: [] });
+      const structured = {
+        compositions: compositions.map((comp) => ({
+          id: comp.id,
+          width: comp.width,
+          height: comp.height,
+          fps: comp.fps,
+          durationInFrames: comp.durationInFrames,
+          props: summarizeSchema(comp.propsSchema),
+          ...comp.propsSchema ? { propsSchema: comp.propsSchema } : {}
+        }))
+      };
       const lines = [`Available compositions (${compositions.length}):
 `];
       for (const comp of compositions) {
@@ -18494,7 +18813,7 @@ function registerListCompositionsTool(server) {
       }
       lines.push("");
       lines.push("Use clipform_render_composition with a compositionId to render. inputProps are validated strictly against the schema - unknown or missing props fail.");
-      return textResult(lines.join("\n"));
+      return structuredResult(lines.join("\n"), structured);
     }
   );
 }
@@ -18509,6 +18828,11 @@ function registerListAssetsTool(server) {
       inputSchema: {
         type: external_exports.enum(["sfx", "animation", "font", "all"]).default("all").optional().describe("Asset type to list (default: all)")
       },
+      outputSchema: {
+        sfx: external_exports.array(external_exports.object({ name: external_exports.string(), description: external_exports.string().nullable().optional(), path: external_exports.string().optional() })),
+        animations: external_exports.array(external_exports.object({ name: external_exports.string(), description: external_exports.string().nullable().optional(), path: external_exports.string().optional() })),
+        fonts: external_exports.array(external_exports.object({ name: external_exports.string(), weights: external_exports.array(external_exports.union([external_exports.string(), external_exports.number()])).optional() }))
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ type }) => {
@@ -18519,6 +18843,11 @@ function registerListAssetsTool(server) {
       if (!result.ok) return errorResult(result.error);
       const data = result.data;
       const lines = [];
+      const structured = {
+        sfx: (data.sfx ?? []).map((s) => ({ name: s.name, description: s.description ?? null, path: s.path })),
+        animations: (data.animations ?? []).map((a) => ({ name: a.name, description: a.description ?? null, path: a.path })),
+        fonts: (data.fonts ?? []).map((f) => ({ name: f.name, ...Array.isArray(f.weights) ? { weights: f.weights } : {} }))
+      };
       if (data.sfx?.length) {
         lines.push(`## Sound Effects (${data.sfx.length})
 `);
@@ -18543,7 +18872,7 @@ function registerListAssetsTool(server) {
         }
         lines.push("");
       }
-      return textResult(lines.length ? lines.join("\n") : "No assets found.");
+      return structuredResult(lines.length ? lines.join("\n") : "No assets found.", structured);
     }
   );
 }
@@ -18594,6 +18923,12 @@ For multi-question builds, pass wait: false on every render: each call returns a
         background_color: external_exports.string().optional().describe("Background color (default '#000')"),
         wait: external_exports.boolean().optional().default(true).describe("true (default) blocks until the video is ready and returns its URL. false returns a job ID immediately - fire all renders first, then poll clipform_check_render. Use false whenever rendering more than one video.")
       },
+      outputSchema: {
+        status: external_exports.enum(["rendering", "complete"]).describe("'rendering' when wait:false (poll check_render); 'complete' with a public_url when wait:true"),
+        job_id: external_exports.string().optional().describe("Present when status is 'rendering' - pass to check_render"),
+        public_url: external_exports.string().optional().describe("Present when status is 'complete' - attach via upload_node_media (fit_media: true)"),
+        duration_seconds: external_exports.number().optional()
+      },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
     },
     async ({ items, audio_url, background_audio_url, background_audio_volume, duration_seconds, random_effects, transition, style_preset, texture, duotone, background_color, wait }) => {
@@ -18625,30 +18960,52 @@ For multi-question builds, pass wait: false on every render: each call returns a
           if (r.ok) completeJob(job.id, r.data);
           else failJob(job.id, r.error);
         }).catch((err) => failJob(job.id, err instanceof Error ? err.message : String(err)));
-        return textResult(
+        return structuredResult(
           [
             `Render started (${items.length} item${items.length > 1 ? "s" : ""}).`,
             `Job ID: ${job.id}`,
             `Fire any remaining renders now, then poll clipform_check_render. Renders typically take ${RENDER_TIMING.expectedRange}.`
-          ].join("\n")
+          ].join("\n"),
+          { status: "rendering", job_id: job.id }
         );
       }
       const result = await apiCall();
       if (!result.ok) return errorResult(result.error);
       const data = result.data;
-      return textResult(
+      return structuredResult(
         [
           `Video rendered (${items.length} item${items.length > 1 ? "s" : ""}).`,
           `Public URL: ${data.public_url}`,
           data.duration_seconds ? `Duration: ${data.duration_seconds}s` : "",
           `Attach via clipform_upload_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
-        ].filter(Boolean).join("\n")
+        ].filter(Boolean).join("\n"),
+        {
+          status: "complete",
+          ...data.public_url ? { public_url: data.public_url } : {},
+          ...typeof data.duration_seconds === "number" ? { duration_seconds: data.duration_seconds } : {}
+        }
       );
     }
   );
 }
 
 // src/tools/check-render.ts
+function projectJob(id, job) {
+  if (!job) return { job_id: id, status: "not_found" };
+  if (job.status === "rendering") {
+    return { job_id: id, status: "rendering", elapsed_seconds: Math.round((Date.now() - job.createdAt) / 1e3) };
+  }
+  if (job.status === "failed") {
+    return { job_id: id, status: "failed", ...job.error ? { error: job.error } : {} };
+  }
+  const data = job.result;
+  return {
+    job_id: id,
+    status: "complete",
+    ...data?.public_url ? { public_url: data.public_url } : {},
+    ...typeof data?.duration_seconds === "number" ? { duration_seconds: data.duration_seconds } : {}
+  };
+}
 var LOST_JOB_RECOVERY = [
   `Jobs expire after 30 minutes and are lost if the server restarts - the render itself may still have completed.`,
   `To recover, re-run the original render call with identical arguments:`,
@@ -18685,6 +19042,18 @@ Pass job_ids to check a whole batch in ONE call - one line of status per job. Pa
         job_id: external_exports.string().uuid().optional().describe("A single job ID returned by the render tool"),
         job_ids: external_exports.array(external_exports.string().uuid()).min(1).max(20).optional().describe("Multiple job IDs - check the whole batch in one call instead of one call per job")
       },
+      outputSchema: {
+        jobs: external_exports.array(
+          external_exports.object({
+            job_id: external_exports.string(),
+            status: external_exports.enum(["rendering", "complete", "failed", "not_found"]),
+            public_url: external_exports.string().optional(),
+            duration_seconds: external_exports.number().optional(),
+            elapsed_seconds: external_exports.number().optional(),
+            error: external_exports.string().optional()
+          })
+        ).describe("One entry per queried job; attach completed public_urls via upload_node_media")
+      },
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
     },
     async ({ job_id, job_ids }) => {
@@ -18700,38 +19069,41 @@ Pass job_ids to check a whole batch in ONE call - one line of status per job. Pa
         }
         if (job.status === "rendering") {
           const elapsed = Math.round((Date.now() - job.createdAt) / 1e3);
-          return textResult(
+          return structuredResult(
             [
               `Status: rendering (${elapsed}s elapsed)`,
               `Tool: ${job.tool}`,
               ``,
               `Still in progress. Check again in ${RENDER_TIMING.pollDelay}.`
-            ].join("\n")
+            ].join("\n"),
+            { jobs: [projectJob(ids[0], job)] }
           );
         }
         if (job.status === "failed") {
           return errorResult(`Render failed: ${job.error}`);
         }
         const data = job.result;
-        return textResult(
+        return structuredResult(
           [
             `Render complete.`,
             ...data.public_url ? [`Public URL: ${data.public_url}`] : [],
             ...data.duration_seconds ? [`Duration: ${data.duration_seconds}s`] : [],
             `Attach via clipform_upload_node_media with fit_media: true (composed 9:16 frame - contain, never crop).`
-          ].join("\n")
+          ].join("\n"),
+          { jobs: [projectJob(ids[0], job)] }
         );
       }
       const results = ids.map((id) => describeJob(id, getJob(id)));
       const pending = results.filter((r) => !r.done).length;
       const lost = results.some((r) => r.line.includes("NOT FOUND"));
-      return textResult(
+      return structuredResult(
         [
           `Render batch: ${results.length - pending}/${results.length} finished${pending ? ` - check again in ${RENDER_TIMING.pollDelay}` : ""}.`,
           ...results.map((r) => r.line),
           ...pending === 0 ? [``, `Attach completed renders via clipform_upload_node_media with fit_media: true (composed 9:16 frames - contain, never crop).`] : [],
           ...lost ? [``, LOST_JOB_RECOVERY] : []
-        ].join("\n")
+        ].join("\n"),
+        { jobs: ids.map((id) => projectJob(id, getJob(id))) }
       );
     }
   );
@@ -19047,4 +19419,4 @@ export {
   JSONRPCMessageSchema,
   createServer
 };
-//# sourceMappingURL=chunk-KP64A2KW.js.map
+//# sourceMappingURL=chunk-3MTEM3VC.js.map