@mambalabsdev/mcp-github-organization-signal-scanner 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,142 @@
+# GitHub Organization Signal Scanner MCP Server
+
+[![Smithery](https://smithery.ai/badge/mambabuilt/mcp-github-organization-signal-scanner)](https://smithery.ai/servers/mambabuilt/mcp-github-organization-signal-scanner) [![Glama score](https://glama.ai/mcp/servers/mambalabsdev/mcp-github-organization-signal-scanner/badges/score.svg)](https://glama.ai/mcp/servers/mambalabsdev/mcp-github-organization-signal-scanner) [![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dcom.mambabuilt%252Fmcp-github-organization-signal-scanner%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-github-organization-signal-scanner&limit=1) [![npm version](https://img.shields.io/npm/v/@mambalabsdev/mcp-github-organization-signal-scanner)](https://www.npmjs.com/package/@mambalabsdev/mcp-github-organization-signal-scanner) [![npm downloads](https://img.shields.io/npm/dm/@mambalabsdev/mcp-github-organization-signal-scanner)](https://www.npmjs.com/package/@mambalabsdev/mcp-github-organization-signal-scanner) [![license](https://img.shields.io/github/license/mambalabsdev/mcp-github-organization-signal-scanner)](https://github.com/mambalabsdev/mcp-github-organization-signal-scanner/blob/main/LICENSE) [![mcpservers.org](https://img.shields.io/badge/mcpservers.org-listed-blue)](https://mcpservers.org/servers/mambalabsdev/mcp-github-organization-signal-scanner)
+
+An MCP server that resolves a company domain to its GitHub organization with repo, language and activity signals. It wraps the Mamba Labs GitHub Organization Signal Scanner actor on Apify and returns a Clay-ready flat JSON row to any MCP client.
+
+## What's Inside
+
+- [What it does](#what-it-does)
+- [Quick start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Example prompts](#example-prompts)
+- [Inputs](#inputs)
+- [Output](#output)
+- [Example output](#example-output)
+- [Features](#features)
+- [Full actor documentation](#full-actor-documentation)
+- [Mamba Labs GTM Suite](#mamba-labs-gtm-suite)
+- [License](#license)
+
+## What it does
+
+Give it a company domain and it finds that company's GitHub organization and returns repository count, followers, creation date, top languages, total stars, the most recent push, how many repositories are actively worked on, and whether the company ships a public SDK. One flat row per company, read through GitHub's own documented REST API.
+
+Forks and archived repositories are excluded from the language and star derivations, and the exclusion is counted on the row. A rate limited request reports `not_extractable` and never a zero, because a zero is a number a buyer would filter on. A login that resolves to a personal user account rather than an organization is reported as `identity_mismatch`. It reads organization and repository metadata only: it does not clone repositories, read source, scan for secrets or assess code quality.
+
+All of the scanning runs on Apify. This package is a thin client that calls the actor and hands back the result unchanged.
+
+## Quick start
+
+You need Node.js 18 or newer and an Apify account with an API token.
+
+Add this to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "mamba-github-organization-signal-scanner": {
+      "command": "npx",
+      "args": ["-y", "@mambalabsdev/mcp-github-organization-signal-scanner"],
+      "env": {
+        "APIFY_TOKEN": "your-apify-token"
+      }
+    }
+  }
+}
+```
+
+Get your token at https://console.apify.com/account/integrations, paste it in, and restart Claude Desktop. The `scan_github_organization_signals` tool will be available.
+
+## Prerequisites
+
+- Node.js 18 or newer
+- An Apify account with an API token
+- Optional: your own GitHub personal access token, free to create at github.com/settings/tokens with no scopes at all for public data, if you want to scan more than a handful of companies
+
+## Example prompts
+
+- "Find the GitHub organization for stripe.com and summarize its activity."
+- "Scan the GitHub org `vercel` and tell me its top languages and total stars."
+- "Does figma.com ship a public SDK? Check its GitHub organization."
+- "Scan notion.so's GitHub org, counting a repo as active if it was pushed in the last 30 days."
+
+## Inputs
+
+- `company_domain` (optional): bare company domain, for example `stripe.com`. This is the lookup key and the join key for every other actor in the fleet.
+- `company_name` (optional but strongly recommended): what the identity gate checks a discovered record against, so supplying it is the cheapest way to reduce wrong matches.
+- `github_org` (optional): if you already know the organization login, for example `stripe`, put it here and the tool skips discovery entirely and goes straight to the API, which is faster and spends fewer rate limited requests.
+- `includeRepoDetail` (optional): when true (the default) the organization repositories are read and the language, star, activity and SDK signals are derived from them. Set false to return the organization record only, which is one request instead of several and is friendlier to the unauthenticated rate limit.
+- `includeContributorEstimate` (optional): when true one extra request reads the contributor count of the organization's most starred repository, as a floor on the size of its public engineering surface. False by default, because one extra request per company is real money against a 60 per hour unauthenticated budget.
+- `activeWindowDays` (optional): how recently a repository must have been pushed to count as active. One of `30`, `90`, `180` or `365`, with 90 the default. This changes what active means on the row.
+- `repoPageBudget` (optional): how many pages of 100 repositories to read for a large organization. One of `1`, `2`, `3` or `5`. This is a cost and completeness dial, not a change of answer: the row always reports how many repositories were sampled and whether the sample is complete.
+- `githubToken` (optional): your own GitHub personal access token, free to create with no scopes at all for public data. Without it the tool runs at GitHub's 60 requests per hour, which is enough for a handful of companies and not enough for a list. With it the limit is 5,000 per hour.
+- `skipCache` (optional): when false (the default) a successful lookup is cached for seven days and reused. Set true to force a fresh fetch.
+
+## Output
+
+The tool returns the actor's flat JSON row for the company, with 32 snake_case fields and no nested objects. `github_discovery` says how the organization was found, `github_rejected_candidate` records a candidate the identity gate turned away, `repos_sampled` and `repos_complete` say how much of the organization was read, and `repos_excluded` counts the forks and archived repositories left out. See the Apify Store page for the full output schema.
+
+## Example output
+
+```json
+{
+  "degraded": false,
+  "degradation_reason": null,
+  "company_domain": "stripe.com",
+  "company_name": "Stripe",
+  "github_org": "stripe",
+  "github_url": "https://github.com/stripe",
+  "github_discovery": "homepage_link",
+  "github_rejected_candidate": null,
+  "github_account_type": "Organization",
+  "public_repos": 98,
+  "followers": 3469,
+  "org_created_at": "2011-06-17T15:42:37Z",
+  "org_location": "San Francisco, CA",
+  "top_languages": "TypeScript, Go, Ruby, JavaScript, HTML",
+  "total_stars": 42821,
+  "most_starred_repo": "stripe-node",
+  "most_starred_repo_stars": 4485,
+  "most_recent_push_at": "2026-08-22T18:33:15.000Z",
+  "active_repos_90d": 56,
+  "has_public_sdk": true,
+  "repos_sampled": 98,
+  "repos_complete": true,
+  "repos_excluded": "forks=6, archived=5",
+  "rate_limit_remaining": 57,
+  "coverage": 1,
+  "fetch_status": "ok",
+  "run_date": "2026-08-22T19:23:50.177Z"
+}
+```
+
+## Features
+
+- Resolves a GitHub organization starting from a company domain
+- Repository count, stars, followers and top languages
+- Recent push activity and repositories active in a window you choose
+- Public SDK detection, a direct developer tooling signal
+- Runs keyless, with your own GitHub token available for scale
+- Rejected candidates recorded in `github_rejected_candidate`
+- 32 flat snake_case fields, one row per company
+
+## Full actor documentation
+
+This server is a thin client and holds no scanning logic. For the complete input and output reference, pricing, and run history, see the Apify Store page:
+
+https://apify.com/mambalabs/github-organization-signal-scanner
+
+---
+
+## Mamba Labs GTM Suite
+
+This server is one of the Mamba Labs GTM Suite MCP servers. Every actor in the suite takes a domain or a company and returns one flat row, so they stack in the same Clay table without reshaping anything. The actor behind this server is the GitHub Organization Signal Scanner, immutable Apify actor ID `ahF8RRpv5mzPao5CN`.
+
+> Built by [Mamba Labs](https://github.com/mambalabsdev) | [npm](https://www.npmjs.com/org/mambalabsdev) | [Apify Store](https://apify.com/mambalabs)
+
+## License
+
+MIT
+
+Built by Mamba Labs. https://apify.com/mambalabs

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,46 @@ 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;
+// memory=512 matches the actor's declared defaultRunOptions.memoryMbytes and
+// is pinned so the run starts at the size the actor asks for: `apify-actor-start`
+// bills once per GB with a minimum of one. Keep this in step with the actor.
+const ACTOR_RUN_MEMORY_MBYTES = 512;
+// 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;
+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). The /v2/acts/{id} endpoint accepts it directly,
+// so a Store rename never breaks these calls.
+//
+// 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 whatever
+// the timeout parameter says, so a long run reads as a timeout even though the
+// actor goes on to finish. Starting the run, polling it to a terminal status and
+// then reading the dataset is the only way to wait 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 instead of reporting none.
 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=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
-    // 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 +74,107 @@ 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=${ACTOR_RUN_MEMORY_MBYTES}`, { 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. Surfacing it here is what keeps a crashed run from reading
+    // as "no results found".
+    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.
+    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({
@@ -115,22 +204,22 @@ server.registerTool("scan_github_organization_signals", {
             .describe("Optional. If you already know the organization login, for example \"stripe\", put it here and the actor skips discovery entirely and goes straight to the API, which is faster and spends fewer of your rate limited requests."),
         includeRepoDetail: z.boolean()
             .optional()
-            .describe("When \"true\" (default) the organization repositories are read and the language, star, activity and SDK signals are derived from them. Set \"false\" to return the organization record only, which is one request instead of several and is much friendlier to the unauthenticated rate limit. Sent as a string for Clay compatibility."),
+            .describe("When true (default) the organization repositories are read and the language, star, activity and SDK signals are derived from them. Set false to return the organization record only, which is one request instead of several and is much friendlier to the unauthenticated rate limit."),
         includeContributorEstimate: z.boolean()
             .optional()
-            .describe("When \"true\" the actor spends one extra request to read the contributor count of the organization most starred repository, as a floor on the size of its public engineering surface. Default \"false\", because one extra request per company is real money against a 60 per hour unauthenticated budget. Sent as a string for Clay compatibility."),
+            .describe("When true the actor spends one extra request to read the contributor count of the organization most starred repository, as a floor on the size of its public engineering surface. Default false, because one extra request per company is real money against a 60 per hour unauthenticated budget."),
         activeWindowDays: z.enum(["30", "90", "180", "365"])
             .optional()
-            .describe("How recently a repository must have been pushed to count as active. 90 days by default. This changes what \"active\" means on the row, so pick the window your own definition of an engaged engineering team uses. Sent as a string for Clay compatibility."),
+            .describe("How recently a repository must have been pushed to count as active. 90 days by default. This changes what \"active\" means on the row, so pick the window your own definition of an engaged engineering team uses."),
         repoPageBudget: z.enum(["1", "2", "3", "5"])
             .optional()
-            .describe("How many pages of 100 repositories to read for a large organization. This is a cost and completeness dial, not a change of answer: the row always reports how many repositories were actually sampled and whether the sample is complete. Sent as a string for Clay compatibility."),
+            .describe("How many pages of 100 repositories to read for a large organization. This is a cost and completeness dial, not a change of answer: the row always reports how many repositories were actually sampled and whether the sample is complete."),
         githubToken: z.string()
             .optional()
-            .describe("YOUR OWN GitHub personal access token, free to create at github.com/settings/tokens with no scopes at all for public data. OPTIONAL: without it the actor runs at GitHub 60 requests per hour, which is enough for a handful of companies and not enough for a list. With it the limit is 5,000 per hour. It is marked secret, so the value never renders on this page."),
+            .describe("YOUR OWN GitHub personal access token, free to create at github.com/settings/tokens with no scopes at all for public data. OPTIONAL: without it the actor runs at GitHub 60 requests per hour, which is enough for a handful of companies and not enough for a list. With it the limit is 5,000 per hour. A token passed here travels in the tool call and stays in the chat transcript, so prefer setting GITHUB_TOKEN in this server's environment: when this argument is omitted the server sends that variable instead."),
         skipCache: z.boolean()
             .optional()
-            .describe("When \"false\" (default) a successful lookup is cached for seven days and reused, which costs you nothing on a repeated run. Set \"true\" to force a fresh fetch. Sent as a string for Clay compatibility."),
+            .describe("When false (default) a successful lookup is cached for seven days and reused, which costs you nothing on a repeated run. Set true to force a fresh fetch."),
     },
 }, async ({ company_domain, company_name, github_org, includeRepoDetail, includeContributorEstimate, activeWindowDays, repoPageBudget, githubToken, skipCache }) => {
     return runActor("ahF8RRpv5mzPao5CN", "GitHub Organization Signal Scanner", compact({
@@ -141,7 +230,7 @@ server.registerTool("scan_github_organization_signals", {
         includeContributorEstimate: boolToString(includeContributorEstimate),
         activeWindowDays,
         repoPageBudget,
-        githubToken,
+        githubToken: githubToken ?? process.env.GITHUB_TOKEN,
         skipCache: boolToString(skipCache),
     }));
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mambalabsdev/mcp-github-organization-signal-scanner",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "MCP server for the Mamba Labs GitHub Organization Signal Scanner actor on Apify. Resolve a company domain to its GitHub organization with repo, language and activity signals.",
   "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": [
@@ -38,11 +39,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-github-organization-signal-scanner"
 }