@zyphr-dev/mcp-server 0.1.0

package/src/schemas.ts

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+
+const emailAddress = z.object({
+  email: z.string().email(),
+  name: z.string().optional(),
+});
+
+const recipient = z.union([z.string().email(), emailAddress]);
+
+export const sendEmailShape = {
+  to: z
+    .union([recipient, z.array(recipient).min(1)])
+    .describe('Recipient email address (string or {email,name}) or an array of them'),
+  from: z
+    .union([z.string().email(), emailAddress])
+    .optional()
+    .describe('Sender address. Defaults to the account-level "from" address.'),
+  replyTo: z.union([z.string().email(), emailAddress]).optional(),
+  cc: z.array(z.string().email()).optional(),
+  bcc: z.array(z.string().email()).optional(),
+  subject: z.string().min(1),
+  html: z.string().optional().describe('Rendered HTML body. Mutually exclusive with templateId.'),
+  text: z.string().optional().describe('Plain-text body. Mutually exclusive with templateId.'),
+  templateId: z.string().optional().describe('Template ID. When set, html/text are ignored.'),
+  templateData: z
+    .record(z.unknown())
+    .optional()
+    .describe('Variables to interpolate into the template'),
+  tags: z.array(z.string()).optional(),
+  metadata: z.record(z.unknown()).optional(),
+  subscriberId: z.string().optional(),
+  category: z.string().optional(),
+  scheduledAt: z
+    .string()
+    .datetime()
+    .optional()
+    .describe('ISO 8601 timestamp for scheduled delivery'),
+} as const;
+
+export const sendPushShape = {
+  userId: z.string().optional().describe('Send to all devices for this user/subscriber'),
+  deviceId: z.string().optional().describe('Send to a specific device only'),
+  title: z.string().optional(),
+  body: z.string().optional(),
+  data: z.record(z.unknown()).optional().describe('Custom data payload delivered to the device'),
+  badge: z.number().int().nonnegative().optional(),
+  sound: z.string().optional(),
+  imageUrl: z.string().url().optional(),
+  contentAvailable: z.boolean().optional().describe('Silent/background push'),
+  tags: z.array(z.string()).optional(),
+  metadata: z.record(z.unknown()).optional(),
+  collapseKey: z.string().optional(),
+  subscriberId: z.string().optional(),
+  subscriberExternalId: z.string().optional(),
+  category: z.string().optional(),
+  force: z.boolean().optional().describe('Skip subscriber preference checks'),
+  sendAt: z.string().datetime().optional(),
+  delay: z.number().int().nonnegative().optional(),
+} as const;
+
+export const sendSmsShape = {
+  to: z.string().min(1).describe('Recipient phone number in E.164 format (e.g. +14155551234)'),
+  from: z.string().optional().describe('Sender phone number or sender ID'),
+  body: z.string().min(1),
+  subscriberId: z.string().optional(),
+  scheduledAt: z.string().datetime().optional(),
+  metadata: z.record(z.unknown()).optional(),
+} as const;
+
+// Integration
+
+export const sdkLanguages = ['node', 'python', 'ruby', 'go', 'php', 'csharp'] as const;
+export type SdkLanguage = (typeof sdkLanguages)[number];
+
+export const quickstartChannels = ['email', 'push', 'sms', 'inbox', 'webhook'] as const;
+export type QuickstartChannel = (typeof quickstartChannels)[number];
+
+export const getQuickstartShape = {
+  channel: z
+    .enum(quickstartChannels)
+    .describe('Which Zyphr channel to wire up'),
+  language: z
+    .enum(['node', 'python', 'ruby', 'go', 'php', 'csharp'])
+    .describe('Target language for the integration'),
+  framework: z
+    .string()
+    .optional()
+    .describe(
+      'Optional framework hint (e.g. "express", "nextjs", "flask", "fastapi", "rails", "gin", "laravel", "aspnetcore"). Falls back to plain SDK code when unrecognized.',
+    ),
+} as const;
+
+export const getSdkInstallShape = {
+  language: z
+    .enum(sdkLanguages)
+    .describe('Target language for the integration'),
+  packageManager: z
+    .string()
+    .optional()
+    .describe(
+      'Optional package manager override (e.g. "yarn" instead of "npm"). When recognized, only that manager is returned; otherwise the full list is returned.',
+    ),
+} as const;
+
+// Templates
+
+export const listTemplatesShape = {
+  limit: z.number().int().positive().max(200).optional(),
+  offset: z.number().int().nonnegative().optional(),
+} as const;
+
+export const getTemplateShape = {
+  id: z.string().min(1).describe('Template ID'),
+} as const;
+
+export const renderTemplateShape = {
+  id: z.string().min(1).describe('Template ID'),
+  variables: z
+    .record(z.unknown())
+    .describe('Key/value variables to interpolate into the template'),
+} as const;
+
+export const createTemplateShape = {
+  name: z.string().min(1),
+  description: z.string().optional(),
+  subject: z.string().optional().describe('Default subject (email templates)'),
+  html: z.string().optional(),
+  text: z.string().optional(),
+} as const;
+
+// Subscribers
+
+export const findSubscriberShape = {
+  externalId: z
+    .string()
+    .min(1)
+    .describe('Subscriber external ID (your application user/customer ID)'),
+} as const;
+
+export const listSubscribersShape = {
+  status: z.enum(['active', 'inactive']).optional(),
+  email: z.string().email().optional(),
+  limit: z.number().int().positive().max(200).optional(),
+  offset: z.number().int().nonnegative().optional(),
+} as const;
+
+export const createSubscriberShape = {
+  externalId: z.string().min(1).describe('Your application user/customer ID'),
+  email: z.string().email().optional(),
+  phone: z.string().optional(),
+  name: z.string().optional(),
+  avatarUrl: z.string().url().optional(),
+  timezone: z.string().optional(),
+  locale: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+} as const;
+
+export const updateSubscriberShape = {
+  id: z.string().min(1).describe('Zyphr subscriber ID'),
+  email: z.string().email().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  name: z.string().nullable().optional(),
+  avatarUrl: z.string().url().nullable().optional(),
+  timezone: z.string().optional(),
+  locale: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+  status: z.enum(['active', 'inactive']).optional(),
+} as const;
+
+export const setSubscriberPreferencesShape = {
+  id: z.string().min(1).describe('Zyphr subscriber ID'),
+  preferences: z
+    .array(
+      z.object({
+        categoryId: z.string().optional(),
+        channel: z.string().optional().describe('email | push | sms | in_app'),
+        enabled: z.boolean().optional(),
+      }),
+    )
+    .min(1),
+} as const;
+
+// Webhooks
+
+export const listWebhooksShape = {
+  limit: z.number().int().positive().max(200).optional(),
+  offset: z.number().int().nonnegative().optional(),
+} as const;
+
+export const createWebhookShape = {
+  url: z.string().url().describe('Receiver URL that Zyphr will POST events to'),
+  events: z
+    .array(z.string().min(1))
+    .min(1)
+    .describe('Event types to subscribe to (e.g. ["email.*", "subscriber.created"])'),
+  description: z.string().optional(),
+  secret: z
+    .string()
+    .optional()
+    .describe('Optional secret used to sign payloads. If omitted, Zyphr generates one.'),
+  metadata: z.record(z.unknown()).optional(),
+  headers: z.record(z.string()).optional().describe('Custom headers to send with every delivery'),
+  version: z.string().optional(),
+  rateLimit: z.number().int().positive().optional(),
+} as const;
+
+export const getWebhookDeliveriesShape = {
+  webhookId: z.string().min(1).describe('Webhook endpoint ID'),
+  status: z.enum(['pending', 'delivering', 'delivered', 'failed', 'exhausted']).optional(),
+  eventType: z.string().optional(),
+  search: z.string().optional(),
+  startDate: z.string().datetime().optional(),
+  endDate: z.string().datetime().optional(),
+  limit: z.number().int().positive().max(200).optional(),
+  offset: z.number().int().nonnegative().optional(),
+} as const;
+
+export const sendInboxMessageShape = {
+  subscriberId: z.string().min(1).describe('Subscriber to deliver the in-app message to'),
+  title: z.string().min(1),
+  body: z.string().optional(),
+  actionUrl: z.string().url().optional(),
+  actionLabel: z.string().optional(),
+  imageUrl: z.string().url().optional(),
+  icon: z.string().optional(),
+  category: z.string().optional(),
+  priority: z.enum(['low', 'normal', 'high', 'urgent']).optional(),
+  data: z.record(z.unknown()).optional(),
+  tags: z.array(z.string()).optional(),
+  expiresAt: z.string().datetime().optional(),
+} as const;

