@neschadin/sendgrid-mcp 0.0.0-stage → 3.0.0

package/src/tools/console_settings.ts

@@ -0,0 +1,329 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+import type {
+  MailSettingName,
+  SendGridClient,
+  TrackingSettingName,
+} from '../client';
+import {
+  EnforcedTlsOutputSchema,
+  InboundParseSettingsListOutputSchema,
+  jsonReadResult,
+  jsonText,
+  MailSettingsListOutputSchema,
+  paginateArray,
+  SettingDetailOutputSchema,
+  TrackingSettingsListOutputSchema,
+} from './output_schemas';
+import {
+  ensureSafeToolRegistration,
+  ListPagingInputFields,
+  ReadInputFields,
+} from './tool_utils';
+
+const ConfirmTokenSchema = z
+  .literal('CONFIRM')
+  .describe('Safety token required for mutating SendGrid console settings');
+
+const MailSettingNameSchema = z.enum([
+  'address_whitelist',
+  'bcc',
+  'bounce_purge',
+  'footer',
+  'forward_bounce',
+  'forward_spam',
+  'plain_content',
+  'spam_check',
+  'template',
+]);
+
+const TrackingSettingNameSchema = z.enum([
+  'click',
+  'open',
+  'subscription',
+  'google_analytics',
+]);
+
+const SettingValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+  z.array(z.string()),
+]);
+
+export function registerConsoleSettingsTools(
+  server: McpServer,
+  client: SendGridClient,
+) {
+  ensureSafeToolRegistration(server);
+
+  server.registerTool(
+    'get_enforced_tls',
+    {
+      description:
+        'Read Enforced TLS settings (GET /v3/user/settings/enforced_tls). require_tls drops mail when the recipient MX does not offer TLS.',
+      inputSchema: z.object({ ...ReadInputFields }),
+      outputSchema: EnforcedTlsOutputSchema,
+    },
+    async ({ response_format }) => {
+      const settings = await client.getEnforcedTls();
+      return jsonReadResult(
+        settings,
+        `require_tls=${settings.require_tls} require_valid_cert=${settings.require_valid_cert} version=${settings.version}`,
+        response_format,
+      );
+    },
+  );
+
+  server.registerTool(
+    'list_mail_settings',
+    {
+      description:
+        'List SendGrid mail settings summaries (footer, bounce purge, spam check, etc.).',
+      inputSchema: z.object({ ...ListPagingInputFields }),
+      outputSchema: MailSettingsListOutputSchema,
+    },
+    async (params) => {
+      const response = await client.listMailSettings({
+        limit: params.limit,
+        offset: params.offset,
+      });
+      const settings = response.result ?? [];
+      const { items, pagination } = paginateArray(
+        settings,
+        params.limit,
+        params.offset,
+      );
+      return jsonReadResult(
+        { ...pagination, settings: items },
+        jsonText(response),
+        params.response_format,
+      );
+    },
+  );
+
+  server.registerTool(
+    'get_mail_setting',
+    {
+      description: 'Read one SendGrid mail setting by name.',
+      inputSchema: z.object({
+        setting: MailSettingNameSchema,
+        ...ReadInputFields,
+      }),
+      outputSchema: SettingDetailOutputSchema,
+    },
+    async ({ setting, response_format }) =>
+      jsonReadResult(
+        await client.getMailSetting(setting as MailSettingName),
+        undefined,
+        response_format,
+      ),
+  );
+
+  server.registerTool(
+    'list_tracking_settings',
+    {
+      description:
+        'List SendGrid tracking settings summaries (click, open, subscription, etc.).',
+      inputSchema: z.object({ ...ListPagingInputFields }),
+      outputSchema: TrackingSettingsListOutputSchema,
+    },
+    async (params) => {
+      const response = await client.listTrackingSettings();
+      const settings = response.result ?? [];
+      const { items, pagination } = paginateArray(
+        settings,
+        params.limit,
+        params.offset,
+      );
+      return jsonReadResult(
+        { ...pagination, settings: items },
+        jsonText(response),
+        params.response_format,
+      );
+    },
+  );
+
+  server.registerTool(
+    'get_tracking_setting',
+    {
+      description: 'Read one SendGrid tracking setting by name.',
+      inputSchema: z.object({
+        setting: TrackingSettingNameSchema,
+        ...ReadInputFields,
+      }),
+      outputSchema: SettingDetailOutputSchema,
+    },
+    async ({ setting, response_format }) =>
+      jsonReadResult(
+        await client.getTrackingSetting(setting as TrackingSettingName),
+        undefined,
+        response_format,
+      ),
+  );
+
+  server.registerTool(
+    'list_inbound_parse_settings',
+    {
+      description: 'List inbound parse (receive email webhook) settings.',
+      inputSchema: z.object({ ...ListPagingInputFields }),
+      outputSchema: InboundParseSettingsListOutputSchema,
+    },
+    async (params) => {
+      const settings = await client.listInboundParseSettings();
+      const { items, pagination } = paginateArray(
+        settings,
+        params.limit,
+        params.offset,
+      );
+      return jsonReadResult(
+        { ...pagination, settings: items },
+        jsonText(items),
+        params.response_format,
+      );
+    },
+  );
+
+  server.registerTool(
+    'update_mail_setting',
+    {
+      description:
+        'Update one SendGrid mail setting (PATCH /mail_settings/{name}). Payload fields depend on setting type.',
+      inputSchema: z.object({
+        confirmToken: ConfirmTokenSchema,
+        setting: MailSettingNameSchema,
+        settings: z
+          .record(z.string(), SettingValueSchema)
+          .describe(
+            'Setting payload, e.g. { "enabled": true } or footer { "enabled", "html_content", "plain_content" }',
+          ),
+      }),
+    },
+    async ({ setting, settings }) => ({
+      content: [
+        {
+          type: 'text',
+          text: jsonText(
+            await client.updateMailSetting(
+              setting as MailSettingName,
+              settings,
+            ),
+          ),
+        },
+      ],
+    }),
+  );
+
+  server.registerTool(
+    'update_tracking_setting',
+    {
+      description:
+        'Update one SendGrid tracking setting (click/open/subscription/google_analytics).',
+      inputSchema: z.object({
+        confirmToken: ConfirmTokenSchema,
+        setting: TrackingSettingNameSchema,
+        settings: z
+          .record(z.string(), SettingValueSchema)
+          .describe(
+            'Tracking payload, commonly { "enabled": true }. Open tracking may include substitution_tag.',
+          ),
+      }),
+    },
+    async ({ setting, settings }) => ({
+      content: [
+        {
+          type: 'text',
+          text: jsonText(
+            await client.updateTrackingSetting(
+              setting as TrackingSettingName,
+              settings,
+            ),
+          ),
+        },
+      ],
+    }),
+  );
+
+  server.registerTool(
+    'create_inbound_parse_setting',
+    {
+      description:
+        'Create inbound parse setting. Hostname MX must point to SendGrid.',
+      inputSchema: z.object({
+        confirmToken: ConfirmTokenSchema,
+        url: z.url(),
+        hostname: z.string().min(1),
+        spamCheck: z.boolean().optional(),
+        sendRaw: z.boolean().optional(),
+      }),
+    },
+    async ({ url, hostname, spamCheck, sendRaw }) => ({
+      content: [
+        {
+          type: 'text',
+          text: jsonText(
+            await client.createInboundParseSetting({
+              url,
+              hostname,
+              spam_check: spamCheck,
+              send_raw: sendRaw,
+            }),
+          ),
+        },
+      ],
+    }),
+  );
+
+  server.registerTool(
+    'update_inbound_parse_setting',
+    {
+      description: 'Update inbound parse setting for a hostname.',
+      inputSchema: z.object({
+        confirmToken: ConfirmTokenSchema,
+        hostname: z.string().min(1),
+        url: z.url().optional(),
+        newHostname: z.string().min(1).optional(),
+        spamCheck: z.boolean().optional(),
+        sendRaw: z.boolean().optional(),
+      }),
+    },
+    async ({ hostname, url, newHostname, spamCheck, sendRaw }) => ({
+      content: [
+        {
+          type: 'text',
+          text: jsonText(
+            await client.updateInboundParseSetting(hostname, {
+              url,
+              hostname: newHostname,
+              spam_check: spamCheck,
+              send_raw: sendRaw,
+            }),
+          ),
+        },
+      ],
+    }),
+  );
+
+  server.registerTool(
+    'delete_inbound_parse_setting',
+    {
+      description: 'Delete inbound parse setting by hostname.',
+      inputSchema: z.object({
+        confirmToken: ConfirmTokenSchema,
+        hostname: z.string().min(1),
+      }),
+    },
+    async ({ hostname }) => {
+      await client.deleteInboundParseSetting(hostname);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Inbound parse setting for hostname "${hostname}" deleted.`,
+          },
+        ],
+      };
+    },
+  );
+}

package/src/tools/delivery_trace.ts

@@ -0,0 +1,291 @@
+import {
+  isSendGridApiError,
+  type EmailLogMessage,
+  type SendGridClient,
+  type SendGridMessageActivity,
+} from '../client';
+
+export function activityQueryForXMessageId(xMessageId: string): string {
+  const id = xMessageId.trim();
+  if (id.length === 0) {
+    throw new Error('xMessageId is empty');
+  }
+  if (id.includes("'") || id.includes('"') || /\s/u.test(id)) {
+    throw new Error(
+      'xMessageId contains quotes or whitespace and cannot be placed in an Email Activity query',
+    );
+  }
+  return `msg_id LIKE '${id}%'`;
+}
+
+export function compileActivitySearch(input: {
+  query?: string;
+  xMessageId?: string;
+}): string {
+  const like = input.xMessageId
+    ? activityQueryForXMessageId(input.xMessageId)
+    : undefined;
+  const query = input.query?.trim();
+  if (like && query) return `(${query}) AND ${like}`;
+  if (like) return like;
+  if (query) return query;
+  throw new Error('Provide query or xMessageId');
+}
+
+const EMAIL_LOGS_FIELDS = new Set([
+  'sg_message_id',
+  'subject',
+  'to_email',
+  'status',
+  'reason',
+  'categories',
+  'sg_message_id_created_at',
+]);
+
+/** Activity queries using msg_id/from_email/LIKE are rejected by POST /v3/logs. */
+export function activityQueryCanFallbackToLogs(query: string): boolean {
+  if (/\bLIKE\b/iu.test(query)) return false;
+  const identifiers = query.match(/[a-z_][a-z0-9_]*(?=\s*(?:=|IN\b|<|>))/giu) ?? [];
+  if (identifiers.length === 0) return false;
+  return identifiers.every((identifier) =>
+    EMAIL_LOGS_FIELDS.has(identifier.toLowerCase()),
+  );
+}
+
+export function rejectActivityOffset(offset: number | undefined): void {
+  if (offset !== undefined && offset > 0) {
+    throw new Error(
+      'GET /v3/messages does not document offset. A request that includes it still returns 200 and is not a reliable next page. Narrow the query with to_email, last_event_time, or msg_id LIKE.',
+    );
+  }
+}
+
+export function activityListMeta(count: number, limit: number): {
+  total_count: number;
+  count: number;
+  offset: number;
+  has_more: boolean;
+  next_offset: null;
+  note?: string;
+} {
+  const hasMore = count >= limit && count > 0;
+  return {
+    total_count: count,
+    count,
+    offset: 0,
+    has_more: hasMore,
+    next_offset: null,
+    ...(hasMore
+      ? {
+          note: 'Email Activity does not page with offset. Narrow the query (to_email, last_event_time, status) to see other messages.',
+        }
+      : {}),
+  };
+}
+
+export function logsEqualityQuery(
+  field: 'to_email' | 'sg_message_id',
+  value: string,
+): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.includes("'") || trimmed.includes('"')) {
+    throw new Error(`${field} cannot be quoted into an Email Logs query`);
+  }
+  return `${field}='${trimmed}'`;
+}
+
+export function summarizeActivityMessage(
+  message: SendGridMessageActivity,
+): string {
+  const lines = [
+    `msg_id=${message.msg_id}`,
+    `status=${message.status ?? 'n/a'}`,
+    `from=${message.from_email ?? 'n/a'}`,
+    `to=${message.to_email ?? 'n/a'}`,
+    `subject=${message.subject ?? 'n/a'}`,
+    `last_event_time=${message.last_event_time ?? 'n/a'}`,
+  ];
+  const asmGroupId = message['asm_group_id'];
+  if (typeof asmGroupId === 'number' || typeof asmGroupId === 'string') {
+    lines.push(`asm_group_id=${asmGroupId}`);
+  }
+  const outboundIp = message['outbound_ip'];
+  if (typeof outboundIp === 'string') {
+    lines.push(
+      `outbound_ip=${outboundIp} type=${String(message['outbound_ip_type'] ?? 'n/a')}`,
+    );
+  }
+  const reason = message['reason'];
+  if (typeof reason === 'string' && reason.length > 0) {
+    lines.push(`reason=${reason}`);
+  }
+  const events = message['events'];
+  if (Array.isArray(events) && events.length > 0) {
+    const last = events[events.length - 1];
+    if (last && typeof last === 'object') {
+      const event = last as Record<string, unknown>;
+      lines.push(
+        `last_event=${String(event['event_name'] ?? 'n/a')} reason=${String(event['reason'] ?? 'n/a')} bounce_type=${String(event['bounce_type'] ?? 'n/a')} mx=${String(event['mx_server'] ?? 'n/a')}`,
+      );
+    }
+    lines.push(`events=${events.length}`);
+  }
+  return lines.join(', ');
+}
+
+function mapLogMessage(row: EmailLogMessage): SendGridMessageActivity | undefined {
+  if (!row.sg_message_id) return undefined;
+  return {
+    msg_id: row.sg_message_id,
+    from_email: row.from_email,
+    to_email: row.to_email,
+    subject: row.subject,
+    status: row.status,
+    ...(row.reason ? { reason: row.reason } : {}),
+    ...(row.sg_message_id_created_at
+      ? { last_event_time: row.sg_message_id_created_at }
+      : {}),
+  };
+}
+
+async function logsMessages(
+  client: SendGridClient,
+  query: string,
+  limit: number,
+): Promise<SendGridMessageActivity[]> {
+  const logs = await client.searchEmailLogs({ query, limit });
+  return (logs.messages ?? []).flatMap((row) => {
+    const mapped = mapLogMessage(row);
+    return mapped ? [mapped] : [];
+  });
+}
+
+export async function searchActivityOrLogs(
+  client: SendGridClient,
+  query: string,
+  limit: number,
+): Promise<{
+  messages: SendGridMessageActivity[];
+  source: 'activity' | 'logs';
+  note?: string;
+}> {
+  try {
+    const response = await client.filterMessages(query, limit);
+    const messages = response.messages ?? [];
+    if (messages.length === 0 && client.preferEmailLogs) {
+      if (!activityQueryCanFallbackToLogs(query)) {
+        return {
+          messages,
+          source: 'activity',
+          note: 'Email Activity returned no rows. This query cannot be sent to Email Logs: POST /v3/logs rejects msg_id, from_email, and LIKE.',
+        };
+      }
+      try {
+        const fromLogs = await logsMessages(client, query, limit);
+        if (fromLogs.length > 0) {
+          return {
+            messages: fromLogs,
+            source: 'logs',
+            note: 'Email Activity returned no rows. SENDGRID_REGION=eu often has no Activity detail, so these rows are from POST /v3/logs.',
+          };
+        }
+      } catch (logsError) {
+        const logsText =
+          logsError instanceof Error ? logsError.message : String(logsError);
+        return {
+          messages: [],
+          source: 'activity',
+          note: `Email Activity returned no rows. Email Logs fallback failed: ${logsText}`,
+        };
+      }
+    }
+    return { messages, source: 'activity' };
+  } catch (error) {
+    if (
+      !isSendGridApiError(error) ||
+      (error.status !== 403 && error.status !== 404)
+    ) {
+      throw error;
+    }
+    if (!activityQueryCanFallbackToLogs(query)) {
+      throw new Error(
+        `Email Activity failed (${error.status}). Email Logs was not queried because POST /v3/logs rejects msg_id, from_email, and LIKE. Use to_email='...' with sendgrid_search_email_logs.`,
+      );
+    }
+    try {
+      const fromLogs = await logsMessages(client, query, limit);
+      return {
+        messages: fromLogs,
+        source: 'logs',
+        note: `Email Activity returned ${error.status}. Rows are from POST /v3/logs. Logs only accepts equality/IN on sg_message_id, subject, to_email, status, reason, categories, and sg_message_id_created_at.`,
+      };
+    } catch (logsError) {
+      const logsText =
+        logsError instanceof Error ? logsError.message : String(logsError);
+      throw new Error(
+        `Email Activity failed (${error.status}). Email Logs fallback also failed.\n${logsText}`,
+      );
+    }
+  }
+}
+
+export async function traceMessage(
+  client: SendGridClient,
+  msgId: string,
+): Promise<{ message: SendGridMessageActivity; note?: string }> {
+  try {
+    return { message: await client.getMessageById(msgId) };
+  } catch (error) {
+    if (
+      !isSendGridApiError(error) ||
+      (error.status !== 404 && error.status !== 403)
+    ) {
+      throw error;
+    }
+
+    const isXMessageId = !msgId.includes('.');
+    if (isXMessageId && error.status === 404) {
+      const found = await client.filterMessages(
+        activityQueryForXMessageId(msgId),
+        10,
+      );
+      const rows = found.messages ?? [];
+      const only = rows[0];
+      if (rows.length === 1 && only?.msg_id) {
+        return {
+          message: await client.getMessageById(only.msg_id),
+          note: `Resolved x-message-id ${msgId} to msg_id ${only.msg_id} via msg_id LIKE.`,
+        };
+      }
+      if (rows.length > 1) {
+        throw new Error(
+          `x-message-id ${msgId} matches ${rows.length} messages. Call get_message_activity with one full msg_id:\n${rows.map((row) => row.msg_id).join('\n')}`,
+        );
+      }
+      throw new Error(
+        `No Email Activity row for x-message-id ${msgId}. It may not be indexed yet, or this account has no Activity detail. Try search_email_logs with to_email equality.`,
+      );
+    }
+
+    if (msgId.includes('.')) {
+      try {
+        const fromLogs = await logsMessages(
+          client,
+          logsEqualityQuery('sg_message_id', msgId),
+          5,
+        );
+        const message = fromLogs[0];
+        if (message) {
+          return {
+            message,
+            note: `Email Activity returned ${error.status}. Loaded from POST /v3/logs, which has status and reason but no event chain.`,
+          };
+        }
+      } catch {
+        // Keep the original Activity error below.
+      }
+    }
+
+    throw error;
+  }
+}