@clipform/mcp-server 1.10.1 → 1.12.0

package/dist/{chunk-MWNHJLHD.js → chunk-P6TIRFDL.js}

@@ -22277,7 +22277,9 @@ async function callInternalApi(path, options = {}) {
   const headers = {
     "Content-Type": "application/json"
   };
-  if (INTERNAL_SECRET) {
+  if (_apiKey) {
+    headers["Authorization"] = `Bearer ${_apiKey}`;
+  } else if (INTERNAL_SECRET) {
     headers["Authorization"] = `Bearer ${INTERNAL_SECRET}`;
   }
   const fetchOptions = { method, headers };
@@ -23232,6 +23234,65 @@ If neither native web search nor this tool is available and the topic is post-cu
   );
 }
 
+// src/tools/youtube-transcript.ts
+function registerYouTubeTranscriptTool(server) {
+  server.registerTool(
+    "clipform_youtube_transcript",
+    {
+      title: "Get YouTube Transcript",
+      description: `Extract the transcript, title, and channel info from a YouTube video.
+
+Use this as the first step when creating a comprehension quiz about a YouTube video. Returns the full transcript text plus metadata (title, channel, duration). Feed this into your quiz-writing process to create questions that test whether someone actually watched and understood the video.
+
+WHEN TO USE:
+- User provides a YouTube URL and wants a quiz, summary, or content based on the video
+- You need to understand what a YouTube video covers before creating content about it
+
+DOES NOT WORK FOR:
+- Private or age-restricted videos
+- Videos with captions disabled
+- Non-YouTube URLs`,
+      inputSchema: {
+        url: external_exports.string().url().describe(
+          "YouTube video URL (any format: watch?v=, youtu.be/, shorts/)"
+        ),
+        lang: external_exports.string().optional().default("en").describe(
+          "Transcript language code (default: 'en'). Try 'en' first, omit for auto-detect if English unavailable."
+        ),
+        max_chars: external_exports.number().optional().default(15e3).describe(
+          "Maximum transcript characters to return (default: 15000). Increase for longer videos where full context matters."
+        )
+      },
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    async ({ url, lang, max_chars }) => {
+      const result = await callInternalApi("/internal/youtube-transcript", {
+        body: { url, lang, max_chars }
+      });
+      if (!result.ok) return errorResult(result.error);
+      const data = result.data;
+      const meta = data.metadata;
+      const lines = [
+        `## Video: ${meta.title}`,
+        `Channel: ${meta.author}`,
+        `Duration: ~${Math.round(data.durationSeconds / 60)} minutes`,
+        `Language: ${data.language}`,
+        `Transcript length: ${data.transcript.length} characters`,
+        ``,
+        `## Transcript`,
+        ``,
+        data.transcript
+      ];
+      return textResult(lines.join("\n"));
+    }
+  );
+}
+
 // src/tools/generate-tts.ts
 var TtsItemSchema = external_exports.object({
   text: external_exports.string().min(1).max(5e3).describe("Narration text"),
@@ -23592,17 +23653,16 @@ function registerRenderCompositionTool(server) {
     "clipform_render_composition",
     {
       title: "Render Composition",
-      description: `Render a video composition to MP4, PNG, or GIF.
+      description: `Render a video composition to MP4 or PNG.
 
 Output formats:
-- mp4: Video file (H.264 codec, best for social media)
+- mp4: Video file (H.264 codec, correct BT.709 colors, best for social media)
 - png: Still image (single frame)
-- gif: Animated GIF (looping)
 
 For narrated quiz slideshows, prefer clipform_generate_slideshow which handles the full workflow (focal point detection, audio sync, storage upload). Use this tool for custom compositions like ScorecardQuiz, ShortFormQuiz, or PresenterDirected.`,
       inputSchema: {
         compositionId: external_exports.string().describe("The composition ID (e.g. 'ScorecardQuiz', 'ShortFormQuiz', 'PresenterDirected')"),
-        outputFormat: external_exports.enum(["mp4", "png", "gif"]).default("mp4").describe("Output format (default: mp4)"),
+        outputFormat: external_exports.enum(["mp4", "png"]).default("mp4").describe("Output format (default: mp4)"),
         inputProps: external_exports.record(external_exports.unknown()).optional().describe("Props object matching the composition's expected schema")
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
@@ -24333,6 +24393,94 @@ There are NO correct answers. Each option maps to one or more outcome categories
       };
     }
   );
+  server.registerPrompt(
+    "create-comprehension-quiz",
+    {
+      title: "Create a YouTube Comprehension Quiz",
+      description: "Build a comprehension quiz from a YouTube video - tests whether the viewer actually watched and understood the content"
+    },
+    async () => {
+      const sessionContext = await getSessionContext();
+      return {
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: "I want to create a comprehension quiz based on a YouTube video. What's the best approach?"
+            }
+          },
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: `${sessionContext ? sessionContext + "\n\n" : ""}Here's how to build a comprehension quiz from a YouTube video. Read the quiz guide (clipform://guides/quiz) for general craft, and the comprehension guide (clipform://guides/comprehension-quiz) for video-specific techniques.
+
+## Comprehension Quiz Workflow
+
+1. **Extract the transcript** with clipform_youtube_transcript - pass the YouTube URL. Returns transcript, title, channel, and duration.
+2. **Analyse the content** - identify:
+   - Key claims, facts, or arguments made in the video
+   - Specific details a casual viewer might miss
+   - The video's main thesis or conclusion
+   - Any surprising or counterintuitive points
+3. **Write comprehension questions** - these test whether someone WATCHED the video, not general knowledge:
+   - "According to the video, what is the main reason...?"
+   - "What example does the video use to illustrate...?"
+   - Include 1-2 inference questions: "Based on the video, why does the presenter believe...?"
+   - Avoid questions answerable without watching (e.g., common knowledge about the topic)
+4. **Adapt to the audience** - if specified (e.g., "for a 5-year-old"), simplify language, reduce option count, focus on concrete/visual details rather than abstract arguments
+5. **Create the form** with clipform_create_form:
+   - show_step_counter: true
+   - disable_back_navigation: true
+6. **Add questions** with clipform_add_node (type: "choice"):
+   - config: { choice: { show_answer_feedback: true } }
+   - randomise_options: true in config
+   - score: 1 on correct option, score: 0 on wrong
+   - 3-4 wrong answers per question - make distractors plausible (things someone might guess without watching)
+7. **Generate narration** with clipform_generate_tts - reference the video naturally: "If you watched closely, you'll know this one..." Keep each narration 5-10 seconds.
+8. **Build video** for each question:
+   - clipform_search_media (kind: "image") - 3 images per question
+   - clipform_generate_video - Ken Burns video synced to audio
+9. **Attach media** with clipform_upload_node_media. Include captions, set show_captions: true.
+10. **Update end screen** with clipform_update_node:
+    - show_score: true, icon: "trophy"
+    - show_share_button: true
+    - cta_type: "restart", cta_text: "Rewatch and try again?"
+    - score_ranges with messages that reference the video:
+      \`\`\`json
+      { "min": 0, "max": 2, "title": "Were you even watching?", "message": "Time for a rewatch - this video is worth it." },
+      { "min": 3, "max": 5, "title": "Casual Viewer", "message": "You caught the highlights but missed some details." },
+      { "min": 6, "max": 8, "title": "Focused Student", "message": "You were paying attention - impressive." }
+      \`\`\`
+11. **Publish** with clipform_update_form
+12. **Tag** - tags: ["quiz", "comprehension", "youtube"] + 2-3 topic words from the video
+13. **Log** with clipform_log_generation - include the YouTube URL, video title, and channel as sources
+
+## Question Types for Comprehension
+
+| Type | Example | Tests |
+|------|---------|-------|
+| Detail recall | "What specific number did the presenter mention?" | Active listening |
+| Sequence | "What was discussed BEFORE the section about...?" | Following the structure |
+| Inference | "Based on the video, why does the presenter believe...?" | Understanding arguments |
+| Contrast | "The video compares X and Y. What was the key difference?" | Comprehension depth |
+| Conclusion | "What was the presenter's final point?" | Watched to the end |
+
+Wrong answers should sound right to someone who didn't watch but googled the topic. The quiz should be unfair to non-watchers and fair to watchers.
+
+## Before building, ask
+
+1. What's the YouTube URL?
+2. How many questions? (default: 8)
+3. Who's the audience? (age, knowledge level)
+4. Media style: text only, still images, or slideshow video with narration?`
+            }
+          }
+        ]
+      };
+    }
+  );
   server.registerPrompt(
     "create-funnel",
     {
@@ -24456,6 +24604,7 @@ Each question is a micro variable-reward event - the same dopamine loop that kee
 
 ## Question Design
 
+- **Randomize correct answer position** - never put the correct answer in the same slot for every question. Vary it across A/B/C/D so there's no pattern to guess.
 - **Myth-busters**: "Sushi means raw fish - True or False?" (False - it means seasoned rice)
 - **Sounds fake but true**: counterintuitive correct answers make people rewatch
 - **Common misconceptions**: "Capital of Australia?" (not Sydney - Canberra)
@@ -24466,6 +24615,29 @@ Each question is a micro variable-reward event - the same dopamine loop that kee
 
 For numeric questions (population, speed, weight), scale the real answer by random multipliers (0.3x to 3x) rounded to the same magnitude. Makes wrong answers plausible but clearly different.
 
+## Color Brain Questions (ColorSwatch composition)
+
+Inspired by the Color Brain board game - every answer is identified by its colours. Show flat colour chips, ask "what has these colours?". Use the \`ColorSwatch\` composition for the question card.
+
+**Colour palette constraint:** Swatches are solid flat chips. Only use clearly distinguishable basic colours: red, blue, green, yellow, white, black, orange, purple, pink, brown, grey. No navy vs blue, no teal vs cyan - they look the same as flat chips. The skill is picking subjects where a combo of basic colours is unique enough to identify.
+
+**Question categories:**
+- Flags: "Which country's flag has these colours?" (pair with FlagReveal for answer)
+- Brand logos: red + yellow = McDonald's, red + white = Coca-Cola
+- Sports teams: red + white = Arsenal, red + blue + white = Barcelona
+- Superheroes/characters: red + blue = Spider-Man, yellow + black = Batman
+- Food: red + green = watermelon, yellow + brown = banana
+
+**Difficulty scaling:**
+- Easy: iconic subjects with unique colour combos (Japan flag: red + white)
+- Medium: common subjects but colours shared with others (Italy vs Ireland: both green + white + one more)
+- Hard: obscure subjects or very common colour combos that fit many answers
+
+**Design rules:**
+- 2-4 colours per question works best. 5+ gets messy and hard to distinguish.
+- If two answer options would produce identical swatches, don't use that question.
+- Pair with a reveal composition (FlagReveal, image, or text) for the answer.
+
 ## Narration Style
 
 You're a quiz master, not a question reader. Each question's narration should:
@@ -24552,6 +24724,77 @@ Do NOT say "let's see if you get this right" - there is no right answer.
 
 ${WRITING_PRINCIPLES}
 
+${MEDIA_WORKFLOW}`
+        }
+      ]
+    })
+  );
+  server.registerResource(
+    "guide-comprehension-quiz",
+    "clipform://guides/comprehension-quiz",
+    {
+      description: "Craft knowledge for YouTube comprehension quizzes - extracting questions from transcripts, distractor design, audience adaptation",
+      mimeType: "text/markdown"
+    },
+    async () => ({
+      contents: [
+        {
+          uri: "clipform://guides/comprehension-quiz",
+          mimeType: "text/markdown",
+          text: `# Comprehension Quiz Guide
+
+## How it differs from a trivia quiz
+
+A trivia quiz tests general knowledge. A comprehension quiz tests whether someone watched a specific piece of content. The questions should be **unfair to non-watchers and fair to watchers**.
+
+| | Trivia Quiz | Comprehension Quiz |
+|---|---|---|
+| Source | Research + your knowledge | The video transcript |
+| Questions | General facts | Specific claims from the video |
+| Wrong answers | Common misconceptions | Things you'd guess without watching |
+| Goal | Entertainment + learning | Proof of watching + retention |
+
+## Extracting questions from transcripts
+
+Read the transcript looking for:
+
+1. **Specific numbers or data** - "The presenter says it takes X days to..." (detail recall)
+2. **Causal claims** - "According to the video, this happens because..." (comprehension)
+3. **Examples used** - "What example does the presenter use to explain...?" (attention)
+4. **Sequence of topics** - "What does the presenter discuss right after...?" (structure following)
+5. **The main argument** - "What is the presenter's main point about...?" (thesis comprehension)
+6. **Counterintuitive points** - anything the presenter says is surprising or commonly misunderstood
+
+## Distractor design (wrong answers)
+
+Make wrong answers plausible to someone who **didn't watch**:
+
+- Use correct facts from other sources about the same topic (tests whether they watched THIS video)
+- Include things that sound likely based on the title alone
+- For number questions, use nearby values that seem reasonable
+- Never include obviously joke answers - every option should feel possible
+
+## Audience adaptation
+
+| Audience | Question style | Language | Count |
+|----------|---------------|----------|-------|
+| Young children (5-8) | Concrete details, visual moments | Simple, short sentences | 4-6 |
+| Older children (9-12) | Details + basic inference | Clear, direct | 6-8 |
+| Teens (13-17) | Inference + sequence + argument | Natural, conversational | 6-10 |
+| Adults | Full range including critical analysis | Match the video's register | 6-10 |
+
+For young children: focus on "What did you SEE?" and "Who did what?" rather than abstract arguments.
+
+## Narration style
+
+Reference the video naturally but don't spoil:
+
+- "If you were paying attention during the bit about..."
+- "This is one of those details most people miss..."
+- "The presenter made a really specific claim here..."
+
+${WRITING_PRINCIPLES}
+
 ${MEDIA_WORKFLOW}`
         }
       ]
@@ -24775,6 +25018,7 @@ function createServer() {
   registerAttachNodeAudioTool(server);
   registerLogGenerationTool(server);
   registerSearchNewsTool(server);
+  registerYouTubeTranscriptTool(server);
   registerGenerateTtsTool(server);
   registerGenerateSlideshowTool(server);
   registerGenerateVideoTool(server);
@@ -24795,4 +25039,4 @@ export {
   setApiKey,
   createServer
 };
-//# sourceMappingURL=chunk-MWNHJLHD.js.map
+//# sourceMappingURL=chunk-P6TIRFDL.js.map