@mambalabsdev/mcp-meta-brand-presence-mapper 1.0.0 → 1.1.0

package/README.md

@@ -46,12 +46,12 @@ Tool: `map_meta_brand_presence`
 
 | Input | Type | Meaning |
 |---|---|---|
-| `company_domain` | string | Bare company domain, for example shopify.com. Supply this or a handle. With a domain the actor runs full discovery; with a handle it skips straight to |
+| `company_domain` | string | Bare company domain, for example shopify.com. Supply this or a handle. With a domain the actor runs full discovery; with a handle it skips straight to the fetch. |
 | `company_name` | string | Optional. Improves search accuracy and is what the identity gate checks a discovered profile against, so supplying it reduces wrong matches. |
-| `handle` | string | Optional. The Instagram handle with or without the leading @. Supplying it skips Instagram discovery AND gives Threads its handle for free, because Th |
-| `platforms` | array | Which of the three Meta surfaces to map. Default is all three. Dropping Facebook is the common choice: it is the least reliable of the three and it co |
-| `includeFollowerCounts` | boolean | When "true" (default) the profile page is fetched and the counts are extracted. Set "false" to resolve the profile URL only, which is cheaper and need |
-| `skipCache` | boolean | When "false" (default) a successful lookup is cached for seven days and reused. Set "true" to force a fresh fetch. Sent as a string for Clay compatibi |
+| `handle` | string | Optional. The Instagram handle with or without the leading @. Supplying it skips Instagram discovery AND gives Threads its handle for free, because Threads handles are Instagram handles (5 of 5 measured). |
+| `platforms` | array | Which of the three Meta surfaces to map. Default is all three. Dropping Facebook is the common choice: it is the least reliable of the three and it costs a fetch to find that out. |
+| `includeFollowerCounts` | boolean | Default true: the profile page is fetched and the follower counts are extracted. Set false to resolve the profile URL only, which is cheaper and needs no proxy. |
+| `skipCache` | boolean | Default false: a successful lookup is cached for seven days and reused. Set true to force a fresh fetch. |
 
 ## Reading the output
 

package/build/index.js

@@ -19,6 +19,20 @@ function compact(obj) {
     }
     return out;
 }
+// START AND POLL, NOT RUN-SYNC. Apify's synchronous endpoint carries a platform
+// ceiling of 300 seconds on the HTTP wait and answers 408 past it while the run
+// keeps going and keeps billing. Starting the run, polling it to a terminal
+// status, and then reading the dataset waits as long as the actor needs.
+//
+// How long the actor run itself may take, in seconds: long enough for a large
+// batch, short enough that a hung run cannot bill indefinitely.
+const ACTOR_RUN_TIMEOUT_SECS = 1800;
+// How long this wrapper waits: the run's own timeout plus two minutes, so the
+// run's TIMED-OUT status is what the caller sees.
+const WRAPPER_WAIT_MS = (ACTOR_RUN_TIMEOUT_SECS + 120) * 1000;
+const POLL_INTERVAL_MS = Number(process.env.MAMBA_POLL_INTERVAL_MS ?? 3000);
+const TERMINAL = new Set(["SUCCEEDED", "FAILED", "TIMED-OUT", "ABORTED", "ABORTING"]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 // The actor types its switches as strings ("true"/"false") for Clay
 // compatibility, because Clay sends every input as a string and a boolean typed
 // field silently receives "false" and reads it as truthy. The model gets a real
@@ -33,29 +47,17 @@ async function runActor(actorPath, actorLabel, input) {
         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=512 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
+    // defaultRunOptions.memoryMbytes. an unspecified memory can run at 2048
+    // MB, 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=512`;
-    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 +67,105 @@ 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?timeout=${ACTOR_RUN_TIMEOUT_SECS}&memory=512`, { 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}).` }],
+        };
+    }
+    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. Pass actor output through unchanged: the wrapper never
+    // reinterprets a status field.
+    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({
@@ -118,10 +198,10 @@ server.registerTool("map_meta_brand_presence", {
             .describe("Which of the three Meta surfaces to map. Default is all three. Dropping Facebook is the common choice: it is the least reliable of the three and it costs a fetch to find that out."),
         includeFollowerCounts: z.boolean()
             .optional()
-            .describe("When \"true\" (default) the profile page is fetched and the counts are extracted. Set \"false\" to resolve the profile URL only, which is cheaper and needs no proxy. Sent as a string for Clay compatibility."),
+            .describe("Default true: the profile page is fetched and the follower counts are extracted. Set false to resolve the profile URL only, which is cheaper and needs no proxy."),
         skipCache: z.boolean()
             .optional()
-            .describe("When \"false\" (default) a successful lookup is cached for seven days and reused. Set \"true\" to force a fresh fetch. Sent as a string for Clay compatibility."),
+            .describe("Default false: a successful lookup is cached for seven days and reused. Set true to force a fresh fetch."),
     },
 }, async ({ company_domain, company_name, handle, platforms, includeFollowerCounts, skipCache }) => {
     return runActor("HXh65I0JBjPsunbY8", "Instagram Threads Facebook Brand Presence Mapper", compact({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mambalabsdev/mcp-meta-brand-presence-mapper",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for the Mamba Labs Instagram Threads Facebook Brand Presence Mapper actor on Apify. Resolve a company domain to its Instagram, Threads and Facebook accounts with follower and post counts.",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   ],
   "scripts": {
     "build": "tsc && chmod +x build/index.js",
+    "test": "npm run build && node --test test/*.test.js",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -39,11 +40,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.23.8"
+    "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-meta-brand-presence-mapper"
 }