package/src/server.ts

@@ -0,0 +1,26 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { loadToolGuards } from './config.js';
+import { registerSendTools } from './tools/send.js';
+import { registerSubscriberTools } from './tools/subscribers.js';
+import { registerTemplateTools } from './tools/templates.js';
+import { registerIntegrationTools } from './tools/integration.js';
+import { registerWebhookTools } from './tools/webhooks.js';
+
+export const SERVER_NAME = 'zyphr';
+export const SERVER_VERSION = '0.1.0';
+
+export function createServer(): McpServer {
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  const guards = loadToolGuards();
+  registerSendTools(server, guards);
+  registerTemplateTools(server, guards);
+  registerSubscriberTools(server, guards);
+  registerWebhookTools(server, guards);
+  registerIntegrationTools(server, guards);
+
+  return server;
+}

package/src/tools/index.ts

@@ -0,0 +1,7 @@
+// Tool registration is performed inside `createServer` (src/server.ts).
+// Each tool file exports a `register*Tools(server, guards)` function.
+export { registerSendTools } from './send.js';
+export { registerTemplateTools } from './templates.js';
+export { registerSubscriberTools } from './subscribers.js';
+export { registerWebhookTools } from './webhooks.js';
+export { registerIntegrationTools } from './integration.js';

package/src/tools/integration.ts

