@sendinel/mcp-server 1.0.31 → 1.0.33

package/build/tools/campaigns.js

@@ -12,7 +12,9 @@ import { getProjectId } from '../project.js';
 import { checkPlanLimit } from '../plan-limits.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 { approvalExcerpt, assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval } from '../lib/action-approvals.js';
+import { resolveSendAudience } from '../lib/send-audience.js';
+import { generateEmailFromBrief, parseAudienceRules } from '../lib/email-generation.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
 import { getScheduleWindowBounds, groupScheduleByCampaign, parseFutureDate } from '../lib/schedule.js';
 import { sendEmailForSite } from '../lib/email-provider.js';
@@ -67,7 +69,7 @@ function applyCampaignSendAtField(updates, sendAt, campaignType) {
     updates.send_at = parsed.scheduledAt;
     return null;
 }
-async function applyCampaignTargetingFields(updates, input, projectId) {
+export async function applyCampaignTargetingFields(updates, input, projectId) {
     if (input.trigger_event_name !== undefined)
         updates.trigger_event_name = input.trigger_event_name?.trim() || null;
     if (input.trigger_tag !== undefined)
@@ -151,63 +153,6 @@ function applySegmentPaymentDateRule(query, field, rule) {
         q = q.lte(column, rule.before);
     return q;
 }
-async function getSegmentContactIds(projectId, rules) {
-    let q = db()
-        .from('subscribers')
-        .select('id, email')
-        .eq('project_id', projectId)
-        .eq('global_unsubscribed', false)
-        .is('cooled_at', null);
-    if (rules.lifecycle_stage)
-        q = q.eq('lifecycle_stage', rules.lifecycle_stage);
-    q = applySegmentPaymentRules(q, rules.payment);
-    if (rules.min_score !== undefined)
-        q = q.gte('engagement_score', rules.min_score);
-    if (rules.max_score !== undefined)
-        q = q.lte('engagement_score', rules.max_score);
-    if (rules.source)
-        q = q.eq('source', rules.source);
-    if (rules.subscribed_after)
-        q = q.gte('created_at', `${rules.subscribed_after}T00:00:00Z`);
-    if (rules.subscribed_before)
-        q = q.lte('created_at', `${rules.subscribed_before}T23:59:59Z`);
-    if (rules.has_opened === true)
-        q = q.not('last_opened_at', 'is', null);
-    if (rules.has_opened === false)
-        q = q.is('last_opened_at', null);
-    if (rules.has_clicked === true)
-        q = q.not('last_clicked_at', 'is', null);
-    if (rules.has_clicked === false)
-        q = q.is('last_clicked_at', null);
-    if (rules.tag)
-        q = q.contains('tags', [rules.tag]);
-    if (rules.site_id) {
-        const { data: subs } = await db()
-            .from('site_subscriptions')
-            .select('contact_id')
-            .eq('site_id', rules.site_id)
-            .eq('subscribed', true);
-        const siteIds = (subs ?? []).map((s) => s.contact_id);
-        if (!siteIds.length)
-            return [];
-        q = q.in('id', siteIds);
-    }
-    const { data, error } = await q;
-    if (error || !data)
-        return [];
-    let ids = data.map((c) => c.id);
-    const { data: suppressed } = await db()
-        .from('suppressions')
-        .select('email')
-        .eq('project_id', projectId);
-    if (suppressed?.length) {
-        const suppressedEmails = new Set(suppressed.map((s) => s.email));
-        ids = data
-            .filter((c) => !suppressedEmails.has(c.email))
-            .map((c) => c.id);
-    }
-    return ids;
-}
 function extractJsonObject(raw) {
     const cleaned = raw.replace(/```(?:json)?/gi, '').replace(/```/g, '').trim();
     const start = cleaned.indexOf('{');
@@ -282,6 +227,94 @@ async function validateBranchTarget(campaignId, action, targetStepId, targetCamp
     }
     return null;
 }
+/**
+ * Create, enroll and activate a one-email broadcast (#3669). Shared by broadcast_to_segment and
+ * send_broadcast so both run the same steps. Enrolls exactly the given contact ids.
+ */
+async function executeBroadcast(input) {
+    const limit = await checkPlanLimit('active_campaigns');
+    if (!limit.allowed) {
+        return { ok: false, error: `Campaign limit reached (${limit.current}/${limit.limit}). Upgrade your plan for more campaigns.`, code: 'PLAN_LIMIT' };
+    }
+    const { data: campaign, error: campaignErr } = await db()
+        .from('campaigns')
+        .insert({
+        project_id: input.projectId,
+        site_id: input.siteId,
+        segment_id: input.segmentId,
+        name: input.name,
+        type: 'broadcast',
+        status: 'draft',
+        send_at: input.sendAt,
+        send_class: input.sendClass,
+        sends_per_hour: input.sendsPerHour ?? null,
+        requires_approval: false,
+        metadata: { source: input.source, ...(input.metadata ?? {}) },
+    })
+        .select('id')
+        .single();
+    if (campaignErr || !campaign) {
+        return { ok: false, error: campaignErr?.message ?? 'Failed to create campaign', code: 'CAMPAIGN_CREATE_FAILED' };
+    }
+    const { data: step, error: stepErr } = await db()
+        .from('campaign_steps')
+        .insert({
+        campaign_id: campaign.id,
+        step_order: 0,
+        subject: input.subject,
+        body_html: input.bodyHtml,
+        body_text: input.bodyText ?? null,
+        ...(Array.isArray(input.blocks) ? { blocks: input.blocks } : {}),
+        delay_days: 0,
+        delay_hours: 0,
+    })
+        .select('id')
+        .single();
+    if (stepErr || !step) {
+        return { ok: false, error: stepErr?.message ?? 'Campaign created but failed to add broadcast step', code: 'STEP_CREATE_FAILED', campaign_id: campaign.id };
+    }
+    await recordBrandAssetUsage({
+        client: db(),
+        projectId: input.projectId,
+        source: 'campaign_step',
+        resourceId: step.id,
+        html: input.bodyHtml,
+        assetIds: input.brandAssetIds,
+    }).catch((err) => {
+        console.warn('Failed to record brand asset usage for MCP broadcast:', err);
+    });
+    const nextSendAt = input.sendAt ?? new Date().toISOString();
+    const batchSize = 500;
+    for (let i = 0; i < input.contactIds.length; i += batchSize) {
+        const batch = input.contactIds.slice(i, i + batchSize).map((contact_id) => ({
+            campaign_id: campaign.id,
+            contact_id,
+            next_send_at: nextSendAt,
+        }));
+        const { error: enrollErr } = await db()
+            .from('campaign_enrollments')
+            .upsert(batch, { onConflict: 'campaign_id,contact_id', ignoreDuplicates: true });
+        if (enrollErr) {
+            return { ok: false, error: enrollErr.message, code: 'ENROLLMENT_FAILED', campaign_id: campaign.id, enrolled_before_failure: i };
+        }
+    }
+    const { error: activateErr } = await db()
+        .from('campaigns')
+        .update({ status: 'active', total_enrolled: input.contactIds.length, updated_at: new Date().toISOString() })
+        .eq('id', campaign.id)
+        .eq('project_id', input.projectId);
+    if (activateErr) {
+        return { ok: false, error: activateErr.message, code: 'ACTIVATION_FAILED', campaign_id: campaign.id, enrolled: input.contactIds.length };
+    }
+    return { ok: true, campaignId: campaign.id, stepId: step.id, enrolled: input.contactIds.length, nextSendAt };
+}
+function heldBackLines(audience) {
+    return {
+        matched: audience.matched,
+        not_signed_up_for_sender: audience.notOnSender,
+        held_back_by_consent: audience.heldBack,
+    };
+}
 export function registerCampaignTools(server) {
     server.registerTool('review_campaign_portfolio', {
         title: 'Review Campaign Portfolio',
@@ -569,7 +602,17 @@ export function registerCampaignTools(server) {
                 if (!decision.allowed)
                     return txt(decision.reason ?? 'This channel cannot request this action.');
                 if (decision.tier !== 'autonomous') {
-                    const approval = await requestApproval('update_campaign_status', approvalParams, undefined, channelContext);
+                    const { data: camp } = await db()
+                        .from('campaigns')
+                        .select('name, total_enrolled, trigger_event_name, trigger_tag')
+                        .eq('id', campaign_id)
+                        .eq('project_id', getProjectId())
+                        .maybeSingle();
+                    const approval = await requestApproval('update_campaign_status', approvalParams, undefined, channelContext, {
+                        campaign_name: camp?.name ?? null,
+                        enrolled: typeof camp?.total_enrolled === 'number' ? camp.total_enrolled : null,
+                        trigger: camp?.trigger_event_name ?? (camp?.trigger_tag ? `tag ${camp.trigger_tag}` : null),
+                    });
                     return j(approval);
                 }
             }
@@ -824,7 +867,16 @@ export function registerCampaignTools(server) {
             ...(segment.rules ?? {}),
             ...(segment.site_id ? { site_id: segment.site_id } : {}),
         };
-        const contactIds = await getSegmentContactIds(projectId, rules);
+        // #3669: the same audience rules as send_broadcast and the dashboard: paged, signed up to this
+        // sender, consent gate applied. The count shown is the count enrolled.
+        let audience;
+        try {
+            audience = await resolveSendAudience(projectId, site_id, rules);
+        }
+        catch (error) {
+            return j({ error: `Could not load this audience: ${error instanceof Error ? error.message : String(error)}`, code: 'AUDIENCE_LOOKUP_FAILED' });
+        }
+        const contactIds = audience.contactIds;
         if (!confirmed) {
             return j({
                 confirmation_required: true,
@@ -838,16 +890,18 @@ export function registerCampaignTools(server) {
                     sends_per_hour: sends_per_hour ?? null,
                 },
                 matching_contacts: contactIds.length,
+                audience: heldBackLines(audience),
                 will_send_at: 'immediately',
                 message: `Broadcast "${campaignName}" will enroll ${contactIds.length} eligible contact(s) from segment "${segment.name}" and activate immediately. Call again with confirmed=true to proceed.`,
             });
         }
         if (contactIds.length === 0) {
             return j({
-                error: 'No eligible contacts match this segment.',
+                error: 'Nobody in this segment can get email from this sender right now.',
                 code: 'EMPTY_SEGMENT',
                 segment_id,
                 site_id,
+                audience: heldBackLines(audience),
             });
         }
         const channelContext = currentChannelContext();
@@ -856,7 +910,12 @@ export function registerCampaignTools(server) {
             return txt(decision.reason ?? 'This channel cannot request this action.');
         if (decision.tier !== 'autonomous') {
             if (!approval_id) {
-                const approval = await requestApproval('broadcast_to_segment', approvalParams, undefined, channelContext);
+                const approval = await requestApproval('broadcast_to_segment', approvalParams, undefined, channelContext, {
+                    subject,
+                    segment_name: segment.name,
+                    recipient_count: contactIds.length,
+                    body_excerpt: approvalExcerpt(body_html),
+                });
                 return j(approval);
             }
             const check = await checkApproval(approval_id, { consume: true, action: 'broadcast_to_segment', params: approvalParams });
@@ -864,98 +923,28 @@ export function registerCampaignTools(server) {
                 return txt(`Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`);
             }
         }
-        const limit = await checkPlanLimit('active_campaigns');
-        if (!limit.allowed) {
-            return j({
-                error: `Campaign limit reached (${limit.current}/${limit.limit}). Upgrade your plan for more campaigns.`,
-                code: 'PLAN_LIMIT',
-            });
-        }
-        const { data: campaign, error: campaignErr } = await db()
-            .from('campaigns')
-            .insert({
-            project_id: projectId,
-            site_id,
-            segment_id,
+        const executed = await executeBroadcast({
+            projectId,
+            siteId: site_id,
+            segmentId: segment_id,
             name: campaignName,
-            type: 'broadcast',
-            status: 'draft',
-            sends_per_hour: sends_per_hour ?? null,
-            requires_approval: false,
-            metadata: { source: 'mcp_broadcast_to_segment' },
-        })
-            .select('id')
-            .single();
-        if (campaignErr || !campaign) {
-            return j({ error: campaignErr?.message ?? 'Failed to create campaign', code: 'CAMPAIGN_CREATE_FAILED' });
-        }
-        const { data: step, error: stepErr } = await db()
-            .from('campaign_steps')
-            .insert({
-            campaign_id: campaign.id,
-            step_order: 0,
             subject,
-            body_html,
-            body_text: body_text ?? null,
-            delay_days: 0,
-            delay_hours: 0,
-        })
-            .select('id')
-            .single();
-        if (stepErr || !step) {
-            return j({
-                error: stepErr?.message ?? 'Campaign created but failed to add broadcast step',
-                code: 'STEP_CREATE_FAILED',
-                campaign_id: campaign.id,
-            });
-        }
-        await recordBrandAssetUsage({
-            client: db(),
-            projectId,
-            source: 'campaign_step',
-            resourceId: step.id,
-            html: body_html,
-            assetIds: brand_asset_ids,
-        }).catch((err) => {
-            console.warn('Failed to record brand asset usage for MCP broadcast:', err);
+            bodyHtml: body_html,
+            bodyText: body_text ?? null,
+            sendsPerHour: sends_per_hour ?? null,
+            contactIds,
+            sendAt: null,
+            sendClass: 'broadcast',
+            brandAssetIds: brand_asset_ids,
+            source: 'mcp_broadcast_to_segment',
         });
-        const sendAt = new Date().toISOString();
-        const batchSize = 500;
-        for (let i = 0; i < contactIds.length; i += batchSize) {
-            const batch = contactIds.slice(i, i + batchSize).map((contact_id) => ({
-                campaign_id: campaign.id,
-                contact_id,
-                next_send_at: sendAt,
-            }));
-            const { error: enrollErr } = await db()
-                .from('campaign_enrollments')
-                .upsert(batch, { onConflict: 'campaign_id,contact_id', ignoreDuplicates: true });
-            if (enrollErr) {
-                return j({
-                    error: enrollErr.message,
-                    code: 'ENROLLMENT_FAILED',
-                    campaign_id: campaign.id,
-                    enrolled_before_failure: i,
-                });
-            }
-        }
-        const { error: activateErr } = await db()
-            .from('campaigns')
-            .update({
-            status: 'active',
-            total_enrolled: contactIds.length,
-            updated_at: new Date().toISOString(),
-        })
-            .eq('id', campaign.id)
-            .eq('project_id', projectId);
-        if (activateErr) {
-            return j({
-                error: activateErr.message,
-                code: 'ACTIVATION_FAILED',
-                campaign_id: campaign.id,
-                enrolled: contactIds.length,
-            });
+        if (!executed.ok) {
+            const { ok: _ok, ...failure } = executed;
+            return j(failure);
         }
+        const campaign = { id: executed.campaignId };
+        const step = { id: executed.stepId };
+        const sendAt = executed.nextSendAt;
         await logAudit({
             action: 'campaign.broadcast_to_segment',
             resourceType: 'campaign',
@@ -985,6 +974,226 @@ export function registerCampaignTools(server) {
             message: `Broadcast "${campaignName}" is active with ${contactIds.length} contact(s) enrolled for immediate sending.`,
         });
     });
+    server.registerTool('send_broadcast', {
+        title: 'Send Broadcast',
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+        description: 'Send a one-off email in two calls. Call 1: give an audience (audience in plain words, or segment_id) and content (brief for an AI draft, or html + subject); it returns the finished email, the recipient count, the sender and an approval_id, and sends nothing. A person approves it (approve_url works on a phone). Call 2: pass ONLY approval_id; it sends exactly what was approved. Use this for "send an email to…", newsletters, announcements.',
+        inputSchema: {
+            audience: z.string().min(3).max(500).optional().describe('Who gets it, in plain words (for example "trial users who have not opened anything"). Use this or segment_id.'),
+            segment_id: z.string().uuid().optional().describe('A saved segment. Use this or audience.'),
+            brief: z.string().min(10).max(4000).optional().describe('What the email should say; Sendinel drafts it in your brand voice. Use this or html.'),
+            html: z.string().min(1).optional().describe('A finished HTML body. Requires subject. Use this or brief.'),
+            subject: z.string().min(1).max(300).optional().describe('Subject line. Required with html; overrides the drafted subject with brief.'),
+            body_text: z.string().optional().describe('Plain-text version for html. Derived from the HTML when omitted.'),
+            site_id: z.string().uuid().optional().describe('Sender. Optional when the project has exactly one sender.'),
+            send_at: z.string().datetime().optional().describe('Future ISO time to send. Omit to send right after approval.'),
+            name: z.string().min(1).max(200).optional().describe('Campaign name. Defaults from the subject.'),
+            send_class: z.enum(['broadcast', 'product']).optional().describe('broadcast (marketing, default) or product (account and onboarding email). Decides which consent rules apply.'),
+            brand_asset_ids: z.array(z.string().uuid()).optional().describe('Brand media assets used in the body.'),
+            approval_id: z.string().uuid().optional().describe('Call 2 only: the approved approval_id from call 1. Pass nothing else.'),
+        },
+    }, async (args) => {
+        const projectId = getProjectId();
+        const { approval_id } = args;
+        // ── Call 2: execute exactly the approved, frozen payload. Nothing else is trusted. ──
+        if (approval_id) {
+            const extras = Object.entries(args).filter(([key, value]) => key !== 'approval_id' && value !== undefined).map(([key]) => key);
+            if (extras.length) {
+                return j({ error: `Call send_broadcast with only approval_id to send. Remove: ${extras.join(', ')}. To change anything, start over without approval_id.`, code: 'APPROVAL_CALL_TAKES_ONLY_APPROVAL_ID' });
+            }
+            const { data: row, error: rowErr } = await db()
+                .from('action_approvals')
+                .select('params')
+                .eq('id', approval_id)
+                .eq('project_id', projectId)
+                .eq('action', 'send_broadcast')
+                .maybeSingle();
+            if (rowErr)
+                return j({ error: rowErr.message, code: 'APPROVAL_LOOKUP_FAILED' });
+            if (!row)
+                return txt(`Approval ${approval_id} is not_found. Request a new approval.`);
+            const stored = (row.params ?? {});
+            const check = await checkApproval(approval_id, { consume: true, action: 'send_broadcast', params: stored });
+            if (!check.approved) {
+                return txt(`Approval ${approval_id} is ${check.status}. ${check.status === 'pending' ? 'Waiting for human approval via dashboard.' : 'Request a new approval.'}`);
+            }
+            const payload = (stored.payload ?? {});
+            const contactIds = Array.isArray(payload.contact_ids) ? payload.contact_ids.map(String) : [];
+            if (payload.send_at && new Date(payload.send_at).getTime() <= Date.now()) {
+                // An approved future time that has now passed: send right away rather than silently skip.
+                payload.send_at = null;
+            }
+            const executed = await executeBroadcast({
+                projectId,
+                siteId: String(payload.site_id),
+                segmentId: payload.segment_id ?? null,
+                name: String(payload.name),
+                subject: String(payload.subject),
+                bodyHtml: String(payload.body_html),
+                bodyText: payload.body_text ?? null,
+                blocks: Array.isArray(payload.blocks) ? payload.blocks : null,
+                contactIds,
+                sendAt: payload.send_at ?? null,
+                sendClass: payload.send_class === 'product' ? 'product' : 'broadcast',
+                brandAssetIds: Array.isArray(payload.brand_asset_ids) ? payload.brand_asset_ids : undefined,
+                source: 'mcp_send_broadcast',
+                metadata: { approval_id, ...(payload.rules ? { audience_rules: payload.rules } : {}) },
+            });
+            if (!executed.ok) {
+                const { ok: _ok, ...failure } = executed;
+                return j(failure);
+            }
+            await logAudit({
+                action: 'campaign.send_broadcast',
+                resourceType: 'campaign',
+                resourceId: executed.campaignId,
+                details: { approval_id, decided_by: check.decided_by ?? null, site_id: payload.site_id, segment_id: payload.segment_id ?? null, contacts_enrolled: executed.enrolled, send_at: payload.send_at ?? null, source: 'mcp' },
+            }).catch(() => { });
+            fireWebhookEvent('campaign.activated', {
+                campaign_id: executed.campaignId,
+                campaign_name: payload.name,
+                type: 'broadcast',
+                contacts_enrolled: executed.enrolled,
+                steps: 1,
+            }).catch(() => { });
+            return j({
+                campaign_id: executed.campaignId,
+                step_id: executed.stepId,
+                status: 'active',
+                contacts_enrolled: executed.enrolled,
+                send_at: payload.send_at ?? 'now',
+                message: payload.send_at
+                    ? `Scheduled: "${payload.subject}" goes to ${executed.enrolled} people at ${payload.send_at}.`
+                    : `Sending: "${payload.subject}" is going to ${executed.enrolled} people now. Delivery happens over the next few minutes; check the campaign for results.`,
+            });
+        }
+        // ── Call 1: resolve, render, count, request approval. Sends nothing. ──
+        const { audience, segment_id, brief, html, subject, body_text, site_id, send_at, name, send_class, brand_asset_ids } = args;
+        if (Boolean(audience) === Boolean(segment_id))
+            return j({ error: 'Give exactly one of audience or segment_id.', code: 'AUDIENCE_REQUIRED' });
+        if (Boolean(brief) === Boolean(html))
+            return j({ error: 'Give exactly one of brief or html.', code: 'CONTENT_REQUIRED' });
+        if (html && !subject)
+            return j({ error: 'subject is required with html.', code: 'SUBJECT_REQUIRED' });
+        let sendAt = null;
+        if (send_at) {
+            const parsed = parseFutureDate(send_at, 'send_at');
+            if ('error' in parsed)
+                return j({ error: parsed.error, code: 'INVALID_SEND_AT' });
+            sendAt = parsed.scheduledAt;
+        }
+        // Sender: the given one, or the only one. Never guessed between several.
+        const { data: sites, error: sitesErr } = await db()
+            .from('sites')
+            .select('id, name, from_email')
+            .eq('project_id', projectId);
+        if (sitesErr)
+            return j({ error: sitesErr.message, code: 'SITE_LOOKUP_FAILED' });
+        const site = site_id ? (sites ?? []).find((s) => s.id === site_id) : (sites?.length === 1 ? sites[0] : null);
+        if (!site) {
+            return j({
+                error: site_id ? 'Site not found in this project.' : 'This project has more than one sender. Pass site_id.',
+                code: site_id ? 'SITE_NOT_FOUND' : 'SITE_REQUIRED',
+                sites: (sites ?? []).map((s) => ({ id: s.id, name: s.name, from_email: s.from_email })),
+            });
+        }
+        const apiKey = process.env.ANTHROPIC_API_KEY;
+        if ((audience || brief) && !apiKey)
+            return j({ error: 'ANTHROPIC_API_KEY not configured', code: 'AI_NOT_CONFIGURED' });
+        const anthropic = apiKey ? new Anthropic({ apiKey }) : null;
+        let rules;
+        let segmentName;
+        if (segment_id) {
+            const { data: segment, error: segmentErr } = await db()
+                .from('segments')
+                .select('id, name, rules, site_id')
+                .eq('id', segment_id)
+                .eq('project_id', projectId)
+                .maybeSingle();
+            if (segmentErr)
+                return j({ error: segmentErr.message, code: 'SEGMENT_LOOKUP_FAILED' });
+            if (!segment)
+                return j({ error: 'Segment not found', code: 'SEGMENT_NOT_FOUND' });
+            rules = { ...(segment.rules ?? {}), ...(segment.site_id ? { site_id: segment.site_id } : {}) };
+            segmentName = segment.name;
+        }
+        else {
+            try {
+                rules = await parseAudienceRules(anthropic, audience);
+            }
+            catch (error) {
+                return j({ error: error instanceof Error ? error.message : String(error), code: 'AUDIENCE_NOT_UNDERSTOOD' });
+            }
+            segmentName = audience;
+        }
+        const sendClass = send_class === 'product' ? 'product' : 'broadcast';
+        let resolved;
+        try {
+            resolved = await resolveSendAudience(projectId, site.id, rules, sendClass);
+        }
+        catch (error) {
+            return j({ error: `Could not load this audience: ${error instanceof Error ? error.message : String(error)}`, code: 'AUDIENCE_LOOKUP_FAILED' });
+        }
+        if (resolved.contactIds.length === 0) {
+            return j({ error: 'Nobody in this audience can get this email from this sender.', code: 'EMPTY_AUDIENCE', audience: heldBackLines(resolved), rules });
+        }
+        let content;
+        if (brief) {
+            try {
+                const generated = await generateEmailFromBrief(anthropic, projectId, site.id, brief);
+                content = { subject: subject ?? generated.subject, body_html: generated.body_html, body_text: generated.body_text, blocks: generated.blocks };
+            }
+            catch (error) {
+                return j({ error: error instanceof Error ? error.message : String(error), code: 'DRAFT_FAILED' });
+            }
+        }
+        else {
+            content = { subject: subject, body_html: html, body_text: body_text ?? approvalExcerpt(html, 100000), blocks: null };
+        }
+        const campaignName = name ?? `Broadcast - ${content.subject.slice(0, 120)}`;
+        const payload = {
+            site_id: site.id,
+            segment_id: segment_id ?? null,
+            rules: segment_id ? null : rules,
+            subject: content.subject,
+            body_html: content.body_html,
+            body_text: content.body_text,
+            blocks: content.blocks,
+            name: campaignName,
+            send_at: sendAt,
+            send_class: sendClass,
+            brand_asset_ids: brand_asset_ids ?? null,
+            // Frozen at approval time: the people approved are the people enrolled.
+            contact_ids: resolved.contactIds,
+        };
+        const approvalParams = { payload };
+        const channelContext = currentChannelContext();
+        const decision = assertChannelCanExecute('send_broadcast', approvalParams, channelContext);
+        if (!decision.allowed)
+            return txt(decision.reason ?? 'This channel cannot request this action.');
+        const approval = await requestApproval('send_broadcast', approvalParams, undefined, channelContext, {
+            subject: content.subject,
+            segment_name: segment_id ? segmentName : null,
+            audience_label: segment_id ? null : `"${segmentName}"`,
+            recipient_count: resolved.contactIds.length,
+            body_excerpt: approvalExcerpt(content.body_html),
+            send_at: sendAt,
+        });
+        return j({
+            ...approval,
+            rendered: { subject: content.subject, body_html: content.body_html, body_text: content.body_text },
+            recipient_count: resolved.contactIds.length,
+            audience: { label: segmentName, segment_id: segment_id ?? null, ...heldBackLines(resolved) },
+            site: { id: site.id, name: site.name, from_email: site.from_email },
+            send_at: sendAt ?? 'right after approval',
+            next: 'Show the user the subject, recipient count and approve_url. After a person approves, call send_broadcast with only approval_id. Do not say it was sent before that call succeeds.',
+        });
+    });
     server.registerTool('clone_campaign', {
         title: 'Clone Campaign',
         annotations: {

package/build/tools/gateway.d.ts

@@ -3,4 +3,15 @@ export interface GatewayOptions {
     scopes?: string[];
     toolGroups?: string[];
 }
+/**
+ * Plain words people use for a tool, so search_tools finds "send email", "welcome" or
+ * "last campaign" (#3669). Matched alongside name, group and description.
+ */
+export declare const INTENT_ALIASES: Record<string, string[]>;
+/** Every word of the query must appear somewhere in the tool's text (name, group, description, aliases). */
+export declare function matchesToolQuery(entry: {
+    name: string;
+    group: string;
+    description: string;
+}, query: string): boolean;
 export declare function registerGatewayTools(server: McpServer, options: GatewayOptions): void;

package/build/tools/gateway.js

@@ -9,6 +9,29 @@ const notFound = (message) => ({
     isError: true,
     content: [{ type: 'text', text: message }],
 });
+/**
+ * Plain words people use for a tool, so search_tools finds "send email", "welcome" or
+ * "last campaign" (#3669). Matched alongside name, group and description.
+ */
+export const INTENT_ALIASES = {
+    send_broadcast: ['send email', 'send an email', 'email blast', 'blast', 'newsletter', 'announce', 'announcement', 'one-off email'],
+    list_campaigns: ['last campaign', 'latest campaign', 'recent campaign', 'my campaigns'],
+    get_campaign: ['last campaign', 'campaign details', 'campaign results'],
+    create_campaign: ['welcome', 'welcome email', 'onboarding', 'drip', 'sequence', 'triggered email'],
+    add_campaign_step: ['welcome', 'onboarding', 'follow up email', 'next email in sequence'],
+};
+/** Every word of the query must appear somewhere in the tool's text (name, group, description, aliases). */
+export function matchesToolQuery(entry, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return true;
+    const haystack = [entry.name, entry.name.replace(/_/g, ' '), entry.group, entry.description, ...(INTENT_ALIASES[entry.name] ?? [])]
+        .join(' \n ')
+        .toLowerCase();
+    if (haystack.includes(q))
+        return true;
+    return q.split(/\s+/).filter(Boolean).every((token) => haystack.includes(token));
+}
 async function buildCatalog(options) {
     const innerServer = new McpServer({ name: 'sendinel-gateway-inner', version: '1.0.0' });
     registerAllTools(innerServer, { scopes: options.scopes, toolGroups: options.toolGroups });
@@ -39,7 +62,7 @@ export function registerGatewayTools(server, options) {
         description: 'Search the permitted Sendinel MCP tool catalog by keyword and/or group. Returns name, group, and description. Call describe_tool for the full input schema before invoke_tool.',
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
         inputSchema: {
-            query: z.string().optional().describe('Keyword to match against tool name, group, or description'),
+            query: z.string().optional().describe('Words to match against tool name, group, description, or common phrasing (for example "send email")'),
             group: z.string().optional().describe('Restrict results to one tool group, for example campaigns'),
         },
     }, async ({ query, group }) => {
@@ -49,11 +72,7 @@ export function registerGatewayTools(server, options) {
         const results = catalog.entries.filter((tool) => {
             if (requestedGroup && tool.group !== requestedGroup)
                 return false;
-            if (!q)
-                return true;
-            return (tool.name.toLowerCase().includes(q) ||
-                tool.group.toLowerCase().includes(q) ||
-                tool.description.toLowerCase().includes(q));
+            return matchesToolQuery(tool, q);
         });
         return jsonResult({
             tools: results.map(({ name, group, description }) => ({ name, group, description })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.31",
+  "version": "1.0.33",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",