@clipform/mcp-server 1.33.0 → 1.35.0

package/README.md

@@ -84,7 +84,7 @@ You can also pass the key as a CLI flag: `npx -y @clipform/mcp-server --api-key=
 
 | Tool | Description |
 |------|-------------|
-| `clipform_render_composition` | Render a video composition to MP4 or PNG (waits, returns URL) |
+| `clipform_render_composition` | Render a video composition to MP4 or PNG - flag reveals, emoji puzzles, grids, timelines, map motion and more. Pass `wait: false` to fire renders in parallel and poll for results |
 | `clipform_generate_tts` | Generate narration audio with word-level captions |
 | `clipform_generate_slideshow` | Create slideshow videos from images + audio (waits, returns URL) |
 | `clipform_generate_video` | Generate video from images, clips, or both synced to audio. Pass `wait: false` to fire renders in parallel and poll for results |

package/dist/{chunk-SY7YZPSC.js → chunk-6MLZZSNM.js}

@@ -2,7 +2,7 @@ import {
   WORKFLOW_TYPES,
   getDiscoveryParams,
   getSessionContextWithAuth
-} from "./chunk-KWEBCAPF.js";
+} from "./chunk-BYJMRIB6.js";
 import {
   __export
 } from "./chunk-HCZI2UJ5.js";
@@ -4212,6 +4212,29 @@ Wrong answers should sound right to someone who didn't watch but googled the top
 
 > **Text-only override:** If the user explicitly asked for text-only (no video), skip steps 7-8 (video production and media attachment). Still generate narration in step 6.`;
 }
