@sendinel/mcp-server 1.0.138 → 1.0.140

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 343 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 344 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 |
 |-------|-------|---------|
@@ -34,7 +34,7 @@ Sendinel currently exposes 35 tool groups and 343 tools (gateway mode exposes 4
 | `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 |
-| `contacts` | 39 | Subscriber CRUD, saved views, tags, email log, suppression, merge, timeline |
+| `contacts` | 40 | Subscriber CRUD, saved views, tags, email log, suppression, merge, timeline |
 | `content` | 14 | Content blocks, gated asset links, blog ingest and auto-publish, sources |
 | `data` | 19 | Platform connectors, imports, API keys, migration jobs, notifications, tenant export |
 | `data-proposals` | 3 | Data-derived campaign proposal generation, listing, approval |

package/build/lib/db-errors.d.ts

@@ -0,0 +1,12 @@
+/** Caller-safe database errors. Never serialize database messages, details or hints. */
+export declare function mapDbError(error: unknown): {
+    error: string;
+    code: string;
+};
+export declare function dbErrorResult(error: unknown): {
+    isError: boolean;
+    content: {
+        type: 'text';
+        text: string;
+    }[];
+};

package/build/lib/db-errors.js

@@ -0,0 +1,20 @@
+/** Caller-safe database errors. Never serialize database messages, details or hints. */
+export function mapDbError(error) {
+    const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+    if (code === '23505')
+        return { error: 'A record with these values already exists.', code: 'conflict' };
+    if (code === '23503' || code === 'PGRST116') {
+        return { error: 'The requested or referenced record was not found.', code: 'not_found' };
+    }
+    if (code.startsWith('23') || code.startsWith('22')) {
+        return { error: 'The supplied values are not valid. Check the input and try again.', code: 'validation_failed' };
+    }
+    return { error: 'The operation could not be completed. Please try again later.', code: 'internal_error' };
+}
+export function dbErrorResult(error) {
+    console.warn('[mcp] Database operation failed:', error);
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(mapDbError(error)) }],
+    };
+}

package/build/lib/url-validation.d.ts

@@ -1,3 +1,6 @@
+/** Redirect destinations may use HTTP or HTTPS, but never executable URL schemes. */
+export declare function assertHttpUrl(raw: string): string;
+export declare const RESERVED_LINK_SLUGS: Set<string>;
 export declare function isSafeRedirectUrl(url: unknown): url is string;
 export declare function isAllowedHttpsHostUrl(url: unknown, allowedDomains: readonly string[]): url is string;
 export declare function normalizeActiveCampaignAccountUrl(accountUrl: string): string;

package/build/lib/url-validation.js

@@ -1,3 +1,18 @@
+/** Redirect destinations may use HTTP or HTTPS, but never executable URL schemes. */
+export function assertHttpUrl(raw) {
+    const url = new URL(raw);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error('Only http and https URLs are supported.');
+    }
+    return url.toString();
+}
+// Shared /s namespace: system routes cannot be claimed by a tenant.
+export const RESERVED_LINK_SLUGS = new Set([
+    'admin', 'api', 'app', 'login', 'dashboard', 's', 'a', 'www', 'support', 'billing',
+    'auth', 'static', 'assets', 'aup', 'ccpa', 'changelog', 'cloud-storage', 'demo-video',
+    'developer', 'embed', 'gdpr', 'getting-started', 'invite', 'legal', 'lp', 'oauth',
+    'pricing', 'privacy', 'reset-password', 'sign-in', 'sign-up', 'terms',
+]);
 export function isSafeRedirectUrl(url) {
     if (typeof url !== 'string' || !url)
         return false;

package/build/tools/approvals.js

@@ -42,7 +42,7 @@ export function registerApprovalTools(server, options) {
             idempotentHint: true,
             openWorldHint: false,
         },
-        description: 'List all pending approval requests for this project. Shows what actions are waiting for human approval.',
+        description: 'List all pending approval requests for this project. Excludes expired requests without mutating them. Shows what actions are waiting for human approval.',
         inputSchema: {},
     }, async () => {
         const { data, error } = await db()
@@ -50,10 +50,11 @@ export function registerApprovalTools(server, options) {
             .select('id, action, tier, channel, summary, status, requested_at, expires_at')
             .eq('project_id', getProjectId())
             .eq('status', 'pending')
+            .gt('expires_at', new Date().toISOString())
             .order('requested_at', { ascending: false })
             .limit(25);
         if (error)
-            return txt(`Error: ${error.message}`);
+            return j({ error: error.message, code: 'INTERNAL_ERROR' });
         return j({ pending: data ?? [], count: data?.length ?? 0 });
     });
 }

package/build/tools/campaigns.d.ts

@@ -7,7 +7,8 @@ export declare function buildCampaignFiresOn(campaign: Record<string, unknown>):
 /**
  * Diagnostic warnings indicating why a campaign's trigger configuration cannot fire (#3852).
  */
-export declare function buildCampaignTriggerDiagnostics(campaign: Record<string, unknown>): string[];
+export declare function buildCampaignTriggerDiagnostics(campaign: Record<string, unknown>, seenEvents?: ReadonlySet<string> | null): string[];
+export declare function campaignTriggerKind(campaign: Record<string, unknown>): 'event' | 'tag' | 'date_field' | 'contact_event' | 'manual';
 export declare function applyCampaignTargetingFields(updates: Record<string, unknown>, input: {
     trigger_event_name?: string | null;
     trigger_tag?: string | null;

package/build/tools/campaigns.js

@@ -1,3 +1,4 @@
+import { dbErrorResult } from '../lib/db-errors.js';
 import { resolveCampaignReentry, readCampaignPeriods, campaignPeriodFields } from "@sendinel/domain";
 import { CAMPAIGN_BRANCH_CONDITIONS, campaignBranchConditionValue, isContactPropertyConditionList, STEP_PROPERTY_CONDITIONS_ERROR, validateStepPropertyRules } from "@sendinel/domain";
 import { z } from 'zod';
@@ -105,11 +106,18 @@ export function buildCampaignFiresOn(campaign) {
 /**
  * Diagnostic warnings indicating why a campaign's trigger configuration cannot fire (#3852).
  */
-export function buildCampaignTriggerDiagnostics(campaign) {
+export function buildCampaignTriggerDiagnostics(campaign, seenEvents) {
     const config = (campaign.trigger_config && typeof campaign.trigger_config === 'object' ? campaign.trigger_config : {});
     const events = normalizeTriggerList([...normalizeTriggerList(config.events), campaign.trigger_event_name]);
     const tags = normalizeTriggerList([...normalizeTriggerList(config.tags), campaign.trigger_tag]);
     const diagnostics = [];
+    if (events.length && seenEvents === null)
+        diagnostics.push('Event history unavailable; prior receipt of these events is unknown.');
+    if (seenEvents)
+        for (const event of events) {
+            if (!seenEvents.has(event))
+                diagnostics.push(`Event "${event}" has never been seen in this project; check the event name or send a test event.`);
+        }
     if ((events.length || tags.length) && campaign.type !== 'triggered') {
         diagnostics.push(`campaign type is "${String(campaign.type)}"; event and tag triggers only start campaigns of type "triggered" (it will never fire)`);
     }
@@ -133,6 +141,37 @@ export function buildCampaignTriggerDiagnostics(campaign) {
     }
     return diagnostics;
 }
+export function campaignTriggerKind(campaign) {
+    if (campaign.trigger_type === 'date_field' || campaign.trigger_type === 'contact_event')
+        return campaign.trigger_type;
+    const config = normalizeTriggerConfig(campaign.trigger_config);
+    if (normalizeTriggerValue(campaign.trigger_event_name) || config.events.length)
+        return 'event';
+    if (normalizeTriggerValue(campaign.trigger_tag) || config.tags.length)
+        return 'tag';
+    return 'manual';
+}
+async function campaignTriggerOutput(campaign) {
+    let seenEvents;
+    const config = normalizeTriggerConfig(campaign.trigger_config);
+    if (normalizeTriggerValue(campaign.trigger_event_name) || config.events.length) {
+        try {
+            // /v1/events -> intakeContactEvent stores event_type=custom and title=event.
+            // Read all pages: a capped sample cannot establish that an event was never seen.
+            const rows = await readAllRows(db().from('contact_events').select('id, title')
+                .eq('project_id', getProjectId()).eq('event_type', 'custom'));
+            seenEvents = new Set(rows.map(row => normalizeTriggerValue(row.title)).filter((value) => value !== null));
+        }
+        catch {
+            seenEvents = null;
+        }
+    }
+    return {
+        trigger_kind: campaignTriggerKind(campaign),
+        fires_on: buildCampaignFiresOn(campaign),
+        trigger_diagnostics: buildCampaignTriggerDiagnostics(campaign, seenEvents),
+    };
+}
 function applyCampaignSendAtField(updates, sendAt, campaignType) {
     if (sendAt === undefined)
         return null;
@@ -165,13 +204,20 @@ export async function applyCampaignTargetingFields(updates, input, projectId, ex
         if (hasTriggerEvent)
             return 'cannot set trigger_event_name on a date_field campaign';
         const config = input.trigger_config ?? {};
+        const unknown = Object.keys(config).filter(key => !['field', 'days_before', 'recurring'].includes(key));
+        if (unknown.length)
+            return `Unknown date_field keys: ${unknown.join(', ')}; allowed: field, days_before, recurring; use days_before, not offset_days`;
+        if (config.days_before !== undefined && (typeof config.days_before !== 'number' || !Number.isInteger(config.days_before) || config.days_before < 0 || config.days_before > 30))
+            return 'days_before must be an integer from 0 to 30; use days_before, not offset_days';
+        if (config.recurring !== undefined && typeof config.recurring !== 'boolean')
+            return 'recurring must be a boolean';
         const field = typeof config.field === 'string' ? config.field.trim() : '';
         if (!/^[A-Za-z0-9_.-]{1,80}$/.test(field))
             return 'date field is required';
         updates.trigger_type = 'date_field';
         updates.trigger_config = {
             field,
-            days_before: Math.max(0, Math.min(30, Number(config.days_before ?? 0) || 0)),
+            days_before: config.days_before ?? 0,
             recurring: config.recurring !== false,
         };
     }
@@ -197,6 +243,24 @@ export async function applyCampaignTargetingFields(updates, input, projectId, ex
             updates.trigger_config = null;
         }
         else {
+            const unknown = Object.keys(input.trigger_config).filter(key => !['events', 'tags', 'where'].includes(key));
+            if (unknown.length)
+                return `Unknown trigger_config keys: ${unknown.join(', ')}; allowed: events, tags, where`;
+            if ('where' in input.trigger_config) {
+                const where = input.trigger_config.where;
+                if (!where || typeof where !== 'object' || Array.isArray(where))
+                    return 'where must be an object of string, number or boolean values';
+                const keys = new Set();
+                for (const [key, value] of Object.entries(where)) {
+                    const normalizedKey = key.trim().replace(/^ctx\./, '');
+                    if (!normalizedKey || normalizedKey === '__proto__' || keys.has(normalizedKey))
+                        return `where.${key} has an empty or duplicate normalized key`;
+                    keys.add(normalizedKey);
+                    if (!['string', 'number', 'boolean'].includes(typeof value) || (typeof value === 'number' && !Number.isFinite(value))) {
+                        return `where.${key} must be a string, number or boolean; operators like $gt are not supported`;
+                    }
+                }
+            }
             const config = buildCampaignTriggerConfig(input.trigger_config);
             if (!config)
                 return 'trigger_config must include events or tags';
@@ -819,40 +883,56 @@ export function registerCampaignTools(server) {
             send_only_if_event: z.string().trim().min(1).optional().describe('Send this step only if the contact has an event with this name by send time; otherwise skip it and continue the journey.'),
         },
     }, async ({ campaign_id, step_order, subject, body_html, body_text, blocks, delay_days, delay_hours, variant_label, survey_id, brand_asset_ids, skip_if_event, send_only_if_event, skip_if_property, send_only_if_property }) => {
-        const properties = validateStepPropertyRules({ skip_if_property, send_only_if_property });
-        if (!properties.ok)
-            return j({ error: properties.error, code: "INVALID_INPUT" });
-        const renderVars = {};
-        if (survey_id) {
-            const surveyLink = await resolveSurveyShortLink(db(), getProjectId(), survey_id);
-            if (!surveyLink)
-                return j({ error: 'Survey has no short link yet', code: 'SURVEY_LINK_NOT_READY' });
-            renderVars.survey_link = surveyLink;
+        try {
+            const properties = validateStepPropertyRules({ skip_if_property, send_only_if_property });
+            if (!properties.ok)
+                return j({ error: properties.error, code: "INVALID_INPUT" });
+            const { data: campaign, error: campaignError } = await db()
+                .schema('email')
+                .from('campaigns')
+                .select('id')
+                .eq('id', campaign_id)
+                .eq('project_id', getProjectId())
+                .maybeSingle();
+            if (campaignError)
+                return dbErrorResult(campaignError);
+            if (!campaign)
+                return { ...j({ error: 'Campaign not found.', code: 'not_found' }), isError: true };
+            const renderVars = {};
+            if (survey_id) {
+                const surveyLink = await resolveSurveyShortLink(db(), getProjectId(), survey_id);
+                if (!surveyLink)
+                    return j({ error: 'Survey has no short link yet', code: 'SURVEY_LINK_NOT_READY' });
+                renderVars.survey_link = surveyLink;
+            }
+            const renderedSubject = survey_id ? renderTemplateVars(subject, renderVars) : subject;
+            const normalizedBlocks = blocks ? normalizeComposerBlocks(blocks) : undefined;
+            const htmlFromBlocks = normalizedBlocks?.length ? blocksToHtml(normalizedBlocks) : undefined;
+            const renderedHtml = body_html !== undefined && survey_id ? renderTemplateVars(body_html, renderVars) : body_html ?? htmlFromBlocks;
+            const renderedText = body_text !== undefined && survey_id ? renderTemplateVars(body_text, renderVars) : body_text;
+            const { data, error } = await db()
+                .from('campaign_steps')
+                .insert({ campaign_id, step_order, subject: renderedSubject, body_html: renderedHtml, body_text: renderedText ?? (normalizedBlocks?.length ? blocksToText(normalizedBlocks) : undefined), blocks: normalizedBlocks ?? null, delay_days, delay_hours, variant_label: variant_label ?? 'A', skip_if_event: skip_if_event ?? null, send_only_if_event: send_only_if_event ?? null, ...properties.rules })
+                .select()
+                .single();
+            if (error)
+                return dbErrorResult(error);
+            await recordBrandAssetUsage({
+                client: db(),
+                projectId: getProjectId(),
+                source: 'campaign_step',
+                resourceId: data.id,
+                html: renderedHtml,
+                assetIds: brand_asset_ids,
+            }).catch((err) => {
+                console.warn('Failed to record brand asset usage for MCP campaign step:', err);
+            });
+            await logAudit({ action: 'campaign.step_created', resourceType: 'campaign_step', resourceId: data.id, details: { property_rules: properties.rules } });
+            return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (error) {
+            return dbErrorResult(error);
         }
-        const renderedSubject = survey_id ? renderTemplateVars(subject, renderVars) : subject;
-        const normalizedBlocks = blocks ? normalizeComposerBlocks(blocks) : undefined;
-        const htmlFromBlocks = normalizedBlocks?.length ? blocksToHtml(normalizedBlocks) : undefined;
-        const renderedHtml = body_html !== undefined && survey_id ? renderTemplateVars(body_html, renderVars) : body_html ?? htmlFromBlocks;
-        const renderedText = body_text !== undefined && survey_id ? renderTemplateVars(body_text, renderVars) : body_text;
-        const { data, error } = await db()
-            .from('campaign_steps')
-            .insert({ campaign_id, step_order, subject: renderedSubject, body_html: renderedHtml, body_text: renderedText ?? (normalizedBlocks?.length ? blocksToText(normalizedBlocks) : undefined), blocks: normalizedBlocks ?? null, delay_days, delay_hours, variant_label: variant_label ?? 'A', skip_if_event: skip_if_event ?? null, send_only_if_event: send_only_if_event ?? null, ...properties.rules })
-            .select()
-            .single();
-        if (error)
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }] };
-        await recordBrandAssetUsage({
-            client: db(),
-            projectId: getProjectId(),
-            source: 'campaign_step',
-            resourceId: data.id,
-            html: renderedHtml,
-            assetIds: brand_asset_ids,
-        }).catch((err) => {
-            console.warn('Failed to record brand asset usage for MCP campaign step:', err);
-        });
-        await logAudit({ action: 'campaign.step_created', resourceType: 'campaign_step', resourceId: data.id, details: { property_rules: properties.rules } });
-        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
     });
     server.registerTool('update_campaign_status', {
         title: 'Update Campaign Status',
@@ -3188,8 +3268,7 @@ Return ONLY valid JSON with this exact shape:
             send_class: campaign.send_class,
             unsub_footer_template: campaign.unsub_footer_template,
             ...targeting,
-            fires_on: buildCampaignFiresOn({ ...campaign, status: willActivate ? 'active' : 'draft' }),
-            trigger_diagnostics: buildCampaignTriggerDiagnostics({ ...campaign, status: willActivate ? 'active' : 'draft' }),
+            ...await campaignTriggerOutput({ ...campaign, status: willActivate ? 'active' : 'draft' }),
             steps_created: steps.length,
             contacts_enrolled: enrolled,
             status: willActivate ? 'active' : 'draft',
@@ -3381,7 +3460,7 @@ Return ONLY valid JSON with this exact shape:
     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. Bind billing, payment failed, dunning or trial ending mail to an event trigger such as 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.',
+        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. Bind billing, payment failed, dunning or trial ending mail to an event trigger such as 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, derived trigger_kind, fires_on and trigger_diagnostics (including unseen-event warnings).',
         inputSchema: {
             ...reentryFields,
             campaign_id: z.string().uuid().optional(),
@@ -3395,7 +3474,7 @@ Return ONLY valid JSON with this exact shape:
     }, async ({ approval_id, ...args }) => {
         if (approval_id) {
             const result = await resumeCampaignEdit('set_campaign_trigger', approval_id, args);
-            return j(result.error ? result : { ...result, fires_on: buildCampaignFiresOn(result), trigger_diagnostics: buildCampaignTriggerDiagnostics(result) });
+            return j(result.error ? result : { ...result, ...await campaignTriggerOutput(result) });
         }
         if (!args.campaign_id)
             return j({ error: 'campaign_id is required', code: 'INVALID_FIELD' });
@@ -3435,7 +3514,7 @@ Return ONLY valid JSON with this exact shape:
         if (reentry.period_key !== undefined)
             updates.period_key = reentry.period_key;
         const result = await finishCampaignEdit('set_campaign_trigger', args, existing, updates, params => requestApproval('set_campaign_trigger', params));
-        return j(result.error || result.requires_approval ? result : { ...result, fires_on: buildCampaignFiresOn(result), trigger_diagnostics: buildCampaignTriggerDiagnostics(result) });
+        return j(result.error || result.requires_approval ? result : { ...result, ...await campaignTriggerOutput(result) });
     });
     server.registerTool('update_campaign', {
         title: 'Update Campaign',
@@ -3468,7 +3547,7 @@ Return ONLY valid JSON with this exact shape:
     }, async ({ approval_id, ...input }) => {
         if (approval_id) {
             const result = await resumeCampaignEdit('update_campaign', approval_id, input);
-            return j(result.error ? result : { ...result, fires_on: buildCampaignFiresOn(result), trigger_diagnostics: buildCampaignTriggerDiagnostics(result) });
+            return j(result.error ? result : { ...result, ...await campaignTriggerOutput(result) });
         }
         const { campaign_id, name, site_id, segment_id, send_at, topic, trigger_event_name, trigger_tag, trigger_type, trigger_config, type, sends_per_hour, send_in_contact_timezone, send_class, unsub_footer_template, reentry_mode, period_key } = input;
         if (!campaign_id)
@@ -3599,7 +3678,7 @@ Return ONLY valid JSON with this exact shape:
             idempotentHint: true,
             openWorldHint: false,
         },
-        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. ' + ACTIVATION_APPROVAL_DESCRIPTION,
+        description: 'Get full campaign details including all steps, enrollment counts and derived trigger_kind (event/tag/date_field/contact_event/manual), 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. ' + ACTIVATION_APPROVAL_DESCRIPTION,
         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();
@@ -3672,8 +3751,7 @@ Return ONLY valid JSON with this exact shape:
             ...campaign,
             reentry_mode: campaign.period_key ? "per_event_period" : "once_ever",
             requires_approval_description: ACTIVATION_APPROVAL_DESCRIPTION,
-            fires_on: buildCampaignFiresOn(campaign),
-            trigger_diagnostics: buildCampaignTriggerDiagnostics(campaign),
+            ...await campaignTriggerOutput(campaign),
             total_sent: periods?.totals?.sent ?? sentCount ?? 0,
             ...(periods?.totals ? { unique_opened: periods.totals.opened, unique_clicked: periods.totals.clicked } : {}),
             ...campaignPeriodFields(periods, period),