mcp-youtube-intelligence 0.2.6 → 0.2.8

package/README.md

@@ -19,13 +19,13 @@ You need API keys for three services:
 | `APIFY_TOKEN` | [Apify Console](https://console.apify.com/) → Account → Integrations → API token |
 | `GEMINI_API_KEY` | [Google AI Studio](https://aistudio.google.com/) → Get API key |
 
-`GEMINI_API_KEY` is optional — if omitted, the tool falls back to word-frequency topic extraction instead of semantic analysis.
+`GEMINI_API_KEY` is optional — if omitted, the tool falls back to word-frequency topic extraction instead of semantic analysis. The same fallback applies when a configured Gemini call fails (invalid key, exhausted quota, blocked content); the result's `note` says why.
 
 **Optional**
 
 | 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
 
@@ -79,6 +79,20 @@ channel_url: YouTube channel URL or @handle. Accepts:
 max_videos:  Number of recent videos to analyze (default: 5, max: 50)
 ```
 
+Returns a JSON object:
+
+| Field | Meaning |
+|-------|---------|
+| `channel_id`, `channel_title` | The resolved channel |
+| `channel_url` | Your `channel_url` input, echoed back |
+| `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. 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, 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."
 
 ## Development

package/build/analyze_channel.js

@@ -25,6 +25,7 @@ const GEMINI_TRANSCRIPT_WORD_LIMIT = 1000;
 const DEFAULT_OUTPUT_DIR = "./output/";
 const MAX_VIDEOS = 50;
 const FETCH_TIMEOUT_MS = 30_000; // bound every outbound request so a stalled external API can't hang the tool call indefinitely
+const NOTE_CAUSE_MAX_CHARS = 200; // cap on a failure cause quoted in the result's `note`
 // ---------------------------------------------------------------------------
 // Fetch helper
 // ---------------------------------------------------------------------------
@@ -411,6 +412,24 @@ const TECH_TERMS = new Set([
     "ui", "ux", "ci", "cd", "ide", "orm", "jwt", "ssh", "tcp", "dns", "cdn",
     "js", "ts", "tsx", "jsx", "php", "os",
 ]);
+// Google APIs report errors as {"error": {"code", "message", "status", "details": [{"reason"}]}}.
+// Returns the readable message and, when present, the machine-readable reason. A body in any
+// other shape (plain text, an HTML error page from a proxy) comes back trimmed and otherwise
+// untouched.
+function parseGoogleError(body) {
+    try {
+        const error = JSON.parse(body)?.error;
+        if (typeof error?.message === "string" && error.message) {
+            const details = Array.isArray(error.details) ? error.details : [];
+            const reason = details.map((d) => d?.reason).find((r) => typeof r === "string");
+            return { message: error.message, reason };
+        }
+    }
+    catch {
+        // Not JSON — fall through to the raw text.
+    }
+    return { message: body.trim() };
+}
 export async function extractTopicsWithLLM(transcriptItems, geminiApiKey) {
     const results = [];
     let attempted = 0;
@@ -475,38 +494,68 @@ ${truncated}`;
                 }, "Gemini API");
             }
             if (!resp.ok) {
-                const detail = await resp.text();
-                if (resp.status === 401 || resp.status === 403) {
+                const { message, reason } = parseGoogleError(await resp.text());
+                const failure = `Gemini API error ${resp.status}: ${message}`;
+                // Google reports a bad or expired key as HTTP 400 with reason API_KEY_INVALID, not as
+                // 401/403, so the status alone missed the commonest credential failure.
+                const badKey = reason === "API_KEY_INVALID" || /^API key (not valid|expired)/i.test(message);
+                if (resp.status === 401 || resp.status === 403 || badKey) {
                     // Auth failures are invariant across requests using the same key — every
                     // remaining video would fail identically, so stop instead of repeating a
                     // doomed call up to max_videos times.
-                    lastRequestError = `Gemini API error ${resp.status}: ${detail}`;
+                    lastRequestError = failure;
                     console.warn(`[analyze_channel] Gemini authentication failed (${resp.status}), aborting remaining videos: ${lastRequestError}`);
                     break;
                 }
-                throw new Error(`Gemini API error ${resp.status}: ${detail}`);
+                throw new Error(failure);
             }
             const body = await parseJsonResponse(resp, "Gemini API");
-            const text = body.candidates?.[0]?.content?.parts?.[0]?.text ?? "{}";
-            let parsed = {};
+            const candidate = body.candidates?.[0];
+            const text = candidate?.content?.parts?.[0]?.text;
+            // Each of the four checks below counts toward the same "every attempted video
+            // produced nothing usable" total-failure check after the loop as an HTTP-level
+            // failure does: a Gemini that answers 200 with nothing parseable is as much an
+            // outage as one that answers 5xx, and must not be reported as a clean success.
+            if (typeof text !== "string" || !text.trim()) {
+                // A blocked prompt or a stopped generation is still HTTP 200. This used to fall
+                // through a "{}" default and be recorded as a successful, empty analysis.
+                const why = body.promptFeedback?.blockReason ?? candidate?.finishReason;
+                lastRequestError = `Gemini returned no content for video ${videoId}${why ? ` (${why})` : ""}`;
+                console.warn(`[analyze_channel] ${lastRequestError}, skipping`);
+                continue;
+            }
+            let parsed;
             try {
                 parsed = JSON.parse(text);
             }
             catch {
-                // Counts toward the same "every attempted video produced nothing usable"
-                // check below as an HTTP-level failure — an all-malformed-JSON response is
-                // just as much a Gemini outage as an all-5xx one, and previously only the
-                // latter was surfaced as a thrown error instead of a silent empty success.
                 lastRequestError = `Gemini returned unparseable JSON for video ${videoId}`;
                 console.warn(`[analyze_channel] ${lastRequestError}, skipping`);
                 continue;
             }
-            results.push({
+            // Valid JSON is not necessarily an object: `null` used to throw a cryptic
+            // "Cannot read properties of null", and an array or a bare scalar was recorded
+            // as an empty entry.
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                lastRequestError = `Gemini returned an unexpected JSON shape for video ${videoId}`;
+                console.warn(`[analyze_channel] ${lastRequestError}, skipping`);
+                continue;
+            }
+            const fields = parsed;
+            const entry = {
                 video_id: videoId,
-                theme: parsed.theme ?? "",
-                entities: parsed.entities ?? [],
-                tags: parsed.tags ?? [],
-            });
+                theme: fields.theme ?? "",
+                entities: fields.entities ?? [],
+                tags: fields.tags ?? [],
+            };
+            // Partial objects stay valid (only a theme, only tags, ...). One carrying nothing
+            // at all tells the caller nothing and would inflate the "semantic topics" count.
+            if (!entry.theme && !entry.entities.length && !entry.tags.length) {
+                lastRequestError = `Gemini returned no usable topics for video ${videoId}`;
+                console.warn(`[analyze_channel] ${lastRequestError}, skipping`);
+                continue;
+            }
+            results.push(entry);
         }
         catch (err) {
             // Isolate this video's failure so one bad request doesn't discard
@@ -540,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;
@@ -555,6 +609,14 @@ export function extractTopics(transcriptItems, topN = 20) {
 // ---------------------------------------------------------------------------
 // Main: analyzeChannel
 // ---------------------------------------------------------------------------
+// The note is read by the MCP client's model, which cannot see this server's stderr, so a
+// failure cause has to travel in the result itself. Collapse it to one short line, and scrub
+// the API key: it rides in the request URL, and some runtimes echo the URL in network errors.
+function summarizeFailure(message, secret) {
+    const scrubbed = secret ? message.split(secret).join("[redacted]") : message;
+    const oneLine = scrubbed.replace(/\s+/g, " ").trim() || "unknown error";
+    return oneLine.length > NOTE_CAUSE_MAX_CHARS ? `${oneLine.slice(0, NOTE_CAUSE_MAX_CHARS)}…` : oneLine;
+}
 export async function analyzeChannel(channelInput, maxVideos) {
     if (maxVideos < 1)
         throw new Error(`max_videos must be at least 1, got ${maxVideos}`);
@@ -588,21 +650,33 @@ export async function analyzeChannel(channelInput, maxVideos) {
     let topics_structured = [];
     let geminiUsed = false;
     let geminiConfigured = false;
-    try {
-        const geminiKey = getGeminiApiKey();
-        geminiConfigured = true;
-        topics_structured = await extractTopicsWithLLM(transcriptItems, geminiKey);
-        geminiUsed = true;
+    let geminiKey;
+    let geminiFailure = "";
+    // 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
-        console.warn(`[analyze_channel] Gemini extraction unavailable, using keyword fallback: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    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 API error — check logs for details).`
-            : `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 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.6",
+  "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",