@clipform/mcp-server 1.10.0 → 1.11.0

package/README.md

@@ -23,7 +23,7 @@ Use this for stdio-based MCP clients. Pass your API key to authenticate with you
 **Claude Code:**
 
 ```bash
-claude mcp add clipform -e CLIPFORM_API_KEY=cf_live_xxx -- npx -y @clipform/mcp-server
+claude mcp add clipform -e CLIPFORM_API_KEY=cf_xxx -- npx -y @clipform/mcp-server
 ```
 
 **Claude Desktop / Cursor / Windsurf / OpenClaw** - add to your MCP config:
@@ -35,7 +35,7 @@ claude mcp add clipform -e CLIPFORM_API_KEY=cf_live_xxx -- npx -y @clipform/mcp-
       "command": "npx",
       "args": ["-y", "@clipform/mcp-server"],
       "env": {
-        "CLIPFORM_API_KEY": "cf_live_xxx"
+        "CLIPFORM_API_KEY": "cf_xxx"
       }
     }
   }
@@ -44,7 +44,7 @@ claude mcp add clipform -e CLIPFORM_API_KEY=cf_live_xxx -- npx -y @clipform/mcp-
 
 Generate an API key in your Clipform dashboard under **Settings > API Keys**.
 
-You can also pass the key as a CLI flag: `npx -y @clipform/mcp-server --api-key=cf_live_xxx`
+You can also pass the key as a CLI flag: `npx -y @clipform/mcp-server --api-key=cf_xxx`
 
 **Anonymous mode** (no API key): Forms go into a shared workspace with the free-tier 3-node limit. You'll get a claim URL to move forms into your account.
 

package/dist/{chunk-NC3CXX2N.js → chunk-MV3ZI5ZT.js}

@@ -22109,7 +22109,6 @@ var CONTACT_FIELDS = [
 var CONTACT_FIELDS_MAP = Object.fromEntries(
   CONTACT_FIELDS.map((f) => [f.id, f])
 );
-var API_KEY_PREFIX = ENV.isProduction ? "cf_live_" : "cf_test_";
 
 // src/lib/schemas.ts
 var ACTIVE_NODE_TYPES = Object.entries(NODE_TYPES).filter(([, def]) => def.is_active && !def.is_system).map(([type]) => type);
@@ -23233,6 +23232,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"),
@@ -23593,17 +23651,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 }
@@ -24334,6 +24391,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",
     {
@@ -24457,6 +24602,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)
@@ -24553,6 +24699,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}`
         }
       ]
@@ -24776,6 +24993,7 @@ function createServer() {
   registerAttachNodeAudioTool(server);
   registerLogGenerationTool(server);
   registerSearchNewsTool(server);
+  registerYouTubeTranscriptTool(server);
   registerGenerateTtsTool(server);
   registerGenerateSlideshowTool(server);
   registerGenerateVideoTool(server);
@@ -24796,4 +25014,4 @@ export {
   setApiKey,
   createServer
 };
-//# sourceMappingURL=chunk-NC3CXX2N.js.map
+//# sourceMappingURL=chunk-MV3ZI5ZT.js.map