+function compositionQuizWorkflow(args, sessionContext, authMode = "authenticated") {
+  const topic = args.topic ? ` about "${args.topic}"` : "";
+  const count = args.question_count ?? 5;
+  const discovery = buildDiscovery(getDiscoveryParams("quiz", "composition", authMode === "anonymous" ? "demo" : "full"), args, authMode);
+  return `${sessionContext ? sessionContext + "\n\n" : ""}${discovery}Here's how to build a ${count}-question composition quiz${topic} with Clipform - a guess-and-reveal quiz where each question is a rendered composition (flag sweep, emoji rebus, blurred photo resolving) instead of a stock-image slideshow. Read the attached quiz and composition guides for the mechanic matrix, the clue \u2192 reveal node pattern, and difficulty design.
+
+## Composition Quiz Workflow
+
+1. **Discover what's renderable** - call clipform_list_compositions. Availability varies by session; choose mechanics ONLY from what it returns. Match each question to a mechanic via the composition guide's matrix. Mix 2-3 mechanics across the quiz; for questions with no fitting composition, use the base quiz's Ken Burns pipeline instead.
+2. **Write questions** - difficulty curve as in the base guide. Difficulty = subject obscurity (Japan's flag vs Kiribati's), never clue degradation. ${count} questions \u2248 ${count * 2 + 1} nodes (each question is a clue + reveal pair) - check the plan's node limit.
+3. **Render all clips** with clipform_render_composition, wait: false on EVERY call - fire the full batch (clue clip + reveal clip per question), then collect URLs with clipform_check_render. Chain-state compositions: clue clip animate: true, reveal clip animate: false + answer props.
+4. **Build the whole form in ONE clipform_create_form call** - pass nodes, settings, and tags together; do NOT create an empty form and add nodes one by one:
+   - Settings: show_step_counter: true, disable_back_navigation: true
+   - Per question, a PAIR of nodes:
+     - Clue node (type: "choice"): question as prompt, config { choice: { show_answer_feedback: true }, randomise_options: true }, options with score: 1 on the correct answer and score: 0 on 2-3 wrong ones. Scored options enable correct-answer marking automatically.
+     - Reveal node (type: "button"): the answer in the prompt ("It was Japan!"), config { button_text: "Next one" }
+   - Final end_screen node: show_score: true, icon: "trophy", show_share_button: true, cta_type: "restart", cta_text: a short challenge. NOTE: per-tier messages (score_ranges) are coming soon - write one great message.
+   - tags: format "quiz", genre "trivia", and 2-3 topic words
+5. **Generate narration** with clipform_generate_tts - batch ALL items in one call. The visual does the teasing: set stakes, never describe what's on screen or read the clue aloud. Reveal narration can celebrate.
+6. **Attach media** with clipform_upload_node_media (batch all uploads in one call) - clue clip on each choice node, reveal clip on each button node. Include captions, set show_captions: true.
+7. **Publish** with clipform_update_form
+8. **Log** with clipform_log_generation - record the composition IDs used per question alongside sources and attributions`;
+}
 function interviewWorkflow(args, sessionContext, authMode = "authenticated") {
   const purpose = args.purpose ?? "responses";
   const format = args.response_format ?? "all";
@@ -4222,18 +4245,17 @@ function interviewWorkflow(args, sessionContext, authMode = "authenticated") {
 ## Workflow
 
 1. **Identify the ask** - what do you need from respondents? ${purpose}.
-2. **Create the form** with clipform_create_form:
-   - show_step_counter: true
-   - disable_back_navigation: false
-3. **Add a warm-up question** - something easy: "Tell us your name and role" (type: "open")
-4. **Add core questions** (type: "open") - 2-3 max, one topic per question.${format === "all" ? " Enable text + audio + video responses." : ` Enable ${format} responses.`}
-5. **Add contact collection** (type: "contact") - first name + email minimum${consent ? `
-6. **Add consent** - "I agree that my response may be used in [context]"` : ""}
-7. **Update end screen** - set expectations: "Thanks! We'll be in touch."
-8. **Optional - Rich Media:** Add TTS narration (clipform_generate_tts) with a warm, inviting tone - "We'd love to hear your story..." Video backgrounds (clipform_search_media \u2192 clipform_generate_video) on the intro question can set a professional tone.
-9. **Publish** with clipform_update_form
-10. **Tag the form** - pass tags: one format (quiz/survey/interview/feedback/lead-gen), one genre (trivia/personality/nps/poll/testimonial), and 2-3 topic words
-11. **Log** with clipform_log_generation`;
+2. **Build the whole form in ONE clipform_create_form call** - pass nodes, settings, and tags together; do NOT create an empty form and add nodes one by one:
+   - Settings: show_step_counter: true, disable_back_navigation: false
+   - Warm-up question first (type: "open") - something easy: "Tell us your name and role"
+   - 2-3 core questions (type: "open") - one topic per question.${format === "all" ? " Enable text + audio + video responses." : ` Enable ${format} responses.`}
+   - Contact collection (type: "contact") - first name + email minimum${consent ? `
+   - Consent node - "I agree that my response may be used in [context]"` : ""}
+   - End screen that sets expectations: "Thanks! We'll be in touch."
+   - tags: one format (quiz/survey/interview/feedback/lead-gen), one genre (trivia/personality/nps/poll/testimonial), and 2-3 topic words
+3. **Optional - Rich Media:** Add TTS narration (clipform_generate_tts, batch all questions in one call) with a warm, inviting tone - "We'd love to hear your story..." Video backgrounds (clipform_search_media \u2192 clipform_generate_video) on the intro question can set a professional tone.
+4. **Publish** with clipform_update_form
+5. **Log** with clipform_log_generation`;
 }
 function surveyWorkflow(args, sessionContext, authMode = "authenticated") {
   const topic = args.topic ? ` for ${args.topic}` : "";
@@ -4244,18 +4266,17 @@ function surveyWorkflow(args, sessionContext, authMode = "authenticated") {
 ## Workflow
 
 1. **Define the key metric** - what's the one number you care about? (NPS, satisfaction, likelihood to recommend)
-2. **Create the form** with clipform_create_form:
-   - show_step_counter: true
-   - disable_back_navigation: false
-3. **Add key metric question first** (type: "choice" or "rating") - put it first while attention is highest
-4. **Add one "why?" follow-up** (type: "open") - "What's the main reason for your score?"
-5. **Add 2-3 specific questions** (type: "choice") - only ask what you'll act on${!anonymous ? `
-6. **Contact** - collect name + email for follow-up` : ""}
-7. **Optional - Rich Media:** For a more engaging experience, add TTS narration (clipform_generate_tts) for the intro or key questions, video backgrounds (clipform_search_media \u2192 clipform_generate_video), or background music (clipform_search_music).
-8. **Update end screen** - "Thanks for your feedback!"
-9. **Publish** with clipform_update_form
-10. **Tag the form** - pass tags: one format (quiz/survey/interview/feedback/lead-gen), one genre (trivia/personality/nps/poll/testimonial), and 2-3 topic words
-11. **Log** with clipform_log_generation
+2. **Build the whole form in ONE clipform_create_form call** - pass nodes, settings, and tags together; do NOT create an empty form and add nodes one by one:
+   - Settings: show_step_counter: true, disable_back_navigation: false
+   - Key metric question FIRST (type: "choice" or "rating") - while attention is highest
+   - One "why?" follow-up (type: "open") - "What's the main reason for your score?"
+   - 2-3 specific questions (type: "choice") - only ask what you'll act on${!anonymous ? `
+   - Contact collection (type: "contact") - name + email for follow-up` : ""}
+   - End screen: "Thanks for your feedback!"
+   - tags: one format (quiz/survey/interview/feedback/lead-gen), one genre (trivia/personality/nps/poll/testimonial), and 2-3 topic words
+3. **Optional - Rich Media:** For a more engaging experience, add TTS narration (clipform_generate_tts) for the intro or key questions, video backgrounds (clipform_search_media \u2192 clipform_generate_video), or background music (clipform_search_music).
+4. **Publish** with clipform_update_form
+5. **Log** with clipform_log_generation
 
 ## Key rule: 5 questions max. Every extra question costs completions.`;
 }
@@ -4272,25 +4293,22 @@ function testimonialWorkflow(args, sessionContext, authMode = "authenticated") {
 ## Workflow
 
 1. **Define the story arc** - what transformation or experience do you want to capture?
-2. **Create the form** with clipform_create_form:
-   - show_step_counter: true
-   - disable_back_navigation: false
-3. **Add warm-up question** (type: "open") - "Tell us your name and [role/relationship/context]". Enable video + audio + text responses.
-4. **Add 2-3 storytelling prompts** (type: "open") - follow the before \u2192 during \u2192 after arc. Enable video responses. Example prompts:
-   - "What was your biggest challenge before?"
-   - "What was the experience like working with us?"
-   - "What's different now? What would you tell someone considering it?"
-5. **Add consent node** - "I agree that my response may be used in marketing materials, on the website, and in sales presentations."
-6. **Generate narration** with clipform_generate_tts - batch all prompts in a single call. Warm, appreciative tone - "We'd love to hear your story..." Keep each narration 5-8 seconds.
-7. **Optional: build video** for the intro/warm-up question to set the tone.
-8. **Update end screen** - "Thank you for sharing your story! Your experience will help others."
-   - icon: "party"
-   - No score, no restart CTA
-9. **Publish** with clipform_update_form
-10. **Tag the form** - pass tags: format "testimonial", genre "story", and 2-3 topic words
-11. **Log** with clipform_log_generation
+2. **Build the whole form in ONE clipform_create_form call** - pass nodes, settings, and tags together; do NOT create an empty form and add nodes one by one:
+   - Settings: show_step_counter: true, disable_back_navigation: false
+   - Warm-up question (type: "open") - "Tell us your name and [role/relationship/context]". Enable video + audio + text responses.
+   - 2-3 storytelling prompts (type: "open") - follow the before \u2192 during \u2192 after arc. Enable video responses. Example prompts:
+     - "What was your biggest challenge before?"
+     - "What was the experience like working with us?"
+     - "What's different now? What would you tell someone considering it?"
+   - Consent node - "I agree that my response may be used in marketing materials, on the website, and in sales presentations."
+   - End screen: "Thank you for sharing your story! Your experience will help others." icon: "party", no score, no restart CTA
+   - tags: format "testimonial", genre "story", and 2-3 topic words
+3. **Generate narration** with clipform_generate_tts - batch all prompts in a single call. Warm, appreciative tone - "We'd love to hear your story..." Keep each narration 5-8 seconds.
+4. **Optional: build video** for the intro/warm-up question to set the tone.
+5. **Publish** with clipform_update_form
+6. **Log** with clipform_log_generation
 
-> **Text-only override:** If the user explicitly asked for text-only (no video), skip steps 6-7 (narration and video production).`;
+> **Text-only override:** If the user explicitly asked for text-only (no video), skip steps 3-4 (narration and video production).`;
 }
 function applicationWorkflow(args, sessionContext, authMode = "authenticated") {
   const role = args.role ?? "an application";
@@ -4300,20 +4318,17 @@ function applicationWorkflow(args, sessionContext, authMode = "authenticated") {
 ## Workflow
 
 1. **Define what you're screening for** - what qualifications matter, and what questions reveal fit?
-2. **Create the form** with clipform_create_form:
-   - show_step_counter: true
-   - disable_back_navigation: false
-3. **Add contact collection** (type: "contact") - name, email, phone. Place it first while motivation is high.
-4. **Add 2-3 structured screening questions** (type: "choice") - experience level, availability, relevant qualifications. These help you filter quickly.
-5. **Add 1-2 open response questions** (type: "open") - "Tell us why you're interested" or "Walk us through a relevant experience." Enable video + audio + text responses.
-6. **Optional: add "Anything else?"** (type: "open") - catches things you didn't think to ask.
-7. **Optional - Rich Media:** Add TTS narration (clipform_generate_tts) - professional and welcoming: "Thanks for your interest - let's get to know you." Video backgrounds (clipform_search_media \u2192 clipform_generate_video) on the intro can make the application feel more personal.
-8. **Update end screen** - "Your application has been submitted. We'll review it and get back to you."
-   - icon: "tick"
-   - No score, no restart
-9. **Publish** with clipform_update_form
-10. **Tag the form** - pass tags: format "application", genre "screening", and 2-3 topic words
-11. **Log** with clipform_log_generation`;
+2. **Build the whole form in ONE clipform_create_form call** - pass nodes, settings, and tags together; do NOT create an empty form and add nodes one by one:
+   - Settings: show_step_counter: true, disable_back_navigation: false
+   - Contact collection first (type: "contact") - name, email, phone - while motivation is high
+   - 2-3 structured screening questions (type: "choice") - experience level, availability, relevant qualifications. These help you filter quickly.
+   - 1-2 open response questions (type: "open") - "Tell us why you're interested" or "Walk us through a relevant experience." Enable video + audio + text responses.
+   - Optional "Anything else?" (type: "open") - catches things you didn't think to ask.
+   - End screen: "Your application has been submitted. We'll review it and get back to you." icon: "tick", no score, no restart
+   - tags: format "application", genre "screening", and 2-3 topic words
+3. **Optional - Rich Media:** Add TTS narration (clipform_generate_tts) - professional and welcoming: "Thanks for your interest - let's get to know you." Video backgrounds (clipform_search_media \u2192 clipform_generate_video) on the intro can make the application feel more personal.
+4. **Publish** with clipform_update_form
+5. **Log** with clipform_log_generation`;
 }
 function bookingWorkflow(args, sessionContext, authMode = "authenticated") {
   const eventName = args.event_name ?? "an event";
@@ -4324,19 +4339,15 @@ function bookingWorkflow(args, sessionContext, authMode = "authenticated") {
 ## Workflow
 
 1. **Define the essentials** - what info do you actually need from attendees? Keep the list short.
-2. **Create the form** with clipform_create_form:
-   - show_step_counter: false (it's so short, a counter adds unnecessary UI)
-   - disable_back_navigation: false
+2. **Build the whole form in ONE clipform_create_form call** - pass nodes, settings, and tags together; do NOT create an empty form and add nodes one by one:
+   - Settings: show_step_counter: false (it's so short, a counter adds unnecessary UI), disable_back_navigation: false
+   - Contact collection (type: "contact") - name + email minimum. Add phone only if needed.
+   - 1-3 event-specific questions (type: "choice") - session preferences, dietary requirements, experience level. Only ask what you'll use.
+   - End screen: "You're registered! Here's what to expect." Include event details (date, time, location/link) in the message. icon: "tick", no score, no restart, cta_type: "external_link" with a URL to calendar invite or event page (if available)
+   - tags: format "registration", genre "${eventType}", and 2-3 topic words
 3. **Optional: add welcome video** - a short intro from the host. Generate narration with clipform_generate_tts, then build a video with clipform_search_media + clipform_generate_video.
-4. **Add contact collection** (type: "contact") - name + email minimum. Add phone only if needed.
-5. **Add 1-3 event-specific questions** (type: "choice") - session preferences, dietary requirements, experience level. Only ask what you'll use.
-6. **Update end screen** - "You're registered! Here's what to expect." Include event details (date, time, location/link) in the message.
-   - icon: "tick"
-   - No score, no restart
-   - cta_type: "external_link" with a URL to calendar invite or event page (if available)
-7. **Publish** with clipform_update_form
-8. **Tag the form** - pass tags: format "registration", genre "${eventType}", and 2-3 topic words
-9. **Log** with clipform_log_generation
+4. **Publish** with clipform_update_form
+5. **Log** with clipform_log_generation
 
 ## Key rule: 3-5 fields max. Every extra field costs registrations.`;
 }
@@ -4351,7 +4362,8 @@ var WORKFLOW_BUILDERS = {
 };
 var QUIZ_VARIANT_BUILDERS = {
   "personality": personalityQuizWorkflow,
-  "comprehension": comprehensionQuizWorkflow
+  "comprehension": comprehensionQuizWorkflow,
+  "composition": compositionQuizWorkflow
 };
 async function getWorkflowText(type, args = {}, variant) {
   const { text: sessionContext, authMode } = await getSessionContextWithAuth();
@@ -4539,6 +4551,40 @@ Outcome categories: ${args.categories}` : "";
       };
     }
   );
+  server.registerPrompt(
+    "create-composition-quiz",
+    {
+      title: "Create a Composition Quiz",
+      description: "Build a guess-and-reveal quiz from rendered compositions - flag sweeps, emoji puzzles, blur reveals, odd-one-out grids - instead of stock-image slideshows",
+      argsSchema: {
+        topic: external_exports.string().optional().describe("Quiz topic (e.g. 'world flags', 'movie emoji', '90s music')"),
+        question_count: external_exports.string().optional().default("5").describe("Number of questions (default: 5 - each question is a clue + reveal node pair)")
+      }
+    },
+    async (rawArgs) => {
+      const args = coercePromptArgs(rawArgs);
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `I want to create a composition quiz${args.topic ? ` about "${args.topic}"` : ""}. ${args.question_count ?? 5} questions, guess-and-reveal style.`
+            }
+          },
+          resourceLink("guide-quiz", "clipform://guides/quiz", "Quiz Writing Guide"),
+          resourceLink("guide-quiz-composition", "clipform://guides/quiz/composition", "Composition Quiz Addendum"),
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: await getWorkflowText("quiz", args, "composition")
+            }
+          }
+        ]
+      };
+    }
+  );
   server.registerPrompt(
     "create-funnel",
     {
@@ -4659,4 +4705,4 @@ export {
   getWorkflowText,
   registerPrompts
 };
-//# sourceMappingURL=chunk-SY7YZPSC.js.map
+//# sourceMappingURL=chunk-6MLZZSNM.js.map