notifycx-mcp 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,43 @@
-# 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 |
+| `add_domain` | Add domain + get DNS records (SPF/DKIM) |
+| `check_domain` | Poll verification after DNS is configured |
+| `list_domains` / `get_domain` | Domain / SPF / DKIM status |
+| `list_webhooks` / `create_webhook` / `update_webhook` / `delete_webhook` / `get_webhook` / `test_webhook` | Webhook setup (Pro+) |
+| `list_email_logs` | Recent delivery logs |
+| `get_usage` | Quota / account_verified |
+| `list_api_keys` | Key metadata (prefix only — create keys in the dashboard) |
+
+Typical setup path: `add_domain` → add DNS → `check_domain` → `send_email`. Optional: `create_webhook` after a verified domain.
+
+## 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,305 @@
+#!/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,
+    client: "mcp"
+  });
+}
+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);
+}
+function ok(result) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+  };
+}
+function fail(err) {
+  return {
+    content: [{ type: "text", text: formatError(err) }],
+    isError: true
+  };
+}
+var eventTypeEnum = z.enum([
+  "Bounce",
+  "Click",
+  "Complaint",
+  "Delivery",
+  "DeliveryDelay",
+  "Open",
+  "Send"
+]);
+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 webhookWriteShape = {
+  webhookUrl: z.string().url().describe("HTTPS URL to receive webhook events"),
+  subscribedEvents: z.array(eventTypeEnum).min(1).describe("Event types to subscribe to"),
+  domainId: z.string().uuid().describe("Verified sending domain id from list_domains"),
+  matchMode: z.enum(["domain", "hosts", "froms"]).optional().describe("Optional match scope (default domain)"),
+  matchHosts: z.array(z.string()).max(20).optional().describe("When matchMode is hosts"),
+  matchFroms: z.array(z.string()).max(20).optional().describe("When matchMode is froms")
+};
+var server = new McpServer({
+  name: "notifycx-mcp",
+  version: "1.1.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 {
+      return ok(await client().send(args));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+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 {
+      return ok(await client().sendTest(args));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "list_domains",
+  "List Notify sending domains and verification status (SPF/DKIM). Use when wiring a production from address or debugging domain auth. Includes DNS tokens when present.",
+  {},
+  async () => {
+    try {
+      return ok(await client().listDomains());
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "get_domain",
+  "Get one Notify sending domain by hostname, including DNS records/tokens for pending verification.",
+  {
+    domain: z.string().min(1).describe("Domain hostname, e.g. example.com")
+  },
+  async (args) => {
+    try {
+      return ok(await client().getDomain(args.domain));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "add_domain",
+  "Add a sending domain and start SPF/DKIM verification. Returns DNS records the user must add. After DNS is configured, call check_domain. Then use send_email with a from address on that domain.",
+  {
+    domain: z.string().min(1).describe("Domain hostname to verify, e.g. example.com"),
+    dnsProvider: z.enum([
+      "vercel",
+      "cloudflare",
+      "squarespace",
+      "namecheap",
+      "godaddy",
+      "route53",
+      "other"
+    ]).optional().describe("Optional DNS provider hint for dashboard UX")
+  },
+  async (args) => {
+    try {
+      return ok(await client().addDomain(args));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "check_domain",
+  "Poll SES for domain SPF/DKIM verification status after DNS records were added. Call after add_domain. When both succeed, production send_email with that from domain is unlocked.",
+  {
+    domain: z.string().min(1).describe("Domain hostname to check")
+  },
+  async (args) => {
+    try {
+      return ok(await client().checkDomain(args.domain));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+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: eventTypeEnum.optional().describe("Filter logs by analytics event type")
+  },
+  async (args) => {
+    try {
+      return ok(await client().listLogs(args));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "get_usage",
+  "Get Notify plan usage and quota (hourly/monthly sends, account_verified). Use when debugging limits or confirming production unlock.",
+  {},
+  async () => {
+    try {
+      return ok(await client().getUsage());
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "list_api_keys",
+  "List API key metadata for the account (id, name, prefix only \u2014 never the full secret). Create or rotate keys in the Notify dashboard Credentials page.",
+  {},
+  async () => {
+    try {
+      return ok(await client().listApiKeys());
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "list_webhooks",
+  "List Notify webhook subscriptions (URL, events, domain scope).",
+  {},
+  async () => {
+    try {
+      return ok(await client().listWebhooks());
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "get_webhook",
+  "Get one Notify webhook by id.",
+  {
+    id: z.string().uuid().describe("Webhook subscription id")
+  },
+  async (args) => {
+    try {
+      return ok(await client().getWebhook(args.id));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "create_webhook",
+  "Create a Notify webhook for delivery events on a verified domain. Requires Pro or Scale (free plan has 0 webhooks). Use list_domains to get domainId.",
+  webhookWriteShape,
+  async (args) => {
+    try {
+      return ok(await client().createWebhook(args));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "update_webhook",
+  "Update an existing Notify webhook (URL, events, domain scope).",
+  {
+    id: z.string().uuid().describe("Webhook subscription id"),
+    webhookUrl: webhookWriteShape.webhookUrl.optional(),
+    subscribedEvents: webhookWriteShape.subscribedEvents.optional(),
+    domainId: webhookWriteShape.domainId.optional(),
+    matchMode: webhookWriteShape.matchMode,
+    matchHosts: webhookWriteShape.matchHosts,
+    matchFroms: webhookWriteShape.matchFroms
+  },
+  async (args) => {
+    try {
+      const { id, ...input } = args;
+      return ok(await client().updateWebhook(id, input));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "delete_webhook",
+  "Delete a Notify webhook subscription by id.",
+  {
+    id: z.string().uuid().describe("Webhook subscription id")
+  },
+  async (args) => {
+    try {
+      return ok(await client().deleteWebhook(args.id));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+server.tool(
+  "test_webhook",
+  "Send a test Notify webhook payload to a URL (does not require an existing subscription id).",
+  {
+    webhookUrl: z.string().url().describe("HTTPS URL to receive the test payload"),
+    eventType: eventTypeEnum.describe("Event type for the test payload"),
+    domainId: z.string().uuid().optional().describe("Optional verified domain id for scoped test payloads")
+  },
+  async (args) => {
+    try {
+      return ok(await client().testWebhook(args));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+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.1.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.1.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.8.1",
+    "tsup": "^8.0.1",
+    "typescript": "^5.6.3"
+  }
+}