@mambalabsdev/mcp-youtube-channel-transcript-extractor 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # YouTube Channel Stats Extractor MCP Server
 
-[![Smithery](https://smithery.ai/badge/mambabuilt/mcp-youtube-channel-transcript-extractor)](https://smithery.ai/servers/mambabuilt/mcp-youtube-channel-transcript-extractor) [![Glama score](https://glama.ai/mcp/servers/mambalabsdev/mcp-youtube-channel-transcript-extractor/badges/score.svg)](https://glama.ai/mcp/servers/mambalabsdev/mcp-youtube-channel-transcript-extractor) [![npm version](https://img.shields.io/npm/v/@mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://www.npmjs.com/package/@mambalabsdev/mcp-youtube-channel-transcript-extractor) [![npm downloads](https://img.shields.io/npm/dm/@mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://www.npmjs.com/package/@mambalabsdev/mcp-youtube-channel-transcript-extractor) [![license](https://img.shields.io/github/license/mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://github.com/mambalabsdev/mcp-youtube-channel-transcript-extractor/blob/main/LICENSE)
+[![Smithery](https://smithery.ai/badge/mambabuilt/mcp-youtube-channel-transcript-extractor)](https://smithery.ai/servers/mambabuilt/mcp-youtube-channel-transcript-extractor) [![Glama score](https://glama.ai/mcp/servers/mambalabsdev/mcp-youtube-channel-transcript-extractor/badges/score.svg)](https://glama.ai/mcp/servers/mambalabsdev/mcp-youtube-channel-transcript-extractor) [![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dcom.mambabuilt%252Fmcp-youtube-channel-transcript-extractor%26limit%3D1&query=%24.servers%5B0%5D._meta%5B%22io.modelcontextprotocol.registry%2Fofficial%22%5D.status&label=mcp%20registry&color=blue)](https://registry.modelcontextprotocol.io/v0/servers?search=com.mambabuilt/mcp-youtube-channel-transcript-extractor&limit=1) [![npm version](https://img.shields.io/npm/v/@mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://www.npmjs.com/package/@mambalabsdev/mcp-youtube-channel-transcript-extractor) [![npm downloads](https://img.shields.io/npm/dm/@mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://www.npmjs.com/package/@mambalabsdev/mcp-youtube-channel-transcript-extractor) [![license](https://img.shields.io/github/license/mambalabsdev/mcp-youtube-channel-transcript-extractor)](https://github.com/mambalabsdev/mcp-youtube-channel-transcript-extractor/blob/main/LICENSE)
 
 MCP server for the Mamba Labs **YouTube Channel Stats Extractor** actor on Apify.
 

package/build/index.js

@@ -9,7 +9,6 @@ const here = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
 // Distinctive UA so Apify run meta.userAgent marks MCP-originated runs.
 const USER_AGENT = `mambalabs-mcp ${pkg.name}@${pkg.version}`;
-const APIFY_TOKEN = process.env.APIFY_TOKEN;
 // Drop undefined values so optional inputs are not sent to the actor at all.
 function compact(obj) {
     const out = {};
@@ -26,36 +25,49 @@ function compact(obj) {
 function boolToString(v) {
     return v === undefined ? undefined : v ? "true" : "false";
 }
-// actorPath is the actor's IMMUTABLE Apify actor id, not its slug, so a Store
-// rename never breaks these calls.
+// How long the actor run itself is allowed to take, in seconds. One value for
+// every Mamba Labs wrapper, set 2026-10-05: start and poll exists so a long run
+// survives, and a shorter limit would end the long runs it was built for. Past
+// this limit the run ends TIMED-OUT and the caller is told so, with the run id.
+const ACTOR_RUN_TIMEOUT_SECS = 1800;
+// How long this wrapper waits for that run, in milliseconds. The actor's own
+// timeout plus two minutes, so the run's own TIMED-OUT status is what the
+// caller sees rather than the wrapper giving up first and reporting nothing.
+const WRAPPER_WAIT_MS = (ACTOR_RUN_TIMEOUT_SECS + 120) * 1000;
+const POLL_INTERVAL_MS = 3000;
+// memory=1024 matches the actor's declared defaultRunOptions.memoryMbytes.
+// `apify-actor-start` bills once per GB with a minimum of one, so an explicit
+// value keeps the caller from paying for more memory than the actor asks for.
+// Keep this in step with the actor's defaultRunOptions.
+const RUN_QUERY = `timeout=${ACTOR_RUN_TIMEOUT_SECS}&memory=1024`;
+const TERMINAL = new Set(["SUCCEEDED", "FAILED", "TIMED-OUT", "ABORTED", "ABORTING"]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Shared caller. actorPath is the actor's immutable Apify actor ID (a stable key
+// that survives Store renames).
+//
+// START AND POLL, NOT RUN-SYNC. Apify's synchronous endpoints carry a platform
+// ceiling of 300 seconds on the HTTP wait itself and answer 408 past it, so a
+// long run reads as a timeout even though the actor goes on and bills. Starting
+// the run, polling it to a terminal status and then reading the dataset waits
+// as long as the actor needs.
+//
+// The token is read here rather than at module load, so the tool registers
+// unconditionally and a server started without APIFY_TOKEN still advertises its
+// capabilities.
+//
+// The wrapper never reinterprets a row's status field: not_extractable,
+// blocked and not_found are different answers and are passed through unchanged.
 async function runActor(actorPath, actorLabel, input) {
+    const APIFY_TOKEN = process.env.APIFY_TOKEN;
     if (!APIFY_TOKEN) {
         return { isError: true, content: [{ type: "text", text: "APIFY_TOKEN is not set. Create a token at https://console.apify.com/account/integrations and set it as the APIFY_TOKEN environment variable." }] };
     }
-    // memory=1024 is deliberate and matches the actor's declared
-    // defaultRunOptions.memoryMbytes. run-sync-get-dataset-items runs at 2048 MB
-    // unless told otherwise, and `apify-actor-start` bills once per GB with a
-    // minimum of one, so leaving the default in place would charge the caller
-    // more start events per run than the actor asks for. Keep this in step with
-    // the actor's defaultRunOptions.
-    const url = `https://api.apify.com/v2/acts/${actorPath}/run-sync-get-dataset-items?timeout=300&memory=1024`;
-    let response;
-    try {
-        response = await fetch(url, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${APIFY_TOKEN}`,
-                "Content-Type": "application/json",
-                "User-Agent": USER_AGENT,
-            },
-            body: JSON.stringify(input),
-        });
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return { isError: true, content: [{ type: "text", text: `Could not reach the Apify API: ${message}` }] };
-    }
-    if (!response.ok) {
+    const headers = {
+        Authorization: `Bearer ${APIFY_TOKEN}`,
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
+    };
+    const httpError = async (response) => {
         let detail = "";
         try {
             const body = (await response.json());
@@ -65,27 +77,104 @@ async function runActor(actorPath, actorLabel, input) {
         catch {
             detail = "";
         }
-        let message;
         switch (response.status) {
+            case 400:
+                return `The ${actorLabel} run was rejected as invalid input.${detail}`;
             case 401:
-                message = "Invalid Apify token. Check your APIFY_TOKEN environment variable.";
-                break;
+                return "Invalid Apify token. Check your APIFY_TOKEN environment variable.";
             case 402:
-                message = "Insufficient Apify credits. Check your account balance at https://console.apify.com/billing";
-                break;
-            case 408:
-                message = `The ${actorLabel} run timed out after 300 seconds. Try again, or run the actor on Apify directly for longer jobs.`;
-                break;
+                return "Insufficient Apify credits. Check your account balance at https://console.apify.com/billing";
             default:
-                message = `Apify request to ${actorLabel} failed with status ${response.status}.${detail}`;
+                return `Apify request to ${actorLabel} failed with status ${response.status}.${detail}`;
+        }
+    };
+    // 1. Start the run.
+    let started;
+    try {
+        started = await fetch(`https://api.apify.com/v2/acts/${actorPath}/runs?${RUN_QUERY}`, { method: "POST", headers, body: JSON.stringify(input) });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Could not reach the Apify API: ${message}` }] };
+    }
+    if (!started.ok) {
+        return { isError: true, content: [{ type: "text", text: await httpError(started) }] };
+    }
+    let run;
+    try {
+        run = (await started.json()).data ?? {};
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run start returned a response that could not be parsed: ${message}` }] };
+    }
+    const runId = run.id;
+    if (!runId) {
+        return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run start returned no run id, so there is nothing to wait for.` }] };
+    }
+    // 2. Poll to a terminal status.
+    const deadline = Date.now() + WRAPPER_WAIT_MS;
+    let status = run.status ?? "READY";
+    let datasetId = run.defaultDatasetId;
+    while (!TERMINAL.has(status)) {
+        if (Date.now() >= deadline) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `The ${actorLabel} run ${runId} was still ${status} after ${Math.round(WRAPPER_WAIT_MS / 1000)} seconds and this call stopped waiting. The run itself is still on Apify: read it at https://console.apify.com/actors/runs/${runId}` }],
+            };
+        }
+        await sleep(POLL_INTERVAL_MS);
+        let poll;
+        try {
+            poll = await fetch(`https://api.apify.com/v2/actor-runs/${runId}`, { headers });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { isError: true, content: [{ type: "text", text: `Lost contact with the Apify API while waiting for ${actorLabel} run ${runId}: ${message}` }] };
+        }
+        if (!poll.ok) {
+            return { isError: true, content: [{ type: "text", text: await httpError(poll) }] };
         }
-        return { isError: true, content: [{ type: "text", text: message }] };
+        const body = (await poll.json());
+        status = body.data?.status ?? status;
+        datasetId = body.data?.defaultDatasetId ?? datasetId;
+    }
+    // 3. A run that did not succeed is a failure the caller must see, never an
+    // empty success.
+    if (status !== "SUCCEEDED") {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `The ${actorLabel} run did not succeed (run ID: ${runId}, status: ${status}). Read it at https://console.apify.com/actors/runs/${runId}` }],
+        };
+    }
+    if (!datasetId) {
+        return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run ${runId} succeeded but reported no dataset, so there is nothing to return.` }] };
+    }
+    // 4. Read the dataset.
+    let ds;
+    try {
+        ds = await fetch(`https://api.apify.com/v2/datasets/${datasetId}/items?format=json`, { headers });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `Could not read the ${actorLabel} dataset: ${message}` }] };
+    }
+    if (!ds.ok) {
+        return { isError: true, content: [{ type: "text", text: await httpError(ds) }] };
+    }
+    let items;
+    try {
+        items = await ds.json();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run returned a response that could not be parsed: ${message}` }] };
+    }
+    if (!Array.isArray(items)) {
+        const asObj = items;
+        const detail = asObj?.error?.message ? `${asObj.error.message}` : JSON.stringify(items);
+        return { isError: true, content: [{ type: "text", text: `The ${actorLabel} run did not return a dataset. ${detail}` }] };
     }
-    // A 2xx normally carries the dataset array. Pass actor output through
-    // unchanged: the wrapper must never reinterpret a status field, because
-    // not_extractable, blocked and not_found are different answers and collapsing
-    // them is exactly the defect the actor was built to avoid.
-    const items = await response.json();
     return { content: [{ type: "text", text: JSON.stringify(items, null, 2) }] };
 }
 const server = new McpServer({
@@ -95,7 +184,7 @@ const server = new McpServer({
 // YouTube Channel Stats Extractor (immutable actor ID 6hSpD3kd2s2IQ4VSs)
 server.registerTool("get_youtube_channel_stats", {
     title: "Get YouTube Channel Stats",
-    description: "Resolve a company domain, or a YouTube handle, to that company's YouTube channel. Returns the subscriber count, the stable UC channel id, channel name, creation date and description, as one flat Clay ready row. Subscriber counts are rounded by YouTube above roughly a thousand subscribers, on the page and in its official API alike, and the row flags that. Optional transcript pulling is available and is CURRENTLY GATED by YouTube: the caption track list is readable and the caption content endpoint returns an empty body without a proof of origin token, which the row reports as not_extractable rather than as a video having no captions. No API key needed. Read only; requires an APIFY_TOKEN and consumes Apify credits per call.",
+    description: "Resolve a company domain, or a YouTube handle, to that company's YouTube channel. Returns the subscriber count, the stable UC channel id, channel name, creation date and description, as one flat Clay ready row. Subscriber counts are rounded by YouTube above roughly a thousand subscribers, on the page and in its official API alike, and the row flags that. Optional transcript pulling is available and is CURRENTLY GATED by YouTube: the caption track list is readable and the caption content endpoint returns an empty body without a proof of origin token, which the row reports as not_extractable rather than as a video having no captions. A company with no channel reports youtube_status not_found. Read youtube_status before any count. Use it to look up one known company channel per call; it does not search YouTube, list a channel's videos, or return video detail, and the package name mentions transcripts only because transcript pulling is an option. No API key needed. Read only; requires an APIFY_TOKEN and consumes Apify credits per call.",
     annotations: {
         title: "Get YouTube Channel Stats",
         readOnlyHint: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mambalabsdev/mcp-youtube-channel-transcript-extractor",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "MCP server for the Mamba Labs YouTube Channel Stats Extractor actor on Apify. Resolve a company domain or YouTube handle to the channel with subscriber count and channel metadata.",
   "type": "module",
   "bin": {
@@ -14,7 +14,9 @@
   ],
   "scripts": {
     "build": "tsc && chmod +x build/index.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/*.test.js",
+    "sync-fixture": "node scripts/sync-input-schema-fixture.mjs"
   },
   "keywords": [
     "mcp",
@@ -37,12 +39,12 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.23.8"
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@types/node": "^20.14.0",
-    "typescript": "^5.6.0"
+    "@types/node": "^26.4.1",
+    "typescript": "5.9.3"
   },
   "mcpName": "com.mambabuilt/mcp-youtube-channel-transcript-extractor"
 }