mcp-youtube-intelligence 0.2.7 → 0.2.8

package/README.md

@@ -25,7 +25,7 @@ You need API keys for three services:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `ANALYZE_CHANNEL_OUTPUT_DIR` | `./output/` | Directory where per-channel JSON analysis artifacts are written |
+| `ANALYZE_CHANNEL_OUTPUT_DIR` | `./output/` | Directory where per-channel JSON analysis artifacts are written. The default is relative to the server's working directory, which your MCP client chooses (some start servers in `/`, where the write is denied). Set an absolute path to be sure: when the write fails the analysis still succeeds, but the result has no `output_path` and the reason goes only to stderr |
 
 ## Installation
 
@@ -88,9 +88,9 @@ Returns a JSON object:
 | `sample_video_ids` | The most recent uploads that were analyzed |
 | `videos_analyzed` | How many videos were fetched from the channel's uploads playlist |
 | `transcripts_available` | How many of those came back with caption content |
-| `topics` | Up to 20 top keywords by frequency across all transcripts. Always computed |
+| `topics` | Up to 20 top keywords by frequency across all transcripts. Always computed. Counts plain English words only: a word with an accented or non-Latin letter is skipped, so a transcript in another language gives few or no keywords here (`topics_structured` still works for it when Gemini is configured) |
 | `topics_structured` | Per video: `theme`, `entities[]`, `tags[]` from Gemini. Empty when Gemini is not configured or fails. Only the first 1,000 words of each transcript are sent, and a video Gemini blocks or returns nothing usable for is left out |
-| `note` | Which analysis mode ran. When Gemini was configured but failed, it also says why |
+| `note` | Which analysis mode ran. When Gemini was configured but failed, or when none of the videos returned a transcript (so there was nothing to analyze), it also says why |
 | `output_path` | Where the JSON artifact was written. Absent if the write failed |
 
 **Example prompt:** "Analyze the @fireship YouTube channel and tell me what topics they cover most."

package/build/analyze_channel.js

