mcp-youtube-intelligence 0.2.4 → 0.2.6

package/README.md

@@ -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:

package/build/analyze_channel.js

@@ -97,6 +97,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 };
@@ -261,10 +264,10 @@ export async function runApifyTranscriptScraper(videoUrls, token) {
     if (runResp === undefined) {
         runResp = await startRun();
     }
-    else if (!runResp.ok && runResp.status >= 500) {
-        // Retry once on a transient 5xx — the same one-shot tolerance given above to a
-        // thrown network error; a 503 here previously failed the whole tool call
-        // immediately instead of getting that same retry.
+    else if (!runResp.ok && (runResp.status >= 500 || runResp.status === 429)) {
+        // Retry once on a transient 5xx, or a 429 — Apify returns 429 when the account's
+        // concurrent-actor-run limit is hit, which clears within seconds, unlike a bad
+        // token or malformed request. Same tolerance already given to Gemini below.
         runResp = await startRun();
     }
     if (!runResp.ok) {
@@ -289,11 +292,13 @@ export async function runApifyTranscriptScraper(videoUrls, token) {
             continue;
         }
         if (!statusResp.ok) {
-            // 4xx = permanent error (invalid run ID, bad token) — fail fast instead of polling to timeout
-            if (statusResp.status >= 400 && statusResp.status < 500) {
+            // Most 4xx are permanent (invalid run ID, bad token) — fail fast instead of
+            // polling to timeout. 429 is the exception: Apify's own rate limit, which the
+            // next scheduled poll (APIFY_POLL_INTERVAL_MS later) already backs off past.
+            if (statusResp.status >= 400 && statusResp.status < 500 && statusResp.status !== 429) {
                 throw new Error(`Apify poll error ${statusResp.status} for run ${runId}: ${await statusResp.text()}`);
             }
-            continue; // 5xx or network transient — keep polling
+            continue; // 5xx, 429, or network transient — keep polling
         }
         let statusBody;
         try {
@@ -329,7 +334,7 @@ export async function runApifyTranscriptScraper(videoUrls, token) {
     if (itemsResp === undefined) {
         itemsResp = await fetchItems();
     }
-    else if (!itemsResp.ok && itemsResp.status >= 500) {
+    else if (!itemsResp.ok && (itemsResp.status >= 500 || itemsResp.status === 429)) {
         itemsResp = await fetchItems();
     }
     if (!itemsResp.ok)
@@ -488,7 +493,12 @@ ${truncated}`;
                 parsed = JSON.parse(text);
             }
             catch {
-                console.warn(`[analyze_channel] Gemini returned unparseable JSON for video ${videoId}, skipping`);
+                // 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({
@@ -505,9 +515,9 @@ ${truncated}`;
             console.warn(`[analyze_channel] Gemini request failed for video ${videoId}, skipping: ${lastRequestError}`);
         }
     }
-    // Every attempted video failed at the HTTP level — surface it as a total
-    // failure so analyzeChannel's note reports a Gemini outage instead of
-    // silently claiming success with zero structured topics.
+    // Every attempted video failed, whether at the HTTP level or via unparseable
+    // JSON — surface it as a total failure so analyzeChannel's note reports a
+    // Gemini outage instead of silently claiming success with zero structured topics.
     if (attempted > 0 && results.length === 0 && lastRequestError) {
         throw new Error(lastRequestError);
     }

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,19 +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("--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
-
-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({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-youtube-intelligence",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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",