mcp-youtube-intelligence 0.2.5 → 0.2.7

package/README.md

@@ -19,7 +19,7 @@ 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**
 
@@ -33,6 +33,16 @@ You need API keys for three services:
 npm install -g mcp-youtube-intelligence
 ```
 
+## CLI flags
+
+```bash
+mcp-youtube-intelligence --version   # or -v — print the installed version and exit
+mcp-youtube-intelligence --help      # or -h — print usage and exit
+```
+
+Running the command with no flags starts the MCP server itself (stdio transport) — this is what
+an MCP client config invokes; it's not meant to be run bare in a terminal for interactive use.
+
 ## Usage
 
 Add to your Claude Desktop / MCP client config:
@@ -69,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 |
+| `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 |
+| `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
 // ---------------------------------------------------------------------------
@@ -97,6 +98,9 @@ export function getGeminiApiKey() {
 // ---------------------------------------------------------------------------
 export function parseChannelInput(input) {
     const trimmed = input.trim();
+    if (!trimmed) {
+        throw new Error("channel_url must not be empty.");
+    }
     // Bare @handle — e.g. @fireship or @web.dev (periods allowed in handles)
     if (/^@[\w.-]+$/.test(trimmed))
         return { type: "handle", value: trimmed };
@@ -408,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;
@@ -472,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
@@ -552,6 +604,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}`);
@@ -585,20 +645,24 @@ export async function analyzeChannel(channelInput, maxVideos) {
     let topics_structured = [];
     let geminiUsed = false;
     let geminiConfigured = false;
+    let geminiKey;
+    let geminiFailure = "";
     try {
-        const geminiKey = getGeminiApiKey();
+        geminiKey = getGeminiApiKey();
         geminiConfigured = true;
         topics_structured = await extractTopicsWithLLM(transcriptItems, geminiKey);
         geminiUsed = true;
     }
     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 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 API error — check logs for details).`
+            ? `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,

package/build/cli.js

@@ -0,0 +1,30 @@
+/**
+ * Pure argv → output-text mapping for the --version/--help flags, split out of
+ * index.ts so it can be unit tested without importing index.ts itself — that
+ * module connects a stdio MCP transport as a top-level side effect on import,
+ * which would hang a test runner.
+ */
+const HELP_TEXT = (version) => `mcp-youtube-intelligence v${version} — MCP server for YouTube channel intelligence
+
+Usage:
+  mcp-youtube-intelligence [options]
+
+Options:
+  --help, -h      Show this help message
+  --version, -v   Print the installed version
+
+Tools provided:
+  analyze_channel   Extract transcripts, topics, and competitive signals from a YouTube channel`;
+/**
+ * Returns the text to print for --version/-v or --help/-h, or null if argv
+ * contains neither (the normal MCP-server-startup path). --version/-v takes
+ * precedence when both are present.
+ */
+export function getCliOutput(argv, version) {
+    if (argv.includes("--version") || argv.includes("-v"))
+        return version;
+    if (argv.includes("--help") || argv.includes("-h"))
+        return HELP_TEXT(version);
+    return null;
+}
+//# sourceMappingURL=cli.js.map

package/build/index.js

@@ -11,24 +11,12 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { analyzeChannel } from "./analyze_channel.js";
+import { getCliOutput } from "./cli.js";
 const require = createRequire(import.meta.url);
 const { version: packageVersion } = require("../package.json");
-if (process.argv.includes("--version") || process.argv.includes("-v")) {
-    console.log(packageVersion);
-    process.exit(0);
-}
-if (process.argv.includes("--help") || process.argv.includes("-h")) {
-    console.log(`mcp-youtube-intelligence v${packageVersion} — MCP server for YouTube channel intelligence
-
-Usage:
-  mcp-youtube-intelligence [options]
-
-Options:
-  --help, -h      Show this help message
-  --version, -v   Print the installed version
-
-Tools provided:
-  analyze_channel   Extract transcripts, topics, and competitive signals from a YouTube channel`);
+const cliOutput = getCliOutput(process.argv, packageVersion);
+if (cliOutput !== null) {
+    console.log(cliOutput);
     process.exit(0);
 }
 const server = new McpServer({
@@ -37,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), 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.",
     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.5",
+  "version": "0.2.7",
   "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",