@mambalabsdev/mcp-partner-member-directory-extractor 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mamba Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# Partner and Member Directory Extractor MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Smithery](https://smithery.ai/badge/mambabuilt/mcp-partner-member-directory-extractor)](https://smithery.ai/servers/mambabuilt/mcp-partner-member-directory-extractor) [![Glama score](https://glama.ai/mcp/servers/mambalabsdev/mcp-partner-member-directory-extractor/badges/score.svg)](https://glama.ai/mcp/servers/mambalabsdev/mcp-partner-member-directory-extractor) [![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dcom.mambabuilt%252Fmcp-partner-member-directory-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-partner-member-directory-extractor&limit=1) [![npm version](https://img.shields.io/npm/v/@mambalabsdev/mcp-partner-member-directory-extractor)](https://www.npmjs.com/package/@mambalabsdev/mcp-partner-member-directory-extractor) [![npm downloads](https://img.shields.io/npm/dm/@mambalabsdev/mcp-partner-member-directory-extractor)](https://www.npmjs.com/package/@mambalabsdev/mcp-partner-member-directory-extractor) [![license](https://img.shields.io/github/license/mambalabsdev/mcp-partner-member-directory-extractor)](https://github.com/mambalabsdev/mcp-partner-member-directory-extractor/blob/main/LICENSE) [![mcpservers.org](https://img.shields.io/badge/mcpservers.org-listed-blue)](https://mcpservers.org/servers/mambalabsdev/mcp-partner-member-directory-extractor)
+
+An MCP server for the Mamba Labs Partner and Member Directory Extractor actor on Apify. Give it a partner directory or a member list URL. Each listed company comes back as one row with its website, domain, tier, tags, and location.
+
+## What's Inside
+
+- [What it does](#what-it-does)
+- [Quick start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Example prompts](#example-prompts)
+- [Tool](#tool)
+- [Inputs](#inputs)
+- [Pricing](#pricing)
+- [Your keys](#your-keys)
+- [Full actor documentation](#full-actor-documentation)
+- [License](#license)
+
+## What it does
+
+The actor reads three directory families: directories built on PartnerPage (Clay's Solutions Partner Directory and the Zapier partner directory among them), read through PartnerPage's public listing API; the Shopify Partner Directory; and member lists that link to one profile page per member, such as a trade association directory. Each row carries `listing_name`, `company_domain`, `website`, `listing_url`, `tier`, `tags`, `location`, `rating`, `review_count`, `partner_since`, and the `listed_email` and `listed_phone` the directory publishes. robots.txt is checked before every request. A directory that builds its list in the browser returns one free row with `row_status` `unsupported`.
+
+All of the work runs on Apify. This package is a thin client that starts the actor run, waits for it, and hands back the dataset rows.
+
+## Quick start
+
+You need Node.js 18 or newer and an Apify account with an API token.
+
+Add this to your Claude Desktop config (`claude_desktop_config.json`), Cursor, or any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "mamba-partner-member-directory-extractor": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mambalabsdev/mcp-partner-member-directory-extractor"
+      ],
+      "env": {
+        "APIFY_TOKEN": "your-apify-token"
+      }
+    }
+  }
+}
+```
+
+Restart the client. The `extract_directory_companies` tool appears.
+
+## Prerequisites
+
+- Node.js 18 or newer.
+- An Apify API token from [console.apify.com/account/integrations](https://console.apify.com/account/integrations), set as `APIFY_TOKEN`. The server lists its tool without a token; a call needs one.
+
+## Example prompts
+
+- "List every agency in the Clay experts directory with its website and tier."
+- "Pull 100 Shopify partners that do store migrations, with their rating and location."
+- "Turn the IAB UK member directory into a list of company domains."
+
+## Tool
+
+`extract_directory_companies`. One tool. Example arguments:
+
+```json
+{
+  "directory_url": "https://www.clay.com/en/experts",
+  "max_listings": "200"
+}
+```
+
+## Inputs
+
+Every buyer facing input of the actor. Omitted inputs take the actor's own defaults. Numbers and yes or no inputs are sent as text.
+
+| Input | Type | Description |
+|---|---|---|
+| `directory_url` | string | One directory page |
+| `directory_urls` | array | Up to 20 directory pages |
+| `max_listings` | string | Listings per directory, 1 to 5000. Default 100 |
+| `max_pages` | string | Shopify and member lists: listing pages to read. Default 10 |
+| `include_details` | string | PartnerPage: tags, location, and email. Default true |
+| `dedupe_domains` | string | Return a repeated company once. Default true |
+| `max_charge_usd` | string | Optional cost cap for the run |
+
+## Pricing
+
+Pay per event on Apify, billed to your Apify account. Prices in USD.
+
+| Event | Free plan | Bronze | Silver | Gold |
+|---|---|---|---|---|
+| `company-listed`, per company row | $0.004 | $0.0038 | $0.0036 | $0.0034 |
+| `apify-actor-start`, per run start (one per GB of run memory) | $0.0015 | $0.0015 | $0.0015 | $0.0015 |
+
+Skipped repeats, and no listings, robots disallowed, blocked, unsupported, and error rows are free.
+
+## Your keys
+
+The actor needs no key. Proxy traffic adds nothing to your price: Mamba Labs pays the platform costs of the run.
+
+## Full actor documentation
+
+[apify.com/mambalabs/partner-member-directory-extractor](https://apify.com/mambalabs/partner-member-directory-extractor)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported versions
+
+The latest published `1.x` release of
+`@mambalabsdev/mcp-partner-member-directory-extractor` receives security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x     | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a vulnerability
+
+Please do not open a public GitHub issue for security reports.
+
+Email security reports to **labs@mambamindsetgrowth.com** with:
+
+- a description of the issue and its impact,
+- steps to reproduce, and
+- any relevant logs or proof of concept.
+
+We aim to acknowledge reports within 3 business days and to provide a remediation
+timeline after triage. Coordinated disclosure is appreciated.
+
+## Handling of credentials
+
+This server reads an `APIFY_TOKEN` from the environment and uses it only to call
+the Apify API on your behalf. The token is never logged or written to disk by this
+package. Treat your `APIFY_TOKEN` as a secret and rotate it at
+https://console.apify.com/account/integrations if you believe it has been exposed.

package/build/index.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+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}`;
+// Drop undefined values so optional inputs are not sent to the actor.
+function compact(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+// How long the actor run itself is allowed to take, in seconds. The suite's
+// slowest measured run on 2026-09-22 was 152 s on a seven platform search, so
+// 1800 s is roughly twelve times that: headroom for a slow day without letting a
+// hung run bill indefinitely.
+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;
+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." }] };
+    }
+    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());
+            if (body?.error?.message)
+                detail = ` ${body.error.message}`;
+        }
+        catch {
+            detail = "";
+        }
+        switch (response.status) {
+            case 400:
+                return `The ${actorLabel} run was rejected as invalid input.${detail}`;
+            case 401:
+                return "Invalid Apify token. Check your APIFY_TOKEN environment variable.";
+            case 402:
+                return "Insufficient Apify credits. Check your account balance at https://console.apify.com/billing";
+            default:
+                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}`, { 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) }] };
+        }
+        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}` }] };
+    }
+    return { content: [{ type: "text", text: JSON.stringify(items, null, 2) }] };
+}
+const server = new McpServer({
+    name: "mamba-partner-member-directory-extractor",
+    version: pkg.version,
+});
+// Partner and Member Directory Extractor (immutable actor ID ZX0XJPPUvnFJxeC1a). Every buyer facing input of
+// the actor is exposed. Numbers and yes or no inputs are text, as the actor's input schema types them.
+const bool = () => z.enum(["true", "false"]).optional();
+server.registerTool("extract_directory_companies", {
+    title: "Extract companies from a partner or member directory",
+    description: "Turn a vendor partner directory or a trade body member list into one company row per listing. Give directory_url or directory_urls (up to 20). Reads directories built on PartnerPage (for example https://www.clay.com/en/experts or the Zapier partner directory) through PartnerPage's public listing API, the Shopify Partner Directory (any https://www.shopify.com/partners/directory/... page), and member lists that link to one profile page per member. Each row: listing_name, company_domain, website, listing_url, tier, tags, location, rating, review_count, partner_since, and the email and phone the directory itself publishes. robots.txt is checked before every request. A directory that cannot be read (it builds its list in the browser) returns one free row with row_status unsupported. A run that does not succeed is returned as an error with its run ID. Read-only; requires an APIFY_TOKEN; Apify charges per company row.",
+    annotations: {
+        title: "Extract companies from a partner or member directory",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    inputSchema: {
+        directory_url: z.string().optional().describe("One directory page URL."),
+        directory_urls: z.array(z.string()).optional().describe("Up to 20 directory page URLs."),
+        max_listings: z.string().optional().describe("Listings per directory, 1 to 5000. Each company row is billed. Default 100."),
+        max_pages: z.string().optional().describe("Shopify and member list directories: listing pages to read, 1 to 100. Default 10."),
+        include_details: bool().describe("PartnerPage directories: true adds tags, location, and the listed email with one more request per listing. Default true."),
+        dedupe_domains: bool().describe("Return a company listed more than once only once; skipped repeats are free. Default true."),
+        max_charge_usd: z.string().optional().describe("Optional. The run stops before any row that would take its charges over this amount."),
+    },
+}, async (args) => runActor("ZX0XJPPUvnFJxeC1a", "Partner and Member Directory Extractor", compact(args)));
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@mambalabsdev/mcp-partner-member-directory-extractor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "MCP server for Partner and Member Directory Extractor. Turn a vendor partner directory (PartnerPage, Shopify Partner Directory) or a trade body member list into one company row per listing with website, domain, tier, tags, and location. Runs on Apify. Clay-ready output.",
+  "type": "module",
+  "bin": {
+    "mcp-partner-member-directory-extractor": "./build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x build/index.js",
+    "test": "npm run build && node --test test/*.test.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "partner-directory",
+    "member-directory",
+    "lead-generation",
+    "list-building",
+    "b2b",
+    "apify",
+    "clay"
+  ],
+  "author": "Mamba Labs <labs@mambamindsetgrowth.com>",
+  "license": "MIT",
+  "homepage": "https://apify.com/mambalabs/partner-member-directory-extractor",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mambalabsdev/mcp-partner-member-directory-extractor"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "5.9.3"
+  },
+  "mcpName": "com.mambabuilt/mcp-partner-member-directory-extractor"
+}