@mambalabsdev/mcp-sequencer-event-poller 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,114 @@
-# Temporary Holding Version
+# Sequencer Event Poller 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-sequencer-event-poller)](https://smithery.ai/servers/mambabuilt/mcp-sequencer-event-poller) [![Glama score](https://glama.ai/mcp/servers/mambalabsdev/mcp-sequencer-event-poller/badges/score.svg)](https://glama.ai/mcp/servers/mambalabsdev/mcp-sequencer-event-poller) [![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Dcom.mambabuilt%252Fmcp-sequencer-event-poller%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-sequencer-event-poller&limit=1) [![npm version](https://img.shields.io/npm/v/@mambalabsdev/mcp-sequencer-event-poller)](https://www.npmjs.com/package/@mambalabsdev/mcp-sequencer-event-poller) [![npm downloads](https://img.shields.io/npm/dm/@mambalabsdev/mcp-sequencer-event-poller)](https://www.npmjs.com/package/@mambalabsdev/mcp-sequencer-event-poller) [![license](https://img.shields.io/github/license/mambalabsdev/mcp-sequencer-event-poller)](https://github.com/mambalabsdev/mcp-sequencer-event-poller/blob/main/LICENSE) [![mcpservers.org](https://img.shields.io/badge/mcpservers.org-listed-blue)](https://mcpservers.org/servers/mambalabsdev/mcp-sequencer-event-poller)
+
+An MCP server for the Mamba Labs Sequencer Event Poller actor on Apify. It reads replies, bounces, unsubscribes, meetings booked, interest changes, and LinkedIn replies from your own Instantly, Smartlead, HeyReach, and lemlist accounts, and returns one flat row per event.
+
+## 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
+
+Pick a time window, for example the last 24 hours, and get every event from the sequencers you have keys for in one table: vendor, event type, when it happened, the lead's email, name, and company, the campaign, and the reply text where the vendor returns it. One free run summary row gives counts per vendor and event type and says whether each vendor was read, skipped, or refused the key. With only new events on, a scheduled run returns only events an earlier run has not returned.
+
+The actor only reads. It never creates, edits, pauses, or sends anything in a sequencer, and it never creates a campaign.
+
+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-sequencer-event-poller": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mambalabsdev/mcp-sequencer-event-poller"
+      ],
+      "env": {
+        "APIFY_TOKEN": "your-apify-token",
+        "LEMLIST_API_KEY": "your-lemlist-key"
+      }
+    }
+  }
+}
+```
+
+Restart the client. The `poll_sequencer_events` 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.
+- At least one of your own vendor keys: `INSTANTLY_API_KEY` (API v2, read scope; Instantly API access needs a paid Instantly plan), `SMARTLEAD_API_KEY`, `HEYREACH_API_KEY`, `LEMLIST_API_KEY`. With none set, a call returns one summary row that says no key was given.
+
+## Example prompts
+
+- "Which leads replied in Smartlead or lemlist in the last 24 hours?"
+- "List every bounce and unsubscribe across my sequencers this week."
+- "Who replied on LinkedIn through HeyReach since Monday, and what did they say?"
+
+## Tool
+
+`poll_sequencer_events`. One tool. Example arguments:
+
+```json
+{
+  "since_hours": 24,
+  "event_types": ["reply", "linkedin_reply", "bounce", "meeting_booked"]
+}
+```
+
+## Inputs
+
+Every buyer facing input of the actor except the four vendor keys, which are read from this server's environment, never from tool arguments. Omitted inputs take the actor's own defaults.
+
+| Input | Type | Required | Description |
+|---|---|---|---|
+| `since_hours` | integer | no | Look back this many hours, at most 2160. Default 24. |
+| `since`, `until` | string | no | Optional exact window in UTC. |
+| `event_types` | array | no | Any of reply, linkedin_reply, bounce, unsubscribe, meeting_booked, interested, not_interested, out_of_office, connection_accepted, open, click. |
+| `only_new` | boolean | no | Skip events an earlier run returned. Default true. |
+| `state_key` | string | no | Name for the only new events memory. |
+| `instantly_campaign_ids`, `smartlead_campaign_ids`, `heyreach_campaign_ids`, `lemlist_campaign_ids` | array | no | Read only these campaigns. |
+| `max_pages_per_query` | integer | no | Pages of 100 records per vendor query. Default 20. |
+| `max_events` | integer | no | Event rows per run. Default 5000. |
+| `max_charge_usd` | string | no | 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 |
+|---|---|---|---|---|
+| `event-row`, per sequencer event | $0.008 | $0.0076 | $0.0072 | $0.0068 |
+| `apify-actor-start`, per run start | $0.001 | $0.001 | $0.001 | $0.001 |
+
+The run summary row and already delivered events are free. Mamba Labs pays the platform costs of the run.
+
+## Your keys
+
+The actor stores no key. Each vendor key is your own: this server reads it from its environment and sends it in the run input of that run only. The vendor API calls run on your own vendor account, under that vendor's plan and rate limits.
+
+## Full actor documentation
+
+[apify.com/mambalabs/sequencer-event-poller](https://apify.com/mambalabs/sequencer-event-poller)
+
+## 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-sequencer-event-poller` 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,245 @@
+#!/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. Fleet standard
+// (standing build rule 5, 2026-10-05). A large Instantly backfill is paced at
+// about 3 s per request, so a long window can take several minutes.
+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-sequencer-event-poller",
+    version: pkg.version,
+});
+// Provider keys come from this server's own environment, never from tool
+// arguments, so an agent transcript never carries them. Each is the caller's
+// own key; the actor stores none.
+function keysFromEnv() {
+    const out = {};
+    const k0 = process.env.INSTANTLY_API_KEY?.trim();
+    if (k0)
+        out.instantly_api_key = k0;
+    const k1 = process.env.SMARTLEAD_API_KEY?.trim();
+    if (k1)
+        out.smartlead_api_key = k1;
+    const k2 = process.env.HEYREACH_API_KEY?.trim();
+    if (k2)
+        out.heyreach_api_key = k2;
+    const k3 = process.env.LEMLIST_API_KEY?.trim();
+    if (k3)
+        out.lemlist_api_key = k3;
+    return out;
+}
+// Sequencer Event Poller (immutable actor ID S6s8Rjd61tGdrMRk4). Every buyer facing input of the actor is exposed except the four vendor keys, which come from the environment (see keysFromEnv).
+server.registerTool("poll_sequencer_events", {
+    title: "Poll sequencer events",
+    description: "Read replies, bounces, unsubscribes, meetings booked, interest changes, and LinkedIn replies from your own Instantly, Smartlead, HeyReach, and lemlist accounts for a time window. Returns one flat row per event (vendor, event type, time, lead email and name, company, campaign, reply text where the vendor returns it) plus one free run summary row with counts and the status of each vendor. Vendor keys are read from this server's environment (INSTANTLY_API_KEY, SMARTLEAD_API_KEY, HEYREACH_API_KEY, LEMLIST_API_KEY); vendors with no key are skipped. Read-only: it never creates, edits, pauses, or sends anything in a sequencer. A run that does not succeed is returned as an error with its run ID. Requires an APIFY_TOKEN and is billed per event row.",
+    annotations: {
+        title: "Poll sequencer events",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    inputSchema: {
+        since_hours: z.number().int().min(1).max(2160)
+            .optional()
+            .describe("Read events from this many hours before the run, at most 2160 (90 days). Default 24. Ignored when since is set."),
+        since: z.string()
+            .optional()
+            .describe("Optional start of the window in UTC, for example 2026-10-20T00:00:00Z."),
+        until: z.string()
+            .optional()
+            .describe("Optional end of the window in UTC. Default now."),
+        event_types: z.array(z.enum(["reply", "linkedin_reply", "bounce", "unsubscribe", "meeting_booked", "interested", "not_interested", "out_of_office", "connection_accepted", "open", "click"]))
+            .optional()
+            .describe("Which events to return. Default: reply, linkedin_reply, bounce, unsubscribe, meeting_booked, interested, connection_accepted."),
+        only_new: z.boolean()
+            .optional()
+            .describe("Skip events an earlier run already returned (free). Default true."),
+        state_key: z.string()
+            .optional()
+            .describe("Optional name for the only new events memory, so two schedules keep separate memories."),
+        instantly_campaign_ids: z.array(z.string())
+            .optional()
+            .describe("Read only these Instantly campaigns (UUIDs). Empty: all campaigns."),
+        smartlead_campaign_ids: z.array(z.string())
+            .optional()
+            .describe("Read only these Smartlead campaigns. Empty: all non draft campaigns."),
+        heyreach_campaign_ids: z.array(z.string())
+            .optional()
+            .describe("Read only these HeyReach campaigns (numeric ids). Empty: all campaigns."),
+        lemlist_campaign_ids: z.array(z.string())
+            .optional()
+            .describe("Read only these lemlist campaigns (cam_ ids). Empty: all campaigns."),
+        max_pages_per_query: z.number().int().min(1).max(100)
+            .optional()
+            .describe("Pages of 100 records per vendor query. Default 20."),
+        max_events: z.number().int().min(1).max(50000)
+            .optional()
+            .describe("Event rows per run, oldest first. Default 5000."),
+        max_charge_usd: z.string()
+            .optional()
+            .describe("Optional. The run stops before a charge that would pass this amount."),
+    },
+}, async (args) => runActor("S6s8Rjd61tGdrMRk4", "Sequencer Event Poller", { ...compact(args), ...keysFromEnv() }));
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@mambalabsdev/mcp-sequencer-event-poller",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "MCP server for Sequencer Event Poller. Replies, bounces, unsubscribes, meetings, and LinkedIn replies from your own Instantly, Smartlead, HeyReach, and lemlist accounts, one row per event. Read only. Runs on Apify.",
+  "type": "module",
+  "bin": {
+    "mcp-sequencer-event-poller": "./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",
+    "instantly",
+    "smartlead",
+    "heyreach",
+    "lemlist",
+    "cold-email",
+    "replies",
+    "apify",
+    "clay"
+  ],
+  "author": "Mamba Labs <labs@mambamindsetgrowth.com>",
+  "license": "MIT",
+  "homepage": "https://apify.com/mambalabs/sequencer-event-poller",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mambalabsdev/mcp-sequencer-event-poller"
+  },
+  "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-sequencer-event-poller"
+}