@neschadin/sendgrid-mcp 0.0.0-stage → 3.0.0

package/src/config.ts

@@ -0,0 +1,197 @@
+import { z } from 'zod';
+
+const RegionSchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .pipe(z.enum(['global', 'eu']));
+
+const HttpUrlSchema = z.url({ protocol: /^https?$/ });
+
+const ConfigInputSchema = z.object({
+  apiKey: z.string().min(1),
+  fromEmail: z.email(),
+  fromName: z.string().min(1).default('SendGrid MCP'),
+  region: RegionSchema.default('global'),
+  apiBaseUrl: HttpUrlSchema.optional(),
+  onBehalfOf: z.string().trim().min(1).optional(),
+});
+
+export type McpTransport = 'stdio' | 'http';
+export type HttpAuthMode = 'token' | 'none';
+
+export interface HttpEndpointConfig {
+  host: string;
+  port: number;
+  authMode: HttpAuthMode;
+  authToken?: string;
+  allowedHosts: string[];
+  allowedOrigins: string[];
+  trustProxy: boolean;
+  tlsKeyFile?: string;
+  tlsCertFile?: string;
+}
+
+export type AppConfig = z.output<typeof ConfigInputSchema> & {
+  apiBaseUrl: string;
+  preferEmailLogs: boolean;
+  transport: McpTransport;
+  http?: HttpEndpointConfig;
+};
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
+
+const CONFIG_HELP = `SendGrid MCP credentials missing.
+
+Set SENDGRID_API_KEY and SENDGRID_FROM_EMAIL.
+Optional: SENDGRID_REGION=global|eu (default global), SENDGRID_API_BASE_URL, SENDGRID_FROM_NAME, SENDGRID_ON_BEHALF_OF, READ_ONLY=true.
+Remote MCP: MCP_TRANSPORT=http, MCP_HTTP_HOST, MCP_HTTP_PORT, MCP_AUTH_TOKEN.
+Non-loopback HTTP requires MCP_AUTH_TOKEN and either TLS files or MCP_TRUST_PROXY=true.`;
+
+function blankToUndefined(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function loadConfig(
+  env: Record<string, string | undefined> = Bun.env,
+): AppConfig {
+  const apiKey = blankToUndefined(env['SENDGRID_API_KEY']);
+  const fromEmail = blankToUndefined(env['SENDGRID_FROM_EMAIL']);
+  if (!apiKey || !fromEmail) {
+    throw new Error(CONFIG_HELP);
+  }
+
+  const region = blankToUndefined(env['SENDGRID_REGION']);
+  const apiBaseUrl = blankToUndefined(env['SENDGRID_API_BASE_URL']);
+  const fromName = blankToUndefined(env['SENDGRID_FROM_NAME']);
+  const onBehalfOf = blankToUndefined(env['SENDGRID_ON_BEHALF_OF']);
+
+  const parsed = ConfigInputSchema.safeParse({
+    apiKey,
+    fromEmail,
+    ...(fromName ? { fromName } : {}),
+    ...(region ? { region } : {}),
+    ...(apiBaseUrl ? { apiBaseUrl } : {}),
+    ...(onBehalfOf ? { onBehalfOf } : {}),
+  });
+  if (!parsed.success) {
+    throw new Error(
+      `Invalid SendGrid MCP config: ${z.prettifyError(parsed.error)}`,
+    );
+  }
+
+  const resolvedBaseUrl =
+    parsed.data.apiBaseUrl ??
+    (parsed.data.region === 'eu'
+      ? 'https://api.eu.sendgrid.com/v3'
+      : 'https://api.sendgrid.com/v3');
+
+  const transport = resolveTransport(env);
+  const http = transport === 'http' ? resolveHttpEndpoint(env) : undefined;
+
+  return {
+    ...parsed.data,
+    apiBaseUrl: resolvedBaseUrl.replace(/\/+$/u, ''),
+    preferEmailLogs: parsed.data.region === 'eu',
+    transport,
+    ...(http ? { http } : {}),
+  };
+}
+
+function resolveTransport(env: Record<string, string | undefined>): McpTransport {
+  const raw = blankToUndefined(env['MCP_TRANSPORT'])?.toLowerCase() ?? 'stdio';
+  if (raw === 'stdio' || raw === 'http') return raw;
+  throw new Error('MCP_TRANSPORT must be stdio or http');
+}
+
+function splitList(value: string | undefined): string[] {
+  return (value ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter((item) => item.length > 0);
+}
+
+function resolveHttpEndpoint(
+  env: Record<string, string | undefined>,
+): HttpEndpointConfig {
+  const host = blankToUndefined(env['MCP_HTTP_HOST']) ?? '127.0.0.1';
+  const portRaw = blankToUndefined(env['MCP_HTTP_PORT']) ?? '3000';
+  const port = Number(portRaw);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error('MCP_HTTP_PORT must be an integer from 1 to 65535');
+  }
+
+  const authRaw = blankToUndefined(env['MCP_AUTH_MODE'])?.toLowerCase() ?? 'token';
+  if (authRaw !== 'token' && authRaw !== 'none') {
+    throw new Error('MCP_AUTH_MODE must be token or none');
+  }
+  const authToken = blankToUndefined(env['MCP_AUTH_TOKEN']);
+  const loopback = LOOPBACK_HOSTS.has(host);
+  if (authRaw === 'none' && !loopback) {
+    throw new Error(
+      'MCP_AUTH_MODE=none is only allowed when MCP_HTTP_HOST is loopback. Set MCP_AUTH_TOKEN.',
+    );
+  }
+  if (authRaw === 'token' && !authToken) {
+    throw new Error('MCP_AUTH_TOKEN is required when MCP_TRANSPORT=http and MCP_AUTH_MODE=token');
+  }
+
+  const tlsKeyFile = blankToUndefined(env['MCP_TLS_KEY_FILE']);
+  const tlsCertFile = blankToUndefined(env['MCP_TLS_CERT_FILE']);
+  if (Boolean(tlsKeyFile) !== Boolean(tlsCertFile)) {
+    throw new Error('MCP_TLS_KEY_FILE and MCP_TLS_CERT_FILE must be set together');
+  }
+  const trustProxy = ['1', 'true', 'yes', 'on'].includes(
+    blankToUndefined(env['MCP_TRUST_PROXY'])?.toLowerCase() ?? '',
+  );
+  if (!loopback && !tlsKeyFile && !trustProxy) {
+    throw new Error(
+      `Refusing plaintext HTTP on ${host}. Set MCP_TLS_KEY_FILE and MCP_TLS_CERT_FILE, or MCP_TRUST_PROXY=true behind a TLS proxy.`,
+    );
+  }
+
+  const allowedHosts = splitList(env['MCP_ALLOWED_HOSTS']);
+  const allowedOrigins = splitList(env['MCP_ALLOWED_ORIGINS']);
+  if (!loopback && allowedHosts.length === 0) {
+    throw new Error(
+      'MCP_ALLOWED_HOSTS is required when MCP_HTTP_HOST is not loopback',
+    );
+  }
+
+  return {
+    host,
+    port,
+    authMode: authRaw,
+    ...(authToken ? { authToken } : {}),
+    allowedHosts,
+    allowedOrigins,
+    trustProxy,
+    ...(tlsKeyFile ? { tlsKeyFile } : {}),
+    ...(tlsCertFile ? { tlsCertFile } : {}),
+  };
+}
+
+export const MAX_TOOL_INPUT_ELEMENTS = 10_000;
+
+export function buildServerInstructions(config: AppConfig): string {
+  const behalf = config.onBehalfOf
+    ? `on-behalf-of: ${config.onBehalfOf}`
+    : 'on-behalf-of: not set';
+
+  return `SendGrid MCP for transactional email, dynamic templates, delivery diagnostics, and console settings. Contact and list marketing CRUD is out of scope.
+
+This instance: region ${config.region}, API ${config.apiBaseUrl}, from ${config.fromEmail}. ${behalf}.
+READ_ONLY is checked on each call. When true, send and mutating tools return an error before any SendGrid request.
+
+Workflow:
+1. Safe send: sendgrid_validate_send_request, then sendgrid_send_with_preflight. sendgrid_send_email_advanced skips those checks.
+2. POST /v3/mail/send returns x-message-id, which is not msg_id. Pass that header as xMessageId to sendgrid_search_message_activity (compiled to msg_id LIKE '<id>%'), then sendgrid_get_message_activity for the event chain (reason, bounce_type, asm_group_id, outbound_ip).
+3. Delivery incident: search activity, sendgrid_check_suppression, sendgrid_triage_delivery_issue. Remove one suppression with sendgrid_delete_suppression and confirmToken "CONFIRM". GET /v3/messages has no offset. On Activity 403/404, and on an empty Activity result when region is eu, use Email Logs (sendgrid_search_email_logs).
+4. 403: sendgrid_get_scopes. Email Activity may require the add-on. Browser, device, and client stats retain about 7 days.
+5. Event Webhook config is in SendGrid. A local receiver exists only when SENDGRID_EVENT_WEBHOOK_PORT is set; its buffer is in-memory.
+6. Mutating tools require confirmToken "CONFIRM". Tool arguments are rejected above ${MAX_TOOL_INPUT_ELEMENTS} combined array elements and object members. Responses redact oauth_client_secret and api_key values.
+7. Subusers: sendgrid_list_subusers, then pass username as onBehalfOf. onBehalfOf="parent" ignores SENDGRID_ON_BEHALF_OF for that call.
+8. Event Webhooks: list/get/update/toggle, or sendgrid_manage_event_webhook with action create|delete|test and confirmToken "CONFIRM".
+9. Transport: ${config.transport}${config.http ? ` at ${config.http.host}:${config.http.port}/mcp (${config.http.authMode} auth)` : ''}.`;
+}

package/src/http.ts

@@ -0,0 +1,132 @@
+import { timingSafeEqual } from 'node:crypto';
+import {
+  createMcpHandler,
+  hostHeaderValidationResponse,
+  localhostAllowedHostnames,
+  localhostAllowedOrigins,
+  originValidationResponse,
+  type AuthInfo,
+  type McpServer,
+} from '@modelcontextprotocol/server';
+import type { HttpEndpointConfig } from './config';
+import { logError, logInfo } from './logger';
+
+function tokenEquals(presented: string, expected: string): boolean {
+  const left = Buffer.from(presented);
+  const right = Buffer.from(expected);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+export function authorizeBearer(
+  request: Request,
+  expectedToken: string,
+): AuthInfo | Response {
+  const header = request.headers.get('authorization');
+  const presented = header?.match(/^Bearer\s+(\S+)\s*$/iu)?.[1];
+  if (!presented || !tokenEquals(presented, expectedToken)) {
+    return new Response(JSON.stringify({ error: 'invalid_token' }), {
+      status: 401,
+      headers: {
+        'content-type': 'application/json',
+        'www-authenticate': 'Bearer error="invalid_token"',
+        'cache-control': 'no-store',
+      },
+    });
+  }
+
+  return {
+    token: presented,
+    clientId: 'static-token',
+    scopes: [],
+    expiresAt: Math.floor(Date.now() / 1000) + 3600,
+  };
+}
+
+export function createHttpFetch(options: {
+  factory: () => McpServer;
+  http: HttpEndpointConfig;
+  onerror?: (error: Error) => void;
+}): {
+  fetch: (request: Request) => Promise<Response>;
+  close: () => Promise<void>;
+} {
+  const handler = createMcpHandler(options.factory, {
+    legacy: 'stateless',
+    onerror: options.onerror,
+  });
+  const hosts =
+    options.http.allowedHosts.length > 0
+      ? options.http.allowedHosts
+      : localhostAllowedHostnames();
+  const origins =
+    options.http.allowedOrigins.length > 0
+      ? options.http.allowedOrigins
+      : localhostAllowedOrigins();
+
+  return {
+    close: () => handler.close(),
+    fetch: async (request) => {
+      const url = new URL(request.url);
+      if (
+        request.method === 'GET' &&
+        (url.pathname === '/health' || url.pathname === '/health/')
+      ) {
+        return Response.json({ status: 'ok' });
+      }
+      if (url.pathname !== '/mcp' && url.pathname !== '/mcp/') {
+        return new Response('Not found', { status: 404 });
+      }
+
+      const rejected =
+        hostHeaderValidationResponse(request, hosts) ??
+        originValidationResponse(request, origins);
+      if (rejected) return rejected;
+
+      let authInfo: AuthInfo | undefined;
+      if (options.http.authMode === 'token') {
+        const auth = authorizeBearer(request, options.http.authToken ?? '');
+        if (auth instanceof Response) return auth;
+        authInfo = auth;
+      }
+
+      return handler.fetch(request, authInfo ? { authInfo } : undefined);
+    },
+  };
+}
+
+export function startHttpServer(options: {
+  factory: () => McpServer;
+  http: HttpEndpointConfig;
+}): { url: string; stop: () => Promise<void> } {
+  const endpoint = createHttpFetch({
+    factory: options.factory,
+    http: options.http,
+    onerror: (error) => {
+      logError(`MCP HTTP error: ${error.message}`);
+    },
+  });
+  const tls =
+    options.http.tlsKeyFile && options.http.tlsCertFile
+      ? {
+          key: Bun.file(options.http.tlsKeyFile),
+          cert: Bun.file(options.http.tlsCertFile),
+        }
+      : undefined;
+  const server = Bun.serve({
+    hostname: options.http.host,
+    port: options.http.port,
+    fetch: endpoint.fetch,
+    ...(tls ? { tls } : {}),
+  });
+  const scheme = tls ? 'https' : 'http';
+  const url = `${scheme}://${server.hostname ?? options.http.host}:${server.port}/mcp`;
+  logInfo(`HTTP MCP listening on ${url}`);
+
+  return {
+    url,
+    stop: async () => {
+      await endpoint.close();
+      await server.stop(true);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+import { McpServer } from '@modelcontextprotocol/server';
+import {
+  serveStdio,
+  StdioServerTransport,
+} from '@modelcontextprotocol/server/stdio';
+import { version } from '../package.json';
+import { SendGridClient } from './client';
+import {
+  buildServerInstructions,
+  loadConfig,
+  MAX_TOOL_INPUT_ELEMENTS,
+} from './config';
+import { startHttpServer } from './http';
+import { logError, logInfo, logWarn } from './logger';
+import { registerDiagnosticsTools } from './tools/diagnostics';
+import { registerEmailTools } from './tools/email';
+import { registerPreflightTools } from './tools/preflight';
+import { registerSyncTools } from './tools/sync';
+import { registerTemplateTools } from './tools/templates';
+import { registerAccountTools } from './tools/account';
+import { registerConsoleSettingsTools } from './tools/console_settings';
+import {
+  startWebhookReceiverFromEnv,
+  stopWebhookReceiver,
+} from './webhook_receiver';
+
+function buildServer(
+  client: SendGridClient,
+  fromEmail: string,
+  fromName: string,
+  instructions: string,
+): McpServer {
+  const server = new McpServer(
+    {
+      name: 'sendgrid-mcp-server',
+      version,
+    },
+    {
+      instructions,
+      maxToolInputElements: MAX_TOOL_INPUT_ELEMENTS,
+    },
+  );
+
+  registerTemplateTools(server, client);
+  registerEmailTools(server, client, fromEmail, fromName);
+  registerPreflightTools(server, client);
+  registerDiagnosticsTools(server, client);
+  registerSyncTools(server, client);
+  registerAccountTools(server, client);
+  registerConsoleSettingsTools(server, client);
+
+  return server;
+}
+
+async function main() {
+  const env = loadConfig();
+  if (!env.apiKey.startsWith('SG.')) {
+    logWarn('SENDGRID_API_KEY does not start with SG.');
+  }
+  try {
+    startWebhookReceiverFromEnv();
+  } catch (error) {
+    logWarn(`Webhook receiver not started: ${String(error)}`);
+  }
+  const client = new SendGridClient(env.apiKey, env.apiBaseUrl, {
+    onBehalfOf: env.onBehalfOf,
+    preferEmailLogs: env.preferEmailLogs,
+  });
+  const instructions = buildServerInstructions(env);
+  const factory = () =>
+    buildServer(client, env.fromEmail, env.fromName, instructions);
+
+  if (env.transport === 'http' && env.http) {
+    const endpoint = startHttpServer({ factory, http: env.http });
+    let shuttingDown = false;
+    const shutdown = async (signal: string) => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      logInfo(`Shutdown requested (${signal})`);
+      try {
+        await endpoint.stop();
+      } finally {
+        stopWebhookReceiver();
+        process.exit(0);
+      }
+    };
+    process.on('SIGINT', () => {
+      void shutdown('SIGINT');
+    });
+    process.on('SIGTERM', () => {
+      void shutdown('SIGTERM');
+    });
+    logInfo('Server started');
+    return;
+  }
+
+  // serveStdio owns onclose. Wrap close so the webhook listener (a keep-alive
+  // handle) is released when stdin ends or the process is signalled.
+  const transport = new StdioServerTransport();
+  const closeTransport = transport.close.bind(transport);
+  transport.close = async () => {
+    try {
+      await closeTransport();
+    } finally {
+      logInfo('Transport closed');
+      stopWebhookReceiver();
+    }
+  };
+
+  const handle = serveStdio(factory,
+    {
+      transport,
+      onerror: (error) => {
+        logError(`MCP transport error: ${error.message}`);
+      },
+    },
+  );
+
+  let shuttingDown = false;
+  const shutdown = async (signal: string) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    logInfo(`Shutdown requested (${signal})`);
+    try {
+      await handle.close();
+    } finally {
+      stopWebhookReceiver();
+      process.exit(0);
+    }
+  };
+
+  process.on('SIGINT', () => {
+    void shutdown('SIGINT');
+  });
+  process.on('SIGTERM', () => {
+    void shutdown('SIGTERM');
+  });
+
+  logInfo('Server started');
+}
+
+main().catch((err) => {
+  logError(`Fatal: ${String(err)}`);
+  stopWebhookReceiver();
+  process.exit(1);
+});

package/src/logger.ts

@@ -0,0 +1,43 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+function parseLevel(input: string | undefined): LogLevel {
+  const normalized = (input ?? '').trim().toLowerCase();
+  if (normalized === 'debug') return 'debug';
+  if (normalized === 'warn') return 'warn';
+  if (normalized === 'error') return 'error';
+  return 'info';
+}
+
+const currentLevel = parseLevel(Bun.env['SENDGRID_MCP_LOG_LEVEL']);
+
+function canLog(level: LogLevel): boolean {
+  return LEVEL_ORDER[level] >= LEVEL_ORDER[currentLevel];
+}
+
+export function log(level: LogLevel, message: string): void {
+  if (!canLog(level)) return;
+  process.stderr.write(`[sendgrid-mcp] ${level.toUpperCase()} ${message}\n`);
+}
+
+export function logDebug(message: string): void {
+  log('debug', message);
+}
+
+export function logInfo(message: string): void {
+  log('info', message);
+}
+
+export function logWarn(message: string): void {
+  log('warn', message);
+}
+
+export function logError(message: string): void {
+  log('error', message);
+}

package/src/redact.ts

@@ -0,0 +1,91 @@
+const SECRET_KEYS = new Set([
+  'oauth_client_secret',
+  'api_key',
+  'apikey',
+  'authorization',
+  'password',
+]);
+
+const JSON_SECRET_STRING =
+  /"(oauth_client_secret|api_key|apikey|authorization|password)"\s*:\s*("(?:\\.|[^"\\])*"|null)/gi;
+
+export function formatRedactedSecret(value: unknown): string {
+  if (typeof value === 'string' && value.startsWith('<redacted')) {
+    return value;
+  }
+  if (typeof value === 'string') {
+    return `<redacted len=${value.length}>`;
+  }
+  if (value == null) return '<redacted>';
+  return '<redacted>';
+}
+
+export function redactSensitiveFields(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(redactSensitiveFields);
+  }
+
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, nested] of Object.entries(
+      value as Record<string, unknown>,
+    )) {
+      out[key] = SECRET_KEYS.has(key.toLowerCase())
+        ? formatRedactedSecret(nested)
+        : redactSensitiveFields(nested);
+    }
+    return out;
+  }
+
+  return value;
+}
+
+export function redactSecretsInText(text: string): string {
+  if (!JSON_SECRET_STRING.test(text)) {
+    JSON_SECRET_STRING.lastIndex = 0;
+    return text;
+  }
+  JSON_SECRET_STRING.lastIndex = 0;
+
+  try {
+    return JSON.stringify(redactSensitiveFields(JSON.parse(text)), null, 2);
+  } catch {
+    JSON_SECRET_STRING.lastIndex = 0;
+    return text.replace(JSON_SECRET_STRING, (_match, key: string, raw: string) => {
+      try {
+        return `"${key}": ${JSON.stringify(formatRedactedSecret(JSON.parse(raw)))}`;
+      } catch {
+        return `"${key}": ${JSON.stringify(formatRedactedSecret(undefined))}`;
+      }
+    });
+  }
+}
+
+export function redactToolResult(result: unknown): unknown {
+  if (!result || typeof result !== 'object') return result;
+  const record = result as Record<string, unknown>;
+  const content = Array.isArray(record['content'])
+    ? record['content'].map((block) => {
+        if (
+          block &&
+          typeof block === 'object' &&
+          (block as { type?: unknown }).type === 'text' &&
+          typeof (block as { text?: unknown }).text === 'string'
+        ) {
+          return {
+            ...(block as Record<string, unknown>),
+            text: redactSecretsInText((block as { text: string }).text),
+          };
+        }
+        return block;
+      })
+    : record['content'];
+
+  return {
+    ...record,
+    ...(content !== undefined ? { content } : {}),
+    ...(record['structuredContent'] !== undefined
+      ? { structuredContent: redactSensitiveFields(record['structuredContent']) }
+      : {}),
+  };
+}

