notifycx-mcp 1.0.0 → 1.1.0

package/README.md

@@ -28,8 +28,15 @@ Get your API key from [Credentials](https://notify.cx/dashboard/credentials). Do
 |------|-------------|
 | `send_email` | Production transactional send (verified `from`) |
 | `send_test_email` | Non-delivering API rehearsal |
-| `list_domains` | Domain / SPF / DKIM status |
+| `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
 

package/dist/index.js

@@ -17,7 +17,8 @@ function requireApiKey() {
 function client() {
   return new Notify({
     apiKey: requireApiKey(),
-    baseUrl: process.env.NOTIFY_BASE_URL
+    baseUrl: process.env.NOTIFY_BASE_URL,
+    client: "mcp"
   });
 }
 function formatError(err) {
@@ -36,6 +37,26 @@ function formatError(err) {
   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(
@@ -46,9 +67,17 @@ var sendShape = {
   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.0.0"
+  version: "1.1.0"
 });
 server.tool(
   "send_email",
@@ -56,15 +85,9 @@ server.tool(
   sendShape,
   async (args) => {
     try {
-      const result = await client().send(args);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
+      return ok(await client().send(args));
     } catch (err) {
-      return {
-        content: [{ type: "text", text: formatError(err) }],
-        isError: true
-      };
+      return fail(err);
     }
   }
 );
@@ -74,33 +97,72 @@ server.tool(
   sendShape,
   async (args) => {
     try {
-      const result = await client().sendTest(args);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
+      return ok(await client().sendTest(args));
     } catch (err) {
-      return {
-        content: [{ type: "text", text: formatError(err) }],
-        isError: true
-      };
+      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.",
+  "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 {
-      const result = await client().listDomains();
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
+      return ok(await client().listDomains());
     } catch (err) {
-      return {
-        content: [{ type: "text", text: formatError(err) }],
-        isError: true
-      };
+      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);
     }
   }
 );
@@ -110,27 +172,126 @@ server.tool(
   {
     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")
+    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 {
-      const result = await client().listLogs(args);
-      return {
-        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
-      };
+      return ok(await client().testWebhook(args));
     } catch (err) {
-      return {
-        content: [{ type: "text", text: formatError(err) }],
-        isError: true
-      };
+      return fail(err);
     }
   }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notifycx-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Official MCP server for Notify — transactional email tools for coding agents",
   "type": "module",
   "bin": {
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "notifycx": "^1.0.0",
+    "notifycx": "^1.1.0",
     "zod": "^3.24.2"
   },
   "devDependencies": {