@sendinel/mcp-server 1.0.10 → 1.0.12

package/build/tools/campaigns.js

@@ -1,20 +1,31 @@
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
-import { db } from '../db.js';
+import { NAME_FALLBACKS, renderTemplateString as renderTemplateVars, resolveBrandTokens } from '@sendinel/domain';
+import { adminDb, db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { checkPlanLimit } from '../plan-limits.js';
-import { buildVoicePrompt, buildEmailSystemPrompt, validateTemplate } from '../lib/voice.js';
+import { buildVoicePrompt, buildEmailSystemPrompt, deriveTemplateVariables, validateTemplate } from '../lib/voice.js';
 import { fireWebhookEvent } from '../lib/webhook-events.js';
 import { assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval } from '../lib/action-approvals.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
-import { getScheduleWindowBounds, groupScheduleByCampaign } from '../lib/schedule.js';
+import { getScheduleWindowBounds, groupScheduleByCampaign, parseFutureDate } from '../lib/schedule.js';
 import { sendEmailForSite } from '../lib/email-provider.js';
 import { renderTemplateString, resolveSurveyShortLink } from '../lib/survey-link-resolver.js';
 import { logAudit } from '../audit.js';
 import { recordBrandAssetUsage } from '../lib/brand-asset-usage.js';
 import { BLOCK_GENERATION_SCHEMA, blocksToHtml, blocksToText, normalizeComposerBlocks } from '../lib/composer-blocks.js';
+import { callSendinelV1 } from '../lib/v1-client.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
+const SENT_EMAIL_STATUSES = ['sent', 'delivered', 'opened', 'clicked', 'bounced', 'complained', 'unsubscribed'];
+function stripHtml(value) {
+    return value
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 function normalizeTriggerValue(value) {
     if (typeof value !== 'string')
         return null;
@@ -35,6 +46,21 @@ function buildCampaignTriggerConfig(value) {
         return null;
     return { events, tags };
 }
+function applyCampaignSendAtField(updates, sendAt, campaignType) {
+    if (sendAt === undefined)
+        return null;
+    if (sendAt === null) {
+        updates.send_at = null;
+        return null;
+    }
+    if (campaignType !== 'broadcast')
+        return 'send_at only applies to broadcast campaigns';
+    const parsed = parseFutureDate(sendAt, 'send_at');
+    if ('error' in parsed)
+        return parsed.error;
+    updates.send_at = parsed.scheduledAt;
+    return null;
+}
 async function applyCampaignTargetingFields(updates, input, projectId) {
     if (input.trigger_event_name !== undefined)
         updates.trigger_event_name = input.trigger_event_name?.trim() || null;
@@ -225,32 +251,14 @@ export function registerCampaignTools(server) {
             abandoned_days: z.number().int().min(1).max(365).optional(),
         },
     }, async ({ dry_run = false, dormant_draft_days, abandoned_days }) => {
-        const apiKey = process.env.SENDINEL_API_KEY;
-        if (!apiKey)
-            return j({ error: 'SENDINEL_API_KEY is required to run review_campaign_portfolio from MCP' });
-        const base = (process.env.NEXT_PUBLIC_APP_URL ?? process.env.SENDINEL_APP_URL ?? process.env.APP_URL ?? 'https://sendinel.ai').replace(/\/$/, '');
-        const res = await fetch(`${base}/api/v1/campaigns/review`, {
-            method: 'POST',
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                'Content-Type': 'application/json',
-                'X-Sendinel-Project-Id': getProjectId(),
-            },
-            body: JSON.stringify({
+        const result = await callSendinelV1('/api/v1/campaigns/review', {
+            body: {
                 dry_run,
                 ...(dormant_draft_days !== undefined ? { dormant_draft_days } : {}),
                 ...(abandoned_days !== undefined ? { abandoned_days } : {}),
-            }),
+            },
         });
-        const body = await res.text();
-        if (!res.ok)
-            return j({ error: `Campaign portfolio review failed: ${res.status}`, body });
-        try {
-            return j(JSON.parse(body));
-        }
-        catch {
-            return txt(body);
-        }
+        return result.ok ? j(result.data) : j({ error: result.error, status: result.status });
     });
     server.registerTool('get_campaign_calendar', {
         title: 'Get Campaign Calendar',
@@ -389,7 +397,7 @@ export function registerCampaignTools(server) {
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: 'Create a new email campaign. For triggered campaigns, provide one trigger shape: trigger_event_name, trigger_tag, trigger_type=date_field with trigger_config, or segment_id for ongoing audience targeting.',
+        description: 'Create a new email campaign. For triggered campaigns, provide one trigger shape: trigger_event_name, trigger_tag, trigger_type=date_field with trigger_config, or segment_id for ongoing audience targeting. For type=broadcast, send_at schedules the send for a future instant; the campaign must still be activated via update_campaign_status.',
         inputSchema: {
             site_id: z.string().uuid(),
             name: z.string().min(1).max(200),
@@ -402,8 +410,9 @@ export function registerCampaignTools(server) {
             trigger_type: z.enum(['date_field']).optional().describe('Set for elapsed-time triggers keyed on a contact custom_properties date field'),
             trigger_config: z.record(z.string(), z.unknown()).nullable().optional().describe('For trigger_type=date_field: { field, days_before?, recurring? }. Otherwise: { events?: string[], tags?: string[] }.'),
             segment_id: z.string().uuid().nullable().optional().describe('Segment UUID for ongoing audience targeting; membership is re-evaluated on sends'),
+            send_at: z.string().datetime().nullable().optional().describe('For type=broadcast only: ISO 8601 instant to schedule the send. Must be in the future. Set null for no schedule. The campaign must still be activated via update_campaign_status.'),
         },
-    }, async ({ site_id, name, type, description, sends_per_hour, requires_approval, trigger_event_name, trigger_tag, trigger_type, trigger_config, segment_id }) => {
+    }, async ({ site_id, name, type, description, sends_per_hour, requires_approval, trigger_event_name, trigger_tag, trigger_type, trigger_config, segment_id, send_at }) => {
         const limit = await checkPlanLimit('active_campaigns');
         if (!limit.allowed) {
             return { content: [{ type: 'text', text: `Active campaign limit reached (${limit.current}/${limit.limit}). Upgrade to Pro for unlimited campaigns.` }] };
@@ -418,6 +427,9 @@ export function registerCampaignTools(server) {
             sends_per_hour: sends_per_hour ?? null,
             requires_approval,
         };
+        const scheduleError = applyCampaignSendAtField(insertPayload, send_at, type);
+        if (scheduleError)
+            return j({ error: scheduleError, code: 'INVALID_FIELD' });
         const targetingError = await applyCampaignTargetingFields(insertPayload, { trigger_event_name, trigger_tag, trigger_type, trigger_config, segment_id }, projectId);
         if (targetingError)
             return j({ error: targetingError, code: targetingError === 'Segment not found' ? 'NOT_FOUND' : 'INVALID_FIELD' });
@@ -618,7 +630,7 @@ export function registerCampaignTools(server) {
             return j({ error: 'Campaign or contact not found', code: 'NOT_FOUND' });
         const { data: enrollment, error } = await db()
             .from('campaign_enrollments')
-            .select('id, status, current_step, current_step_id, enrolled_at, completed_at, next_send_at, exit_reason')
+            .select('id, status, current_step, enrolled_at, completed_at, next_send_at, exit_reason:exited_reason')
             .eq('campaign_id', campaign_id)
             .eq('contact_id', contact_id)
             .maybeSingle();
@@ -627,19 +639,34 @@ export function registerCampaignTools(server) {
         if (!enrollment) {
             return j({ enrolled: false, enrollment: null, campaign: campaignRes.data, contact: contactRes.data });
         }
-        const { count: stepsSent } = await db()
-            .from('email_log')
-            .select('id', { count: 'exact', head: true })
-            .eq('project_id', projectId)
-            .eq('campaign_id', campaign_id)
-            .eq('contact_id', contact_id)
-            .not('status', 'eq', 'failed');
+        const [{ count: stepsSent, error: stepsSentError }, currentStepResult] = await Promise.all([
+            db()
+                .from('email_log')
+                .select('id', { count: 'exact', head: true })
+                .eq('project_id', projectId)
+                .eq('campaign_id', campaign_id)
+                .eq('contact_id', contact_id)
+                .not('status', 'eq', 'failed'),
+            enrollment.current_step == null
+                ? Promise.resolve({ data: null, error: null })
+                : db()
+                    .from('campaign_steps')
+                    .select('id')
+                    .eq('campaign_id', campaign_id)
+                    .eq('step_order', enrollment.current_step)
+                    .maybeSingle(),
+        ]);
+        if (stepsSentError)
+            return txt(`Error: ${stepsSentError.message}`);
+        if (currentStepResult.error)
+            return txt(`Error: ${currentStepResult.error.message}`);
         return j({
             enrolled: true,
             campaign: campaignRes.data,
             contact: contactRes.data,
             enrollment: {
                 ...enrollment,
+                current_step_id: currentStepResult.data?.id ?? null,
                 current_step_order: enrollment.current_step ?? 0,
                 steps_sent: stepsSent ?? 0,
             },
@@ -970,6 +997,133 @@ export function registerCampaignTools(server) {
         }
         return j({ ...newCampaign, steps_copied: steps.length, cloned_from: campaign_id });
     });
+    server.registerTool('list_sequence_templates', {
+        title: 'List Sequence Templates',
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        description: 'List curated multi-step sequence templates available to clone into a draft campaign. Use clone_sequence_template to clone one.',
+        inputSchema: {
+            category: z.enum(['welcome', 'reengagement', 'winback', 'onboarding', 'nurture', 'launch', 'event', 'transactional']).optional().describe('Filter by category'),
+        },
+    }, async ({ category }) => {
+        let query = db()
+            .from('sequence_templates')
+            .select('id, slug, category, name, description, use_case, estimated_steps, estimated_duration_days')
+            .order('category')
+            .order('name');
+        if (category)
+            query = query.eq('category', category);
+        const { data, error } = await query;
+        if (error)
+            return txt(`Error: ${error.message}`);
+        return j(data ?? []);
+    });
+    server.registerTool('clone_sequence_template', {
+        title: 'Clone Sequence Template',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: 'Clone a curated sequence template into a new DRAFT campaign with its steps copied in. The result is not activated and no contacts are enrolled.',
+        inputSchema: {
+            template_id: z.string().uuid().describe('Sequence template to clone, from list_sequence_templates'),
+            new_name: z.string().min(1).optional().describe('Defaults to "<template name> (cloned)"'),
+            site_id: z.string().uuid().optional().describe('Defaults to the project\'s oldest active site'),
+        },
+    }, async ({ template_id, new_name, site_id }) => {
+        const projectId = getProjectId();
+        const { data: template, error: templateError } = await db()
+            .from('sequence_templates')
+            .select('*')
+            .eq('id', template_id)
+            .maybeSingle();
+        if (templateError)
+            return txt(`Error: ${templateError.message}`);
+        if (!template)
+            return txt('Error: Template not found');
+        const limit = await checkPlanLimit('active_campaigns');
+        if (!limit.allowed)
+            return txt(`Active campaign limit reached (${limit.current}/${limit.limit}).`);
+        let targetSiteId = site_id ?? null;
+        if (targetSiteId) {
+            const { data: targetSite, error: targetSiteError } = await db()
+                .from('sites')
+                .select('id')
+                .eq('id', targetSiteId)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (targetSiteError)
+                return txt(`Error: ${targetSiteError.message}`);
+            if (!targetSite)
+                return txt('Error: Site not found for this project');
+        }
+        else {
+            const { data: site, error: siteError } = await db()
+                .from('sites')
+                .select('id')
+                .eq('project_id', projectId)
+                .eq('active', true)
+                .order('created_at', { ascending: true })
+                .limit(1)
+                .maybeSingle();
+            if (siteError)
+                return txt(`Error: ${siteError.message}`);
+            targetSiteId = site?.id ?? null;
+        }
+        if (!targetSiteId) {
+            return txt('Error: A sending domain is required before cloning a template — create one with create_site first, or pass site_id.');
+        }
+        const cloneName = new_name?.trim() || `${template.name} (cloned)`;
+        const { data: campaign, error: campaignError } = await db()
+            .from('campaigns')
+            .insert({
+            project_id: projectId,
+            site_id: targetSiteId,
+            name: cloneName,
+            type: 'sequence',
+            status: 'draft',
+        })
+            .select()
+            .single();
+        if (campaignError)
+            return txt(`Error creating campaign: ${campaignError.message}`);
+        const steps = Array.isArray(template.template?.steps) ? template.template.steps : [];
+        if (steps.length > 0) {
+            const { error: stepsError } = await db()
+                .from('campaign_steps')
+                .insert(steps.map((step, index) => ({
+                campaign_id: campaign.id,
+                step_order: index,
+                subject: step.subject || `Email ${index + 1}`,
+                body_html: step.body_html || '<p>Edit this email before sending.</p>',
+                body_text: step.body_text ?? null,
+                delay_days: step.delay_days ?? 0,
+                delay_hours: step.delay_hours ?? 0,
+                condition_type: step.condition_type ?? null,
+                condition_lookback_hours: step.condition_lookback_hours ?? null,
+            })));
+            if (stepsError)
+                return txt(`Campaign created but steps failed: ${stepsError.message}`);
+        }
+        await logAudit({
+            action: 'sequence_template.cloned',
+            resourceType: 'campaign',
+            resourceId: campaign.id,
+            details: { template_id, template_slug: template.slug, source: 'mcp' },
+        }).catch(() => { });
+        return j({
+            ...campaign,
+            steps_copied: steps.length,
+            cloned_from_template_id: template_id,
+            message: `Created draft campaign "${cloneName}" from template "${template.name}" (${steps.length} step(s) copied). It is a DRAFT — not active, and no contacts are enrolled.`,
+        });
+    });
     server.registerTool('generate_email', {
         title: 'Generate Email',
         annotations: {
@@ -1018,7 +1172,7 @@ export function registerCampaignTools(server) {
             ? `Brand: ${site.name}, Domain: ${site.sending_domain}, From: ${site.from_name} <${site.from_email}>`
             : 'No brand info available';
         const voicePrompt = buildVoicePrompt(site?.brand_voice, project?.brand_settings ?? null);
-        let systemPrompt = `${buildEmailSystemPrompt(brandContext, voicePrompt)}
+        let systemPrompt = `${buildEmailSystemPrompt(brandContext, voicePrompt, project?.brand_settings ?? null)}
 
 Generate structured Composer blocks first. Return ONLY valid JSON with:
 {
@@ -1314,15 +1468,22 @@ Adapt your tone accordingly:
             .single();
         if (campErr)
             return txt(`Error creating campaign: ${campErr.message}`);
-        const { data: site } = await db()
-            .from('sites')
-            .select('name, sending_domain, from_name, from_email, brand_voice')
-            .eq('id', site_id)
-            .eq('project_id', projectId)
-            .maybeSingle();
+        const [{ data: site }, { data: project }] = await Promise.all([
+            db()
+                .from('sites')
+                .select('name, sending_domain, from_name, from_email, brand_voice')
+                .eq('id', site_id)
+                .eq('project_id', projectId)
+                .maybeSingle(),
+            db()
+                .from('projects')
+                .select('brand_settings')
+                .eq('id', projectId)
+                .maybeSingle(),
+        ]);
         const brandCtx = site ? `Brand: ${site.name}, Domain: ${site.sending_domain}, From: ${site.from_name}` : '';
-        const voicePrompt = buildVoicePrompt(site?.brand_voice);
-        const systemPrompt = `${buildEmailSystemPrompt(brandCtx, voicePrompt)}
+        const voicePrompt = buildVoicePrompt(site?.brand_voice, project?.brand_settings ?? null);
+        const systemPrompt = `${buildEmailSystemPrompt(brandCtx, voicePrompt, project?.brand_settings ?? null)}
 
 Generate structured Composer blocks first. Return ONLY valid JSON with:
 {
@@ -1579,16 +1740,22 @@ Do not include body_html in your response; Sendinel renders body_html from block
         inputSchema: {
             to: z.string().email().describe('Recipient email address'),
             site_id: z.string().uuid().describe('Site UUID (determines from address and Resend key)'),
-            subject: z.string().describe('Email subject line'),
+            subject: z.string().optional().describe('Email subject line. Required unless template_id is supplied and the template has a subject_hint.'),
             html: z.string().optional().describe('HTML body'),
             text: z.string().optional().describe('Plain text body'),
             reply_to: z.string().email().optional().describe('Reply-to address'),
             idempotency_key: z.string().optional().describe('Unique key to prevent duplicate sends'),
+            template_id: z.string().uuid().optional().describe('campaign_templates row to render and send. Mutually exclusive with html.'),
+            template_vars: z.record(z.string(), z.string()).optional().describe('Variable values for template_id rendering. Wins over brand tokens on key collision.'),
         },
-    }, async ({ to, site_id, subject, html, text, reply_to, idempotency_key }) => {
+    }, async ({ to, site_id, subject, html, text, reply_to, idempotency_key, template_id, template_vars }) => {
         const projectId = getProjectId();
-        if (!html && !text)
+        if (template_id && html)
+            return txt("Error: Provide either 'template_id' or 'html', not both");
+        if (!template_id && !html && !text)
             return txt('At least one of html or text is required');
+        if (!template_id && !subject?.trim())
+            return txt('Error: subject is required');
         // Suppression check
         const { data: suppression } = await db()
             .from('suppressions')
@@ -1619,18 +1786,66 @@ Do not include body_html in your response; Sendinel renders body_html from block
         // Site verification
         const { data: site } = await db()
             .from('sites')
-            .select('from_email, from_name')
+            .select('from_email, from_name, name, brand_voice')
             .eq('id', site_id)
             .eq('project_id', projectId)
             .maybeSingle();
         if (!site)
             return txt('Error: Site not found');
+        let resolvedSubject = subject;
+        let resolvedHtml = html;
+        let resolvedText = text;
+        if (template_id) {
+            const { data: template, error: templateError } = await db()
+                .from('campaign_templates')
+                .select('id, subject_hint, body_html, body_text, format')
+                .eq('id', template_id)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (templateError)
+                return txt(`Error: ${templateError.message}`);
+            if (!template)
+                return txt('Error: Template not found');
+            const { data: project } = await adminDb().from('projects').select('brand_settings').eq('id', projectId).maybeSingle();
+            const projectBrand = (project?.brand_settings ?? null);
+            const siteBrand = (site.brand_voice ?? null);
+            const mergedBrand = projectBrand || siteBrand ? { ...(projectBrand ?? {}), ...(siteBrand ?? {}) } : null;
+            const brandVars = resolveBrandTokens(mergedBrand, site.name || undefined);
+            const vars = template_vars ?? {};
+            const renderVars = { ...brandVars, ...vars };
+            const subjectFallingBack = !subject?.trim();
+            const requiredVars = deriveTemplateVariables({
+                body_html: template.format === 'text' ? null : (template.body_html ?? ''),
+                body_text: template.format === 'text' ? (template.body_text ?? '') : null,
+                subject_hint: subjectFallingBack ? (template.subject_hint ?? '') : null,
+            });
+            const satisfied = new Set([
+                ...Object.keys(vars),
+                'brand_name', 'brand_logo_url', 'brand_bg_color', 'brand_text_color', 'brand_accent_color',
+                ...Object.keys(NAME_FALLBACKS),
+            ]);
+            const missing = requiredVars.filter((name) => !satisfied.has(name));
+            if (missing.length) {
+                return txt(`Error: Missing required template variable(s): ${missing.join(', ')}`);
+            }
+            if (template.format === 'text') {
+                resolvedText = renderTemplateVars(template.body_text ?? '', renderVars);
+                resolvedHtml = undefined;
+            }
+            else {
+                resolvedHtml = renderTemplateVars(template.body_html ?? '', renderVars);
+                resolvedText = text ?? stripHtml(resolvedHtml);
+            }
+            resolvedSubject = subject?.trim() || renderTemplateVars(template.subject_hint ?? '', renderVars);
+        }
+        if (!resolvedSubject?.trim())
+            return txt('Error: subject is required');
         const payload = {
             from: `${site.from_name} <${site.from_email}>`,
             to,
-            subject,
-            html,
-            text,
+            subject: resolvedSubject,
+            html: resolvedHtml,
+            text: resolvedText,
             replyTo: reply_to,
         };
         let sendResult;
@@ -1647,13 +1862,13 @@ Do not include body_html in your response; Sendinel renders body_html from block
             contact_id: null,
             to_email: to,
             from_email: site.from_email,
-            subject,
+            subject: resolvedSubject,
             status: 'sent',
             category: 'transactional',
             sent_at: new Date().toISOString(),
             provider_message_id: sendResult.messageId ?? null,
             idempotency_key: idempotency_key ?? null,
-            body_html: html ?? null,
+            body_html: resolvedHtml ?? null,
         }).select('id').single();
         return j({
             sent: true,
@@ -1676,8 +1891,9 @@ Do not include body_html in your response; Sendinel renders body_html from block
         inputSchema: {
             html: z.string().describe('HTML email content to validate'),
             site_id: z.string().uuid().optional().describe('Site UUID — uses the site brand voice config for sign-off check'),
+            custom_variables: z.array(z.string()).optional().describe('Variable names (without braces) this template legitimately uses beyond the fixed known set.'),
         },
-    }, async ({ html, site_id }) => {
+    }, async ({ html, site_id, custom_variables }) => {
         let voiceConfig = null;
         if (site_id) {
             const { data: site } = await db()
@@ -1688,7 +1904,7 @@ Do not include body_html in your response; Sendinel renders body_html from block
                 .maybeSingle();
             voiceConfig = site?.brand_voice ?? null;
         }
-        const result = validateTemplate(html, voiceConfig);
+        const result = validateTemplate(html, voiceConfig, { customVariables: custom_variables });
         return j(result);
     });
     server.registerTool('check_content_consistency', {
@@ -2127,7 +2343,7 @@ Return ONLY valid JSON with this exact shape:
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Update a campaign name, site, segment, send time, topic, or trigger settings. Only provided fields are updated.',
+        description: 'Update a campaign name, site, segment, send time, topic, or trigger settings. send_at schedules a broadcast send (type=broadcast only) and must be a future ISO 8601 instant; set null to clear a pending schedule. Only provided fields are updated.',
         inputSchema: {
             campaign_id: z.string().uuid(),
             name: z.string().min(1).max(200).optional(),
@@ -2144,13 +2360,28 @@ Return ONLY valid JSON with this exact shape:
         },
     }, async ({ campaign_id, name, site_id, segment_id, send_at, topic, trigger_event_name, trigger_tag, trigger_type, trigger_config, sends_per_hour, send_in_contact_timezone }) => {
         const projectId = getProjectId();
+        let campaignType;
+        if (send_at !== undefined && send_at !== null) {
+            const { data: existing, error: fetchError } = await db()
+                .from('campaigns')
+                .select('id, type')
+                .eq('id', campaign_id)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (fetchError)
+                return j({ error: fetchError.message });
+            if (!existing)
+                return j({ error: 'Campaign not found', code: 'NOT_FOUND' });
+            campaignType = existing.type;
+        }
         const updates = { updated_at: new Date().toISOString() };
         if (name !== undefined)
             updates.name = name;
         if (site_id !== undefined)
             updates.site_id = site_id;
-        if (send_at !== undefined)
-            updates.send_at = send_at;
+        const scheduleError = applyCampaignSendAtField(updates, send_at, campaignType);
+        if (scheduleError)
+            return j({ error: scheduleError, code: 'INVALID_FIELD' });
         if (topic !== undefined)
             updates.topic = topic;
         if (sends_per_hour !== undefined)
@@ -2191,7 +2422,7 @@ Return ONLY valid JSON with this exact shape:
             .maybeSingle();
         if (campErr || !campaign)
             return j({ error: campErr?.message ?? 'Campaign not found', code: 'NOT_FOUND' });
-        const [{ data: steps }, { count: enrollCount }] = await Promise.all([
+        const [{ data: steps, error: stepsError }, { count: enrollCount, error: enrollError }, { count: sentCount, error: sentError }, { count: queuedEmailCount, error: queuedEmailError }, { count: failedSendCount, error: failedSendError }, { data: queueRows, error: queueError }, { count: dlqUnresolvedCount, error: dlqError },] = await Promise.all([
             db()
                 .from('campaign_steps')
                 .select('*')
@@ -2202,8 +2433,66 @@ Return ONLY valid JSON with this exact shape:
                 .select('id', { count: 'exact', head: true })
                 .eq('campaign_id', campaign_id)
                 .eq('status', 'active'),
+            db()
+                .from('email_log')
+                .select('id', { count: 'exact', head: true })
+                .eq('project_id', projectId)
+                .eq('campaign_id', campaign_id)
+                .in('status', SENT_EMAIL_STATUSES),
+            db()
+                .from('email_log')
+                .select('id', { count: 'exact', head: true })
+                .eq('project_id', projectId)
+                .eq('campaign_id', campaign_id)
+                .eq('status', 'queued'),
+            db()
+                .from('email_log')
+                .select('id', { count: 'exact', head: true })
+                .eq('project_id', projectId)
+                .eq('campaign_id', campaign_id)
+                .eq('status', 'failed'),
+            db()
+                .from('send_queue')
+                .select('status, next_retry_at')
+                .eq('project_id', projectId)
+                .eq('campaign_id', campaign_id)
+                .in('status', ['pending', 'processing', 'retry']),
+            db()
+                .from('send_dlq')
+                .select('id', { count: 'exact', head: true })
+                .eq('project_id', projectId)
+                .eq('resolved', false)
+                .eq('queue_snapshot->>campaign_id', campaign_id),
         ]);
-        return j({ ...campaign, steps: steps ?? [], active_enrollments: enrollCount ?? 0 });
+        const visibilityError = stepsError ?? enrollError ?? sentError ?? queuedEmailError ?? failedSendError ?? queueError ?? dlqError;
+        if (visibilityError)
+            return j({ error: visibilityError.message, code: 'CAMPAIGN_VISIBILITY_QUERY_FAILED' });
+        const outstandingRows = queueRows ?? [];
+        const pendingOrRetryRows = outstandingRows.filter((row) => row.status !== 'processing');
+        const retryingCount = outstandingRows.filter((row) => row.status === 'retry').length;
+        const processingCount = outstandingRows.filter((row) => row.status === 'processing').length;
+        const nextRetryAt = pendingOrRetryRows
+            .map((row) => row.next_retry_at)
+            .filter((value) => Boolean(value))
+            .sort()[0] ?? null;
+        const queuedCount = queuedEmailCount ?? 0;
+        const failedCount = failedSendCount ?? 0;
+        const unresolvedCount = dlqUnresolvedCount ?? 0;
+        return j({
+            ...campaign,
+            total_sent: sentCount ?? 0,
+            steps: steps ?? [],
+            active_enrollments: enrollCount ?? 0,
+            send_incomplete: queuedCount > 0 || failedCount > 0 || outstandingRows.length > 0 || unresolvedCount > 0,
+            queued_email_count: queuedCount,
+            failed_send_count: failedCount,
+            queue_outstanding_count: outstandingRows.length,
+            queue_pending_count: pendingOrRetryRows.length,
+            queue_retrying_count: retryingCount,
+            queue_processing_count: processingCount,
+            queue_next_retry_at: nextRetryAt,
+            dlq_unresolved_count: unresolvedCount,
+        });
     });
     server.registerTool('unenroll_contact', {
         title: 'Unenroll Contact',

package/build/tools/cloud-import.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCloudImportTools(server: McpServer): void;