package/src/tool_signal.ts

@@ -0,0 +1,50 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+const toolAbortSignal = new AsyncLocalStorage<AbortSignal>();
+const onBehalfOfStore = new AsyncLocalStorage<string>();
+
+/** Call the parent account even when SENDGRID_ON_BEHALF_OF is set. */
+export const PARENT_ACCOUNT = 'parent';
+
+export function currentOnBehalfOf(): string | undefined {
+  return onBehalfOfStore.getStore();
+}
+
+export function resolveOnBehalfOfHeader(
+  override: string | undefined,
+  configured: string | undefined,
+): string | undefined {
+  if (override === PARENT_ACCOUNT) return undefined;
+  return override ?? configured;
+}
+
+export function runWithOnBehalfOf<T>(
+  value: string | undefined,
+  run: () => Promise<T>,
+): Promise<T> {
+  if (value === undefined) return run();
+  return onBehalfOfStore.run(value, run);
+}
+
+export function onBehalfOfFromArgs(args: unknown): string | undefined {
+  if (!args || typeof args !== 'object') return undefined;
+  const value = (args as { onBehalfOf?: unknown }).onBehalfOf;
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+export function currentToolAbortSignal(): AbortSignal | undefined {
+  return toolAbortSignal.getStore();
+}
+
+export function runWithToolAbortSignal<T>(
+  signal: AbortSignal | undefined,
+  run: () => Promise<T>,
+): Promise<T> {
+  return signal ? toolAbortSignal.run(signal, run) : run();
+}
+
+export function abortSignalFromExtra(extra: unknown): AbortSignal | undefined {
+  if (!extra || typeof extra !== 'object') return undefined;
+  const signal = (extra as { mcpReq?: { signal?: unknown } }).mcpReq?.signal;
+  return signal instanceof AbortSignal ? signal : undefined;
+}