@@ -0,0 +1,54 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { isToolEnabled, type ToolGuards } from '../config.js';
+import { resolveQuickstart } from '../integration/quickstart/index.js';
+import { resolveInstallEntry } from '../integration/sdk-snippets.js';
+import { toolResult } from '../result.js';
+import { getQuickstartShape, getSdkInstallShape } from '../schemas.js';
+
+export function registerIntegrationTools(server: McpServer, guards: ToolGuards): void {
+  if (isToolEnabled({ name: 'get_sdk_install_for_language', mutates: false }, guards)) {
+    server.registerTool(
+      'get_sdk_install_for_language',
+      {
+        title: 'Get SDK install instructions for a language',
+        description:
+          'Returns install commands, init snippet, env vars, and docs URL for the chosen language. Use this when wiring Zyphr into a new project so the AI can drop the correct package + client init code.',
+        inputSchema: getSdkInstallShape,
+      },
+      async (args) => {
+        const entry = resolveInstallEntry(args.language, args.packageManager);
+        return toolResult(entry);
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'get_quickstart_for_channel', mutates: false }, guards)) {
+    server.registerTool(
+      'get_quickstart_for_channel',
+      {
+        title: 'Get quickstart code for a channel + language',
+        description:
+          'Returns drop-in service file(s) for the chosen Zyphr channel (email/push/sms/inbox/webhook), language, and optional framework (express, nextjs, flask, fastapi, rails, laravel, aspnetcore). Webhook handlers ALWAYS verify HMAC signatures. Unknown frameworks fall back to plain SDK code.',
+        inputSchema: getQuickstartShape,
+      },
+      async (args) => {
+        const resolved = resolveQuickstart({
+          channel: args.channel,
+          language: args.language,
+          framework: args.framework,
+        });
+        if (!resolved) {
+          return toolResult({
+            error: `No quickstart available for channel=${args.channel} language=${args.language}`,
+          });
+        }
+        const { result, frameworkRecognized } = resolved;
+        return toolResult({
+          ...result,
+          frameworkRecognized,
+          requestedFramework: args.framework ?? null,
+        });
+      },
+    );
+  }
+}

package/src/tools/send.ts

