notifycx-mcp 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# notifycx-mcp
 
-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.
+Official [Model Context Protocol](https://modelcontextprotocol.io) server for [Notify](https://notify.cx).
+
+Use this in Cursor, Claude Code, or other MCP hosts when a coding agent should call Notify tools directly. For app/CI code, prefer the [`notifycx`](https://www.npmjs.com/package/notifycx) SDK or plain `fetch`.
+
+## Install (Cursor)
+
+```json
+{
+  "mcpServers": {
+    "notify": {
+      "command": "npx",
+      "args": ["-y", "notifycx-mcp"],
+      "env": {
+        "NOTIFY_API_KEY": "nk_..."
+      }
+    }
+  }
+}
+```
+
+Get your API key from [Credentials](https://notify.cx/dashboard/credentials). Docs: [notify.cx/mcp](https://notify.cx/mcp).
+
+## Tools
+
+| Tool | When to use |
+|------|-------------|
+| `send_email` | Production transactional send (verified `from`) |
+| `send_test_email` | Non-delivering API rehearsal |
+| `list_domains` | Domain / SPF / DKIM status |
+| `list_email_logs` | Recent delivery logs |
+
+## Pricing
+
+Free: 1,000 emails/mo. Pro: **$10 / 10,000**. Scale: $50 / 100,000.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import Notify, { NotifyError } from "notifycx";
+import { z } from "zod";
+function requireApiKey() {
+  const apiKey = process.env.NOTIFY_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "Missing NOTIFY_API_KEY. Set it in your MCP server env (dashboard \u2192 Credentials)."
+    );
+  }
+  return apiKey;
+}
+function client() {
+  return new Notify({
+    apiKey: requireApiKey(),
+    baseUrl: process.env.NOTIFY_BASE_URL
+  });
+}
+function formatError(err) {
+  if (err instanceof NotifyError) {
+    return JSON.stringify(
+      {
+        error: err.message,
+        status: err.status,
+        body: err.body,
+        hint: err.status === 401 ? "Check NOTIFY_API_KEY in MCP config" : err.message.toLowerCase().includes("domain") || err.message.toLowerCase().includes("sandbox") ? "Verify a domain (SPF/DKIM) or use send_test_email until production is unlocked" : void 0
+      },
+      null,
+      2
+    );
+  }
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+var sendShape = {
+  to: z.string().email().describe("Recipient email address"),
+  from: z.string().min(1).describe(
+    "Sender address or Name <email@verified-domain.com>. Production custom from requires a verified domain."
+  ),
+  subject: z.string().min(1).describe("Email subject line"),
+  html: z.string().min(1).optional().describe("HTML (or plain text) body. Prefer html; message/text also work."),
+  message: z.string().min(1).optional().describe("Alias for html/body content"),
+  text: z.string().min(1).optional().describe("Alias for html/body content")
+};
+var server = new McpServer({
+  name: "notifycx-mcp",
+  version: "1.0.0"
+});
+server.tool(
+  "send_email",
+  "Send transactional email via Notify (password reset, receipt, magic link, invoice, etc.) with a verified from domain. Use when the user wants production delivery. Prefer html for the body. For non-delivering API rehearsal before domain verification, use send_test_email instead.",
+  sendShape,
+  async (args) => {
+    try {
+      const result = await client().send(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: formatError(err) }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "send_test_email",
+  "API rehearsal for Notify: same request shape as production send but does not deliver and does not count toward quota. Use before domain verification or when testing the HTTP contract. For real inbox delivery, use send_email after verifying SPF/DKIM.",
+  sendShape,
+  async (args) => {
+    try {
+      const result = await client().sendTest(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: formatError(err) }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "list_domains",
+  "List Notify sending domains and verification status (SPF/DKIM). Use when wiring a production from address or debugging domain auth.",
+  {},
+  async () => {
+    try {
+      const result = await client().listDomains();
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: formatError(err) }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "list_email_logs",
+  "List recent Notify email delivery logs. Use after a send to check delivery, bounce, open, or click status.",
+  {
+    page: z.number().int().positive().optional().describe("Page number (default 1)"),
+    limit: z.number().int().min(1).max(100).optional().describe("Page size (default 20, max 100)"),
+    eventType: z.enum([
+      "Bounce",
+      "Click",
+      "Complaint",
+      "Delivery",
+      "DeliveryDelay",
+      "Open",
+      "Send"
+    ]).optional().describe("Filter logs by analytics event type")
+  },
+  async (args) => {
+    try {
+      const result = await client().listLogs(args);
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: formatError(err) }],
+        isError: true
+      };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "notifycx-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Official MCP server for Notify — transactional email tools for coding agents",
+  "type": "module",
+  "bin": {
+    "notifycx-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "notify",
+    "mcp",
+    "model-context-protocol",
+    "transactional-email",
+    "cursor",
+    "claude"
+  ],
+  "homepage": "https://notify.cx/mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sunil-sandhu/notifycx.git",
+    "directory": "mcp"
+  },
+  "author": "notify.cx",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "notifycx": "^1.0.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.8.1",
+    "tsup": "^8.0.1",
+    "typescript": "^5.6.3"
+  }
+}