onesignal-mcp 1.0.0 → 1.0.2

package/README.md

@@ -4,10 +4,29 @@ Query the OneSignal API (free tier; use a current v2 Organization API key for ON
 
 ## Tools
 
-- `list_apps` — OneSignal apps.
-- `get_app` — App details by ID.
+- `list_apps` — OneSignal apps the key can send to.
+- `get_app` — One app by id, with platform and player count.
 - `list_notifications` — Recent notifications for an app.
 
 ## Source
 
 [onesignal-mcp](https://github.com/mrfentmen/premium-mcps/tree/main/servers/onesignal-mcp)
+
+<!-- paywall -->
+## Premium tools
+
+These tools need a licence key:
+
+* `sdk_release_timeline`
+* `platform_status`
+
+The tool bodies run on our gateway, not inside this package, so the key is what buys access. Buy one at https://buy.polar.sh/polar_cl_mrO7rS5LZxpqM7oAFFEA10i9121J240U40IIj4JRZO4 and set it in your MCP client config:
+
+```json
+"env": { "MCP_LICENSE_KEY": "polar_..." }
+```
+
+The gateway checks the key against Polar and gives every key 1,000 free premium
+calls a month before per-call billing starts. Every other tool on this server
+stays free.
+<!-- /paywall -->

package/dist/api.d.ts

@@ -5,3 +5,5 @@ export declare function errorMessage(e: unknown): string;
 export declare function listApps(): Promise<string>;
 export declare function getApp(appId: string): Promise<string>;
 export declare function listNotifications(appId: string, limit?: string): Promise<string>;
+/** Which OneSignal SDK people actually install, and how big each one is. */
+export declare function pushSdkPopularity(_args: Record<string, never>): Promise<string>;

package/dist/api.js

@@ -24,7 +24,7 @@ function appHeaders() {
 async function get(path, headers) {
     let res;
     try {
-        res = await fetch(BASE + path, { headers });
+        res = await fetch(BASE + path, { signal: AbortSignal.timeout(30000), headers });
     }
     catch (e) {
         throw new OneSignalError(`Network error: ${e.message}`);
@@ -45,3 +45,57 @@ export function listNotifications(appId, limit) {
     const n = Math.min(Number(limit ?? 10) || 10, 50);
     return get(`/notifications?app_id=${encodeURIComponent(appId)}&limit=${n}`, appHeaders());
 }
+// ---- muxG tools:
+const ONESIGNAL_NPM = "https://registry.npmjs.org";
+const ONESIGNAL_DOWNLOADS = "https://api.npmjs.org/downloads/point/last-week";
+const ONESIGNAL_SDKS = ["onesignal-node", "react-native-onesignal", "onesignal-cordova-plugin"];
+async function onesignalJson(url, accept = "application/json") {
+    const res = await fetch(url, {
+        headers: { "User-Agent": "awesome-mcps/1.0", Accept: accept },
+        signal: AbortSignal.timeout(45000),
+    });
+    if (res.status === 404)
+        throw new OneSignalError(`Not found: ${url.replace(/^https:\/\//, "")}`);
+    if (res.status === 429)
+        throw new OneSignalError("The npm registry is rate limiting this IP. Wait a minute and try again.");
+    if (!res.ok)
+        throw new OneSignalError(`Returned ${res.status} for ${url.replace(/^https:\/\//, "")}`);
+    return (await res.json());
+}
+async function onesignalWeeklyDownloads(pkg) {
+    try {
+        const d = await onesignalJson(`${ONESIGNAL_DOWNLOADS}/${encodeURIComponent(pkg)}`);
+        return typeof d.downloads === "number" ? d.downloads : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Which OneSignal SDK people actually install, and how big each one is. */
+export async function pushSdkPopularity(_args) {
+    const docs = await Promise.all(ONESIGNAL_SDKS.map(async (pkg) => {
+        const [doc, downloads] = await Promise.all([
+            onesignalJson(`${ONESIGNAL_NPM}/${encodeURIComponent(pkg)}`, "application/vnd.npm.install-v1+json"),
+            onesignalWeeklyDownloads(pkg),
+        ]);
+        return { pkg, doc, downloads };
+    }));
+    const rows = docs.map(({ pkg, doc, downloads }) => {
+        const latest = doc["dist-tags"]?.latest;
+        const versions = Object.keys(doc.versions ?? {});
+        const stable = versions.filter((v) => !/-(alpha|beta|rc|next|pre|dev|canary)/.test(v));
+        return { pkg, latest, versions: versions.length, stable: stable.length, downloads, description: doc.description };
+    });
+    const total = rows.reduce((s, r) => s + (r.downloads ?? 0), 0);
+    return [
+        "OneSignal SDK adoption, from the npm registry and the public download counter",
+        ...rows.map((r) => [
+            `${r.pkg} — ${r.latest ?? "no latest tag"}, ${r.versions} version(s) of which ${r.stable} are stable`,
+            r.downloads !== null ? `  weekly downloads: ${r.downloads.toLocaleString("en-US")}${total ? ` (${((r.downloads / total) * 100).toFixed(1)}% of these three)` : ""}` : "  weekly downloads: not reported",
+            r.description ? `  ${r.description.slice(0, 130)}` : "",
+        ].filter(Boolean).join("\n")),
+        "",
+        `Combined weekly downloads across the three SDKs: ${total.toLocaleString("en-US")}`,
+        "Download counts are npm's own, so a package that is also used from a lockfile, a private registry or a vendored copy will undercount. The relative share is the useful signal, not the absolute number.",
+    ].join("\n");
+}

package/dist/gateway.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thin client for the premium gateway.
+ *
+ * The premium tools do not run in this package any more. Their bodies live on
+ * the gateway, which checks a Polar licence key before it does any work, so
+ * deleting anything here buys nothing: the answer only exists behind the gate.
+ *
+ * Set `MCP_LICENSE_KEY` to a Polar licence key. `MCP_GATEWAY_URL` overrides the
+ * endpoint, which is only useful for testing.
+ */
+/** Raised when a premium call cannot be completed. `message` is safe to show. */
+export declare class GatewayError extends Error {
+    readonly refused: boolean;
+    constructor(message: string, refused: boolean);
+}
+export declare function premiumTool(tool: string, args: Record<string, unknown>): Promise<string>;

package/dist/gateway.js

@@ -0,0 +1,85 @@
+/**
+ * Thin client for the premium gateway.
+ *
+ * The premium tools do not run in this package any more. Their bodies live on
+ * the gateway, which checks a Polar licence key before it does any work, so
+ * deleting anything here buys nothing: the answer only exists behind the gate.
+ *
+ * Set `MCP_LICENSE_KEY` to a Polar licence key. `MCP_GATEWAY_URL` overrides the
+ * endpoint, which is only useful for testing.
+ */
+const DEFAULT_GATEWAY_URL = 'https://mcp-gateway.contactae2000.workers.dev/mcp';
+const DEFAULT_TIMEOUT_MS = 25000;
+const USER_AGENT = 'mrfentmen-mcp/1.0';
+/** Raised when a premium call cannot be completed. `message` is safe to show. */
+export class GatewayError extends Error {
+    refused;
+    constructor(message, refused) {
+        super(message);
+        this.refused = refused;
+        this.name = 'GatewayError';
+    }
+}
+export async function premiumTool(tool, args) {
+    const key = (process.env.MCP_LICENSE_KEY ?? '').trim();
+    if (!key) {
+        throw new GatewayError(`"${tool}" is a premium tool and no licence key is set. Set MCP_LICENSE_KEY in your MCP client config.`, true);
+    }
+    const url = (process.env.MCP_GATEWAY_URL ?? DEFAULT_GATEWAY_URL).trim();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                accept: 'application/json',
+                'user-agent': USER_AGENT,
+                authorization: `Bearer ${key}`,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'tools/call',
+                params: { name: tool, arguments: args },
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        throw new GatewayError(`"${tool}" could not reach the licence gateway. Check your connection and try again.`, false);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        throw new GatewayError(`"${tool}" could not reach the licence gateway (HTTP ${response.status}).`, false);
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        throw new GatewayError(`"${tool}" got an unreadable answer from the licence gateway.`, false);
+    }
+    if (body.error) {
+        throw new GatewayError(`"${tool}" was refused by the licence gateway: ${body.error.message ?? 'unknown error'}`, false);
+    }
+    const result = body.result ?? {};
+    const text = (result.content ?? [])
+        .map((part) => part.text ?? '')
+        .join('\n')
+        .trim();
+    if (result.isError) {
+        // The gateway marks a licence refusal structurally, so a missing or rejected
+        // key is told apart from a tool that failed after the gate let it through.
+        if (result.structuredContent?.licenceRefusal) {
+            throw new GatewayError(text || `"${tool}" needs a valid licence key.`, true);
+        }
+        throw new GatewayError(text || `"${tool}" failed on the licence gateway.`, false);
+    }
+    if (!text)
+        throw new GatewayError(`"${tool}" returned no data.`, false);
+    return text;
+}

package/dist/license.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns null when the caller may run the tool, or a short message telling
+ * them how to get a key.
+ *
+ * A good key is remembered for an hour, so a busy session does not hit the
+ * license server on every call and keeps working through a brief outage.
+ */
+export declare function premiumRequired(tool: string): Promise<string | null>;

package/dist/server.js

@@ -1,10 +1,10 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { errorMessage, listApps, getApp, listNotifications, } from "./api.js";
+import { errorMessage, listApps, getApp, listNotifications, pushSdkPopularity } from "./api.js";
+import { premiumTool } from "./gateway.js";
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
 const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
-const MUTATING = { readOnlyHint: false, openWorldHint: true };
 export function createServer() {
     const server = new McpServer({
         name: "onesignal-mcp",
@@ -12,7 +12,7 @@ export function createServer() {
     });
     server.registerTool("list_apps", {
         title: "List apps",
-        description: "OneSignal apps.",
+        description: "OneSignal apps the key can send to.",
         inputSchema: z.object({}),
         annotations: READ_ONLY,
     }, async ({}) => {
@@ -25,7 +25,7 @@ export function createServer() {
     });
     server.registerTool("get_app", {
         title: "Get app",
-        description: "App details by ID.",
+        description: "One app by id, with platform and player count.",
         inputSchema: z.object({
             app_id: z.string().describe("OneSignal app ID.")
         }),
@@ -54,5 +54,53 @@ export function createServer() {
             return textError(errorMessage(e));
         }
     });
+    server.registerTool("push_sdk_popularity", {
+        title: "Push SDK popularity",
+        description: "Which OneSignal SDK people actually install: for each of the Node, React Native and Cordova packages, the latest version, how many versions exist, and last week's npm download count with each one's share of the three.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async (_args) => {
+        try {
+            return text(await pushSdkPopularity(_args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("sdk_release_timeline", {
+        title: "SDK release timeline",
+        description: "The release train of one OneSignal SDK: first and latest publish dates, days since the last release, how many versions exist, the median gap between them, every dist-tag with any prerelease tags still on the board, and the recent versions by date.",
+        inputSchema: z.object({
+            package: z.string().describe("onesignal-node, react-native-onesignal or onesignal-cordova-plugin.").optional(),
+            limit: z.number().describe("How many recent versions to list, 1-15.").optional()
+        }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: sdk_release_timeline ----
+        // The body runs on the gateway, behind the licence gate.
+        // ---- paywall: end ----
+        try {
+            return text(await premiumTool("mcp_onesignal_sdk_release_timeline", args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("platform_status", {
+        title: "Platform status",
+        description: "OneSignal's own reliability record: the headline status, every product area (push, email, SMS, in-app messages, integrations, analytics) with its current state, and the incident history with impact, time to resolve and the latest update on each.",
+        inputSchema: z.object({ limit: z.number().describe("How many incidents to show, 1-15.").optional() }),
+        annotations: READ_ONLY,
+    }, async (args) => {
+        // ---- paywall: platform_status ----
+        // The body runs on the gateway, behind the licence gate.
+        // ---- paywall: end ----
+        try {
+            return text(await premiumTool("mcp_onesignal_platform_status", args));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
     return server;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "onesignal-mcp",
-  "version": "1.0.0",
-  "description": "OneSignal push: apps and notifications. Needs keys.",
+  "version": "1.0.2",
+  "description": "Query the OneSignal API (free tier; use a current v2 Organization API key for ONESIGNAL_USER_KEY and the app REST API key for ONESIGNAL_APP_KEY, Basic auth).",
   "type": "module",
   "mcpName": "io.github.mrfentmen/onesignal-mcp",
   "repository": {