@@ -0,0 +1,153 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getZyphrClient } from '../client.js';
+import { isToolEnabled, type ToolGuards } from '../config.js';
+import { runTool } from '../result.js';
+import {
+  sendEmailShape,
+  sendInboxMessageShape,
+  sendPushShape,
+  sendSmsShape,
+} from '../schemas.js';
+
+function normalizeEmailAddress(value: unknown): { email: string; name?: string } | undefined {
+  if (typeof value === 'string') return { email: value };
+  if (value && typeof value === 'object' && 'email' in value) {
+    return value as { email: string; name?: string };
+  }
+  return undefined;
+}
+
+function normalizeRecipients(to: unknown): { email: string; name?: string }[] {
+  if (Array.isArray(to)) {
+    return to.map(normalizeEmailAddress).filter((v): v is { email: string } => Boolean(v));
+  }
+  const one = normalizeEmailAddress(to);
+  return one ? [one] : [];
+}
+
+export function registerSendTools(server: McpServer, guards: ToolGuards): void {
+  if (isToolEnabled({ name: 'send_email', mutates: true }, guards)) {
+    server.registerTool(
+      'send_email',
+      {
+        title: 'Send email',
+        description:
+          'Send a transactional email via Zyphr. Use either html/text OR templateId+templateData, not both.',
+        inputSchema: sendEmailShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.emails.sendEmail({
+            to: normalizeRecipients(args.to),
+            from: normalizeEmailAddress(args.from),
+            replyTo: normalizeEmailAddress(args.replyTo),
+            cc: args.cc,
+            bcc: args.bcc,
+            subject: args.subject,
+            html: args.html,
+            text: args.text,
+            templateId: args.templateId,
+            templateData: args.templateData,
+            tags: args.tags,
+            metadata: args.metadata,
+            subscriberId: args.subscriberId,
+            category: args.category,
+            scheduledAt: args.scheduledAt ? new Date(args.scheduledAt) : undefined,
+          });
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'send_push', mutates: true }, guards)) {
+    server.registerTool(
+      'send_push',
+      {
+        title: 'Send push notification',
+        description:
+          'Send a push notification. Target one of: userId (all devices for a user), deviceId (specific device), subscriberId, or subscriberExternalId.',
+        inputSchema: sendPushShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.push.sendPush({
+            userId: args.userId,
+            deviceId: args.deviceId,
+            title: args.title,
+            body: args.body,
+            data: args.data,
+            badge: args.badge,
+            sound: args.sound,
+            imageUrl: args.imageUrl,
+            contentAvailable: args.contentAvailable,
+            tags: args.tags,
+            metadata: args.metadata,
+            collapseKey: args.collapseKey,
+            subscriberId: args.subscriberId,
+            subscriberExternalId: args.subscriberExternalId,
+            category: args.category,
+            force: args.force,
+            sendAt: args.sendAt ? new Date(args.sendAt) : undefined,
+            delay: args.delay,
+          });
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'send_sms', mutates: true }, guards)) {
+    server.registerTool(
+      'send_sms',
+      {
+        title: 'Send SMS',
+        description: 'Send an SMS message via Zyphr. The recipient must be in E.164 format.',
+        inputSchema: sendSmsShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.sms.sendSms({
+            to: args.to,
+            from: args.from,
+            body: args.body,
+            subscriberId: args.subscriberId,
+            scheduledAt: args.scheduledAt ? new Date(args.scheduledAt) : undefined,
+            metadata: args.metadata,
+          });
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'send_inbox_message', mutates: true }, guards)) {
+    server.registerTool(
+      'send_inbox_message',
+      {
+        title: 'Send in-app inbox message',
+        description: 'Deliver an in-app inbox notification to a Zyphr subscriber.',
+        inputSchema: sendInboxMessageShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.inbox.sendInApp({
+            subscriberId: args.subscriberId,
+            title: args.title,
+            body: args.body,
+            actionUrl: args.actionUrl,
+            actionLabel: args.actionLabel,
+            imageUrl: args.imageUrl,
+            icon: args.icon,
+            category: args.category,
+            priority: args.priority,
+            data: args.data,
+            tags: args.tags,
+            expiresAt: args.expiresAt ? new Date(args.expiresAt) : undefined,
+          });
+        });
+      },
+    );
+  }
+}

package/src/tools/subscribers.ts

