@neschadin/sendgrid-mcp 0.0.0-stage → 3.0.1

package/src/tools/email.ts

@@ -0,0 +1,486 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import type { SendGridClient } from '../client';
+import {
+  BatchIdOutputSchema,
+  jsonReadResult,
+  ScheduledSendListOutputSchema,
+  ScheduledSendSchema,
+  SendTestEmailOutputSchema,
+} from './output_schemas';
+import {
+  SendRequestSchema,
+  runSendPreflight,
+  toMailSendPayload,
+} from './preflight';
+import { ensureSafeToolRegistration, SEND_PREFLIGHT_HINT } from './tool_utils';
+
+const ConfirmTokenSchema = z
+  .literal('CONFIRM')
+  .describe('Required for mutating scheduled-send state');
+
+export function registerEmailTools(
+  server: McpServer,
+  client: SendGridClient,
+  defaultFromEmail: string,
+  defaultFromName: string,
+) {
+  ensureSafeToolRegistration(server);
+  const RecipientSchema = z.object({
+    email: z.email(),
+    name: z.string().optional(),
+  });
+
+  server.registerTool(
+    'send_email_advanced',
+    {
+      description:
+        `Send email with full /mail/send payload surface (content/template, tracking, asm, scheduling, categories, etc).${SEND_PREFLIGHT_HINT}`,
+      inputSchema: z.object({
+        request: SendRequestSchema,
+      }),
+    },
+    async ({ request }) => {
+      const result = await client.sendMail(toMailSendPayload(request));
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'Email accepted by SendGrid.',
+              `Status code: ${result.statusCode}`,
+              `Message ID: ${result.messageId || '(not returned)'}`,
+            ].join('\n'),
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    'send_template_email_advanced',
+    {
+      description:
+        `Send a dynamic-template email with optional cc/bcc, reply-to, asm, categories, custom args, and scheduling.${SEND_PREFLIGHT_HINT}`,
+      inputSchema: z.object({
+        to: z.array(RecipientSchema).min(1),
+        templateId: z.string().describe('Template ID, e.g. d-xxxxxxxxxxxxxxxx'),
+        dynamicTemplateData: z.record(z.string(), z.unknown()),
+        subject: z.string().optional(),
+        cc: z.array(RecipientSchema).optional(),
+        bcc: z.array(RecipientSchema).optional(),
+        fromEmail: z.email().optional(),
+        fromName: z.string().optional(),
+        replyTo: RecipientSchema.optional(),
+        categories: z.array(z.string()).optional(),
+        customArgs: z.record(z.string(), z.string()).optional(),
+        sendAt: z.number().int().optional(),
+        batchId: z.string().optional(),
+        asmGroupId: z.number().int().optional(),
+        asmGroupsToDisplay: z.array(z.number().int()).optional(),
+        mailSettings: z.record(z.string(), z.unknown()).optional(),
+        trackingSettings: z.record(z.string(), z.unknown()).optional(),
+      }),
+    },
+    async ({
+      to,
+      templateId,
+      dynamicTemplateData,
+      subject,
+      cc,
+      bcc,
+      fromEmail,
+      fromName,
+      replyTo,
+      categories,
+      customArgs,
+      sendAt,
+      batchId,
+      asmGroupId,
+      asmGroupsToDisplay,
+      mailSettings,
+      trackingSettings,
+    }) => {
+      const result = await client.sendMail({
+        personalizations: [
+          {
+            to,
+            cc,
+            bcc,
+            dynamic_template_data: dynamicTemplateData,
+          },
+        ],
+        from: {
+          email: fromEmail ?? defaultFromEmail,
+          name: fromName ?? defaultFromName,
+        },
+        reply_to: replyTo,
+        subject,
+        template_id: templateId,
+        categories,
+        custom_args: customArgs,
+        send_at: sendAt,
+        batch_id: batchId,
+        asm:
+          asmGroupId !== undefined
+            ? {
+                group_id: asmGroupId,
+                groups_to_display: asmGroupsToDisplay,
+              }
+            : undefined,
+        mail_settings: mailSettings,
+        tracking_settings: trackingSettings,
+      });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'Template email accepted by SendGrid.',
+              `Template: ${templateId}`,
+              `Recipients: ${to.length}`,
+              `Status code: ${result.statusCode}`,
+              `Message ID: ${result.messageId || '(not returned)'}`,
+              batchId ? `Batch ID: ${batchId}` : '',
+            ]
+              .filter(Boolean)
+              .join('\n'),
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    'send_sandbox_email',
+    {
+      description:
+        `Send using mail_settings.sandbox_mode=true for payload/template validation without live recipient delivery.${SEND_PREFLIGHT_HINT}`,
+      inputSchema: z.object({
+        request: SendRequestSchema,
+      }),
+    },
+    async ({ request }) => {
+      const payload = toMailSendPayload(request);
+      payload.mail_settings = {
+        ...payload.mail_settings,
+        sandbox_mode: { enable: true },
+      };
+
+      const result = await client.sendMail(payload);
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'Sandbox send accepted by SendGrid.',
+              'No live delivery attempted.',
+              `Status code: ${result.statusCode}`,
+              `Message ID: ${result.messageId || '(not returned)'}`,
+            ].join('\n'),
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    'create_batch_id',
+    {
+      description:
+        'Create a SendGrid batch ID for scheduled sends and later pause/cancel control.',
+      inputSchema: z.object({}),
+      outputSchema: BatchIdOutputSchema,
+    },
+    async () => {
+      const batch = await client.createBatchId();
+      const structured = { batchId: batch.batch_id };
+      return {
+        structuredContent: structured,
+        content: [{ type: 'text', text: `Batch ID: ${batch.batch_id}` }],
+      };
+    },
+  );
+
+  server.registerTool(
+    'schedule_email',
+    {
+      description:
+        `Schedule an email by setting send_at. Creates batch ID automatically when not provided.${SEND_PREFLIGHT_HINT}`,
+      inputSchema: z.object({
+        request: SendRequestSchema,
+        sendAt: z.number().int().describe('Unix timestamp in seconds'),
+        batchId: z.string().optional(),
+        autoCreateBatchId: z
+          .boolean()
+          .optional()
+          .describe(
+            'Default true. If false and batchId missing, sends without batch control',
+          ),
+      }),
+    },
+    async ({ request, sendAt, batchId, autoCreateBatchId }) => {
+      const now = Math.floor(Date.now() / 1000);
+      if (sendAt <= now) {
+        throw new Error(
+          `sendAt must be in the future. Received ${sendAt}, now is ${now}.`,
+        );
+      }
+      const maxSendAt = now + 72 * 60 * 60;
+      if (sendAt > maxSendAt) {
+        throw new Error(
+          `sendAt must be within 72 hours. Received ${sendAt}, max is ${maxSendAt}.`,
+        );
+      }
+
+      let effectiveBatchId = batchId;
+      if (!effectiveBatchId && (autoCreateBatchId ?? true)) {
+        effectiveBatchId = (await client.createBatchId()).batch_id;
+      }
+
+      const result = await client.sendMail(
+        toMailSendPayload({
+          ...request,
+          sendAt,
+          batchId: effectiveBatchId,
+        }),
+      );
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: [
+              'Scheduled email accepted by SendGrid.',
+              `send_at: ${sendAt}`,
+              effectiveBatchId
+                ? `Batch ID: ${effectiveBatchId}`
+                : 'Batch ID: (none)',
+              `Status code: ${result.statusCode}`,
+              `Message ID: ${result.messageId || '(not returned)'}`,
+            ].join('\n'),
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    'list_scheduled_sends',
+    {
+      description:
+        'List paused or canceled scheduled-send batches (GET /v3/user/scheduled_sends). A batch that was only scheduled with send_at, and never paused or canceled, is not in this list.',
+      inputSchema: z.object({}),
+      outputSchema: ScheduledSendListOutputSchema,
+    },
+    async () => {
+      const sends = await client.listScheduledSends();
+      return jsonReadResult(
+        { count: sends.length, sends },
+        sends.length === 0
+          ? 'No paused or canceled scheduled sends.'
+          : sends
+              .map((send) => `- ${send.batch_id} status=${send.status}`)
+              .join('\n'),
+      );
+    },
+  );
+
+  server.registerTool(
+    'get_scheduled_send',
+    {
+      description:
+        'Read pause/cancel state for one scheduled-send batch_id. SendGrid answers a missing batch with 200 and an empty array; this tool reports that as not found.',
+      inputSchema: z.object({
+        batchId: z.string().min(1),
+      }),
+      outputSchema: ScheduledSendSchema,
+    },
+    async ({ batchId }) => {
+      const send = await client.getScheduledSend(batchId);
+      return jsonReadResult(
+        send,
+        `Scheduled send ${send.batch_id} status=${send.status}`,
+      );
+    },
+  );
+
+  server.registerTool(
+    'pause_scheduled_send',
+    {
+      description: 'Pause a scheduled send batch by batch ID.',
+      inputSchema: z.object({
+        confirmToken: ConfirmTokenSchema,
+        batchId: z.string(),
+      }),
+    },
+    async ({ batchId }) => {
+      const result = await client.upsertScheduledSend(batchId, 'pause');
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Scheduled send ${result.batch_id} status: ${result.status}`,
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    'resume_scheduled_send',
+    {
+      description:
+        'Resume a previously paused/canceled batch by deleting its scheduled-send status.',
+      inputSchema: z.object({
+        confirmToken: ConfirmTokenSchema,
+        batchId: z.string(),
+      }),
+    },
+    async ({ batchId }) => {
+      await client.resumeScheduledSend(batchId);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Scheduled send ${batchId} resumed (status entry removed).`,
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    'cancel_scheduled_send',
+    {
+      description:
+        'Cancel a scheduled send batch. This is not guaranteed close to send time.',
+      inputSchema: z.object({
+        confirmToken: ConfirmTokenSchema,
+        batchId: z.string(),
+      }),
+    },
+    async ({ batchId }) => {
+      const result = await client.upsertScheduledSend(batchId, 'cancel');
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Scheduled send ${result.batch_id} status: ${result.status}`,
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    'send_test_email',
+    {
+      description:
+        'Send a test email using a template with mock data. Uses mail_settings.sandbox_mode by default (SendGrid accepts but does not deliver). Set liveDelivery=true with confirmToken="CONFIRM" for real delivery.',
+      inputSchema: z.object({
+        to: z.email().describe('Recipient email for the test'),
+        templateId: z.string().describe('Template ID, e.g. d-xxxxxxxxxxxxxxxx'),
+        mockData: z
+          .record(z.string(), z.unknown())
+          .describe(
+            'Mock dynamic template data as JSON, e.g. {"customerName":"Test User","siteUrl":"https://example.com"}',
+          ),
+        fromEmail: z.email().optional().describe('Override sender email'),
+        fromName: z.string().optional().describe('Override sender name'),
+        liveDelivery: z
+          .boolean()
+          .optional()
+          .describe('Default false. If true, sends live mail instead of sandbox mode.'),
+        confirmToken: ConfirmTokenSchema.optional(),
+      }),
+      outputSchema: SendTestEmailOutputSchema,
+    },
+    async ({
+      to,
+      templateId,
+      mockData,
+      fromEmail,
+      fromName,
+      liveDelivery = false,
+      confirmToken,
+    }) => {
+      if (liveDelivery && confirmToken !== 'CONFIRM') {
+        throw new Error(
+          'Set confirmToken="CONFIRM" with liveDelivery=true to send a live test email.',
+        );
+      }
+
+      const request = {
+        personalizations: [
+          {
+            to: [{ email: to }],
+            dynamicTemplateData: mockData as Record<string, unknown>,
+          },
+        ],
+        from: {
+          email: fromEmail ?? defaultFromEmail,
+          name: fromName ?? defaultFromName,
+        },
+        templateId,
+      };
+      const report = await runSendPreflight(client, request, {
+        checkSenderIdentity: true,
+      });
+      if (!report.ok) {
+        return {
+          structuredContent: {
+            sent: false,
+            sandbox: !liveDelivery,
+            report,
+            statusCode: null,
+            messageId: null,
+          },
+          content: [
+            {
+              type: 'text',
+              text: 'Test email skipped because preflight found blockers.',
+            },
+          ],
+        };
+      }
+
+      const payload = toMailSendPayload(request);
+      if (!liveDelivery) {
+        payload.mail_settings = {
+          ...payload.mail_settings,
+          sandbox_mode: { enable: true },
+        };
+      }
+
+      const result = await client.sendMail(payload);
+
+      return {
+        structuredContent: {
+          sent: true,
+          sandbox: !liveDelivery,
+          report,
+          statusCode: result.statusCode,
+          messageId: result.messageId || null,
+        },
+        content: [
+          {
+            type: 'text',
+            text: [
+              liveDelivery
+                ? 'Live test email accepted by SendGrid.'
+                : 'Sandbox test email accepted by SendGrid (no live delivery).',
+              `To:         ${to}`,
+              `Template:   ${templateId}`,
+              `Status:     ${result.statusCode}`,
+              `Message ID: ${result.messageId || '(not returned)'}`,
+            ].join('\n'),
+          },
+        ],
+      };
+    },
+  );
+}