@@ -589,7 +589,12 @@ export function extractTopics(transcriptItems, topN = 20) {
         else if (typeof snippets === "string") {
             text = snippets;
         }
-        const words = text.toLowerCase().match(/\b[a-z]{2,}\b/g) ?? [];
+        // Split into maximal runs of letters, marks, digits and underscores, then keep only the runs
+        // that are plain ASCII words. A `\b[a-z]{2,}\b` match treats every non-ASCII letter as a word
+        // boundary, so "Zürich" came out as the topic "rich" and "dzień" as "dzie". For ASCII text the
+        // two are identical ("gpt4" and "snake_case" are still skipped); a word with an accented or
+        // non-Latin letter is now dropped whole instead of leaving its ASCII fragment behind.
+        const words = (text.toLowerCase().match(/[\p{L}\p{M}\p{N}_]+/gu) ?? []).filter((w) => /^[a-z]{2,}$/.test(w));
         for (const word of words) {
             if ((word.length >= 4 || TECH_TERMS.has(word)) && !STOPWORDS.has(word) && !CONTRACTION_STOPWORDS.has(word)) {
                 freq[word] = (freq[word] ?? 0) + 1;
@@ -647,23 +652,31 @@ export async function analyzeChannel(channelInput, maxVideos) {
     let geminiConfigured = false;
     let geminiKey;
     let geminiFailure = "";
-    try {
-        geminiKey = getGeminiApiKey();
-        geminiConfigured = true;
-        topics_structured = await extractTopicsWithLLM(transcriptItems, geminiKey);
-        geminiUsed = true;
+    // With no transcript text at all there is nothing for Gemini to read, and no key would change
+    // that, so skip the call (and the key lookup) rather than report "0 semantic topics via Gemini"
+    // or tell the user to set GEMINI_API_KEY for a result it could not improve.
+    const nothingToAnalyze = transcriptsAvailable === 0;
+    if (!nothingToAnalyze) {
+        try {
+            geminiKey = getGeminiApiKey();
+            geminiConfigured = true;
+            topics_structured = await extractTopicsWithLLM(transcriptItems, geminiKey);
+            geminiUsed = true;
+        }
+        catch (err) {
+            // Graceful degradation — topics_structured stays empty; topics is the fallback
+            const reason = err instanceof Error ? err.message : String(err);
+            geminiFailure = summarizeFailure(reason, geminiKey);
+            console.warn(`[analyze_channel] Gemini extraction unavailable, using keyword fallback: ${reason}`);
+        }
     }
-    catch (err) {
-        // Graceful degradation — topics_structured stays empty; topics is the fallback
-        const reason = err instanceof Error ? err.message : String(err);
-        geminiFailure = summarizeFailure(reason, geminiKey);
-        console.warn(`[analyze_channel] Gemini extraction unavailable, using keyword fallback: ${reason}`);
-    }
-    const note = geminiUsed
-        ? `Analyzed ${videoIds.length} video(s), ${transcriptsAvailable} with transcripts — ${topics_structured.length} semantic topics (topics_structured) via Gemini, ${topics.length} keyword topics as supplemental.`
-        : geminiConfigured
-            ? `Analyzed ${videoIds.length} video(s), ${transcriptsAvailable} with transcripts — ${topics.length} keyword topics only (Gemini extraction failed — ${geminiFailure}).`
-            : `Analyzed ${videoIds.length} video(s), ${transcriptsAvailable} with transcripts — ${topics.length} keyword topics only (GEMINI_API_KEY not configured). Set GEMINI_API_KEY for richer structured analysis.`;
+    const note = nothingToAnalyze
+        ? `Analyzed ${videoIds.length} video(s), but none returned a transcript (captions disabled or unavailable, or the transcript scraper could not read them), so topics and topics_structured are empty.`
+        : geminiUsed
+            ? `Analyzed ${videoIds.length} video(s), ${transcriptsAvailable} with transcripts — ${topics_structured.length} semantic topics (topics_structured) via Gemini, ${topics.length} keyword topics as supplemental.`
+            : geminiConfigured
+                ? `Analyzed ${videoIds.length} video(s), ${transcriptsAvailable} with transcripts — ${topics.length} keyword topics only (Gemini extraction failed — ${geminiFailure}).`
+                : `Analyzed ${videoIds.length} video(s), ${transcriptsAvailable} with transcripts — ${topics.length} keyword topics only (GEMINI_API_KEY not configured). Set GEMINI_API_KEY for richer structured analysis.`;
     const result = {
         channel_id: channel.channelId,
         channel_title: channel.title,

package/build/index.js

@@ -25,7 +25,7 @@ const server = new McpServer({
 });
 server.registerTool("analyze_channel", {
     title: "Analyze YouTube Channel",
-    description: "Analyze a YouTube channel and return a JSON object with: channel_id, channel_title, channel_url, sample_video_ids[], videos_analyzed (count of videos fetched from playlist), transcripts_available (count with actual caption content), topics[] (top keyword frequencies across all transcripts), topics_structured[] (per-video semantic analysis — each entry has video_id/theme/entities[]/tags[]), note (which analysis mode ran — and, when Gemini was configured but failed, why), and optional output_path (local artifact path). Requires YOUTUBE_API_KEY and APIFY_TOKEN; set GEMINI_API_KEY for topics_structured semantic analysis (falls back to keyword-only when absent). Supported channel inputs: @handle (e.g. @fireship), youtube.com/@handle URL, /channel/UC... URL, bare 24-char UCxxxxxx ID, or legacy /c/ and /user/ URLs.",
+    description: "Analyze a YouTube channel and return a JSON object with: channel_id, channel_title, channel_url, sample_video_ids[], videos_analyzed (count of videos fetched from playlist), transcripts_available (count with actual caption content), topics[] (top keyword frequencies across all transcripts; plain English words only, so a non-English transcript yields few or no keywords — use topics_structured for those), topics_structured[] (per-video semantic analysis — each entry has video_id/theme/entities[]/tags[]), note (which analysis mode ran — and, when Gemini was configured but failed, or no video returned a transcript, why), and optional output_path (local artifact path). Requires YOUTUBE_API_KEY and APIFY_TOKEN; set GEMINI_API_KEY for topics_structured semantic analysis (falls back to keyword-only when absent). Supported channel inputs: @handle (e.g. @fireship), youtube.com/@handle URL, /channel/UC... URL, bare 24-char UCxxxxxx ID, or legacy /c/ and /user/ URLs.",
     inputSchema: {
         channel_url: z.string().describe("YouTube channel URL or @handle (e.g. @fireship, https://www.youtube.com/@fireship, UCxxxxxxx)"),
         max_videos: z.number().int().min(1).max(50).optional().default(5).describe("Number of recent videos to analyze (default 5, max 50)"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-youtube-intelligence",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "MCP server for extracting structured intelligence from YouTube channels and videos — transcripts, topics, competitive signals",
   "mcpName": "io.github.dmitriusan/mcp-youtube-intelligence",
   "main": "build/index.js",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "zod": "^4.0.0"
+    "zod": "^4.6.6"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",