@@ -0,0 +1,126 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getZyphrClient } from '../client.js';
+import { isToolEnabled, type ToolGuards } from '../config.js';
+import { runTool } from '../result.js';
+import {
+  createSubscriberShape,
+  findSubscriberShape,
+  listSubscribersShape,
+  setSubscriberPreferencesShape,
+  updateSubscriberShape,
+} from '../schemas.js';
+
+export function registerSubscriberTools(server: McpServer, guards: ToolGuards): void {
+  if (isToolEnabled({ name: 'find_subscriber', mutates: false }, guards)) {
+    server.registerTool(
+      'find_subscriber',
+      {
+        title: 'Find subscriber by external ID',
+        description:
+          'Look up a subscriber by the external ID you assigned (typically your application user/customer ID).',
+        inputSchema: findSubscriberShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.subscribers.getSubscriberByExternalId(args.externalId);
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'list_subscribers', mutates: false }, guards)) {
+    server.registerTool(
+      'list_subscribers',
+      {
+        title: 'List subscribers',
+        description: 'List subscribers, optionally filtered by status or email.',
+        inputSchema: listSubscribersShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.subscribers.listSubscribers(
+            args.status,
+            args.email,
+            args.limit,
+            args.offset,
+          );
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'create_subscriber', mutates: true }, guards)) {
+    server.registerTool(
+      'create_subscriber',
+      {
+        title: 'Create subscriber',
+        description: 'Create a new subscriber. `externalId` must be unique within your account.',
+        inputSchema: createSubscriberShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.subscribers.createSubscriber({
+            externalId: args.externalId,
+            email: args.email,
+            phone: args.phone,
+            name: args.name,
+            avatarUrl: args.avatarUrl,
+            timezone: args.timezone,
+            locale: args.locale,
+            metadata: args.metadata,
+          });
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'update_subscriber', mutates: true }, guards)) {
+    server.registerTool(
+      'update_subscriber',
+      {
+        title: 'Update subscriber',
+        description:
+          'Update a subscriber by Zyphr ID. Pass null for email/phone/name/avatarUrl to clear those fields.',
+        inputSchema: updateSubscriberShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.subscribers.updateSubscriber(args.id, {
+            email: args.email ?? undefined,
+            phone: args.phone ?? undefined,
+            name: args.name ?? undefined,
+            avatarUrl: args.avatarUrl ?? undefined,
+            timezone: args.timezone,
+            locale: args.locale,
+            metadata: args.metadata,
+            status: args.status,
+          });
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'set_subscriber_preferences', mutates: true }, guards)) {
+    server.registerTool(
+      'set_subscriber_preferences',
+      {
+        title: 'Set subscriber preferences',
+        description:
+          'Set notification preferences for a subscriber. Each preference targets a category and/or channel and toggles `enabled`.',
+        inputSchema: setSubscriberPreferencesShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.subscribers.setSubscriberPreferences(args.id, {
+            preferences: args.preferences,
+          });
+        });
+      },
+    );
+  }
+}

package/src/tools/templates.ts

@@ -0,0 +1,87 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getZyphrClient } from '../client.js';
+import { isToolEnabled, type ToolGuards } from '../config.js';
+import { runTool } from '../result.js';
+import {
+  createTemplateShape,
+  getTemplateShape,
+  listTemplatesShape,
+  renderTemplateShape,
+} from '../schemas.js';
+
+export function registerTemplateTools(server: McpServer, guards: ToolGuards): void {
+  if (isToolEnabled({ name: 'list_templates', mutates: false }, guards)) {
+    server.registerTool(
+      'list_templates',
+      {
+        title: 'List templates',
+        description: 'List notification templates in the account.',
+        inputSchema: listTemplatesShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.templates.listTemplates(args.limit, args.offset);
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'get_template', mutates: false }, guards)) {
+    server.registerTool(
+      'get_template',
+      {
+        title: 'Get template',
+        description: 'Fetch a single template by ID.',
+        inputSchema: getTemplateShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.templates.getTemplate(args.id);
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'render_template', mutates: false }, guards)) {
+    server.registerTool(
+      'render_template',
+      {
+        title: 'Render template',
+        description:
+          'Preview a template with the given variables WITHOUT sending. Returns the rendered subject/html/text so the AI can show the user what would be sent.',
+        inputSchema: renderTemplateShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.templates.renderTemplate(args.id, { variables: args.variables });
+        });
+      },
+    );
+  }
+
+  if (isToolEnabled({ name: 'create_template', mutates: true }, guards)) {
+    server.registerTool(
+      'create_template',
+      {
+        title: 'Create template',
+        description: 'Create a new notification template.',
+        inputSchema: createTemplateShape,
+      },
+      async (args) => {
+        return runTool(async () => {
+          const zyphr = getZyphrClient();
+          return await zyphr.templates.createTemplate({
+            name: args.name,
+            description: args.description,
+            subject: args.subject,
+            html: args.html,
+            text: args.text,
+          });
+        });
+      },
+    );
+  }
+}