@sendinel/mcp-server 1.0.101 → 1.0.103

package/README.md

@@ -18,7 +18,7 @@ preserves REST outcomes, and redacts failures. See the
 [event-triggered campaign guide](../../docs/event-triggered-campaigns.md) for
 inputs, idempotency, subscription requirements, and conditional step examples.
 
-Sendinel currently exposes 35 tool groups and 340 tools (gateway mode exposes 4 meta-tools, sharing how_to with full mode). These counts are checked against the tool registry in CI, so this table matches what ships.
+Sendinel currently exposes 35 tool groups and 341 tools (gateway mode exposes 4 meta-tools, sharing how_to with full mode). These counts are checked against the tool registry in CI, so this table matches what ships.
 
 | Group | Count | Purpose |
 |-------|-------|---------|
@@ -30,7 +30,7 @@ Sendinel currently exposes 35 tool groups and 340 tools (gateway mode exposes 4
 | `approvals` | 2 | Poll and list risk-tiered action approvals |
 | `automations` | 7 | Automation triggers, previews, and response-gated escalation ladders |
 | `brand_kit` | 6 | Brand Core text import, media library upload/URL ingest, asset-context reads, project logo selection |
-| `campaigns` | 43 | Full campaign lifecycle: create, edit, approve, launch, enroll, schedule, sequence templates, convert imported campaigns |
+| `campaigns` | 44 | Full campaign lifecycle: create, edit, approve, launch, enroll, schedule, sequence templates, convert imported campaigns |
 | `cloud-import` | 6 | Cloud storage import |
 | `compound` | 4 | Higher-level campaign/template/site setup and delivery diagnosis workflows |
 | `connector` | 6 | BYOD connector status, table discovery, schema/view setup, mapping, resync |

package/build/lib/action-approvals.js

@@ -28,6 +28,7 @@ const GATED_ACTIONS = new Set([
     'import_subscribers', // bulk data ingestion
     'subscribe_webhook', // outbound data channel
     'send_transactional', // sends a real email
+    'set_campaign_trigger', // changes who starts an active or paused campaign
     'update_campaign_status', // activation sends real emails (see special case below)
     'add_list_members', // bulk contact-list membership write
     'remove_list_members', // bulk contact-list membership write
@@ -254,6 +255,7 @@ export function buildApprovalSummary(action, params, display = {}) {
             const warnings = display.content_warnings ? ` — Check before approving: ${display.content_warnings}` : '';
             return `Activate ${count} campaign${count === 1 ? '' : 's'}${emails}${names} — each emails contacts when its trigger fires${warnings}`;
         },
+        set_campaign_trigger: (p) => `Change what starts campaign \"${display.campaign_name ?? p.campaign_id}\" from ${display.from_trigger ?? 'its current trigger'} to ${display.to_trigger ?? 'the requested trigger'}; ${typeof display.recipient_count === 'number' ? `up to ${display.recipient_count.toLocaleString('en-US')} people` : 'an unknown number of people'} may start receiving it`,
         update_campaign_status: (p) => (p.status === 'active'
             ? `Activate campaign "${display.campaign_name ?? p.campaign_id}"${typeof display.enrolled === 'number' ? ` — sends email to ${display.enrolled.toLocaleString('en-US')} enrolled contact${display.enrolled === 1 ? '' : 's'}` : ' — will send emails to real contacts'}${display.trigger ? ` and to new contacts on "${display.trigger}"` : ''}${display.content_warnings ? ` — Check before approving: ${display.content_warnings}` : ''}`
             : `Change campaign "${display.campaign_name ?? p.campaign_id}" to ${p.status}`),

package/build/lib/how-to-recipes.js

@@ -6,6 +6,19 @@ const projectRule = 'On hosted /mcp, pass project_id on each call. It is require
 const previewRule = 'preview_email only substitutes sample merge variables; it is not the real send renderer. send_test_email with dry_run:true uses the real renderer without sending, but still follows the approval flow in standard mode; keep the same args plus approval_id when re-calling it. Stdio requires SENDINEL_API_KEY.';
 const sender = { n: 1, tool: 'get_sites', args_example: {}, note: 'Choose the intended sender from the returned array; do not assume the first sender is correct. Replace example content and addresses with the user’s own choices.' };
 export const HOW_TO_RECIPES = [
+    {
+        id: 'set-campaign-trigger', title: 'Set what a campaign fires on',
+        when_to_use: 'Bind an existing campaign to an event such as invoice_payment_failed for dunning, or change its tag/date/contact-event trigger.',
+        synonyms: TOOL_ALIASES.set_campaign_trigger,
+        requires: { scopes: ['write'], tester_ok: false },
+        steps: [
+            { n: 1, tool: 'list_campaigns', args_example: { limit: 25 }, note: 'Select the intended campaign and inspect its status and saved trigger.' },
+            { n: 2, tool: 'set_campaign_trigger', args_example: { campaign_id: from(1, '0.id'), trigger_event_name: 'invoice_payment_failed', trigger_config: { events: ['invoice_payment_failed'], where: { plan: 'paid' } } }, approval, note: 'Use the actual event and intended filter. Drafts save directly; active/paused campaigns return approve_url. Wait for approval, then repeat the SAME args plus approval_id.' },
+            { n: 3, tool: 'get_campaign', args_example: { campaign_id: from(1, '0.id') }, note: 'Verify saved trigger fields, where, fires_on and trigger_diagnostics.' },
+        ],
+        gotchas: [projectRule, 'Archived/completed campaigns refuse changes. clear:true clears trigger fields and cannot be combined with trigger arguments. Drafts still need separate activation approval; setting a trigger does not emit an event.'],
+        done_when: 'The intended trigger and filter round-trip through get_campaign; any activation or live event test remains a separate authorized action.',
+    },
     {
         id: 'send-one-off-email', title: 'Send a one-off email to my list',
         when_to_use: 'Send an announcement or email blast to an audience with human approval.',

package/build/lib/send-audience.d.ts

@@ -9,7 +9,11 @@ import { type SegmentRules } from '@sendinel/domain';
  * Every read throws on failure: an unknown audience must never read as "nobody" or "everyone".
  */
 export type SendClass = 'broadcast' | 'product';
-/** Contact ids matching segment rules (same semantics as the segments tools and the dashboard). */
+/**
+ * Contact ids matching segment rules (same semantics as the segments tools and the dashboard).
+ * Throws SegmentRulesError for invalid rules (#4270): a malformed rule never widens to everyone,
+ * and `{ match_all: true }` is the only way to ask for every contact.
+ */
 export declare function resolveSegmentContactIds(projectId: string, rules: SegmentRules): Promise<string[]>;
 export type SendAudience = {
     /** People the send will enroll. */

package/build/lib/send-audience.js

@@ -15,9 +15,15 @@ async function loadFieldTypes(projectId) {
     }
     return fields;
 }
-/** Contact ids matching segment rules (same semantics as the segments tools and the dashboard). */
+/**
+ * Contact ids matching segment rules (same semantics as the segments tools and the dashboard).
+ * Throws SegmentRulesError for invalid rules (#4270): a malformed rule never widens to everyone,
+ * and `{ match_all: true }` is the only way to ask for every contact.
+ */
 export async function resolveSegmentContactIds(projectId, rules) {
     const tree = normalizeSegmentRulesToTree(rules);
+    if (tree.match_none)
+        return [];
     const fieldTypes = rules.custom_property ? await loadFieldTypes(projectId) : {};
     const q = buildSegmentBaseQuery(db(), projectId);
     const { query: filtered, siteContactIds } = await applySegmentRules(q, rules, db(), projectId, fieldTypes);

package/build/server.js

@@ -85,7 +85,7 @@ const WRITE_TOOLS = new Set([
     'add_subscriber', 'identify_subscriber', 'emit_contact_event', 'import_subscribers', 'update_subscriber', 'bulk_update_subscribers',
     'create_subscriber_view', 'update_subscriber_view', 'delete_subscriber_view',
     'enrich_subscriber',
-    'create_campaign', 'update_campaign', 'delete_campaign', 'add_campaign_step', 'update_campaign_status',
+    'create_campaign', 'set_campaign_trigger', 'update_campaign', 'delete_campaign', 'add_campaign_step', 'update_campaign_status',
     // #3348 - branch/goal writes. Same scope as the campaign edits they sit alongside:
     // they change what the send engine does to enrolled contacts, so they are not read-only.
     'add_campaign_branch', 'remove_campaign_branch', 'set_campaign_goal', 'remove_campaign_goal',

package/build/tools/campaigns.js

@@ -2,7 +2,7 @@ import { readCampaignPeriods, campaignPeriodFields } from "@sendinel/domain";
 import { CAMPAIGN_BRANCH_CONDITIONS, campaignBranchConditionValue, isContactPropertyConditionList, STEP_PROPERTY_CONDITIONS_ERROR, validateStepPropertyRules } from "@sendinel/domain";
 import { z } from 'zod';
 import Anthropic from '@anthropic-ai/sdk';
-import { assertSendAccepted, providerSendError, sendError, SendRefusedError, BLOCKING_CONTENT_ISSUE_KINDS, computeSendContentKey, findContentIssues, sendingHostOf, NAME_FALLBACKS, ONE_SEND_MATCH_STATUSES, ONE_SEND_SENT_STATUSES, ONE_SEND_WINDOW_DAYS, normalizeTriggerConfig, renderTemplateString as renderTemplateVars, resolveBrandTokens, brandWarnings, readAllRows, } from '@sendinel/domain';
+import { assertSendAccepted, providerSendError, sendError, SendRefusedError, BLOCKING_CONTENT_ISSUE_KINDS, computeSendContentKey, findContentIssues, sendingHostOf, NAME_FALLBACKS, ONE_SEND_MATCH_STATUSES, ONE_SEND_SENT_STATUSES, ONE_SEND_WINDOW_DAYS, normalizeTriggerConfig, renderTemplateString as renderTemplateVars, resolveBrandTokens, brandWarnings, readAllRows, isSegmentRulesError, scopeSegmentRulesToSite, SegmentRulesError, validateSegmentRules, } from '@sendinel/domain';
 // Subpath import, not the barrel above -- reply-actions.ts uses node:crypto,
 // and MCP-server-side that's fine (this never runs in an Edge Function), but
 // keeping it off the shared barrel avoids re-creating the Edge-Function
@@ -15,7 +15,7 @@ import { checkPlanLimit } from '../plan-limits.js';
 import { buildVoicePrompt, buildEmailSystemPrompt, deriveTemplateVariables, validateTemplate } from '../lib/voice.js';
 import { fireWebhookEvent } from '../lib/webhook-events.js';
 import { approvalExcerpt, assertChannelCanExecute, currentChannelContext, requestApproval, checkApproval, withApproval } from '../lib/action-approvals.js';
-import { resolveSendAudience } from '../lib/send-audience.js';
+import { resolveSegmentContactIds, resolveSendAudience } from '../lib/send-audience.js';
 import { generateEmailFromBrief, parseAudienceRules } from '../lib/email-generation.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
 import { assertUsableStopReason } from '@sendinel/domain';
@@ -641,7 +641,7 @@ export function registerCampaignTools(server) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'List campaigns, optionally filtered by site and/or status',
+        description: 'List campaigns with saved trigger fields, fires_on summaries and trigger_diagnostics; optionally filter by site or status.',
         inputSchema: {
             site_id: z.string().uuid().optional(),
             period: z.string().min(1).optional().describe("Return one enrollment period in by_period; totals remain all-time."),
@@ -651,7 +651,7 @@ export function registerCampaignTools(server) {
     }, async ({ site_id, status, limit, period }) => {
         let q = db()
             .from('campaigns')
-            .select('id, site_id, name, type, status, sends_per_hour, total_enrolled, total_sent, total_opened, total_clicked, created_at, period_key')
+            .select('id, site_id, name, type, status, sends_per_hour, total_enrolled, total_sent, total_opened, total_clicked, created_at, period_key, segment_id, trigger_type, trigger_event_name, trigger_tag, trigger_config')
             .eq('project_id', getProjectId())
             .order('created_at', { ascending: false })
             .limit(limit ?? 25);
@@ -671,6 +671,8 @@ export function registerCampaignTools(server) {
             const { period_key: _periodKey, ...legacy } = row;
             return {
                 ...legacy,
+                fires_on: buildCampaignFiresOn(row),
+                trigger_diagnostics: buildCampaignTriggerDiagnostics(row),
                 ...campaignPeriodFields(periods, period),
                 ...(periods?.totals ? { total_sent: periods.totals.sent } : {}),
                 unique_opened: periods?.totals?.opened ?? (engagement.ok ? engagement.opened.get(row.id) ?? 0 : null),
@@ -1164,10 +1166,7 @@ export function registerCampaignTools(server) {
             .maybeSingle();
         if (segmentErr || !segment)
             return j({ error: segmentErr?.message ?? 'Segment not found', code: 'SEGMENT_NOT_FOUND' });
-        const rules = {
-            ...(segment.rules ?? {}),
-            ...(segment.site_id ? { site_id: segment.site_id } : {}),
-        };
+        const rules = scopeSegmentRulesToSite(segment.rules, segment.site_id);
         // #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;
@@ -1175,6 +1174,9 @@ export function registerCampaignTools(server) {
             audience = await resolveSendAudience(projectId, site_id, rules);
         }
         catch (error) {
+            // #4270: a malformed segment enrolls nobody and says why.
+            if (isSegmentRulesError(error))
+                return j({ error: error.message, code: 'INVALID_SEGMENT_RULES', errors: error.errors });
             return j({ error: `Could not load this audience: ${error instanceof Error ? error.message : String(error)}`, code: 'AUDIENCE_LOOKUP_FAILED' });
         }
         const contactIds = audience.contactIds;
@@ -1423,7 +1425,7 @@ export function registerCampaignTools(server) {
                 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 } : {}) };
+            rules = scopeSegmentRulesToSite(segment.rules, segment.site_id);
             segmentName = segment.name;
         }
         else {
@@ -1441,6 +1443,9 @@ export function registerCampaignTools(server) {
             resolved = await resolveSendAudience(projectId, site.id, rules, sendClass);
         }
         catch (error) {
+            // #4270: malformed segment or parsed audience rules send to nobody and say why.
+            if (isSegmentRulesError(error))
+                return j({ error: error.message, code: 'INVALID_SEGMENT_RULES', errors: error.errors, rules });
             return j({ error: `Could not load this audience: ${error instanceof Error ? error.message : String(error)}`, code: 'AUDIENCE_LOOKUP_FAILED' });
         }
         if (resolved.contactIds.length === 0) {
@@ -1884,6 +1889,10 @@ Adapt your tone accordingly:
         async function launchFromPlan(plan) {
             let segId = segment_id;
             if (segment_description) {
+                // #4270: never save a segment from rules the segment engine can't use.
+                const rulesCheck = validateSegmentRules(plan.rules);
+                if (!rulesCheck.ok)
+                    return txt(`Error: Could not use the audience rules. ${rulesCheck.errors[0]} Nothing was created.`);
                 const { data: seg, error: segErr } = await db()
                     .from('segments')
                     .insert({ project_id: projectId, name: plan.segment_name, description: segment_description, rules: plan.rules })
@@ -2006,8 +2015,22 @@ Adapt your tone accordingly:
                 q = q.lte(column, rule.before);
             return q;
         }
-        // Helper to get segment contact IDs (simplified inline)
+        // Helper to get segment contact IDs (simplified inline). #4270: rules are validated first
+        // (SegmentRulesError), and anything this flat helper cannot evaluate (rule trees, markers,
+        // custom_property, company filters, multi-tag) goes through the shared evaluator instead of
+        // being ignored, which used to widen those segments to everyone.
+        const INLINE_RULE_KEYS = new Set([
+            'lifecycle_stage', 'payment', 'min_score', 'max_score', 'source', 'subscribed_after', 'subscribed_before',
+            'has_opened', 'has_clicked', 'tag', 'site_id', 'exclude_suppressed', 'metadata',
+        ]);
         const getContactIds = async (rules) => {
+            const check = validateSegmentRules(rules);
+            if (!check.ok)
+                throw new SegmentRulesError(check.errors);
+            const inlineCanEvaluate = Object.keys(rules).every((key) => rules[key] === undefined || INLINE_RULE_KEYS.has(key))
+                && (rules.tag === undefined || typeof rules.tag === 'string');
+            if (!inlineCanEvaluate)
+                return resolveSegmentContactIds(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);
@@ -2073,7 +2096,14 @@ Adapt your tone accordingly:
             catch {
                 return txt(`Error: Failed to parse segment from "${segment_description}"`);
             }
-            contactIds = await getContactIds(parsedRules);
+            try {
+                contactIds = await getContactIds(parsedRules);
+            }
+            catch (error) {
+                if (isSegmentRulesError(error))
+                    return txt(`Error: Could not use the audience parsed from "${segment_description}". ${error.message}`);
+                throw error;
+            }
             contactCount = contactIds.length;
             segmentName = `${name} — segment`;
         }
@@ -2088,7 +2118,14 @@ Adapt your tone accordingly:
                 return txt('Error: segment not found');
             segmentName = seg.name;
             parsedRules = seg.rules;
-            contactIds = await getContactIds(parsedRules);
+            try {
+                contactIds = await getContactIds(parsedRules);
+            }
+            catch (error) {
+                if (isSegmentRulesError(error))
+                    return txt(`Error: Segment "${seg.name}" has rules that can't be used. ${error.message}`);
+                throw error;
+            }
             contactCount = contactIds.length;
         }
         if (!confirmed) {
@@ -2923,11 +2960,15 @@ Return ONLY valid JSON with this exact shape:
             idempotentHint: false,
             openWorldHint: true,
         },
-        description: 'Create a campaign with pre-built email content in one call. Creates the campaign, adds email step(s), optionally enrolls a segment, and activates. Ideal for orchestrators that draft their own content — skips AI generation. Uses two-call confirmation: first call returns a preview, second call with confirmed=true executes.',
+        description: 'Create a sequence, broadcast or triggered campaign with pre-built email content in one call. Set trigger_event_name for dunning (invoice_payment_failed, trial_ending), trigger_tag, or date_field/contact_event trigger_config; events/tags and where filters are supported. Triggered campaigns need no segment. Returns fires_on and trigger_diagnostics. Adds email steps, optionally enrolls a segment, and activates behind standard approval. Ideal for orchestrators that draft their own content — skips AI generation. Uses two-call confirmation: first call returns a preview, second call with confirmed=true executes.',
         inputSchema: {
             site_id: z.string().uuid().describe('Site to send from'),
             name: z.string().min(1).max(200).describe('Campaign name'),
-            type: z.enum(['sequence', 'broadcast']).describe('Campaign type'),
+            type: z.enum(['sequence', 'broadcast', 'triggered']).describe('Campaign type'),
+            trigger_event_name: z.string().nullable().optional(),
+            trigger_tag: z.string().nullable().optional(),
+            trigger_type: z.enum(['manual', 'date_field', 'contact_event']).nullable().optional(),
+            trigger_config: z.record(z.string(), z.unknown()).nullable().optional().describe('Event/tag lists with optional where filter, or date_field/contact_event configuration.'),
             steps: z.array(z.object({
                 subject: z.string().min(1).describe('Email subject line'),
                 body_html: z.string().min(1).describe('Full HTML email body'),
@@ -2936,16 +2977,25 @@ Return ONLY valid JSON with this exact shape:
                 delay_days: z.number().int().min(0).optional().default(0),
                 delay_hours: z.number().int().min(0).max(23).optional().default(0),
             })).min(1).describe('Email steps with pre-built content'),
-            segment_id: z.string().uuid().optional().describe('Segment to auto-enroll. If omitted, campaign is created in draft without enrollments.'),
+            segment_id: z.string().uuid().optional().describe('Segment to auto-enroll. Optional for triggered campaigns; future trigger matches enroll contacts.'),
             sends_per_hour: z.number().int().min(1).nullable().optional().describe('Optional hourly send cap for wave sending. Null or omitted sends without a campaign-specific cap.'),
-            activate: z.boolean().optional().default(false).describe('Set to true to activate immediately after creation. Requires segment_id.'),
+            activate: z.boolean().optional().default(false).describe('Set to true to activate immediately after creation. Requires segment_id or a configured triggered campaign.'),
             confirmed: z.boolean().optional().default(false).describe('Two-call confirmation. First call previews, second call with confirmed=true executes.'),
             approval_id: z.string().uuid().optional().describe('Approval token from a previous call. Required when activate=true — get this by calling once without it, then have a human approve via the dashboard.'),
         },
-    }, async ({ site_id, name, type, steps, segment_id, sends_per_hour, activate, confirmed, approval_id }) => {
+    }, async ({ site_id, name, type, steps, segment_id, sends_per_hour, activate, confirmed, approval_id, trigger_event_name, trigger_tag, trigger_type, trigger_config }) => {
+        const targeting = {};
+        const triggerInput = { trigger_event_name, trigger_tag, trigger_type, trigger_config };
+        const targetingError = await applyCampaignTargetingFields(targeting, triggerInput, getProjectId());
+        if (targetingError)
+            return j({ error: targetingError, code: 'INVALID_FIELD' });
+        const triggerConfig = normalizeTriggerConfig(targeting.trigger_config);
+        const hasEventOrTag = Boolean(targeting.trigger_event_name || targeting.trigger_tag || triggerConfig.events.length || triggerConfig.tags.length);
+        const campaignType = type === 'sequence' && hasEventOrTag ? 'triggered' : type;
+        const canActivateOnTrigger = campaignType === 'triggered' && (hasEventOrTag || targeting.trigger_type === 'date_field' || targeting.trigger_type === 'contact_event');
         // Human-in-the-loop gate for activation
         if (activate && confirmed) {
-            const approvalParams = { site_id, name, type, steps, segment_id, sends_per_hour, activate };
+            const approvalParams = { site_id, name, type, steps, segment_id, sends_per_hour, activate, ...triggerInput };
             const channelContext = currentChannelContext();
             const decision = assertChannelCanExecute('create_campaign_with_content', { activate }, channelContext);
             if (!decision.allowed)
@@ -2991,7 +3041,7 @@ Return ONLY valid JSON with this exact shape:
         if (!confirmed) {
             return j({
                 confirmation_required: true,
-                campaign: { name, type, site: site.name },
+                campaign: { name, type: campaignType, site: site.name, ...targeting },
                 steps: steps.map((s, i) => ({
                     step: i + 1,
                     subject: s.subject,
@@ -3002,8 +3052,8 @@ Return ONLY valid JSON with this exact shape:
                 segment_id: segment_id ?? null,
                 sends_per_hour: sends_per_hour ?? null,
                 estimated_contacts: contactCount,
-                will_activate: activate && !!segment_id,
-                message: `Campaign "${name}" with ${steps.length} step(s) on ${site.name}. ${segment_id ? `Will enroll ~${contactCount} contacts.` : 'No segment — created as draft.'} ${activate && segment_id ? 'Will activate immediately.' : ''} Call again with confirmed=true to proceed.`,
+                will_activate: activate && (!!segment_id || canActivateOnTrigger),
+                message: `Campaign "${name}" with ${steps.length} step(s) on ${site.name}. ${segment_id ? `Will enroll ~${contactCount} contacts.` : canActivateOnTrigger ? 'Future trigger matches will enroll contacts.' : 'No segment — created as draft.'} ${activate && (segment_id || canActivateOnTrigger) ? 'Will activate immediately.' : ''} Call again with confirmed=true to proceed.`,
             });
         }
         // Execute mode (second call)
@@ -3014,7 +3064,8 @@ Return ONLY valid JSON with this exact shape:
             project_id: getProjectId(),
             site_id,
             name,
-            type,
+            type: campaignType,
+            ...targeting,
             status: 'draft',
             segment_id: segment_id ?? null,
             sends_per_hour: sends_per_hour ?? null,
@@ -3078,7 +3129,8 @@ Return ONLY valid JSON with this exact shape:
             }
         }
         // 4. Activate if requested
-        if (activate && segment_id && enrolled > 0) {
+        const willActivate = Boolean(activate && ((segment_id && enrolled > 0) || canActivateOnTrigger));
+        if (willActivate) {
             await db()
                 .from('campaigns')
                 .update({ status: 'active' })
@@ -3087,19 +3139,23 @@ Return ONLY valid JSON with this exact shape:
             fireWebhookEvent('campaign.activated', {
                 campaign_id: campaign.id,
                 campaign_name: name,
-                type,
+                type: campaignType,
                 contacts_enrolled: enrolled,
                 steps: steps.length,
             }).catch(() => { }); // fire-and-forget
         }
+        await logAudit({ action: 'campaign.created', resourceType: 'campaign', resourceId: campaign.id, details: { type: campaignType, ...targeting, activated: willActivate } });
         return j({
             campaign_id: campaign.id,
             name,
-            type,
+            type: campaignType,
+            ...targeting,
+            fires_on: buildCampaignFiresOn({ ...campaign, status: willActivate ? 'active' : 'draft' }),
+            trigger_diagnostics: buildCampaignTriggerDiagnostics({ ...campaign, status: willActivate ? 'active' : 'draft' }),
             steps_created: steps.length,
             contacts_enrolled: enrolled,
-            status: activate && enrolled > 0 ? 'active' : 'draft',
-            message: `Campaign "${name}" created with ${steps.length} step(s). ${enrolled > 0 ? `${enrolled} contacts enrolled.` : 'No contacts enrolled.'} ${activate && enrolled > 0 ? 'Campaign is now active — emails will begin sending on the next cron cycle.' : 'Campaign saved as draft.'}`,
+            status: willActivate ? 'active' : 'draft',
+            message: `Campaign "${name}" created with ${steps.length} step(s). ${enrolled > 0 ? `${enrolled} contacts enrolled.` : 'No contacts enrolled.'} ${willActivate ? 'Campaign is now active — emails will begin sending on the next cron cycle.' : 'Campaign saved as draft.'}`,
         });
     });
     server.registerTool('list_campaign_steps', {
@@ -3284,6 +3340,78 @@ Return ONLY valid JSON with this exact shape:
             return j({ error: error.message });
         return j({ success: true, deleted: campaign.name });
     }));
+    server.registerTool('set_campaign_trigger', {
+        title: 'Set Campaign Trigger',
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        description: 'Set or clear what a campaign fires on: trigger event name, tag, date_field, contact_event, or trigger_config events/tags and where event-data filter. Use for dunning on invoice_payment_failed or trial_ending. Drafts save directly; active/paused campaigns require standard human approval. Archived/completed campaigns cannot change. Returns saved trigger fields, fires_on and trigger_diagnostics.',
+        inputSchema: {
+            campaign_id: z.string().uuid(),
+            trigger_event_name: z.string().nullable().optional(),
+            trigger_tag: z.string().nullable().optional(),
+            trigger_type: z.enum(['manual', 'date_field', 'contact_event']).nullable().optional(),
+            trigger_config: z.record(z.string(), z.unknown()).nullable().optional().describe('Event/tag lists and optional where filter, or date_field/contact_event configuration.'),
+            clear: z.literal(true).optional().describe('Clear all trigger fields back to manual. Cannot be combined with trigger fields.'),
+            approval_id: z.string().uuid().optional(),
+        },
+    }, async ({ approval_id, ...args }) => {
+        const projectId = getProjectId();
+        const { data: existing, error: loadError } = await db().from('campaigns')
+            .select('id, name, type, status, trigger_type, trigger_event_name, trigger_tag, trigger_config, updated_at')
+            .eq('id', args.campaign_id).eq('project_id', projectId).maybeSingle();
+        if (loadError)
+            return j({ error: loadError.message });
+        if (!existing)
+            return j({ error: 'Campaign not found', code: 'NOT_FOUND' });
+        if (!['draft', 'active', 'paused'].includes(existing.status)) {
+            return j({ error: `Cannot change a ${existing.status} campaign trigger`, code: 'INVALID_STATUS' });
+        }
+        const hasFields = ['trigger_event_name', 'trigger_tag', 'trigger_type', 'trigger_config']
+            .some((key) => args[key] !== undefined);
+        if ((!args.clear && !hasFields) || (args.clear && hasFields)) {
+            return j({ error: 'Provide trigger fields or clear=true, exclusively', code: 'INVALID_FIELD' });
+        }
+        const updates = {};
+        const targetingError = await applyCampaignTargetingFields(updates, args.clear
+            ? { trigger_type: 'manual', trigger_event_name: null, trigger_tag: null, trigger_config: null }
+            : args, projectId, existing);
+        if (targetingError)
+            return j({ error: targetingError, code: 'INVALID_FIELD' });
+        const normalized = normalizeTriggerConfig(updates.trigger_config);
+        if (existing.status === 'draft' && existing.type === 'sequence'
+            && (updates.trigger_event_name || updates.trigger_tag || normalized.events.length || normalized.tags.length)) {
+            updates.type = 'triggered';
+        }
+        const execute = async () => {
+            // A draft activated during this call must never bypass approval. The timestamp also
+            // guards against overwriting edits made while an approved call is executing.
+            let query = db().from('campaigns').update({ ...updates, updated_at: new Date().toISOString() })
+                .eq('id', args.campaign_id).eq('project_id', projectId).eq('status', existing.status);
+            if (existing.updated_at)
+                query = query.eq('updated_at', existing.updated_at);
+            const { data, error } = await query.select().maybeSingle();
+            if (error)
+                return j({ error: error.message });
+            if (!data)
+                return j({ error: 'Campaign changed; read it and retry', code: 'CAMPAIGN_CHANGED' });
+            await logAudit({ action: 'campaign.trigger_updated', resourceType: 'campaign', resourceId: args.campaign_id, details: { previous: existing, updates } });
+            return j({ ...data, fires_on: buildCampaignFiresOn(data), trigger_diagnostics: buildCampaignTriggerDiagnostics(data) });
+        };
+        if (existing.status === 'draft')
+            return execute();
+        // The saved state is internal, never caller-supplied. Approval is for this exact before/after.
+        return withApproval('set_campaign_trigger', async (_params) => execute(), {
+            display: async () => {
+                const { count, error } = await db().from('subscribers').select('id', { count: 'exact', head: true })
+                    .eq('project_id', projectId).eq('global_unsubscribed', false);
+                return {
+                    campaign_name: existing.name,
+                    from_trigger: `${buildCampaignFiresOn(existing)} Config: ${JSON.stringify(existing.trigger_config)}`,
+                    to_trigger: `${buildCampaignFiresOn({ ...existing, ...updates })} Config: ${JSON.stringify(updates.trigger_config === undefined ? existing.trigger_config : updates.trigger_config)}`,
+                    recipient_count: error ? null : count,
+                };
+            },
+        })({ ...args, previous_trigger: existing, approval_id });
+    });
     server.registerTool('update_campaign', {
         title: 'Update Campaign',
         annotations: {
@@ -3292,7 +3420,7 @@ Return ONLY valid JSON with this exact shape:
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Update a campaign name, site, segment, send time, topic, trigger settings, or send class (broadcast vs product). trigger_type null (or manual) clears a date_field or contact_event trigger; type switches a draft between sequence and triggered. The response includes fires_on, a plain summary of what the saved campaign fires on, and trigger_diagnostics naming any trigger problems. 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.',
+        description: 'Update a campaign name, site, segment, send time, topic, trigger event name/tag/config (including where filters for dunning), or send class (broadcast vs product). trigger_type null (or manual) clears a date_field or contact_event trigger; type switches a draft between sequence and triggered. The response includes fires_on, a plain summary of what the saved campaign fires on, and trigger_diagnostics naming any trigger problems. 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(),
@@ -3416,7 +3544,7 @@ Return ONLY valid JSON with this exact shape:
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'Get full details of a single campaign including all steps, current enrollment counts, and settings.',
+        description: 'Get full campaign details including all steps, enrollment counts and saved trigger_type, trigger_event_name, trigger_tag, trigger_config (including where filter), fires_on and trigger_diagnostics. Read what event a dunning campaign fires on; use set_campaign_trigger to change it.',
         inputSchema: { campaign_id: z.string().uuid(), period: z.string().min(1).optional().describe("Return results for one enrollment period; totals remain all-time.") },
     }, async ({ campaign_id, period }) => {
         const projectId = getProjectId();
@@ -3487,6 +3615,8 @@ Return ONLY valid JSON with this exact shape:
         const unresolvedCount = dlqUnresolvedCount ?? 0;
         return j({
             ...campaign,
+            fires_on: buildCampaignFiresOn(campaign),
+            trigger_diagnostics: buildCampaignTriggerDiagnostics(campaign),
             total_sent: periods?.totals?.sent ?? sentCount ?? 0,
             ...(periods?.totals ? { unique_opened: periods.totals.opened, unique_clicked: periods.totals.clicked } : {}),
             ...campaignPeriodFields(periods, period),

package/build/tools/contacts.js

@@ -1,7 +1,7 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { CONTACT_ENRICHMENT_PROVIDERS } from '@desler/models';
 import { createContactEnrichmentAdapters, enrichContactFromConnections, } from '@desler/models/contact-enrichment';
-import { buildPreviewAttentionEnvelope, applySegmentRules, ContactPropertyAnomalyLogger, normalizeContactProperties, getAttentionDecision, getContactNeighborhood, getScheduledTouches, findContactDuplicateGroups, readAllPages, readAllRows, chunkIds, } from '@sendinel/domain';
+import { buildPreviewAttentionEnvelope, applySegmentRules, isSegmentRulesError, ContactPropertyAnomalyLogger, normalizeContactProperties, getAttentionDecision, getContactNeighborhood, getScheduledTouches, findContactDuplicateGroups, readAllPages, readAllRows, chunkIds, } from '@sendinel/domain';
 import { z } from 'zod';
 import { callSendinelV1 } from '../lib/v1-client.js';
 import { db, projectClientForWriteback } from '../db.js';
@@ -2103,11 +2103,20 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             q = q.eq('company_id', params.company_id);
         const fieldTypes = params.custom_property ? await loadContactPropertyDefinitions(projectId) : {};
         if (params.custom_property) {
-            ({ query: q } = await applySegmentRules(q, { custom_property: params.custom_property }, db(), projectId, fieldTypes));
+            try {
+                // #4270: the query runs as-is, so a filter it cannot express is an error, not dropped.
+                ({ query: q } = await applySegmentRules(q, { custom_property: params.custom_property }, db(), projectId, fieldTypes, { pushDownOnly: true }));
+            }
+            catch (error) {
+                if (isSegmentRulesError(error))
+                    return txt(`Error: ${error.message}`);
+                throw error;
+            }
         }
         if (params.site_id) {
             // Shared site filter: an inner join, not an id list that overflows past ~350 contacts (#3674).
-            const siteFiltered = await applySegmentRules(q, { site_id: params.site_id }, db(), projectId);
+            // Deliberately everyone on the site, so allowEmpty.
+            const siteFiltered = await applySegmentRules(q, { site_id: params.site_id }, db(), projectId, {}, { allowEmpty: true });
             if (siteFiltered.siteContactIds && siteFiltered.siteContactIds.length === 0)
                 return j({ total: 0, sample: [] });
             q = siteFiltered.query;
@@ -2155,11 +2164,11 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         if (params.tag)
             countQ = countQ.contains('tags', [params.tag]);
         if (params.custom_property) {
-            ({ query: countQ } = await applySegmentRules(countQ, { custom_property: params.custom_property }, db(), projectId, fieldTypes));
+            ({ query: countQ } = await applySegmentRules(countQ, { custom_property: params.custom_property }, db(), projectId, fieldTypes, { pushDownOnly: true }));
         }
         // The total must count the same site the sample came from (#3674).
         if (params.site_id)
-            ({ query: countQ } = await applySegmentRules(countQ, { site_id: params.site_id }, db(), projectId));
+            ({ query: countQ } = await applySegmentRules(countQ, { site_id: params.site_id }, db(), projectId, {}, { allowEmpty: true }));
         const { count } = await countQ;
         return j({ total: count ?? (data ?? []).length, sample: data ?? [] });
     });

package/build/tools/lists.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, normalizeSegmentRulesToTree, readAllRows, } from '@sendinel/domain';
+import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, isSegmentRulesError, normalizeSegmentRulesToTree, readAllRows, } from '@sendinel/domain';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { logAudit } from '../audit.js';
@@ -28,7 +28,10 @@ async function loadFieldTypes(projectId) {
 }
 async function getSegmentContactIds(rules) {
     const projectId = getProjectId();
+    // Throws SegmentRulesError for invalid rules (#4270) instead of widening to everyone.
     const tree = normalizeSegmentRulesToTree(rules);
+    if (tree.match_none)
+        return [];
     const fieldTypes = rules.custom_property ? await loadFieldTypes(projectId) : {};
     const q = buildSegmentBaseQuery(db(), projectId);
     const { query: filtered, siteContactIds } = await applySegmentRules(q, rules, db(), projectId, fieldTypes);
@@ -357,7 +360,16 @@ export function registerListTools(server) {
         },
     }, async ({ list_id, rules, confirmed, approval_id }) => {
         const projectId = getProjectId();
-        const normalizedRules = normalizeSegmentRulesToTree(rules);
+        let normalizedRules;
+        try {
+            normalizedRules = normalizeSegmentRulesToTree(rules);
+        }
+        catch (rulesError) {
+            // #4270: invalid (or empty) filter rules add nobody and say why. Everyone is { match_all: true }.
+            if (isSegmentRulesError(rulesError))
+                return j({ error: rulesError.message, code: 'INVALID_SEGMENT_RULES', errors: rulesError.errors });
+            throw rulesError;
+        }
         const approvalParams = { list_id, rules: normalizedRules };
         const { data: list, error: listError } = await db()
             .from('contact_lists')

package/build/tools/segments.js

@@ -5,7 +5,7 @@ import { db } from '../db.js';
 import { getProjectId } from '../project.js';
 import { getAnthropicModelId } from '../anthropic-model.js';
 import { assertUsableStopReason } from '@sendinel/domain';
-import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, normalizeSegmentRulesToTree, readAllRows, } from '@sendinel/domain';
+import { applySegmentRules, buildSegmentBaseQuery, evaluateSegmentRules, isSegmentRulesError, normalizeSegmentRulesToTree, prepareSegmentRulesForStorage, readAllRows, } from '@sendinel/domain';
 async function loadFieldTypes(projectId) {
     const client = db();
     const scoped = typeof client.schema === 'function' ? client.schema('email') : client;
@@ -27,7 +27,10 @@ async function loadFieldTypes(projectId) {
 }
 async function getSegmentContactIds(rules) {
     const projectId = getProjectId();
+    // Throws SegmentRulesError for invalid rules (#4270) instead of widening to everyone.
     const tree = normalizeSegmentRulesToTree(rules);
+    if (tree.match_none)
+        return [];
     const fieldTypes = rules.custom_property ? await loadFieldTypes(projectId) : {};
     // Shared base query (#3084). This used to be hand-written here and omitted
     // is_test / source_deleted_at / the cooled exclusion the dashboard applies,
@@ -53,6 +56,13 @@ async function getSegmentContactIds(rules) {
 }
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
+/**
+ * #4270: invalid segment rules are an error response naming the first problem,
+ * never an audience of everyone. Returns null for any other error.
+ */
+function invalidRules(error) {
+    return isSegmentRulesError(error) ? txt(`Error: ${error.message}`) : null;
+}
 export function registerSegmentTools(server) {
     server.registerTool('create_segment', {
         title: 'Create Segment',
@@ -69,9 +79,19 @@ export function registerSegmentTools(server) {
             rules: z.record(z.string(), z.unknown()).describe('Segment rule tree: {op:"AND"|"OR", conditions:[{field, operator, value}]} or legacy flat rules. Supported fields include lifecycle_stage, engagement_score, source, created_at, last_opened_at, last_clicked_at, introduced_by_subscriber_id, tags, custom_properties.<key>, payment.<key>. tag may be a plain string (one tag) or {values: string[], mode: "any"|"all"} to match several tags at once.'),
         },
     }, async ({ name, description, rules }) => {
+        let storedRules;
+        try {
+            storedRules = prepareSegmentRulesForStorage(rules);
+        }
+        catch (rulesError) {
+            const invalid = invalidRules(rulesError);
+            if (invalid)
+                return invalid;
+            throw rulesError;
+        }
         const { data, error } = await db()
             .from('segments')
-            .insert({ project_id: getProjectId(), name, description, rules: normalizeSegmentRulesToTree(rules) })
+            .insert({ project_id: getProjectId(), name, description, rules: storedRules })
             .select('id, name, description, rules, created_at')
             .single();
         if (error)
@@ -105,7 +125,17 @@ export function registerSegmentTools(server) {
             return txt(`Error: ${error.message}`);
         const segments = [];
         for (const seg of data ?? []) {
-            const ids = await getSegmentContactIds(seg.rules);
+            let ids;
+            try {
+                ids = await getSegmentContactIds(seg.rules);
+            }
+            catch (rulesError) {
+                if (!isSegmentRulesError(rulesError))
+                    throw rulesError;
+                // #4270: one stored segment with invalid rules matches nobody; its count is unknown, not 0.
+                segments.push({ ...seg, contact_count: null, rules_error: rulesError.message });
+                continue;
+            }
             segments.push({ ...seg, contact_count: ids.length });
         }
         return j(segments);
@@ -131,8 +161,17 @@ export function registerSegmentTools(server) {
             updates.name = name;
         if (description !== undefined)
             updates.description = description;
-        if (rules)
-            updates.rules = normalizeSegmentRulesToTree(rules);
+        if (rules) {
+            try {
+                updates.rules = prepareSegmentRulesForStorage(rules);
+            }
+            catch (rulesError) {
+                const invalid = invalidRules(rulesError);
+                if (invalid)
+                    return invalid;
+                throw rulesError;
+            }
+        }
         const { data, error } = await db()
             .from('segments')
             .update(updates)
@@ -199,7 +238,16 @@ export function registerSegmentTools(server) {
         else {
             return txt('Provide either segment_id or rules.');
         }
-        const ids = await getSegmentContactIds(segRules);
+        let ids;
+        try {
+            ids = await getSegmentContactIds(segRules);
+        }
+        catch (rulesError) {
+            const invalid = invalidRules(rulesError);
+            if (invalid)
+                return invalid;
+            throw rulesError;
+        }
         const sample = ids.slice(0, 10);
         let sampleContacts = [];
         if (sample.length) {
@@ -243,9 +291,12 @@ export function registerSegmentTools(server) {
             return txt(`Error: Failed to parse rules from "${description}"`);
         let parsedRules;
         try {
-            parsedRules = normalizeSegmentRulesToTree(JSON.parse(raw.replace(/```json?\n?|```/g, '').trim()));
+            parsedRules = prepareSegmentRulesForStorage(JSON.parse(raw.replace(/```json?\n?|```/g, '').trim()));
         }
-        catch {
+        catch (parseError) {
+            // #4270: parsed rules that are missing or malformed are an error, never "everyone".
+            if (isSegmentRulesError(parseError))
+                return txt(`Error: Could not use the rules parsed from "${description}". ${parseError.message}`);
             return txt(`Error: Failed to parse rules from "${description}"`);
         }
         const ids = await getSegmentContactIds(parsedRules);

package/build/tools/tool-search.js

@@ -12,6 +12,7 @@ export const STOPWORDS = new Set([
  * Only tools that exist in the registry belong here.
  */
 export const TOOL_ALIASES = {
+    set_campaign_trigger: ['trigger', 'event', 'fires on', 'fires-on', 'dunning', 'set campaign trigger event name', 'invoice payment failed', 'trial ending'],
     send_broadcast: [
         'send email', 'send an email', 'email blast', 'blast', 'newsletter', 'announce', 'announcement', 'one-off email',
         'email my list', 'send to my list', 'email to my list', 'email my subscribers',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.101",
+  "version": "1.0.103",
   "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",